@autoSet stamping: add a shared cross-port api-contract parity gate (#203 follow-up)

[dmealing]

Follow-up to #203. The @autoSet timestamp stamping shipped across all five ports (Python / C# / Java / Kotlin CRUD stamping + TS insertPreserving), each with per-port tests proving insert→both stamped==now(), update/patch→updatedAt bumped + createdAt unchanged, insertPreserving→verbatim. So the behavior is gated per port.

What's not yet landed is the shared cross-port api-contract parity gate (the plan's step 3, docs/superpowers/plans/2026-07-16-issue-203-autoset-stamping-plan.md): a single @autoSet-bearing entity + api-contract scenarios (POST asserts created_at == updated_at; PATCH asserts updated_at bumped, created_at unchanged) that ALL five ports' generated-artifact lanes pass — the parity lock (like #195's coordinated registration). It's additional assurance (per-port tests already cover correctness), but it's the pattern the repo uses to prevent cross-port drift.

Note for whoever picks this up: the timestamp assertions need care in the scenario DSL — comparing two response fields (created_at == updated_at) and comparing a field across two requests (PATCH bumps updated_at). And it must be verified green on all five ports' api-contract lanes (both reference + generated) before landing, or it reds the laggards.

[dmealing]

Closing after scoping across all five ports: a single shared api-contract gate where all five generated-artifact lanes pass is not achievable faithfully, because @autoSet stamping is implemented in a different architectural layer in each port, and each corpus's generated lane only hosts some of those layers.

Where each port stamps @autoSet (verified this session)

Port	Stamping layer (#203)	api-contract generated lane hosts that layer?
TS	codegen Zod validators (in the emitted routes)	✅ yes
C#	generated routes (RoutesGenerator)	✅ yes
Java	generated controller/DTO (stampForInsert / stampAutoSetOnUpdate)	✅ yes
Python	ObjectManager runtime — below the generated router's consumer repo seam	❌ no — the generated lane fills the seam with an in-memory stub that never calls ObjectManager
Kotlin	generated Exposed repository (KotlinRepositoryGenerator)	❌ no — the generated controller does its own direct Exposed writes, never uses the repository, and has zero @autoSet awareness

The api-contract generated lane hosts routes/controllers (so it exercises real TS/C#/Java stamping) but stubs/bypasses the repo/runtime (so it cannot exercise Python's or Kotlin's shipped stamping). persistence-conformance is the mirror image — it drives the runtime/repository write path (exercising Python/Kotlin) but not the routes/controller stamping (TS/C#/Java). No single corpus faithfully exercises all five ports' shipped stamping.

The api-contract corpus is auto-discovered by every port's runner (no per-port allowlist), so any new scenario runs on both lanes in every port. Making it green would require hand-coding stamping into all five hand-rolled reference servers and the Python/Kotlin generated-lane stub repos — which, for the seam ports, asserts a hand-written double, not the shipped code. That is a hollow gate, not a parity lock.

Why this is safe to close

@autoSet correctness is already gated per port by the #203 tests, which assert this exact contract against each port's real shipped stamping path (insert → created==updated; update/patch → updated bumped, created unchanged; insertPreserving verbatim). A shared-YAML restatement adds marginal drift-catching value at the cost of the architectural awkwardness above. A truly faithful cross-port gate would need a 2-corpus split (api-contract generated lane for TS/C#/Java + persistence-conformance roundtrip for Python/Kotlin) with per-port scenario scoping — disproportionate for "additional assurance."

Separately surfaced (verified)

The Kotlin generated Spring controller (KotlinSpringControllerGenerator) does direct inline Exposed writes (transaction { AuthorTable.insert {…} } / .update {…}) with no @autoSet awareness — so the shipped Kotlin generated controller does not stamp @autoSet (only the generated repository does). An adopter using the generated controller would not get stamping. This is a genuine Kotlin-port gap in #203's coverage, tracked separately.

Closing as won't-fix: per-port gates suffice; a single faithful cross-port gate is impractical given the layer divergence.

[dmealing]

Update — resolved after all (reversing the earlier "not planned" close).

I had closed this reasoning that @autoSet stamping lived in a different layer per port, so no single generated-lane gate could faithfully cover all five. On review (Fable), the better move was to remove that divergence: make the two ports whose generated API surface did not stamp (Kotlin controller, Python router) stamp above the persistence seam, per ADR-0045 — after which the faithful cross-port gate is achievable.

Shipped (all on main, full-matrix CI green):

• ADR-0045 — the generated API surface owns metamodel write semantics (no consumer seam between the guarantee and the wire). 46d8e546.
• Kotlin generated Spring controller stamps @autoSet inline (it did direct Exposed writes with zero @autoSet awareness — a real shipped-artifact gap). 46d8e546.
• Python generated FastAPI router stamps @autoSet above the repo seam (stamping had lived only in the ObjectManager runtime, below the seam). abf48d2a.
• The gate — api-contract-conformance now carries autoCreatedAt/autoUpdatedAt @autoSet fields + an autoset-patch scenario asserting fieldsNotEqual:[autoCreatedAt, autoUpdatedAt] after a PATCH (seed both to an old sentinel → PATCH bumps onUpdate, preserves onCreate → they diverge). Format- and timing-agnostic; catches both the no-bump and the lost-update failure modes. New fieldsEqual/fieldsNotEqual matchers in all five runners; all five reference servers stamp; all five ports pass both lanes (26 scenarios × 2). c5905b82.

Follow-up (documented, not blocking): TPH + @autoSet controller stamping in Kotlin and Python (not exercised by the corpus).

Closing as completed.