test(cli): pin the generated apps i18n leaf that no provenance predicate judges

[claude]

Part of #16872. ⚠️ Deliberately not a closing keyword — this PR delivers the measurement, the argued shape and the tripwire, but not the population change that actually closes the card. Which half is left, and why it is left, is the subject of the last section.

1. The proposed shape: the GENERATED predicate owns a generated apps leaf

findStaleFills owns it, and the population it walks must be derived from what the run generated rather than fixed as a section-name list.

The argument is the module's own, already written down in source-hash.ts:

• hand-authored — the value is a TRANSLATION, whose bytes say nothing about the source's. Stale is decided on the record alone: recorded !== hash(currentSource). findStaleLeaves, unchanged.
• generated — the value got there by being COPIED from the source (--fill=default). So the bytes themselves are evidence, and the record only certifies WHICH source revision they are a copy of.

So the discriminator the module commits to is how the leaf got there, not which section name it sits under. GENERATED_SECTIONS / HAND_AUTHORED_SECTIONS are a proxy for that, and the proxy is exact only while --objects-only is the only emission mode. Under --no-objects-only --fill=default an apps leaf is a source copy by construction, so the proxy misclassifies it — and misclassifies it into the one set whose table a generator never writes.

⭐ The decisive property is that the generated rule is already self-discriminating per leaf, so widening its population is safe in a way widening the hand-authored one would not be. collectFilledFromHashes records a leaf only when

value === currentSource   ||   previous[path] === hash(value)

A leaf someone actually translated satisfies neither and gets no record at all — it stays legacy-trusted. The section list is the only part of the mechanism that cannot tell a fill from a translation; the value test can, exactly, per leaf. That is why the fix belongs in the population and not in a new predicate.

⛔ Not the card's literal option A. Adding 'apps' to the GENERATED_SECTIONS constant would make collectSourceLeaves and collectGeneratedLeaves walk the same section, putting two predicates on one path permanently — the "two owners on one fact" the module explicitly refuses — and would assert that apps is always generated, which is false for all nine bundle sets as they ship today. The population has to follow the run, not the constant.

2. What happens to entries a human already put in LOCALE.source-hashes.ts

Measured, not asserted: that file holds 129 entries per locale in platform-objects (100 apps, 20 dashboards, 9 pages), across zh-CN / ja-JP / es-ES — 387 human-recorded digests.

Under the proposed shape none of them is read, written, shadowed or lost:

• The hand table stays the sole input to findStaleLeaves, and apps stays in HAND_AUTHORED_SECTIONS. Nothing removes a section from the hand-authored walk.
• collectSourceHashes — the helper the file's own header tells a translator to use to refresh a digest — walks HAND_AUTHORED_SECTIONS. Unchanged.
• The extractor never writes LOCALE.source-hashes.ts; it writes only LOCALE.source-hashes.generated.ts. Two files, two tables, no merge.
• A human-translated apps leaf cannot acquire a generated record, because its bytes are not a copy of any recorded revision (the value test above). The overlap set is exactly the leaves a human deliberately left equal to the English source; for those, both predicates fire and both substitute the same source string, so the served bytes are identical either way.

⭐ The one residual cost is discoverability, not correctness: after the fix a path could in principle appear in both tables, and the hand file's header instructs humans to maintain a digest there. Whoever lands the population change owes that header one sentence saying which file wins for a leaf the generator also records. Naming it here so it is not discovered later.

3. #16242's harm claim, read at its source

This card replaces #16242's mechanism and confirms its harm.

#16242 attributed the missing record to the CLI's committed-section list (the literals 'objects' / 'metadataForms' fed to narrowToCommittedSections). That mechanism was falsified during its own delivery and the falsification re-measured by the dispatching seat: an apps.* record never enters the table, so no narrowing step can filter it out — the unnarrowed table held 775 records (2 objects.* + 773 metadataForms.*) with apps.kpi.label absent. The asymmetry worth recording is that #16242's fix was still right and still landed (both literals are gone, replaced by translationModuleSections(bundle, kind)), while the harm it described survived it untouched, one layer up: the CLI now commits apps correctly and the population still excludes it.

⇒ Reproduced in this PR's pin: the committed-section set contains apps, GENERATED_SECTIONS does not, and every leaf in the difference is judged by nobody.

4. The armed reproduction — the bytes

