draft-publish-lifecycle: the metadata audit trail records only `save` — publish, rollback and the 409 conflict denial never write a row

[huangyiirene]

Symptom

Staging, publishing and rolling back a metadata item all answer 200, and the audit trail records only one of the three.

• After 3 publishes and 2 rollbacks (all 200, all sent with X-Actor), GET /api/v1/meta/<type>/<name>/audit returns Counter({'save': 5}) — no publish rows, no rollback rows.
• The 409 METADATA_CONFLICT denial is likewise absent.

Reproduced twice, on two actors. Everything else in the lifecycle passes: draft staging, the publish flip, OCC (409 with a passing control), package-wide publish-drafts atomicity, the #4463 draft→active gate, the Studio unpublished badge and Changes counter, /history carrying both publish events, and rollback flipping the served body. So the operations happen — they are simply not written down.

Root cause (source-confirmed)

packages/metadata-protocol/src/protocol.ts writes an allowed-outcome audit row at exactly two sites:

• line 10220 — operation: 'save', outcome: 'allowed' (in the save path, commented "ADR-0010 — success audit (best-effort)")
• line 12848 — operation: 'delete', outcome: 'allowed'

publishMetaItem and rollbackMetaItem reach recordMetadataAudit only through assertLockAllowsWrite() (called at lines 10783 and 12414). That helper records on the deny path and returns early on allow:

const refusal = evaluateLockForWrite(state.lock);
if (!refusal) return null;          // ← allowed: returns before any audit write
…
await this.recordMetadataAudit({ …, outcome: 'denied', … });

So a refused publish is audited and a successful one is not — the inverse of what an audit trail is for. The same asymmetry explains the missing 409: the conflict is refused outside the lock helper, and nothing on that route writes a row either.

Stale-premise check: re-verified on objectstack origin/main (00e9196). Both allowed-outcome sites and both assertLockAllowsWrite call sites are unchanged in substance; only line numbers moved from the run's build (save 9833 → 10220, delete 12429 → 12848).

Reproduction

1. Boot the showcase with writable runtime packages.
2. Stage a draft (PUT …?mode=draft), publish it, roll it back — repeat to 3 publishes and 2 rollbacks, sending X-Actor on every call. All answer 200.
3. GET /api/v1/meta/<type>/<name>/audit → only save rows (Counter({'save': 5})).
4. Force a 409 METADATA_CONFLICT (stale If-Match), then re-read the audit — the denial is absent too.

Scope

The actor stamped on the rows that are written is a second, independent defect with a different located file — filed separately as #7749 so it survives this fix.

Source

Extracted from the QA run #7695 (framework 92f26f7, console 09987b680).

[huangyiirene]

Deliberately deferred this round — behind #8136, not dropped. Recording the known traps now, at the moment of deferring, so whoever picks this up does not re-derive them.

Why deferred. This card edits the audit-write sites in packages/metadata-protocol/src/protocol.ts. #8136 was claimed this round and is a file-wide producer sweep of the same file (raw driver text out of client-facing messages). Its region and this card's region are adjacent in the error/refusal paths — assertLockAllowsWrite records on the deny path, which is exactly the kind of site #8136 is rewriting. Two agents restructuring the same catch/refusal paths concurrently is how a merge lands green and semantically wrong. This card is dispatched as soon as #8136 lands.

Stale-premise re-check, run against origin/main just now (this card's own check was against 00e9196 on 2026-08-11):

• recordMetadataAudit — still 5 occurrences in protocol.ts. Substance intact.
• The two allowed-outcome sites have moved again: the card says save 10220 / delete 12848; they are now at 10627 and 13618. That is the second drift on this card. ⇒ Re-locate by reading, never by line number.
• ⚠️ New signal worth checking before implementing: protocol.ts:9161 now carries a comment reading "…writes its ordinary outcome: 'allowed' row, so nothing…". That did not exist in the excerpt this card was filed from. Something in the audit path has been touched since. Read that comment and its surrounding branch first — it may mean part of this defect is already closed, or that a sibling changed the invariant this card assumes. A premise_still_valid: false outcome here would be a legitimate delivery, not a failure.

Scope reminder carried forward from the card: the actor stamped on the rows that are written is a separate defect with a different located file, filed as #7749. It stays out of this card.

---

Generated by Claude Code

[huangyiirene]

⚠️ A trap for whoever picks this up, relayed from the #8031 dev's handover (recovered over git; its container is 403-blocked on the API). Recording it here because it is precisely the reasoning that would close this card wrongly.

⛔ Do not conclude "publish is already recorded, so #7748 is stale"

packages/metadata-protocol/src/sys-metadata-repository.ts declares:

ExtendedOperation = 'create' | 'update' | 'publish' | 'revert' | 'delete'

documented as "'publish' is recorded when a draft is promoted, 'revert' when a historical version is restored".

That is the sys_metadata_history table — a different table from the audit trail this card describes. Someone reading that declaration will find the word publish next to the word "recorded" and conclude this card is already satisfied. It is not: they would be reading the history table's contract and drawing a conclusion about the audit table.

And a precise statement of what #8031's green run does NOT prove

The #8031 dev was told this card is held behind work in the same neighbourhood, and it declined to claim any coverage — correctly, and worth quoting:

My stub engine short-circuits sys_metadata_audit inserts (return { id: 'audit_skip' }). So my suite is silent on audit behaviour — it neither confirms nor refutes #7748. Do not read my green run as evidence either way.

⭐ That is the right shape of report: a green suite that touched the neighbourhood, with an explicit statement of what it did not measure. ⛔ Do not treat PR #8254's passing tests as coverage of this card's defect.

It changed nothing on this path, per its scope fence.

Status of the hold

This card was held behind #8136 (the protocol.ts error-path producer sweep), not behind #8031. That hold and its earlier stale-premise re-check still stand — see the note of 2026-08-12 18:0xZ, including the ⚠️ protocol.ts:9161 comment that postdates this card and may mean part of the defect is already closed. Read that first.

---

Generated by Claude Code