Repository navigation
Commit df1feae
Fixes #21106
Clause-②: yes
Three release-text follow-ups from the at-tier contract review of PR
#21084 (comment `5926057594`), all due before Version Packages #20639
next picks up PR #21084. Each sentence was checked against the code at
PR #21084's merge commit `8368f1c0`. The target files are byte-identical
between `8368f1c0` and this branch's base (`git diff --stat` printed
nothing). No package source changes.
1. **A deliberate correction of the stage-① pending note.**
`.changeset/20281-connector-sync-moved-to-mapping.md` said
`connectorSource` was "declared, not yet executed" and that "Nothing
executes it in this release". The stage-② note
`.changeset/20919-spec-connector-source-live.md` says the executor reads
it. Both compile into the same `@objectstack/spec` CHANGELOG version.
2. **The "provenance, not identity" ledger sentence** for this release's
`ERROR_CODE_LEDGER` face changes, in a new spec note,
`.changeset/21106-error-code-ledger-provenance-rows.md`.
3. **The two `@objectstack/service-automation` provenance rows**,
`MAPPING_NOT_FOUND` and `UNSUPPORTED_TRANSFORM`, in
`packages/spec/src/api/error-code-ledger.zod.ts`. A hand pin in the
provenance gate's own test,
`packages/spec/scripts/check-error-code-provenance.test.ts`, guards
them.
## 1 · The stage-① note correction
| | Before | After |
|:---|:---|:---|
| Lead label | "**Added (declared, not yet executed):**" | "**Added:**"
|
| Last sentence of that paragraph | "Nothing executes it in this
release, and `os validate` / `os build` warn when it is authored." |
"The connector sync executor, `@objectstack/service-automation`'s
`pullConnectorSource` (#20919), reads it; nothing schedules a pull until
the `job` stage lands." |
Everything else in the file is byte-identical: the front matter, the
summary line, the BREAKING banner, the FROM → TO table and the
retirement kit. The diff is +4 / −3 lines in one paragraph.
**Readings at `8368f1c0`:**
- **"reads it".**
`packages/services/service-automation/src/connector-pull.ts`
`pullConnectorSource` (:209) reads the mapping through `getMetaItem` and
its `connectorSource`. It makes one action call and writes through
`runImport`. The liveness rows say the same:
`packages/spec/liveness/mapping.json`, `connectorSource` `live`,
evidence `connector-pull.ts#pullConnectorSource`.
- **"nothing schedules a pull until the `job` stage lands".** Outside
tests, `pullConnectorSource` has three places in its own package: the
definition, the index re-export and the plugin method (`plugin.ts:621`).
No package source calls the plugin method.
- **Why the review's suggested clause "`os validate` / `os build` warn
when it is authored" is NOT kept.** It is false at `8368f1c0`, measured:
- The ledger row is `live` with `authorWarn: true`.
`lintLivenessProperties`'s `describe()`
(`packages/lint/src/lint-liveness-properties.ts`) has no `live` branch.
It throws its sentinel for that pair, by design: its own header calls
the pair "a ledger authoring mistake".
- Through lint's source, against the built spec:
`runAuthoringRules('validate', …)`, the call `os validate` makes
(`packages/cli/src/commands/validate.ts:522`), THREW
`lintLivenessProperties: ledger entry has unrecognised status "live"`
for a stack whose `mappings[]` carries `connectorSource`. The control
without `connectorSource` gave 0 findings.
- The runtime metadata-write door (`runRuntimeAuthoringRules`) answered
one `authoring-rule-threw` advisory in place of the liveness warning.
- Read at `99398542b` and again at this head.
`lint-liveness-properties.ts`, `authoring-rules.ts`, `runtime-gate.ts`
and `liveness/mapping.json` have no diff between `8368f1c0` and
`99398542b`. The CLI process itself was not run: its closure was not
built here.
- So the corrected note claims no warning. The defect is reported to the
seat as a separate finding below and not changed here.
## 2 · The ledger sentence, and the counts behind it
Measured on `ERROR_CODE_LEDGER` at `8368f1c0` against its parent
`2742e537`, comments stripped:
| Key | Parent | `8368f1c0` | Change |
|:---|---:|---:|:---|
| `@objectstack/rest` | 83 | 76 | −7: `AMBIGUOUS_MATCH`,
`BLANK_MATCH_KEY`, `CONCURRENT_UPDATE`, `ERR_DATASOURCE_UNAVAILABLE`,
`NO_MATCH`, `SUMMARY_RECOMPUTE_FAILED`, `UNIQUE_VIOLATION` |
| `@objectstack/core` | 12 | 17 | +5: `AMBIGUOUS_MATCH`,
`BLANK_MATCH_KEY`, `NO_MATCH`, `SUMMARY_RECOMPUTE_FAILED`,
`UNSUPPORTED_TRANSFORM` |
| `@objectstack/types` | absent | 3 | new key: `CONCURRENT_UPDATE`,
`ERR_DATASOURCE_UNAVAILABLE`, `UNIQUE_VIOLATION` |
| owner keys | 30 | 31 | |
| union (`ErrorCode`) | 280 | 280 | none added, none removed |
**The card and the review say rest lost −8. The measurement is −7.**
Eight codes moved (5 to core and 3 to types), but rest kept
`UNSUPPORTED_TRANSFORM`, which `resolveNamedMapping` still stamps.
Literal counts in `packages/rest/src` non-test source at `8368f1c0`: 0
for each of the seven, and 1 for `UNSUPPORTED_TRANSFORM`. The note says
seven.
The sentence follows the #20206 (`5f9d7d78`) and #19441 (`3f9e2eaa`)
paragraphs. It names both steps of this release's face change, the
#20919 move and this PR's two rows, and says the union, the wire and the
HTTP answers are unchanged.
## 3 · The two rows, and why a pin rather than a wider gate
- **Stamp sites at `8368f1c0`** (unchanged since).
`connector-pull.ts:234` `refuse('MAPPING_NOT_FOUND', 404,
'mapping_not_found', …)` and `:303-304` `refuse('UNSUPPORTED_TRANSFORM',
400, 'unsupported_transform', …)`. Both go onto
`ConnectorPullError.code`, and the class is exported from the package
index.
- **Both codes are registered extension codes.** They are listed under
`@objectstack/rest`, and `UNSUPPORTED_TRANSFORM` under
`@objectstack/core` too. Neither is in `errors.zod.ts`. The executor's
other five codes are standard-catalog members and owe no row:
`VALIDATION_ERROR`, `EXTERNAL_SERVICE_ERROR`, `INTEGRATION_ERROR`,
`SERVICE_UNAVAILABLE`, `INVALID_FIELD`.
- **Placement.** The rows go in the key's existing ASCII order:
`MAPPING_NOT_FOUND` after `INVALID_SIGNAL`, and `UNSUPPORTED_TRANSFORM`
last. One comment records the stamp sites, the statuses and the
reachability reading: no HTTP door on this tree, so the thrown value is
the boundary. No other package's rows were touched.
- **Not widened.** `check:error-code-provenance`'s header declares it
blind to a helper indirection (a `makeError(code, …)` call site). It
also says "Widening is a gate-population change with an unmeasured blast
radius — its own card, never a rider". So this PR keeps the gate's
patterns and pins the two rows by hand instead.
- **Measured for the seat, read-only.** The `refuse('CODE', …)`
call-site form stamps a registered code at 7 sites in 3 packages: core
`artifact-packages.ts` ×4, runtime `artifact-collections.ts` ×1, and
these two. Before this PR, these two were the only unlisted ones; after
it, none is unlisted.
- **The pin.** A new block in the gate's test file has two halves. One
pins the blind spot itself: `scanSourceText` finds no site in a
`refuse('X', …)` call. The other asserts that
`ERROR_CODE_LEDGER['@objectstack/service-automation']` lists each code.
It reads the ledger module inside `packages/spec`, so the suite still
reads nothing outside its package.
- **Ablation, two legs** through `scripts/ablation-replace.mjs` in WRAP
mode, run from the committed state at `c227eb366`:
- Removing the `MAPPING_NOT_FOUND` row gave `1 failed | 16 passed (17)`:
"expected [ …(9) ] to include 'MAPPING_NOT_FOUND'".
- Removing the `UNSUPPORTED_TRANSFORM` row gave `1 failed | 16 passed
(17)`, on that code's case.
- Each leg restored the file (blob `229345964e13` = HEAD, `git diff
HEAD` empty).
- A first attempt at leg one was refused by the tool before any test
ran: its replacement text already existed in the file. The anchor was
changed and the leg re-run. That first attempt is not counted as a run.
## Changeset gate: no `skip-changeset`, and `Check Changeset` stays red
by design
This PR edits a pending changeset that it did not add. `node
scripts/check-empty-changeset.mjs --base origin/main` exits 1 and
refuses `.changeset/20281-connector-sync-moved-to-mapping.md` as the
DELIBERATE CORRECTION class. The precedents are PR #20991 and PR #21012.
Ruling D on #18375 says `skip-changeset` is never applied to a PR that
edits an existing changeset, so no label is applied. `Check Changeset`
is not a required context.
**Confirmation requested in writing on this PR:** the stage-① note's
`connectorSource` paragraph now says the executor reads the binding and
nothing schedules a pull yet. It no longer says nothing executes it or
that `os validate` / `os build` warn.
## `Clause-②: yes`, not the claim's `no`
The claim (`5926939917`) and the dispatch say `patch` with `Clause-②:
no`. The dispatch also says not to keep `no` silently if the diff widens
a public surface, and it does:
- Two literal members are added to
`ERROR_CODE_LEDGER['@objectstack/service-automation']`, a published `as
const` face.
- The ledger header (the #16404 ruling) names this ledger, together with
`StandardErrorCode`, as the published contract face for error codes.
- The two precedents this card names, #20206 and #19441, each declared a
provenance-row addition as `@objectstack/spec` `minor` with `Clause-②:
yes`. Both say "What widens is the per-package face".
So the new note is `minor` with `Clause-②: yes`, and this body's second
line matches it. No accept set changes: the `ErrorCode` union is
unchanged. Every package is in the one `fixed` group, and
`@objectstack/spec` already has a pending `minor`, so the released
version is the same either way. The seat can flip it back if it reads
the precedent differently.
## Verification at `5748c8ddd` (base `99398542b`, merged with
`origin/main` `39ab2940e`)
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` (exit 0) derived 87 commands from the four
changed paths. Each ran on this head, with its exit code captured before
any pipe:
- **84 exit 0.** Among them: `check:error-code-provenance` ("scanned
2636 files; 335 registered-code stamp site(s): 316 listed, 19 waived" /
"OK"), `check-adr-0087-registration.mjs --base origin/main` ("this PR
adds no declared-breaking changeset (2 non-breaking changeset(s)
seen)"), `check-changeset-no-major.mjs --base origin/main` ("This diff
introduces no `major` bump"), `check:api-surface`,
`check:authorable-surface`, `check:docs`, `check:liveness`,
`check:error-code-casing`, `check:dispatcher-error-vocabulary`,
`check:cross-package-test-inputs`, `check:nul-bytes`,
`check:query-options-erasure` and `check:type-check-debt`.
- **1 exit 1, by design:** `check-empty-changeset.mjs --base
origin/main`, the DELIBERATE CORRECTION class above.
- **2 NOT MEASURED** (exit 3, `PREREQUISITE NOT MET`):
`check:dual-build-cjs-loads` (needs a full `pnpm build`) and
`check:lean-entry-closure` (needs `@objectstack/objectql` built). CI
builds the tree. Reason: a built tree was not produced here.
- Reconciled: `dispatch-gates.mjs --ran` exit 0, "87 derived famil(ies)
accounted for — 85 run, 2 NOT-MEASURED".
- `pnpm --filter @objectstack/spec build`: `VERDICT command-exit 0`.
Then `pnpm --filter @objectstack/spec check:generated`: "All 15
generated artifacts are up to date".
- `vitest run --project local` on `src/api` plus
`scripts/check-error-code-provenance.test.ts`: 47 files / 1546 tests
passed. The 12 other spec test files that read the ledger: 182 tests
passed.
- `pnpm --filter @objectstack/spec typecheck`: exit 0. That covers
`tsc`, `check:scripts-typecheck`, and `check:test-typecheck` ("52
file(s) / 246 error(s) / 135 pinned signature(s) held", unchanged).
- Main moved during the run: `origin/main` gained 13 commits after the
branch point. None touches the four files. The delta against `39ab2940e`
is exactly them (+70 / −4).
## Acceptance notes
- **Read and kept in the stage-① note:**
- "Runtime behaviour is deliberately **unchanged**: no connector sync
ever ran." This is about the retired connector-attached keys
(`syncConfig` / `fieldMappings`), and it stays true of them.
- "It carries no cadence (a `job` sets that)." This describes the
design; the corrected clause says nothing schedules a pull until the
`job` stage lands.
- **Reported to the seat, not changed here:**
- **The liveness lint throws on `connectorSource`.** The `live` +
`authorWarn` row reaches `describe()`'s sentinel throw, so `os validate`
/ `os build` stop with an internal lint error, and the runtime door
answers `authoring-rule-threw`, instead of warning on an authored
`connectorSource`. The comments in `authoring-rules.ts` and
`runtime-gate.inert-type-writes.test.ts` still say it warns. The fix is
a choice for its own card: teach `describe()` a caveat branch for
`live`, or change the row.
- **`turbo` 2.11.5 edits `AGENTS.md`.** It arrived with the
development-dependencies bump (`840ec9dab`, now on `main`). On every
turbo invocation it sees as an AI agent's, it appends a managed
`turborepo-agent-rules` block to `AGENTS.md`, a Tier H governed surface,
and `turbo.json` declares no `agentGuidance: false`. Measured here:
`pnpm exec turbo run build --filter='@objectstack/lint...'` and `pnpm
check:type-check-debt` each left `M AGENTS.md`, +11 lines. Each time it
was restored with `git checkout HEAD -- AGENTS.md` (blob `e9e211fc` =
HEAD) and never committed. An agent that commits with `-a` would carry
it into its PR.
---
_Generated by [Claude
Code](https://claude.ai/code/session_017VaLJnYwhPsanVCe9dMCJU)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2488b98 commit df1feae
4 files changed
Lines changed: 70 additions & 4 deletions
File tree
- .changeset
- packages/spec
- scripts
- src/api
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
28 | | - | |
| 28 | + | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
35 | | - | |
36 | | - | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
37 | 38 | | |
38 | 39 | | |
39 | 40 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
25 | | - | |
| 25 | + | |
26 | 26 | | |
27 | 27 | | |
28 | 28 | | |
| |||
150 | 150 | | |
151 | 151 | | |
152 | 152 | | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
153 | 190 | | |
154 | 191 | | |
155 | 192 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1059 | 1059 | | |
1060 | 1060 | | |
1061 | 1061 | | |
| 1062 | + | |
| 1063 | + | |
| 1064 | + | |
| 1065 | + | |
| 1066 | + | |
| 1067 | + | |
| 1068 | + | |
| 1069 | + | |
| 1070 | + | |
| 1071 | + | |
| 1072 | + | |
| 1073 | + | |
| 1074 | + | |
1062 | 1075 | | |
1063 | 1076 | | |
1064 | 1077 | | |
1065 | 1078 | | |
1066 | 1079 | | |
| 1080 | + | |
1067 | 1081 | | |
1068 | 1082 | | |
1069 | 1083 | | |
| |||
0 commit comments