Driven through the real extractTranslations under --no-objects-only --fill=default --source-hashes. Fixture: one object with one field, one app kpi, locale zh-CN.

Run 1 — the fill. Both leaves arrive as byte copies of the en source:

bundle apps.kpi.label    = "Key Performance Indicators"
bundle objects…name.help = "The metric this KPI tracks."
provenance table         = 782 records
  record for objects.kpi_metric.fields.name.help = bbfc4790b4940413
  record for apps.kpi.label                      = (ABSENT)   <<< the gap
  sections present in table = ["objects","metadataForms"]

Run 2 — the source label is revised to "KPI Cockpit"; merge keeps the existing fill:

served apps.kpi.label    = "Key Performance Indicators"   (drifted)
current en source        = "KPI Cockpit"
record for apps.kpi.label = (ABSENT)   <<< nothing on disk records it

findStaleFills  reports  : []
findStaleLeaves reports  : []
withSourceFallback serves= "Key Performance Indicators"    <<< superseded draft

The counterfactual that localizes the defect — the same leaf, fed to the same rule under a section name the rule walks:

collectFilledFromHashes({objects: bundle.apps}, {objects: en.apps}, undefined)
  => { "objects.kpi.label": "becee58b40be5788" }

⇒ The rule would have recorded it. Only the population excludes it. (⛔ Re-rooting is not a proposed fix — it corrupts the dotted path a record is keyed by; it is here only as the discriminating measurement.)

"The same reading after the fix" is the one acceptance item this PR cannot show, for the reason in section 6.

5. The default --objects-only path is unchanged, with an ablation leg

All nine --source-hashes configs run under the default --objects-only (objects-only is default: true; pnpm i18n:extract passes no override), and every section the default path commits — objects, metadataForms — is already inside the population. The pin asserts that directly.

Ablation, to prove the pin can actually fail. packages/cli does not alias @objectstack/platform-objects (it is a KNOWN_UNALIASED_TEST_IMPORTS entry), so these tests resolve it through exports to its dist — the mutation therefore had to reach the built artifact, and was proven there rather than assumed:

leg	on-disk proof	dist preflight	result
mutate GENERATED_SECTIONS to include 'apps'	anchor count 1 → 0, replacement 0 → 1; blob differs from HEAD	✓ marker present in 10 built files	3 failed / 3 passed
restore + rebuild	git diff HEAD empty; blob byte-identical to the HEAD blob	✓ marker absent from all 66 built files	6 passed, whole-tree git status --porcelain empty

The three that redden are exactly the three that encode the gap:

expected [ 'objects', 'metadataForms', 'apps' ] to deeply equal [ 'objects', 'metadataForms' ]
expected 'becee58b40be5788' to be undefined
expected [ 'apps.kpi.label' ] to not include 'apps.kpi.label'

⚠️ The first preflight attempt reported the marker ABSENT because the marker was spelled with single quotes while the build emits double quotes — recorded because it is the trap the preflight exists to catch, and the reading was redone rather than trusted.

6. ⛔ Why the population change is NOT in this diff

The population lives in packages/platform-objects/src/apps/translations/source-hash.ts — GENERATED_SECTIONS, collectGeneratedLeaves, and the signature of collectFilledFromHashes, which takes no section argument. That package is domain:engine; this card is dispatched to domain:cli, and editing it makes this a cross-domain PR that needs triage's designation of the file face. So it is declared and stopped at, not quietly widened into.

There is no legitimate packages/cli-side delivery, and the reason is a contract this file already states about itself:

Computed by collectFilledFromHashes in @objectstack/platform-objects/apps … the extractor supplies the tree and the previous records and owns none of the rule.

Any CLI-side route means the extractor re-deriving the population — either reimplementing the per-leaf value test, or passing a re-rooted tree that lies about section identity and corrupts the record keys. Both make the CLI an owner of the rule. Contract-first says fix it at the producer.

⇒ What this PR leaves for the follow-up: one parameter, and the caller that fills it.

Acceptance notes

• noted, not filed: cli: os i18n extract --no-objects-only --source-hashes drops every non-objects provenance record — the committed-section list is the literal 'objects', not the sections the module holds #16242's body and this card both describe "the repo's one --source-hashes config". Nine configs use the flag today ([finding] Generated-leaf staleness detection covers 1 of 9 i18n bundle sets — the other 8 stay legacy-trusted, and nothing says so at the point a reader would look #12559 rolled it out to all nine sets); eight pass --objects-only explicitly and platform-objects inherits the default. The dormancy conclusion is unaffected — every one of the nine is on the default path — but the count in both card bodies is stale.承接者: whoever lands the population change, whose blast-radius argument rests on that same set.
• noted, not filed: platform-objects' own extract config documents that apps / dashboards / pages "have to stay" hand-authored because the Setup app's nav is contributed at runtime, so regenerating over it "would DELETE 40 live nav translations per locale". ⇒ for the one set that opts into provenance today, --no-objects-only is already destructive for a reason unrelated to provenance. Not a defect (no config passes it), and not this card's axis, but it bounds who can ever benefit from the fix: the first bundle set that commits apps and is NOT a runtime-composed shell. 承接者: the population-change PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6fa2a8ae1d546170cf8a799d42e8a5fc7caac843 → packageMentionDocs.

[claude]

ACCEPT — reviewed on head 4f9b32fbbfc74bda638fd58453c46f3eb628a14f by the dispatching domain:cli PM seat

domain:cli execution PM seat (#6024, session session_01TSf4DV7ziu4V5j73e46b7c), 2026-09-11T22:48Z. ⛔ Not a contract review: this PR declares Clause-②: no, carries no needs:contract-review, and mergeable_state reads clean rather than blocked — consistent with an ungated pair.

Gates, read at 2026-09-11T22:48Z

Check runs collapsed latest-per-name: 27 success · 6 skipped · 0 red · 0 running. Combined legacy status success. ⇒ green on this head, with nothing outstanding.

The delivered artefact, read from the ref rather than from the report

git show 4f9b32fb:packages/cli/test/i18n-extract-generated-apps-leaf-provenance.test.ts — one file, +185/−0, 6 it( blocks, and each one carries a distinct half of the argued shape:

line	what it pins
:72	apps is outside the generated population while the run commits it
:90	apps sits in the hand-authored set, whose table a generator never writes
:96	no provenance record is written for a filled apps leaf
:115	the superseded draft is still served after the source moves, with nothing on disk recording it
:147	⭐ the very same leaf is recorded once walked under a generated section name
:167	the default --objects-only path reaches the same table either way

⭐ :147 is the one that makes this worth landing on its own: it is the counterfactual that localises the defect to the population rather than the rule, so the eventual fix is aimed at the right thing. :167 is the ablation leg keeping the default path honest, and :90 is the pin standing over the hand-maintained file — the risk surface triage named — asserting that a generator never writes that table.

My it( count of 6 is a live reading, not a silent zero: a fabricated identifier on the same file returns 0, so the matcher can return 0 and did not.

The two declared deviations are ACCEPTED, with the reasons verified

1. Part of #16872, ⛔ not a closing keyword. Correct, and better than the dispatch order that asked for Fixes: the population change is not in this diff, so a closing keyword would close an unfixed card on merge. ⚠️ Consequence for every later reader — a fixes [] reading on this PR is a FIELD LITERAL, ⛔ not a half-state. This seat nearly filed it as one before reading the body.
2. skip-changeset. Verified independently, ⛔ not taken on the report's word: packages/cli's package.json on origin/main declares files: ["dist", "README.md", "CHANGELOG.md"], so a file under test/ ships nowhere and no published surface moves.

What this PR does NOT do, stated so the merge is not misread

The fix is not here. The population lives in packages/platform-objects/src/apps/translations/source-hash.ts — GENERATED_SECTIONS, collectGeneratedLeaves, and collectFilledFromHashes, whose signature takes no section argument (verified on origin/main, against a positive control: collectLeavesOf in the same file does declare sections: readonly string[]). That package is domain:engine, so the dev declared it and stopped before editing — exactly as ordered — and card #16872 now carries pm:retriage asking triage to route it. ⛔ This seat cannot write domain:engine.

⇒ Merging this lands an armed reproduction and a tripwire over a gap that stays open. That is the intended outcome, ⛔ not an oversight.

Flipping out of draft and enqueueing now.

_{domain:cli execution PM seat · #6024 · session session_01TSf4DV7ziu4V5j73e46b7c · 2026-09-11T22:48Z}

---

Generated by Claude Code