fix(metadata-protocol): a flow save that skipped canonicalization says so (#4580)

[os-zhuang]

Fixes #4580. Follow-up to #4542 / #4548.

What

saveMetaItem canonicalizes flow bodies before the schema gate (#4548). Four postures live at that seam — three announce themselves, one said nothing:

posture	signal before	signal now
clean canonicalization	row healed, --stored reports canonical	unchanged
refused rename	409 FLOW_CONVERSION_CONFLICT naming token + path	unchanged
canonicalizer throws → raw save	none	console.warn, deduped per flow
no automation service	os migrate meta --stored reports it	unchanged

The fallback itself is correct and is unchanged by this PR: canonicalizeStoredFlow is stricter than the gate (strict parse, cycle detection, control-flow regions), so a WIP draft with a temporary cycle must stay saveable — in publish mode as well as draft. What was wrong is that it was invisible.

Why it mattered

A save that skipped canonicalization was indistinguishable from one that healed the row. A body that is both a legacy dialect and unparseable by the strict canonicalizer re-persisted verbatim — the exact #4542 symptom, arriving silently, while the boot warning for legacy stored rows tells the author that re-saving is the remedy. The author found out only by running os migrate meta --stored and seeing the row failed.

It was also the one quiet link in a chain that is otherwise loud by design (ADR-0087 D2): conversions emit notices, convertStoredItem warns once per row on read, migrateStoredMetadata reports failed with the message.

What changed

One catch block in packages/metadata-protocol/src/protocol.ts now warns with the flow name and the canonicalizer's own error, plus a flowCanonicalizeFallbackWarned dedupe set alongside the existing storedConversionWarned — Studio autosaves the same draft repeatedly and a WIP cycle throws on every write, so an undeduped warning would be a spam loop.

No behavior change: the body still saves, the schema gate stays the arbiter, registerFlow still refuses to arm a malformed flow.

Decision carried forward from #4548

Refusing the save in publish mode was reconsidered here and rejected again, for a reason worth recording:

• publish is the default mode, so refusing would silently tighten validation for every existing caller — a breaking change for bodies that save fine today.
• It can only be enforced where an automation service exists. On a control-plane / metadata-only host resolveFlowCanonicalizer() returns undefined and there is no strict parse to run — so the same body would save on one host and 422 on another. That is unlike the 409, which reflects genuine environment state (a token owned by a live executor); a 422 should depend on the body alone.

Observability was the actual gap, and this closes it.

Tests

5 new cases in protocol.save-flow-canonicalization.test.ts (16 total in the file):

• throw-fallback warns, naming the flow, the canonicalizer's reason, and the --stored remedy
• deduped across three repeat saves of the same flow
• the clean path stays silent
• the conflict path stays silent (the 409 is the signal)
• a host with no automation service stays silent (nothing was skipped)

Assertions filter warnings by message rather than counting all console.warn calls, so unrelated one-shot protocol warnings (e.g. #3770's) can't make them order-dependent.

Full metadata-protocol suite green (206 tests, was 201). Typecheck and eslint clean on both changed files.

Riders

Changeset (.changeset/save-flow-canonicalization-fallback-warning.md). No content/docs/releases/ changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NDmJ5ASMSzcw1q17vh32MG

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 2, 2026 8:50am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol)
• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.