Repository navigation
refactor(metadata-protocol): move the protocol.ts preamble into 22 themed modules, verbatim (#25467 E0) - #29336
Conversation
…emed modules, verbatim Every top-level statement above `export class ObjectStackProtocolImplementation` (183 declarations) moves, byte for byte with its leading comments, into a themed `protocol-*.ts` module. Only import lists, export lists and a module header comment are new; protocol.ts re-exports every name it exported before. Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
…olled-up .d.ts keeps The module import order in protocol.ts decides the declaration order of the published index.d.ts; this order keeps it equal to the base's. Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
… from its module protocol.lookup-artifact-item-call-sites reads envelopePackageId's one definition from protocol-package-bindings.ts and asserts protocol.ts imports it (no copy); protocol.read-verb-canonical-fold reads the four door request aliases from protocol-door-requests.ts when protocol.ts imports them from there. Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
…data-protocol Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
…tocol.ts preamble moved to diffShallow (protocol-write-face.ts), protectionBlockRefusal (protocol-authoring-refusals.ts) in the studio-authoring checklist area, and QUERY_AST_KEYS / WIRE_DOLLAR_ALIASES (protocol-list-query-params.ts) in the spec liveness ledger's query evidence. Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
…dger citations Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
… protocol.ts's E0 note Two more comment lines. They also move protocol.ts's byte offsets off the place where, after the merge of main, the emitter printed a class JSDoc inside getMetaTypes()'s inferred return type in the published index.d.ts. Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk Co-authored-by: Claude <noreply@anthropic.com>
📓 Docs Drift CheckThis PR changes 2 package(s): 131 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: ⛔ 18 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails. What this run could not see
Coarse fallback — 169 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): Which tree this was computed onThis run read A worktree cut from an older # while this PR is open — GitHub drops the merge commit once it closes
git fetch origin dcedc0cf044881cecbe99c515dbe06699775ceec && git checkout dcedc0cf044881cecbe99c515dbe06699775ceec
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a2fcede85c09dd54093f03cecc312d0dc861734f fb09f70ad757bee2e4137df6c3029d242832ca26 && git checkout -B drift-repro a2fcede85c09dd54093f03cecc312d0dc861734f && git merge --no-ff fb09f70ad757bee2e4137df6c3029d242832ca26
node scripts/docs-audit/affected-docs.mjs --json a2fcede85c09dd54093f03cecc312d0dc861734f
|
…oc-link imports the preamble move dropped
The move kept protocol.ts's imports by the identifiers its code uses, so
three comments attached to imports it dropped or moved went nowhere, and
seven import names that only the class's {@link} doc references use were
removed. Restored, each at its base place:
- the [#19295] block above `markErasedAuthoringInput`'s import, now in
protocol-meta-type-schema.ts;
- the [#21207] inline note with `ephemeralStoredHashDigest` in the
metadata-redaction import;
- the [#5488] note after the reference-sites import, where it stood;
- SDUI_MANIFEST_SERVICE, backfillOverlayBundleMembers,
unboundItemDraftAddress, resolveItemLockLazily, REFERENCE_VALUE_TYPES,
externalBindingDatasourceRefusal and ephemeralStoredHashDigest back in
protocol.ts's import lists.
Comments and import lists only. The published index.d.ts is byte-identical
to the previous head's.
Claude-Session: https://claude.ai/code/session_01ADHkmR4MjTzeUv5x6tNkbk
Co-authored-by: Claude <noreply@anthropic.com>
|
domain:server#5 · os-steve · session_01ADHkmQKwKFCp1m6Pb6Q8c1 维护者速读
席位意见:与 diff 相符。本席自己做了一遍逐行比对(base 删除行对 head 新增行),第一版丢了三段 import 注释和七个只被 席位核对ACCEPT ·
|
One conflict, packages/metadata-protocol/src/protocol.ts: main moved the module preamble into themed modules (#29336) while this branch had edited the ConcurrentUpdateError docblock inside it. Resolved by taking main's removal and carrying the docblock edit to protocol-version-tokens.ts, whose move header now names that one changed docblock. The branch's three class-body hunks (updateData, probeRecord, assertVersionOf) merged clean. Claude-Session: https://claude.ai/code/session_017xRBcVy4VXmkQjn2MGeaWk Co-authored-by: Claude <noreply@anthropic.com>
Requested by Steve · project thread
Part of #25467
Clause-②: no
Metadata-protocol: none
维护者速读
protocol.ts类定义之上的整段前言(183 条顶层声明,约 6,300 行)原样搬进 22 个按主题命名的protocol-*.ts模块;protocol.ts照旧导出原来导出的每个名字。没有任何逻辑改动。protocol.ts是 server 车道的热文件,每个改它的 PR 都要排队;这是 [maintainer] refactor(metadata-protocol): splitsrc/protocol.ts(33,065 lines, +10,169 in 30 days) along itsObjectStackProtocolImplementationseams, one move-only slice per PR #25467 裁决 E 的第一步 E0(E1、E2 之后另派),按字母 A 的.d.ts新判据落地。index.d.ts声明集合、顺序、ESM/CJS 导出名单都不变,原始字节只差空行、一条 import 内的名字顺序、一个字面量联合的成员顺序。另把 QA 清单和 spec liveness 账本里 3 处指向被搬符号的引用改指新模块。回滚即整体 revert 本 PR。packages/metadata-protocol/src/protocol.ts(文件头的 import/export 名单);packages/metadata-protocol/src/protocol.read-verb-canonical-fold.test.ts(迁移后的按路径 pin);packages/metadata-protocol/src/protocol.lookup-artifact-item-call-sites.test.ts。pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.read-verb-canonical-fold.test.ts src/protocol.lookup-artifact-item-call-sites.test.ts,预期 2 个文件全绿(main 上的搬移前形态同样绿;搬移后不迁移则红 2 条)。packages/spec/liveness/query.json两处证据引用改指新模块可以留在本 PR(不留则check:liveness红)。What changes
Step E0 of ruling E (6537939895, folded onto #25467 in 6537947529), landed under letter A (6545252863). Move-only.
export class ObjectStackProtocolImplementationinpackages/metadata-protocol/src/protocol.tsthat is not an import or an export list (183 declarations) moves verbatim, with its leading comments, into one of 22 new themed modules:protocol-meta-type-schema,protocol-authoring-refusals,protocol-metadata-issues,protocol-publish-backfill-request,protocol-data-request-shapes,protocol-view-normalization,protocol-package-bindings,protocol-bundle-members,protocol-overlay-merge,protocol-version-tokens,protocol-write-constants,protocol-client-failures,protocol-list-query-params,protocol-discovery-services,protocol-reference-hits,protocol-write-face,protocol-package-lifecycle-types,protocol-mutation-events,protocol-authoring-channel,protocol-audit-entry,protocol-stored-overlay-types,protocol-door-requests.claude/project-thread-6aibsn@4a35157e, seat 4's report 6542958324), redone by tool on freshmain. The three statements added since that trial follow the statement before them:isActionWithheldByDisabledPackage→protocol-authoring-refusals,perPackageLayerEnvelope→protocol-package-bindings,storedEntryRow→protocol-stored-overlay-types.export { … }at a module's foot for a name that was module-private and is now shared;export { … } frominprotocol.tsfor every name it exported before) and a module header comment per module. The three preamble export lists that re-export imports (FormFieldInput,recordNotFoundError,stripReadDecorations) stay inprotocol.tswith their comments.protocol.tsimports the modules in the order that keeps the rolled-up.d.tsdeclaration order equal to the base's.protocol.ts: 30,912 → 24,892 lines (onmainf125ce40da). No class-body member is touched (that is E1/E2).protocol.tsand no longer resolve there are re-pointed at the module it moved to:docs/qa/platform-checklist/areas/studio-authoring.json(diffShallow→protocol-write-face.ts, twice;protectionBlockRefusal→protocol-authoring-refusals.ts) andpackages/spec/liveness/query.json(QUERY_AST_KEYS,WIRE_DOLLAR_ALIASES→protocol-list-query-params.ts; red incheck:platform-checklist --changed-fromandcheck:livenessbefore). Citations that still resolve throughprotocol.ts's re-exports (ConcurrentUpdateError,servedViewExpansion,specValidationFindings, and the ADR texts) are left as they are;check:adr-symbol-anchorsis green..changeset/25467-e0-protocol-preamble-modules.md:patchon@objectstack/metadata-protocol, andpatchon@objectstack/specbecauseliveness/ships in its tarball; both declaration lines.Tests
Forced edits, all because a reader names a moved symbol by its file path: two tests and two data files that are not tests.
Two by-path pins read preamble symbols out of
protocol.tsand are migrated in this PR (forced test edits, both inpackages/metadata-protocol/src/):protocol.lookup-artifact-item-call-sites.test.ts:envelopePackageId's one definition is read fromprotocol-package-bindings.ts; two assertions are added so the pin keeps its reach:protocol.tsdefines no copy of its own, and it importsenvelopePackageIdfrom that module.protocol.read-verb-canonical-fold.test.ts: the four door request aliases (SaveMetaItemRequest…DeleteMetaItemRequest) are read fromprotocol-door-requests.ts, only whenprotocol.tsimports them from that module, so the signature judged is still the one the class names.Two by-path citations in data files are re-pointed (forced, not tests):
docs/qa/platform-checklist/areas/studio-authoring.jsonandpackages/spec/liveness/query.json, as listed under What changes.Before the migration the package suite was 2 failed / 298 passed files, the failures exactly these two pins (13 of 17 verbs found;
function envelopePackageIdnot inprotocol.ts).Ablations (one-off, each from committed HEAD through scripts/ablation-replace.mjs, restored to the HEAD blob with git diff HEAD empty)
saveMetaItemUnaudited'srequest = canonicalizeMetaRequestType(request);replaced byrequest = { ...request };(anchor 1 → 0, bloba0a204da0761→6d869851bc31). The pin goes red:Tests 1 failed | 17 passed (18), received[ "saveMetaItem" ]against[], the verb whose request type now comes from the moved alias.envelopePackageIdsignature changed (served: unknown→served?: unknown; blobe062a10a8f3e→47d2d431def2). Red:Tests 1 failed | 4 passed (5),expected '// Copyright …' to match /\nfunction envelopePackageId\(request…/.function envelopePackageId(…)put back intoprotocol.ts(bloba0a204da0761→cb2f4764a1cf). Red:Tests 1 failed | 4 passed (5),expected '// Copyright …' not to match /\nfunction envelopePackageId\(/.Acceptance notes
Move-only, by tool (a verifier separate from the move tool): every non-import top-level statement of base
protocol.ts(190, the class and the three trailer statements included), leading comments included and blank lines before it excluded, appears verbatim exactly once across headprotocol.tsand the 22 modules: verbatim 190, missing 0, changed 0, surplus 0, duplicated 0. Head adds import statements (109 → 183), 47 export lists and 165 module-header comment lines. Negative control: one operator changed inprotocol-version-tokens.ts(hash = hash & hash→hash = hash | hash) → verbatim 189, changed 1, surplus 1 (simpleHash), exit 1; restored, blob equals HEAD..d.ts, normaliser 2 (letter A). Read-only, not a gate (the card adds no gate). Normalised: drop blank lines; sort the names inside each import brace list; sort each run of consecutive string/number literal members of a union. Everything else survives.dist/index.d.ts(=index.d.ctsbyte for byte, both sides)mainf125ce40da20d8c2c81365a4356b2efed1dd5d25e5d80a55fccfef2adfd4a6c098c686d85f1a4749b0abd939f04a7ae66bbf19398a1f7ff4d905748fe9de667b8092105cffae3deec9557dea44d6d7660b9c7412af3cd0c6aa0382e3ab11dc52505431372f8185ecd97d7dea44d6d7660b9c7412af3cd0c6aa0382e3ab11dc52505431372f8185ecd97dAn earlier reading, base
74a19dd857against headc1d3b9dec3, gave equal normaliser 2 hashes the same way (ff357c33…).Raw diff: 11 added blank lines, 1 line pair (the
@objectstack/spec/apiimport brace list,MetadataAuthoringSurface, MetadataAuthoringClientfirst) and 2 line pairs (columns?:ingetMetaTypes()'s inferred return type, members permuted). Declaration sequence (182 top-level statements) identical but for that import line; the final export-list line identical.Positive controls (each applied to head, each must differ from base and does): a class's
private engine;made public; one name dropped from the export list;MetadataWriteFacemoved to the end; one union literal dropped; onereadonlyremoved; and a real one, an earlier layout of this head whose.d.tscarried a leaked JSDoc comment (below). Negative controls (each allowed kind alone, applied to base, must equal base and does): blank lines inserted; the import brace list reversed; the literal union permuted. The controls assert each edit landed (raw text changed).A declaration-emit trap met on the way, noted (not filed: it changes no published meaning and is TypeScript's behaviour, not this package's). The first layout of this move published
description? /** [#27842] The list's disabledActions … */: string | undefined;insidegetMetaTypes()'s inferred return type: the emitter printed a comment that sits inprotocol.tsat the byte offset of a node reused from another file. One line more in theprotocol.tsheader comment moved the offset and the comment left the.d.ts. It struck again after mergingmainwith fix(metadata-protocol)!: a runtime permission-set save refuses a grant on an object that does not exist #29093 (class-body lines shifted); two more lines in the E0 note (now 5 lines, which also tells the next editor to read the raw.d.tsdiff) cleared it, and the final reading above has no comment in the raw diff. Normaliser 2 does not tolerate it (positive control P6). Any edit ofprotocol.tsonmaincan trip it the same way whilegetMetaTypes()has an inferred return type; E1/E2 will meet it again and should read their raw diffs for it.In flight on the same files, re-read just before opening (
origin/main5780fa49df; 30 commits past this branch's last merge, none touchingprotocol.tsor any file of this PR,git merge-treeclean, so not merged again). fix(metadata-protocol)!: a runtime permission-set save refuses a grant on an object that does not exist #29093 (metadata: a runtime permission-set save accepts a grant on an object that does not exist (200) — the build refuses the same grant (#18202), so a typo silently grants nothing #28990) has merged and is in this branch. Open PRs that touchprotocol.ts, each against this head bygit merge-tree:8372e0a1): hunks at base line 3330 (ConcurrentUpdateError's doc comment, which this PR moves toprotocol-version-tokens.ts) and in the class body. Conflicts: whichever lands second carries that doc-comment edit to the other side.protocol.ts's own import lists, which stay inprotocol.ts, plus class-body hunks. Clean.studio-authoring.jsonin another item (revision 11 of the object designer item). Clean.Any of them landing shifts
protocol.tsoffsets, so the comment leak above can come back on its own; it is not this PR's to guard.E0 is one step of a series;
Part of #25467keeps the card open for E1 and E2.Verification
Readings in this container under
scripts/pm/os-verify-lock.sh, on head20d8c2c813unless named.@objectstack/metadata-protocolbuild,typecheck,test: VERDICT command-exit 0 · Test Files 301 passed | 4 skipped (305) · Tests 22127 passed | 26 skipped (22153).pnpm turbo run typecheckon the 11 packages that depend on@objectstack/metadata-protocol: cli, client, cloud-connection, objectql, plugin-approvals, plugin-security, rest, runtime, service-automation, service-messaging, service-package), on6b1dd49e2b: VERDICT command-exit 0 · Tasks 72 successful, 72 total, every typecheck a cache miss. The two commits after it change the changeset and two comment lines inprotocol.ts; the published.d.tsnormaliser 2 hash is the same.protocol.tsor a moved symbol by path:check:filter-alias-parity,check:system-context-census,check:durability-log-level,check:query-options-erasure,check:engine-double-contract,check:objectql-double-limit,check:platform-checklist(in the battery below), pluscheck:adr-anchors,check:adr-symbol-anchors,check:scripts-symbol-anchorsandpnpm --filter @objectstack/spec check:liveness, each exit 0.gen:liveness-countsleaves the tree clean.dispatch-gates --commands, 71 commands): 71 exit 0.dispatch-gates --ran: 71 derived, 71 run, 0 NOT-MEASURED, 0 UNRUN.eslint packages/metadata-protocol --no-inline-config(the package has nolintscript) exit 0.test:repo(Test Core) and the full farm are CI's.Human Minimum
packages/specholds no runtime logic. (the onepackages/specedit is two evidence citations inliveness/query.json; no schema, type or logic)pnpm lintpasses. (scoped to the package)main, one pull request.packages/spectouched: its generated artifacts are regenerated and committed. (liveness/query.jsononly;gen:liveness-countsregenerates nothing from it, tree clean)content/docs/references/,packages/*/CHANGELOG.mdorcontent/docs/releases/.Generated by Claude Code