decide: approval validity clock and schema wiring for catalog approval provenance

[zohebk8s]

Follow-up to #517. Both items below are against src/cmcp_runtime/catalog/approval.py as merged in #519 (ddfd9c3), which is unchanged on main since. They need a maintainer decision rather than a fix, so they were left out of #531, which covers the rest of that review.

1. Records stop verifying once their approvals expire

verify_catalog_change judges approval validity against the verification clock:

instant = int(time.time()) if now is None else now
...
if instant < approval["approved_at"] or instant >= approval["expires_at"]:
    raise CatalogApprovalMismatch("approval is not currently valid")

Re-verifying a historical record after expires_at raises CatalogApprovalMismatch: approval is not currently valid. A record that was valid when the catalog was approved becomes permanently unverifiable, so the chain cannot be replayed by an auditor later. That works against the purpose stated in #517, which is to let a verifier establish independently how a catalog reached its approved state.

The underlying question is which instant the reviewer key must be valid at:

• approval time, with approved_at and expires_at bounding when the signature could have been produced, and key validity checked against that window;
• an external instant supplied by the caller, such as a pinned checkpoint or transparency receipt timestamp, which is also where design: verifiable approval provenance for tool catalogs #517 says freshness has to come from;
• verification time, the current behaviour, which makes the record an authorization token with a lifetime rather than a provenance record.

Whatever is chosen, the spec doc should say it explicitly. docs/spec/catalog-approval-provenance.md does not currently state which clock governs, and the two readings have opposite consequences for audit.

Suggested resolution: keep the interval as an assertion about when the approval was made, verify key validity against an instant the caller passes in, and default that instant to the record's own approval window rather than time.time(). Revocation stays a verification-time check, since a key revoked today should not validate a record presented today.

2. schemas/catalog-approval.schema.json is never loaded, and does not ship

The schema was added in #519 but nothing reads it. The verifier reimplements structural validation by hand, and the two already disagree. #531 fixes the divergences it found by hand, but one is left deliberately failing there, as a strict xfail, because it cannot be fixed without answering this:

record with approved_at: -1
schema:   rejected (-1 is less than the minimum of 0)
verifier: accepted

Hand-written validation drifting from an unused schema will keep recurring until one of them is the source of truth.

Three connected decisions:

• Does the verifier load and apply the schema? loader.py refuses to load a catalog at all when catalog-entry.schema.json is missing from the installation. If approval records get the same treatment, follow that pattern; if the schema is documentation only, say so in the doc, which currently claims the record is "defined by" the schema.
• If it is loaded, it has to ship. schemas/catalog-approval.schema.json is not in [tool.hatch.build.targets.wheel.force-include] in pyproject.toml, where catalog-entry.schema.json is, so it is absent from the wheel today.
• The schema requires previous_record_hash on every record but defines no value for the first one in a chain. An all zero digest validates against the pattern, so a genesis record is representable, just not specified: one producer writes zeros, another writes the digest of an empty change set, and a verifier cannot distinguish "no predecessor" from a real chain link. Pick the convention, an all zero digest being the usual one, and write it into both the schema and the doc. fix(catalog): pin the approval policy verifier-side and bind the chain fields (#517) #531 asserts that convention in a test so the chain has a defined start, but the schema still does not say it.

Suggested resolution: load and apply the schema in verify_catalog_change before the hand-written checks, force-include it in the wheel, define the genesis digest, and keep the hand-written checks only for what JSON Schema cannot express, such as the runtime hash binding and the signature verification.

Tests

#531 adds an agreement test asserting that whatever the schema rejects the verifier rejects too, which is what surfaced the timestamp case above. Both decisions here need their own coverage on top of it: historical replay of an expired record under whichever clock is chosen, and a genesis record validated against the shipped schema rather than against the convention alone. Listed so the decision and its tests land together.

Not in scope

Rollback and freshness of the presented chain, which #517 already assigns to an external pin or transparency receipt, and wiring the module into startup, the CLI, or the proxy.

[github-actions]

🟡 Contributor Check: MEDIUM

Check	Result
Profile	MEDIUM
Credential	LOW
Overall	MEDIUM

Automated check by AgenTrust Contributor Check.

[imran-siddique]

Both decided. #531 is merged, so these are live now rather than hypothetical.

1. The clock: approval window, with revocation staying at verification time

Take your suggested resolution. Concretely:

• The approved_at/expires_at interval is an assertion about when the approval was made, not a lifetime on the record. Reviewer key validity is checked against an instant inside that window, not against time.time().
• verify_catalog_change takes the instant from the caller, and where the caller supplies none it defaults to the record's own approval window rather than the verification clock. A pinned checkpoint or transparency-receipt timestamp is the better input and design: verifiable approval provenance for tool catalogs #517 already says freshness has to come from there, but requiring one would mean an auditor cannot verify a record without also having the pin, which is a worse default than the one it replaces.
• Revocation stays a verification-time check. A key revoked today must not validate a record presented today, and that is a different question from whether the key was valid when it signed. Keep the two apart in the code as well as in the doc, because they will read as the same check to whoever touches this next.

The reason is the one you gave: judged at the verification clock, this is an authorization token with a lifetime, and #517 asks for something an auditor can replay to establish independently how a catalog reached its approved state. A provenance record that stops verifying on a timer is not that. Write the choice into docs/spec/catalog-approval-provenance.md explicitly, including the sentence that the interval bounds when the signature could have been produced. The doc being silent on which clock governs is how two readings with opposite audit consequences both looked correct.

2. Schema: load it, ship it, and define the genesis digest

Yes to all three, following catalog-entry.schema.json.

• Load and apply it in verify_catalog_change before the hand-written checks, and follow loader.py's pattern of refusing to proceed when the schema is missing from the installation. Hand-written checks stay only for what JSON Schema cannot express: the runtime hash binding, the signature verification, the policy pin, and the key-identity rules.
• Force-include it in the wheel. Confirmed at main efc30dd: [tool.hatch.build.targets.wheel.force-include] lists only schemas/catalog-entry.schema.json, so catalog-approval.schema.json is in the repository and absent from the installed package. Worth noting audit-entry.schema.json and trace-claim.schema.json are in the same position; if either is meant to be loadable at runtime it has the same defect, and that is a separate issue rather than something to fold in here.
• Genesis is the all-zero digest. sha256: followed by 64 zeros, written into both the schema and the doc, so "no predecessor" is distinguishable from a real chain link rather than left to producer convention. Your point that an all-zero digest already validates against the pattern is exactly why it needs specifying: it is representable today and unspecified, which is the worst combination.

Once the schema is the source of truth, the strict xfail in #531 on the negative approved_at stops being a documented divergence and starts failing, which is what it was written for. Remove the xfail in the same PR.

Tests

As you listed. Historical replay of an expired record verifying under the approval-window clock, and a genesis record validated against the shipped schema rather than the convention alone. Add one that the schema is actually present in a built wheel, otherwise the force-include silently regresses the next time someone edits pyproject.toml.

Happy for this to be one PR or two, split at the clock and the schema if that is easier to review.