Reject specs that do not round-trip through JSON at `put()` — the option-1 tightening deferred by #7856

[huangyiirene]

Filed by the domain:metadata PM seat. This is the follow-up the #7856 triage ruling explicitly deferred rather than rejected, and it is filed because the implementing session drafted it but could not file it (the objectstack-ai org does not have the Claude GitHub App connected, so dev containers are blocked from the GitHub API — see #7856's PR #7992). Filing it here so a drafted card does not evaporate; a "drafted" card with no number is not a filing.

Provenance and what is already settled

#7856 (landed as PR #7992, c7e7900) fixed the coherence half: canonicalize now honours toJSON exactly as JSON.stringify does, so canonicalize(x) === canonicalize(JSON.parse(JSON.stringify(x))) holds by construction and put().version === get().hash is true again.

The triage ruling on #7856 (comment 5263973459) chose option 2 (hash the serialized form) and was explicit about this card:

Option 1 (reject non-round-tripping specs at the door) is NOT rejected on the merits — it is a separate accept-set tightening with its own blast radius; if the dev's measurement of real spec corpora shows non-round-tripping values are rare-to-zero, file the option-1 tightening as its own follow-up card (contract-first, likely domain:spec-adjacent for the authorable face) rather than riding it here.

That measurement was taken and it favours the tightening. #7992 hashed this repository's entire checked-in JSON corpus under both the old and new implementations: 1973 files, 0 hashes changed. The only positions that behave differently are those carrying a callable toJSON, and the corpus contains none.

The question this card decides

put() currently accepts a spec whose in-memory form does not round-trip through JSON. After #7992 the stored bytes and the returned version agree, so nothing is incoherent any more — but the author still gets silent lossiness: a Date they wrote is a string when read back, and a class instance is whatever its toJSON yields.

Should put() refuse such a spec, loudly, naming the offending key?

For: it matches the repo's contract-first posture ("declared = enforced"), and it is the hardest shape for an AI author to get silently wrong — the failure becomes a message at the door instead of a value that quietly changes type between write and read.

Against: it is an accept-set tightening, i.e. a breaking change for any caller that does this today. The corpus measurement bounds the blast radius for checked-in specs at zero, but it says nothing about specs constructed at runtime by consumers.

⚠️ Measure the runtime constructors before assuming zero. The 1973-file result covers the on-disk corpus only. put() callers that build a spec in memory — plugins, migrations, tests, SysMetadataRepository writers — are the population this tightening would actually break, and they were not measured by #7992.

⚠️ Three open questions the drafting session flagged

Recorded as questions, not answers — this card does not pick:

1. Where does the refusal live — put() in each repository implementation, or the shared contract suite / hashSpec layer that fix(metadata-core,metadata-fs): hash the serialized form, so put().version identifies the bytes actually stored (#7856) #7992 already unified? The latter is the natural chokepoint but changes the accept set for every implementation at once.
2. What is the error's shape — a declared error code (subject to check:error-code-casing), or a thrown validation error? It must name the offending key path, not just the fact of the failure.
3. Is Date genuinely disallowed, or normalised? A blanket refusal of toJSON-carrying values is simple but rejects Date, which is the single most likely thing an author writes. An alternative is to refuse only values whose toJSON is lossy in a way the reader cannot invert — which is harder to define and may not be worth it.

⚠️ If the choice turns on product intent unreadable from the code, that is a needs-user-decision, not a coin flip — the original card said so and it still applies.

Routing note

Filed domain:metadata because the mechanism lives in packages/metadata-core / packages/metadata-fs. ⚠️ If the remedy changes the authorable acceptance face, it belongs to domain:spec (#6017) — the triage ruling anticipated this ("likely domain:spec-adjacent for the authorable face"). Re-route rather than reaching across.

Precondition

⛔ Do not start before confirming #7992 (c7e7900) is on main — this card is meaningless without it, since the coherence bug would otherwise mask the accept-set question.

[huangyiirene]

⛔ DESIGN EXIT — pm:dispatched → needs-user-decision. Two rulings needed, and the second one is on me.

The dev stopped rather than improvising, which is the correct outcome and what the brief asked for. Its two questions:

(1) ruling on §4.3 strategy (blanket refusal vs normalisation)
(2) decision on reversing #7992's 20 contract pins and accepting an unexercised end-to-end coherence guarantee

Its full report could not be posted (the GitHub API is still unreachable from these containers) and will be relayed when handed over. Recording the shape now so the decision is not blocked on the transcript.

⚠️ Question (2) is a flaw in the card I filed, and I should name it as mine

I wrote this card. I framed option 1 as "not rejected on the merits, deferred with its own blast radius" — treating it as independent of the option-2 fix that landed as #7992 (c7e7900). It is not independent, and the dev found the coupling I missed.

#7992 made this true by construction:

canonicalize(x) === canonicalize(JSON.parse(JSON.stringify(x)))

and pinned it with a table-driven contract suite — Date at a key, Date under an array index, a class whose toJSON yields a string, an object literal carrying its own toJSON, nested cases — placed in the shared repository contract suite so every MetadataRepository implementation is held to it.

⇒ Option 1 refuses, at the door, exactly the specs those pins are built from. Implement the tightening and the coherence guarantee still holds in principle but can no longer be exercised end-to-end, because no caller can construct a case that reaches it. The two options are in tension in a way this card asserted they were not.

That is a genuine architectural question and not mine to settle: is a guarantee that cannot be exercised worth keeping, and at what cost to the tests that currently prove it?

The two candidate readings, without a preference

• Tighten (option 1) and accept the consequence — the accept set narrows so the incoherence becomes unreachable rather than merely corrected. The pins would have to move to a lower layer (canonicalize unit level) or be reversed. The end-to-end coherence property becomes an invariant nothing tests, which is exactly the shape [finding] DEBT ledger counts in check-type-check-coverage.mjs drift silently — @objectstack/metadata-protocol records 28, actually reports 63 #5278-style ratchets exist to refuse elsewhere in this repo.
• Do not tighten — keep the accept set, keep the pins exercised, and accept that authors can still write a Date whose stored form differs from its in-memory form. The version now identifies the stored bytes either way, so nothing is incoherent; the remaining cost is silent lossiness for the author.

⛔ I am not choosing. Both readings are defensible and the choice is about what the platform promises authors, not about the code.

Question (1) — also genuinely a ruling

§4.3 as filed: is Date genuinely disallowed, or normalised? The brief told the dev that if it found itself inventing a definition of "lossy", it should stop rather than invent one. It stopped. That was the instruction working as intended.

Date is the single most likely thing an author writes, so a blanket refusal of toJSON-carrying values has a very different feel from a targeted one — and "targeted" requires a definition of lossiness that nobody has written down.

Precondition still holds

#7992 (c7e7900) is on main, so the coherence half is landed and this card is genuinely about the accept set, not about the bug it fixed.

⚠️ Manual unlock owed. Like #7823 and #7987, the blocker here is a ruling rather than a merged PR, so no automated sweep returns this card. Recorded on the seat sticker (#6367) as this seat's obligation.

⚠️ This is now the third card in the decision box (#7823 · #7987 · #8006), and unlike the first two it is not part of their family — it is independent.

---

Generated by Claude Code