fix(spec): stop teaching the retired ETL layer as a live retry surface in flow.zod.ts (#6630, part 2) - #6753
Merged
Conversation
…e in flow.zod.ts (#6630, part 2) Part 2 of 2 for #6630, closing out the three `automation/flow.zod.ts` prose sites that part 1 (PR #6701) deferred while the file was inside #5593's in-flight surface. #6414 retired the whole L2 ETL layer, so `ETLPipeline.retry` is no longer one of the surfaces that carry the converged `RetryPolicySchema` contract. Three places in this file still said it was: - the `errorHandling` TSDoc enumerated it as a live sibling of `job.retryPolicy` and a `try_catch` node's `retry`; - "a key added to the policy lands on all four surfaces at once" — three; - "the flow surface has a reading the other three do not" — the other two. Text only. No schema key, bound, default, `.describe()` or `retiredKey()` guidance string changes, so nothing regenerates: all 10 of spec's generated artifacts stay green, including `check:docs` and `check:api-surface`. Wording matches part 1's landed choices — enumerations name only surviving surfaces, the retired mention becomes explicitly historical ("did the same until #6414 retired the L2 ETL layer"), counts corrected in place. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-project-manager
added
the
skip-changeset
Claude
This was referenced Aug 8, 2026
os-project-manager
marked this pull request as ready for review
August 8, 2026 17:27
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #6630
Part 2 of 2 — the closing half. Part 1 is PR #6701 (
shared/retry-policy.zod.ts+conversions/registry.ts), which deliberately carried noFixesline so the issue stayed open for this one; see the claim-amendment comment for the split and the part-2 claim for the re-anchored line numbers.automation/flow.zod.tswas inside #5593's in-flight surface when part 1 ran; #5593 has merged (PR #6595), so the file is released.What was wrong
#6414 retired the whole L2 ETL layer —
automation/etl.zod.ts, 9 defs / 27 exported names, with the export absence pinned inautomation/sync-retirement.test.ts.ETLPipeline.retrywas one of the four surfaces that carried the convergedRetryPolicySchemacontract. Three sentences inautomation/flow.zod.tsstill said it was one of four.What changed
Three prose sites, one file, text only. Re-verified on
origin/main@61282f906before editing — the audit's anchors (:665/:745/:752) had drifted; the real ones are below.:640errorHandlingTSDocjob.retryPolicy, atry_catchnode'sretryand an ETL pipeline'sretry":720:727The arithmetic is measured, not assumed:
retryPolicyShape()/RetryPolicySchemahave exactly three consumers onmain—system/job.zod.ts:141(job.retryPolicy),automation/control-flow.zod.ts:318(atry_catchnode'sretry) andautomation/flow.zod.ts:722(flow.errorHandling, the spread).system/worker.zod.ts'sTaskRetryPolicySchemais a separate declaration and was never part of this count.Wording matches part 1's landed choices, which was the point of splitting rather than forking: enumerations name only surviving surfaces, the retired mention becomes explicitly historical in part 1's own words ("did the same until #6414 retired the L2 ETL layer" — the exact sentence part 1 put on
RetryPolicySchema's TSDoc), counts corrected in place. Two files in one package correcting the same defect two different ways would have been its own small drift.Zero acceptance-surface bytes. No schema key, bound, default,
.describe()orretiredKey()guidance string is touched.check:authorable-surfaceis green with no baseline edit.Out of scope, untouched: everything else in
flow.zod.ts; both files part 1 already fixed;content/docs/releases/.Mechanism assumptions — both verified, both held
The dispatch flagged two predictions and asked for them to be falsified if wrong. This time neither was.
1. Zero regen (predicted; held — unlike part 1). Part 1 falsified the same prediction because a
retiredKey().describe()reached two reference pages. Nothing here is a render input::640is a TSDoc block and:720/:727are//comments. Measured rather than argued —check:api-surfacereads the built dist, sopackages/specwas built first — before that it fails as "stale" in any fresh worktree, which is a phantom, not a finding. The.d.tscarries none of the changed text (only the bundled.jsdoes, as a preserved comment), which is why the API surface is byte-identical.2. A pin asserting the four-surface arithmetic or the ETL mention (predicted possible; none exists). Swept, including the file the dispatch named specifically.
automation/flow.test.ts:1578matches the prescription —'was removed in @objectstack/spec 17.0.0','backoffMs','flow.errorHandling'— never the enumeration or the count, exactly as part 1 measured for the rest of this family.automation/sync-retirement.test.ts:152asserts export absence ofETLand is unaffected. Nothing needed flipping.Why this PR adds no pin
Asked explicitly by the dispatch, so answering explicitly.
Nothing in this diff is runtime-observable.
flow.errorHandlingemits the tombstone by spreadingretryPolicyShape(), so the only string a test can reach throughFlowSchemais the very string part 1 already pinned in both directions inshared/retry-policy.test.ts(every live surface named / no retired surface named / prescription intact). A second assertion on that same string reached viaFlowSchemawould pin the spread, not the enumeration — andflow.test.ts:1578already pins the spread.The remaining two sites are
//comments. Pinning those means asserting source text. That idiom does exist in this package (shared/expression-dialect-docs.pin.test.ts,ui/notification.test.ts), so this is a choice and not an impossibility — but a general "a retirement updated some mentions and not others" detector is precisely the gate idea the PM split out as #6635 and asked not to be re-bundled. A one-offreadFileSyncregex overflow.zod.tswould stake out that design in the wrong place.Honest consequence, stated rather than dressed up: reverse verification has no red direction here. Restoring the old sentences turns nothing red, because no assertion reads comment text — which is not a gap this PR left, it is the measurement that motivates #6635.
Changeset: none — the
skip-changesetrouteDeliberate, decided from what the diff contains. Part 1 carried
@objectstack/spec: patchand justified it precisely: "the tombstone guidance is author-visible, so it is a release-noted change rather than a docs-only one." That justification does not transfer. Every byte here is a comment: it reaches no reference page (check:docsgreen), no.d.tsand no published type surface (check:api-surfacegreen), no error message and no parse. There is nothing for a release note to tell a consumer.Per the dispatch, the label is the PM's to apply at acceptance; this PR does not apply it.
Verification
pnpm --filter @objectstack/spec test— 345 files / 8844 tests passed (8844 is main's count; part 1 adds the 8845th)pnpm --filter @objectstack/spec typecheck— green:tsc --noEmit,check:scripts-typecheck,check:test-typecheck(58 files / 267 errors held, ledger unchanged)pnpm --filter @objectstack/spec check:generated— 10/10 artifacts up to date, nothing regenerated, nothing committed.github/workflows/lint.yml— 33/33 pass, includingpnpm lint,check:nul-bytes,check:doc-authoring,check:docs-audit-scope,check:release-notes,check:engine-double-contract,check:route-envelope,check:error-code-casing,check:spec-parsed-aliasnode scripts/check-nul-bytes.mjsOK over 6258 tracked files, plus a directgrep -naPcontrol-byte scan of the changed file — no hitsFiled, not fixed
Filed as #6750:
content/docs/automation/flows.mdx:977is a hand-written guide page (not generated —content/docs/references/**is the generated tree) that inherited the same sentence and still teaches an ETL pipeline'sretryas a live surface, pluscontent/docs/data-modeling/formulas.mdx:52, which names both retired layers (ETL,sync) ascronconsumers. #6630 explicitly scopescontent/docs/**out as the docs seat's surface, so both are filed rather than slipped in here. A third hit,content/docs/protocol/knowledge.mdx:49, is the generic industry term and is not a defect.Generated by Claude Code