Skip to content

Complete freshness dependencies and honest scan state (v0.6.0) - #28

Merged
Shakargy merged 1 commit into
mainfrom
v0.6.0-freshness-and-staleness
Sep 12, 2026
Merged

Shakargy merged 1 commit into
mainfrom
v0.6.0-freshness-and-staleness

Conversation

@Shakargy

@Shakargy Shakargy commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Why

v0.5.1 fixed results that were wrong. This fixes results that were stale while claiming to be current - the same failure wearing a timestamp.

All four problems were reproduced against v0.5.1 before being changed:

Reproduction Before After
Edit the test that justified a route association FRESH STALE, names the test
Delete an evidence file FRESH (old files row still matched) STALE, names the file
Add a new route to a set-level claim FRESH STALE (inventory changed)
Edit source, run dtc verify without rescanning silent, fresh timestamp explicit stale-scan warning

What changed

Dependencies are separate from displayed evidence. Verification was fingerprinting the bounded list shown to a user and treating it as the invalidation set. Results now record a complete dependency set - handler files, tests, guards, helpers - plus a fingerprint of the claim's surface, so adding a route invalidates a claim about "all routes" even though no recorded file changed. A result that recorded nothing is NEEDS_VERIFICATION, never assumed fresh. Unrelated edits still change nothing.

dtc verify reports which snapshot it used. A bounded, read-only comparison against the working tree, surfaced before any result, in JSON as evidence_snapshot, and in MCP as an explicit staleness_warning - agents can't see your files, so they must be told.

Request-based association restores usefulness legitimately. Tests that request the exact route path (supertest, FastAPI TestClient) now count, alongside imports. Method identity holds: requesting GET /users establishes nothing about POST /users. Name similarity is still only a suggestion.

Unresolved is not untested. Routes declared against an unresolved router mount prefix are reported as unresolved with the reason - that gap belongs to DevTime, not the repository. On the FastAPI template this correctly separates 10 unresolvable routes from 13 genuinely unassociated ones.

Migration

verifications gains inventory_fingerprint via an idempotent ALTER. Verified against a simulated pre-v0.6.0 database. Pre-existing rows keep NULL and get re-verified rather than assumed fresh. Decisions and scan history untouched. JSON stays schema_version: 2 (additive fields only).

Verification

  • 173 tests (16 new), including every reproduction plus: empty dependency set, idempotent migration, stale CLI output, stale MCP disclosure, supertest and TestClient association, method separation, and cache.get("users") not being mistaken for an HTTP request.
  • Real repos re-checked (Express, FastAPI template); build + twine clean.

Version 0.6.0. No tag, no publish - awaiting approval.

v0.5.1 fixed results that were wrong. This fixes results that were stale while
claiming to be current.

Freshness:
- Verification recorded only the bounded evidence shown to a user and used it
  as the invalidation set. Results now record a complete dependency set -
  handlers, tests, guards, helpers - plus a fingerprint of the claim's surface.
- Reproduced and fixed: editing the TEST that justified a route association
  left the claim FRESH; DELETING an evidence file left it FRESH because the old
  files row survived with a matching hash; adding a NEW route left a set-level
  claim FRESH because no recorded file changed.
- A dependency that changed, disappeared, or was not seen by the latest scan
  marks the claim STALE and names it. A result with no recorded dependencies is
  NEEDS_VERIFICATION, never assumed fresh. Unrelated edits still change nothing.

Scan state:
- dtc verify recomputes from the last persisted scan, which is not the working
  tree. It now performs a bounded read-only comparison and reports the
  relationship before any result. JSON gains evidence_snapshot; the MCP
  verify_claim tool gains staleness_warning so an agent that cannot see the
  user's files is told which snapshot it reasoned about.

Association:
- Tests that request an exact route path (supertest, FastAPI TestClient) now
  establish association, restoring usefulness that v0.5.1 traded away for
  correctness. Method identity is preserved: requesting GET /users establishes
  nothing about POST /users. Name similarity remains a suggestion only.
- Routes declared relative to an unresolved router mount prefix are reported as
  unresolved rather than untested: that gap belongs to DevTime, not the repo.

Migration: verifications gains inventory_fingerprint via an idempotent ALTER;
pre-v0.6.0 rows keep NULL and are re-verified rather than assumed fresh.
Decisions and scan history are untouched. JSON stays schema_version 2.

173 tests (16 new). Version 0.6.0.
@Shakargy
Shakargy merged commit b167a93 into main Sep 12, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant