Skip to content

Commit a335f1d

Browse files
devx(sdui): one manifest record per ui registry package, so ui PRs on different packages stop conflicting (#26120)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} --> _Requested by **Elon** · [project thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9DPXV532seCFDcrkAJybGzsf)_ Fixes #26051 Clause-②: no Metadata-protocol: none Part of the p1 merge-queue backlog work (#26074). Dispatched by seat `domain:devx#1` (#6023), claim 6415558140, card-thread session `session_01SMJGPXxFBpbgAgXdnsXKVS`. ## What changes `scripts/sdui-manifest.record.json` carried ONE `inTree.registrySourcesSha256` over the `src/` of all 27 ui registry packages, so any two ui PRs that touched any registry package conflicted on that line. Now: - **One record per registry package**, one file each, one line each: `scripts/sdui-manifest.sources/PACKAGE.json` = `{"package","sources","sha256","manifestSha256"}` (the package's own `src/` digest, its file count, and the sha256 of the artefact it was verified against). 27 files. - **The shared record** (`scripts/sdui-manifest.record.json`, same path) keeps only what describes the artefact: `sha256`, `components`, `generatedAt`, and `inTree` = `modulesRoot`, `objectuiWorkspaceVersion`, `registryRecords` (the directory). The retired `registryPackages` / `registrySources` / `registrySourcesSha256` are refused if they reappear. - **The reached package set** is the set of record files: a reached package with no record (new package, new dependency edge into the registry, deleted record) is RED; a record the registry no longer reaches (removed package, dropped edge) is RED. - `sdui.manifest.json` is byte-identical (sha256 `1f6e1ccb925a…`, 106 components). `lint.yml`'s command line (`node scripts/check-sdui-manifest.mjs --self-test && node scripts/check-sdui-manifest.mjs`) is unchanged and keeps working. No `.github/**` or `ui/.github/**` edit. ## Measured first (Ask 1): own `src/` per package, not dependency-inclusive Tree: objectstack `0a6948210c` (base), 27 reached packages, 922 non-test sources. **Detection is the same as one digest over the set.** Any edit under any reached package's `src/` moves exactly that package's digest, so a single PR's edit is caught exactly as before; a dependency's edit is caught through the dependency's own record. Dependency-inclusive digests add no single-PR detection. They would only add conflicts, and at this cost (records a `src/` edit would touch): | package edited | own `src/` (this PR) | dependency-inclusive | |:--|:-:|:-:| | `types` | 1 | 25 | | `core` | 1 | 21 | | `data-objectstack`, `i18n` | 1 | 19 | | `react`, `react-runtime`, `sdui-parser` | 1 | 18 | | `components` | 1 | 17 | | `fields` | 1 | 14 | | `plugin-detail` | 1 | 10 | | `plugin-form`, `plugin-grid` | 1 | 2 | | the other 11 plugins | 1 | 1 | **Merge experiment, real tree, `git merge-tree --write-tree` (no merge driver routes these paths; `git check-attr merge` = unspecified, so this is GitHub's answer):** each branch appends a comment to one `src/` file and runs the generator. | pair | before (single digest, on `0a6948210c`) | after (this PR, on `a8114011`) | |:--|:--|:--| | `plugin-grid/src/FormulaBar.tsx` × `plugin-form/src/DrawerForm.tsx` | exit 1, CONFLICT in `scripts/sdui-manifest.record.json` | exit 0, clean; the merged tree passes `check-sdui-manifest` (exit 0) | | `plugin-grid/src/FormulaBar.tsx` × `plugin-grid/src/ObjectGrid.tsx` | (conflicts) | exit 1, CONFLICT in `scripts/sdui-manifest.sources/plugin-grid.json` only, by design | **The open ui PRs today** (registry packages each changes, non-test `src/` only; none changes `sdui.manifest.json`): #25987 i18n, plugin-grid, plugin-list · #25998 plugin-detail · #26040 components, i18n · #26045 i18n · #26027 plugin-dashboard · #26030 plugin-grid · #26033 core, plugin-form, plugin-grid · #26042 plugin-form · #26044 i18n · #26048 i18n, plugin-map · #26050 fields, plugin-grid · #26062 fields. Under the single digest all 12 conflict pairwise (12 serial landings). Under this layout they conflict only within a shared package; the largest group is `i18n` (5 PRs), so they can land in 5 rounds, e.g. {#25987, #25998, #26027, #26042, #26062} → {#26040, #26030} → {#26045, #26033} → {#26044, #26050} → {#26048}, assuming no source-level conflicts between them. ## The check (Ask 2) `checkTreeWithoutPin` compares each reached package's digest with its own record and names every stale package (`ui/packages/plugin-grid: now 38 file(s) sha256 …, recorded …`), every unrecorded package, every record the registry no longer reaches, every record verified against another artefact, and every malformed record, then prints the one command: `node scripts/gen-sdui-manifest-node.mjs`. The pin mode (`.objectui-sha` present) is untouched. **Why `manifestSha256` is in every package record, and why one line:** a PR that changes the artefact re-records every package against the new sha256, so it still conflicts with every in-flight registry PR, which must regenerate on the merged tree (that is today's behaviour, kept for the case where it matters). Two PRs on the same package touch the same line and conflict. One line per file guarantees git cannot merge a digest from one side with an artefact sha256 from the other; a record that is not in the producer's one-line form is RED. **What this does not force, stated rather than implied:** two PRs on different packages that each leave the artefact unchanged, where only their combination would change it, land without any run seeing the combination. Under the single digest their textual conflict forced that run. Here the next regeneration of any registry package sees the combination. Dependency-inclusive digests would close this only along import edges (not between siblings that interact through `ComponentRegistry`), at the fan-out above. No stale or missing registry source passes: every source edit still reds until regenerated, and every package added to or removed from the reached set still reds. ## Self-test (Ask 3) 29 rows (was 22), roster and floor updated. New or changed in-tree rows: a staged edit to one package is RED naming that package and NOT naming `plugin-form` or `core`; a new package the registry reaches; a new workspace edge (now names `ui/packages/unrelated`); a removed package (names `scripts/sdui-manifest.sources/types.json`); a deleted package record; a record verified against another artefact; a record out of its one-line form; a record from the single-digest layout; and the producer re-recording only the moved package (it back-dates the shared record first, so a producer that stamps today's date reds the row). Ablations, one at a time through `scripts/ablation-replace.mjs`, each restored with `git diff HEAD` empty: | guard removed | self-test | |:--|:--| | the other-artefact comparison (gate) | exit 1, row "a package record verified against another artefact is RED" expected RED got GREEN | | the one-line form comparison (gate) | exit 1, row "a package record out of its one-line form is RED" | | the unreached-record list (gate) | exit 1, row "a removed registry package is RED naming its record" | | the `generatedAt` carry (producer) | exit 1, row "the producer re-records only the package whose sources moved": the second run changed the shared record too | | the per-package record write (producer) | exit 1, the two producer rows | ## The generator (Ask 4) It re-records only the packages whose line changed and leaves the others byte-identical; it removes a record the registry no longer reaches; it prints which packages it re-recorded. The shared record moves only with the artefact: `generatedAt` and the provenance version are carried while the artefact's sha256 is unchanged (the same rule the pin-keyed fields already follow), so a regeneration on another day no longer moves a shared line. **It still builds, and why:** the build plus the enumeration is the only oracle that says whether `sdui.manifest.json` moved. A record written without it would stamp a current digest on a manifest no run checked, which is the narrowing this card forbids. The 8 minutes is a cold turbo cache, not the build of one package. Measured on `0a6948210c`, one container, no remote cache (`TURBO_TOKEN` unset): | run | wall | turbo | |:--|:-:|:--| | cold | 8m49s | 0 of 63 cached, 8m43s | | nothing moved | 6s | 63 of 63 cached | | one edit under `plugin-grid/src` | 33s | 61 of 63 cached, 27s | | one edit under `core/src` | 2m50s | 41 of 63 cached, 2m44s | ## Readers moved (Ask 5) - `docs/releases-maintenance.md`: the regenerate section describes the per-package records, the re-record rule and which PRs still conflict. - `scripts/check-changeset-no-major.mjs`: the "measured out" comment, the real-build assertion (neither record is shipped) and the records-only control now cover `scripts/sdui-manifest.sources/`. Its `--self-test` passes (456 assertions). - `scripts/ui-import/README.md` is not edited: line 140 records what the cutover's step 4 wrote at the time, and that file still exists at that path. - `git grep -n "sdui-manifest.record"` outside CHANGELOGs: only the two scripts, the docs page, `check-changeset-no-major.mjs` and that historical README line. `git grep registrySourcesSha256`: only the retired-field list and its self-test row. ## After this lands: what an in-flight ui PR does (once) A ui PR whose branch re-recorded the old single digest conflicts once on `scripts/sdui-manifest.record.json`: ```sh git merge origin/main # conflict in scripts/sdui-manifest.record.json git checkout --theirs scripts/sdui-manifest.record.json # take main's layout node scripts/gen-sdui-manifest-node.mjs # re-records only this PR's package(s) git add scripts/sdui-manifest.record.json scripts/sdui-manifest.sources sdui.manifest.json git commit ``` After that, PRs on different registry packages no longer conflict with each other on the record. ## Gates Local, on `a8114011` (derived with `node scripts/pm/dispatch-gates.mjs --commands`): 39 of the 40 derived families exit 0, including `node scripts/check-sdui-manifest.mjs --self-test` (29 cases) and `node scripts/check-sdui-manifest.mjs`, `node scripts/check-changeset-no-major.mjs --self-test` and `--base origin/main`, `pnpm check:nul-bytes`, `pnpm check:watch-hint-literal`, `pnpm check:required-contexts`, `pnpm check:doc-authoring` and `pnpm --filter @objectstack/lint run check:doc-formula-expressions` (after the lint closure build). `pnpm check:pm-dispatch-gates` was still running when this PR opened; its reading goes into the report comment on #26051, and CI runs it in Lint & Repo Gates. CI on the PR's check-runs: pending at the time of writing; the seat reads them. Changeset: none, `skip-changeset`. The diff touches only root `scripts/` (private), `docs/` and the records; `sdui.manifest.json` is byte-identical and neither record is copied into `packages/console/dist/` (the `check-changeset-no-major` real-build assertion above). Not Tier H: no governed path (`git diff --name-only` has no `.github/`, `.claude/`, `docs/adr/`, `skills/`, `AGENTS.md`, `CLAUDE.md`). ## Acceptance notes - `i18n` is the hot package: 5 of the 12 open ui PRs touch its `src/`, so they still serialize on `scripts/sdui-manifest.sources/i18n.json`. Whether locale data belongs in the digest at all is a narrowing question (it would let a source change pass unregenerated), not something this PR decides. - The cold-cache cost of a regeneration (8m43s here) is a fresh-container property; card threads run with no turbo remote cache. --- _Generated by [Claude Code](https://claude.ai/code/session_01SMJGPXxFBpbgAgXdnsXKVS)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent b36f1b4 commit a335f1d

32 files changed

Lines changed: 511 additions & 173 deletions

‎docs/releases-maintenance.md‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,12 @@ ships the Console from the same commit as the spec it builds against.
5555
> root `.changeset/` before the first joint Version PR is #25831. New frontend
5656
> changesets go in the root `.changeset/`.
5757
58-
#### After a registry change: regenerate the committed manifest (#12924, #17735, #25712)
58+
#### After a registry change: regenerate the committed manifest (#12924, #17735, #25712, #26051)
5959

6060
The repo-root `sdui.manifest.json` (ADR-0080, the Console's public-tier component
61-
manifest) and its provenance record `scripts/sdui-manifest.record.json` are
62-
generated, and one command writes them:
61+
manifest), its provenance record `scripts/sdui-manifest.record.json` and one record
62+
per registry package under `scripts/sdui-manifest.sources/` are generated, and one
63+
command writes them:
6364

6465
```bash
6566
node scripts/gen-sdui-manifest-node.mjs # no arguments
@@ -68,14 +69,20 @@ node scripts/gen-sdui-manifest-node.mjs # no arguments
6869
It builds the registry packages under `ui/packages/`, enumerates them from
6970
`ui/apps/console` under plain Node, and serializes them through
7071
`@objectstack/sdui-parser` (it needs `packages/sdui-parser/dist`:
71-
`pnpm --filter @objectstack/sdui-parser build`). The record carries an `inTree`
72-
block with a digest of the registry packages' `src/`.
72+
`pnpm --filter @objectstack/sdui-parser build`). Each package record is one line:
73+
a digest of that package's own `src/` and the `sha256` of the artefact it was
74+
verified against. A run rewrites only the records whose line changed, so a PR that
75+
edits one registry package re-records that package alone; the shared record moves
76+
only when the artefact does, and then every package record names the new `sha256`.
7377

74-
A required lint step reads the tracked pair on **every PR**:
78+
A required lint step reads the tracked files on **every PR**:
7579
`node scripts/check-sdui-manifest.mjs` checks the shape, the `sha256` against the
76-
record, and recomputes the source digest from the index. A PR that edits a registry
77-
package's source without regenerating goes red there, and the failure text prints
78-
the regeneration call. ⛔ There is no npm install route to the manifest; that was
80+
record, and recomputes each package's source digest from the index. A PR that edits
81+
a registry package's source without regenerating goes red there, naming the package,
82+
and the failure text prints the regeneration call. Two PRs that edit different
83+
registry packages touch different record files and do not conflict; two that edit
84+
the same package, or a PR that changes the artefact, still conflict once, and the
85+
later one merges `main` and re-runs the command. ⛔ There is no npm install route to the manifest; that was
7986
deleted by ruling 丙 on #17735.
8087

8188
**One producer, one artefact.** `packages/console/build-dist.sh` copies the tracked

‎scripts/check-changeset-no-major.mjs‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1365,9 +1365,10 @@ export function publishedSourceOwners(path, manifestOf) {
13651365
// packed output — one path — and never which files it copies: the day the
13661366
// console build ships a second tracked file, this leg sees it with no edit
13671367
// here, and the day it stops copying the manifest, the leg stops claiming it.
1368-
// `scripts/sdui-manifest.record.json` is measured OUT for that reason rather
1369-
// than by choice: the build reads it for a warning line and does not copy it,
1370-
// so it is not part of the shipped artefact.
1368+
// `scripts/sdui-manifest.record.json` and the per-package records under
1369+
// `scripts/sdui-manifest.sources/` are measured OUT for that reason rather than
1370+
// by choice: the build does not copy them, so they are not part of the shipped
1371+
// artefact.
13711372
//
13721373
// ⚠️ Residual, stated rather than implied: the reader understands the plain
13731374
// shell the script is written in — `NAME="value"` assignments, `$NAME` /
@@ -4875,8 +4876,8 @@ function selfTest() {
48754876
`this repository's ${PACKED_COPY_BUILD_SCRIPTS[0]} copies the repo-root sdui.manifest.json into packages/console/dist/ as read by this leg — got ${JSON.stringify(realPairs)}`,
48764877
);
48774878
assert(
4878-
!realPairs.some((p) => p.source === 'scripts/sdui-manifest.record.json'),
4879-
`measured, not chosen: the real build does not ship the manifest record — got ${JSON.stringify(realPairs)}`,
4879+
!realPairs.some((p) => p.source === 'scripts/sdui-manifest.record.json' || p.source.startsWith('scripts/sdui-manifest.sources/')),
4880+
`measured, not chosen: the real build ships neither the manifest record nor a package record — got ${JSON.stringify(realPairs)}`,
48804881
);
48814882

48824883
// ── The owner of a destination ────────────────────────────────────────
@@ -4956,14 +4957,21 @@ function selfTest() {
49564957
const no = levelOf(copyRepo({ head: { ...PR22812, '.changeset/console-bbbb.md': changeset([[CONSOLE, 'patch']]) } }), declaredNo);
49574958
assert(no.result.verdict === 'none-clean' && no.exitCode === 0, `the manifest moved under \`Clause-②: no\` + \`none\` is unaffected — got ${no.result.verdict} / ${no.exitCode}`);
49584959

4959-
// The record moves with every regeneration but ships nothing.
4960+
// The records move with regeneration but ship nothing: the shared one, and
4961+
// the one-line record of the registry package a ui PR re-recorded.
49604962
const recordOnly = levelOf(
4961-
copyRepo({ head: { 'scripts/sdui-manifest.record.json': '{"objectuiSha":"bbbb"}\n', '.changeset/console-bbbb.md': changeset([[CONSOLE, 'patch']]) } }),
4963+
copyRepo({
4964+
head: {
4965+
'scripts/sdui-manifest.record.json': '{"objectuiSha":"bbbb"}\n',
4966+
'scripts/sdui-manifest.sources/plugin-grid.json': '{"package":"ui/packages/plugin-grid"}\n',
4967+
'.changeset/console-bbbb.md': changeset([[CONSOLE, 'patch']]),
4968+
},
4969+
}),
49624970
yesWidening,
49634971
);
49644972
assert(
49654973
recordOnly.touched.packages.length === 0 && recordOnly.touched.unreadable.length === 0 && recordOnly.result.verdict === 'clean',
4966-
`control: the record alone moves no published file — got ${JSON.stringify(recordOnly.touched)} / ${recordOnly.result.verdict}`,
4974+
`control: the records alone move no published file — got ${JSON.stringify(recordOnly.touched)} / ${recordOnly.result.verdict}`,
49674975
);
49684976

49694977
// #4690 on this leg: a build script that is THERE but yields no copy is

0 commit comments

Comments
 (0)