fix(cloud-connection): install-local runs the ADR-0087 D1 protocol handshake and refuses with the packages door answer (422)

[objectstack-fleet]

Fixes #21762

Clause-②: yes (widening)

What changes

POST /api/v1/marketplace/install-local now runs ADR-0087 D1's protocol handshake, and its kernel:ready rehydrate does too. On origin/main both loaded a package built for another protocol major.

• Install door (packages/cloud-connection/src/marketplace-install-local-plugin.ts, step 1c). The route calls assertProtocolCompat right after the manifest id is parsed. That is before the unrunnable-code judgement, the collision check, the posture gate, manifest.register, the ledger write and syncSchemas. A refusal answers 422 OS_PROTOCOL_INCOMPATIBLE with the handshake's message and error.details: { requiredRange, rangeSource, protocolVersion, targetMajor, migrateCommand }. The answer is the same on the inline-manifest branch and the cloud-snapshot branch. A missing or unreadable range is still admitted, and the handshake's warning goes to ctx.logger.warn.
• Rehydrate. On kernel:ready, checkProtocolCompat judges each ledger entry before register. An incompatible entry is not loaded: nothing is registered, synced, bound or seeded for it. One error line names the code, the package, the handshake's message (which ends with the replay command) and the two remedies (install a compatible version, or DELETE). The boot continues, and the entry stays in the ledger. A missing or unreadable range rehydrates as before, with no new warning.
• One shared answer (packages/metadata-core/src/protocol-handshake.ts). protocolIncompatibleAnswer(err: ProtocolIncompatibleError): ProtocolIncompatibleAnswer returns { status, code, message, details }. details is a closed shape with the five members named one by one. It sits beside ProtocolIncompatibleError and isProtocolIncompatibleError. The packages door's module-private protocolIncompatibleAnswer(deps, err) is deleted, and packages/runtime/src/domains/packages.ts now calls the shared helper. Both doors recognise the error with the shared brand predicate and shape it with the shared helper, so no second copy is left.
• Dependency edge. @objectstack/cloud-connection now imports @objectstack/metadata-core from production source, so the package moves from devDependencies to dependencies (pnpm-lock.yaml: only that importer hunk). No new package enters the install closure, because runtime and core already depend on it.

Rulings applied (triage 5982323247 and its unlock 5986276908)

• The install route calls the same assertProtocolCompat before anything is registered, written or synced.
• The refusal answers through the same carrier as the packages door: 422, with the structured diagnostic in details. Shared, not copied.
• The recogniser is one helper both doors call. It sits beside ProtocolIncompatibleError in metadata-core, the measured common ancestor of runtime and cloud-connection (see H4).
• The rehydrate was measured and then pinned. On BASE it loaded the incompatible entry. Now it does not, logs loudly, and the boot continues. This is the behaviour the ruling expected.

Mechanism assumptions, measured at BASE e27a7c0c9e

• H1, confirmed. git grep -E "assertProtocolCompat|checkProtocolCompat|OS_PROTOCOL_INCOMPATIBLE" over the plugin: 0 hits. The same grep hits runtime/src/domains/packages.ts and metadata-core/src/protocol-handshake.ts.
• H2, confirmed. metadata-core's . entry has export * from './protocol-handshake.js', which already exported assertProtocolCompat, checkProtocolCompat, isProtocolIncompatibleError and ProtocolIncompatibleError.
• H3, confirmed. protocolIncompatibleAnswer(deps, err) at packages.ts:607 was module-private and took DomainHandlerDeps.
• H4, confirmed. cloud-connection listed metadata-core only in devDependencies. Its vitest.config.ts already aliases @objectstack/metadata-core to source, so the check:test-source-alias ledger does not move. Neither runtime nor core re-exports metadata-core, so a direct edge is the only import path. That path does not cross a layering gate: check:lean-entry-closure guards only @objectstack/objectql/core. check:undeclared-dep-imports is green with the edge.
• H5, measured. For the card's manifest, the two doors give byte-identical status, error.code, error.message and error.details. The parity case below asserts this. The envelopes differ in one member: the dispatcher's builder adds error.httpStatus to every error it emits, and install-local's hand-built bodies have never carried it on any exit. Both parse as ApiErrorSchema. See the acceptance notes.
• H6, measured with a throwaway probe on BASE (the plugin through start + kernel:ready, with a ledger entry engines.protocol: ^16). Registered ids: [marketplace-installed-ui, com.example.qaold]. syncSchemas calls: 1. logger.error: []. logger.warn: []. logger.info: rehydrated com.example.qaold@1.0.0. The install reproduced the card: 200, registered, ledger file written, 1 sync.

Clause-② reading: built declaration closure, before and after

The dist of metadata-core, runtime and cloud-connection was built at BASE and again at HEAD. The TypeScript checker walked each entry: the exported names, plus every declaration reachable through members, parameters, return types and heritage.

• @objectstack/metadata-core .: grows by exactly two names. There are 169 exports before and 171 after. The two new ones are interface ProtocolIncompatibleAnswer { status: ProtocolIncompatibleError['status']; code: ProtocolIncompatibleError['code']; message: string; details: Pick of ProtocolIncompatibleDiagnostic over 'requiredRange' | 'rangeSource' | 'protocolVersion' | 'targetMajor' | 'migrateCommand' } and declare function protocolIncompatibleAnswer(err: ProtocolIncompatibleError): ProtocolIncompatibleAnswer. Every type reachable through them (ProtocolIncompatibleError, ProtocolIncompatibleDiagnostic, RangeSource) was already exported, and its declaration text is unchanged. The 24 external references are identical. Five SysMetadata*Object declarations hash differently only because the emitted field-type union prints its members in a different order ("user" | "code" becomes "code" | "user"). The member set is the same.
• @objectstack/metadata-core ./testing: the closure is identical.
• @objectstack/runtime .: index.d.ts and index.d.cts are byte-identical before and after (sha256 prefix cb442723451fa416). The 513 exports are unchanged.
• @objectstack/cloud-connection .: the 40 exports are unchanged. MarketplaceInstallLocalPlugin's declaration gains one untyped private reportProtocolIncompatibleEntry; and doc text. The class already had private members, so its assignability does not move.
• Verdict: yes (widening) holds, for metadata-core only. The door's accept set narrows, but it narrows back to a declared contract: ADR-0087 D1 checks "the package installer", and POST /api/v1/packages already refused the same manifest. I read that as outside Clause-② (execution-duties.md: 条款②只指已发布契约面,拉回已声明契约不触它). The seat should confirm this; I did not take the (narrowing) arm.
• Changeset levels: metadata-core minor, cloud-connection patch, runtime patch. All three are in the fixed group.

metadata-core . exports after this change (order-insensitive; the two new names are ProtocolIncompatibleAnswer and protocolIncompatibleAnswer):

AUDIT_FIELD_DEFS, AUDIT_FIELD_GOVERNANCE, AnonymousFormIntakeCandidate, AnonymousFormIntakeUnavailable, ArtifactConversionNotice, ArtifactForwardConversionOptions, ArtifactForwardConversionResult, ArtifactForwardConversionVerdict, ArtifactReplayedRetirement, BOUND_FORM_FIELD_PREDICATE_ROOTS, BOUND_FORM_VIEW_PREDICATE_ROOTS, BranchError, CacheStats, ConflictError, DeleteOptions, DeleteResult, ENGINE_DELETE_DISPATCH_CASES, ENGINE_DELETE_REJECT_MESSAGE, ENGINE_FINDONE_PREDICATE_CASES, ENGINE_UPDATE_DISPATCH_CASES, ENGINE_UPDATE_ID_CONFLICT_CODE, ENGINE_UPDATE_ID_CONFLICT_STATUS, ENGINE_UPDATE_REJECT_MESSAGE, EngineDeleteDispatch, EngineDeleteDispatchCase, EngineDeleteDispatchInput, EngineFindOnePredicate, EngineFindOnePredicateCase, EngineFindOneQueryInput, EngineUpdateDispatch, EngineUpdateDispatchCase, EngineUpdateDispatchData, EngineUpdateDispatchInput, FormPredicateSurface, HistoryOptions, ITEM_KEY_DISCRIMINATORS, InMemoryRepository, InMemoryRepositoryOptions, InjectedColumnProvenance, LAYER_SOURCE, LayerConfig, LayeredRepository, LayeredRepositoryOptions, ListFilter, METADATA_AUTHORING_CAPABILITY, MetaRef, MetaRefSchema, MetaWriteCapabilityVerdict, MetaWriteOperation, MetadataCache, MetadataCacheOptions, MetadataError, MetadataEvent, MetadataEventSchema, MetadataItem, MetadataItemHeader, MetadataItemSchema, MetadataOp, MetadataOpSchema, MetadataRepository, MetadataType, MetadataTypeSchema, MetadataWriteIntent, NotFoundError, OBJECT_FIELD_TYPE_REFUSED_ERROR_NAME, OBJECT_SCHEMA_MASK_DISABLE_ENV, OBJECT_SCHEMA_MASK_EXEMPT_CAPABILITIES, OBJECT_SCHEMA_MASK_NOT_APPLICABLE, OBJECT_SCHEMA_MASK_UNDETERMINED_METRIC, OBJECT_SCHEMA_READ_ONLY_EXEMPT_CAPABILITIES, OBJECT_SCHEMA_WRITE_CAPABILITIES, ORG_PRESENTATION_AUTHORING_CAPABILITY, OWNER_FIELD_DEF, OWNING_BUSINESS_UNIT_FIELD_DEF, ObjectFieldTypeRefusal, ObjectFieldTypeViolation, ObjectSchemaMaskEvaluationError, ObjectSchemaMaskPassthroughReason, ObjectSchemaMaskPosture, ObjectSchemaMaskResult, ObjectSchemaMaskSecuritySurface, ObjectSchemaMaskTelemetry, ProtocolCompatResult, ProtocolHandshakeManifest, ProtocolIncompatibleAnswer, ProtocolIncompatibleDiagnostic, ProtocolIncompatibleError, PutOptions, PutResult, RangeSource, RecordOrganizationResolver, SchemaValidationError, SysMetadata, SysMetadataAuditObject, SysMetadataCommitObject, SysMetadataHistoryObject, SysMetadataObject, SysViewDefinitionObject, TENANT_SCOPE_FIELD_DEF, UnboundFormPredicateRoot, WarnFn, WatchFilter, anonymousFormIntakeCandidates, anonymousFormIntakePosture, anonymousFormIntakeSlug, anonymousFormIntakeSlugs, anonymousFormIntakeUnavailability, anonymousFormIntakeUnavailableMessage, anonymousFormIntakeUnavailableRemedy, anonymousFormObjectName, anonymousFormSharingPath, applyArtifactForwardConversions, applyAuditFieldGovernance, applyInjectedSystemColumns, applyObjectSchemaMask, assertEngineDeleteDispatch, assertEngineFindOnePredicate, assertEngineUpdateDispatch, assertProtocolCompat, canonicalize, checkProtocolCompat, createFieldPresenceProbe, createRecordOrganizationResolver, createRecordWallOrganizationResolver, declaresOrgOverride, describeUndeclarableFieldType, detectUnboundFormViewPredicateRoots, engineByIdUnhonouredPredicateMessage, engineFindOnePredicateRefusalMessage, engineUpdateDispatchRejectError, engineUpdateIdConflictMessage, engineUpdateIdPredicateConflictMessage, findUndeclarableFieldType, foldVisibilityFingerprintIntoEtag, hashSpec, injectedSystemColumnDefs, isCodeArtifactBody, isDeclarableFieldType, isObjectFieldTypeRefused, isObjectSchemaMaskExempt, isObjectSchemaMaskingEnabled, isProtocolIncompatibleError, isTenantAuthored, itemDiscriminator, metaWriteCapabilityVerdict, normalizeIfNoneMatch, objectFieldVisibilityFingerprint, organizationIdForMetaRead, organizationIdForMetaWrite, parseRangeFloor, platformProvisionsStorage, protocolIncompatibleAnswer, publicFormSlug, rangeAdmitsMajor, readDiscriminatorValue, refKey, resolveDeclaredRange, resolveEngineDeleteDispatch, resolveEngineFindOnePredicate, resolveEngineUpdateDispatch, resolveInjectedColumnProvenance, resolveInstalledSpecVersion, resolveObjectSchemaMaskPosture, resolveRecordOrganizationField, resolveRecordWallOrganizationField, scalarDeleteId, scalarUpdateId, stripInjectedSystemColumns, unboundRootsInCelSource, unhonouredByIdPredicateKeys, unprovisionedInjectedColumns

Tests (HEAD 6ca235b9)

• marketplace-install-local-protocol-handshake.test.ts (new, 11 pins):
  • The inline-manifest and cloud-snapshot refusals: 422, declared envelope (BaseResponseSchema, envelopeViolations, ApiErrorSchema), OS_PROTOCOL_INCOMPATIBLE, exactly the five details. Nothing registered, no ledger file, 0 syncs.
  • The range is judged before the package's code, with a control: the same handler-only job under ^17 answers VALIDATION_ERROR.
  • A refused upgrade leaves the installed ledger file byte-identical.
  • ^17 control: 200, registered, written, synced.
  • No-range control: 200, with one [protocol] warning on the plugin logger.
  • Parity: POST /api/v1/packages, driven through the runtime's real HttpDispatcher, and install-local give byte-equal {status, code, message, details}.
  • Rehydrate: the incompatible entry is not registered, has 0 syncs and produces one error line naming the code, the id and objectstack migrate meta --from 16. The boot continues (a compatible entry rehydrates and the routes mount). DELETE still removes the entry, and a ^17 version replaces it.
• protocol-handshake.test.ts (+3): the helper's status, code and message; exactly five details members valued from the diagnostic; closed shape (a member added to the diagnostic does not leak).
• packages-install-protocol-incompatible.test.ts: the header's "only HTTP door" claim is updated. Its 6 pins still pass unchanged, so the packages door's wire is the same after the switch to the helper.
• Full suites: metadata-core 18 files / 374 passed. cloud-connection 39 / 477 passed. runtime 325 / 4624 passed (19 skipped). typecheck exits 0 for all three, and --listFiles confirms both new test files are in their programs.

Ablations (scripts/ablation-replace.mjs, each restored to the HEAD blob with git diff HEAD empty)

• A: install handshake call replaced with a no-op. Anchor 1 → 0, blob 2ce1f2e4 → e1c43b2a. 6 of 11 went red. The inline refusal read expected 200 to be 422, the card's defect. The ordering pin read VALIDATION_ERROR, the no-range warning count read 0, and parity failed. The 5 rehydrate and control pins stayed green.
• B: rehydrate refusal disabled. 2 of 11 went red: the not-loaded pin (expected [ …(2) ] to not include 'com.example.qaold') and boot-continues. The DELETE and replace preservation pins stayed green.
• C: helper's details turned into a spread of the diagnostic. My first attempt was a no-op: the replacement contained the anchor, the tool counted it 1 → 1 and refused, and nothing ran. Re-anchored, the mutation landed (blob 062e9469 → 7a0a3d18): 2 of 25 went red in metadata-core (exact members, closed shape) and 5 of 11 in cloud-connection. Parity went red too, because install-local read the aliased mutated source while the packages door read the built dist.
• No build sat between mutation and run: each subject is imported relatively from src, or through the existing metadata-core source alias.

Gates (HEAD 6ca235b9)

• node scripts/pm/dispatch-gates.mjs --commands derived 74 commands from this change set. All 74 ran, and --ran reports: 74 derived, 74 run, 0 NOT-MEASURED, 0 UNRUN.
• Two of them first exited 3 (prerequisite, not red). check-plugin-teardown-shape --self-test needed its pinned positive-control commit in this shallow clone; after fetching it, 48 cases passed. check:dual-build-cjs-loads needed every package's dist/; after pnpm build (72/72 tasks), it exited 0.
• pnpm lint (the full eslint . --no-inline-config) exited 0 with no findings.
• origin/main has moved to d13df0c6 (3 commits). None of them touches metadata-core, runtime, cloud-connection or pnpm-lock.yaml, so I did not merge.

Acceptance notes

• packages/spec/src/api/error-code-ledger.zod.ts: the OS_PROTOCOL_INCOMPATIBLE row's comment still says "The one HTTP door that reaches the throw, POST /api/v1/packages". There are two doors now. That file belongs to the domain:spec seat, so this PR does not edit it.
• packages/runtime/src/app-plugin.test.ts (the 422 boot-seam case): its comment calls AppPlugin "the one other caller of assertProtocolCompat". There are three callers now. This is comment drift and is not edited here.
• The GET install-local listing still serves an entry the rehydrate refused, because it reads the ledger. Only the error log says the entry is not loaded. This matches the posture this door already keeps for an unreadable ledger entry (log, wire unchanged).
• Reseed and purge on a refused entry were not measured.
• The handshake judges the top-level manifest only. A multi-package artifact's per-package ranges were not measured at this door, and POST /api/v1/packages and AppPlugin judge the same scope.
• Envelope dialect: install-local's hand-built errors carry no error.httpStatus, and the dispatcher's carry it on every exit. This predates this PR and is door-wide.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/cloud-connection, @objectstack/metadata-core, @objectstack/runtime, touching 14 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/cloud-connection/package.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

11 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/connect-mcp.mdx (via protocolVersion (literal, a string literal in details))
• content/docs/api/environment-routing.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/deployment/cli.mdx (via MarketplaceInstallLocalPlugin (symbol, a top-level class))
• content/docs/getting-started/examples.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/kernel/contracts/metadata-service.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/kernel/services-checklist.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/permissions/permission-sets.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/permissions/system-context.mdx (via handlePackagesRequest (symbol, a top-level function))
• content/docs/protocol/kernel/error-handling.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/protocol/kernel/http-protocol.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/ui/apps.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/releases/v17/17-4.mdx (via /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))
• content/docs/releases/v17/17-5.mdx (via protocolVersion (literal, a string literal in details), /api/v1/packages (route, a path literal in a comment in handleInstall; a path literal in a comment on a changed line))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cloud-connection/package.json) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 29 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 d13df0c630cee5c24b03391a375941a2424dd9d2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 88ac8501153cdc9fcffcff30ee45d9205bad8ad7 — the merge of head 6ca235b90b92737f4c5b8e6acf5aeb114b3438c7 into base d13df0c630cee5c24b03391a375941a2424dd9d2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 88ac8501153cdc9fcffcff30ee45d9205bad8ad7 && git checkout 88ac8501153cdc9fcffcff30ee45d9205bad8ad7
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d13df0c630cee5c24b03391a375941a2424dd9d2 6ca235b90b92737f4c5b8e6acf5aeb114b3438c7 && git checkout -B drift-repro d13df0c630cee5c24b03391a375941a2424dd9d2 && git merge --no-ff 6ca235b90b92737f4c5b8e6acf5aeb114b3438c7

node scripts/docs-audit/affected-docs.mjs --json d13df0c630cee5c24b03391a375941a2424dd9d2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs d13df0c630cee5c24b03391a375941a2424dd9d2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6ca235b90b92737f4c5b8e6acf5aeb114b3438c7
Local-runs: none

Inputs: card #21762 (body and all five comments: triage 5982323247, unlock 5986276908, claim 5986651164, os-dev-report 5987099192, ACCEPT 5987132296), PR #21805 (body, 9-file list, diff), the check-runs on the head. The PR head was still 6ca235b9 when read. GitHub's diff equals git diff e27a7c0c 6ca235b9 (merge-base, 9 files, +596/-52). origin/main is at 0a348031, four commits past the merge-base (the PR body names three, at d13df0c6); none of the 46 files main changed is among the PR's nine, and an in-memory merge of the two is conflict-free. Governing texts read on origin/main: AGENTS.md Post-Task Checklist step 3, execution-duties.md lines 67-71 and 102-108, contract-review.md, clause2-line.mjs, ADR-0087 D1.

① Derived judgments

Public surface, per package entry (surface = what the built entry declarations reach):

1. @objectstack/metadata-core . — ADDED ProtocolIncompatibleAnswer (interface: status = ProtocolIncompatibleError['status'], the literal 422; code = ProtocolIncompatibleError['code'], the literal OS_PROTOCOL_INCOMPATIBLE; message: string; details = Pick of ProtocolIncompatibleDiagnostic over requiredRange, rangeSource, protocolVersion, targetMajor, migrateCommand). ADDED protocolIncompatibleAnswer(err: ProtocolIncompatibleError): ProtocolIncompatibleAnswer. REMOVED none. Types reached through the two: ProtocolIncompatibleError, ProtocolIncompatibleDiagnostic, RangeSource (via rangeSource), all exported from the same module at BASE with unchanged declaration text. src/index.ts:16 is export * from './protocol-handshake.js', so both names land on .. Right: this entry widens by exactly two names. ./testing (src/testing.ts) re-exports only contract-suite and object-schema-fls-contract: unchanged, right. The 169/171 count and the five SysMetadata*Object union-order re-hashes are build readings I did not repeat; the delta they report is what the source implies.
2. @objectstack/runtime . — the deleted protocolIncompatibleAnswer(deps, err) was a non-exported module function of domains/packages.ts; handlePackagesRequest's signature is unchanged; index.ts does not re-export that module; the dropped type ProtocolIncompatibleError import reached no declaration. Surface unchanged: right. Wire of POST /api/v1/packages: deps.error(message, 422, { code, requiredRange, rangeSource, protocolVersion, targetMajor, migrateCommand }) before and after, same keys in the same order. Byte-identical: right (the 6 pins of packages-install-protocol-incompatible.test.ts change only in their header comment, and Test Core is green).
3. @objectstack/cloud-connection . — src/index.ts is not in the diff. MarketplaceInstallLocalPlugin gains the arrow property private reportProtocolIncompatibleEntry, which the declaration emit prints untyped, so ProtocolIncompatibleDiagnostic does not enter this closure, and a class that already had private members keeps the same nominal assignability. Surface unchanged: right.
4. Dependency edge — @objectstack/metadata-core moves from devDependencies to dependencies in cloud-connection; the lockfile hunk is only that importer move. At BASE no production file under packages/cloud-connection/src imported metadata-core (only test-side files did, through the vitest source alias), so the dev-only placement was right then and the move is required now (four value imports). metadata-core depends only on spec and zod: no cycle. runtime and core already depend on it: no new package in the install closure. Right; not a Clause-② event (no built declaration moves).

Accept-set changes, each named:

5. POST /api/v1/marketplace/install-local — a manifest whose resolved range (engines.protocol, then engines.platform, then engine.objectstack: resolveDeclaredRange) excludes PROTOCOL_MAJOR answered 200 (registered, ledger written, synced) and now answers 422 OS_PROTOCOL_INCOMPATIBLE with error.details = exactly the five members, on the inline and the cloud-snapshot branch, after the id gate and before the unrunnable-code judgement, the collision check, the posture gate, register, the ledger write and syncSchemas. A narrowing of the door's observed accept set, judged right, and judged a pull-back to a declared contract rather than a Clause-② narrowing (the reasoning is in ②). No-range and unparsed-range manifests still install; the handshake's [protocol] warning now reaches ctx.logger.warn (additive, log only). The 11 pins assert each of these and the untouched ledger file on a refused upgrade.
6. kernel:ready rehydrate — an incompatible ledger entry is skipped before register, syncSchemas, bindArtifactHandlers, applySideEffects and maybeHealSampleData; one error line names the code, id@version and the handshake message ending in the replay command; the boot continues; the entry stays, so DELETE and a compatible re-install work (pinned). checkProtocolCompat is acted on for incompatible only, so no-range and unparsed entries rehydrate exactly as at BASE. Right, and the triage's "rehydrate behaviour, measured and pinned" is met: BASE loaded the entry silently (the dev's H6 probe), HEAD pins the opposite.
7. Error-code surface — no new code. OS_PROTOCOL_INCOMPATIBLE sits in ERROR_CODE_LEDGER under its producer @objectstack/metadata-core at 422; cloud-connection relays the producer's own error object, so no ledger row is owed, and every check on the head is green. Right.
8. Envelope — install-local's hand-built { success: false, error: { code, message, details } } is the shape of every other refusal in that handler (none carries httpStatus); the parity pin holds { status, code, message, details } byte-equal with the packages door, driven through the real HttpDispatcher. Right.
9. Recogniser — one shaping helper (protocolIncompatibleAnswer) beside the existing brand predicate (isProtocolIncompatibleError), both doors call both. A grep of the head's production sources finds the five details members shaped nowhere but metadata-core/src/protocol-handshake.ts (the CLI's protocol-version-gap.ts and service-package read checkProtocolCompat for prose, not an HTTP answer). No second copy: holds.

Check-runs on 6ca235b9, latest per name, 35 names with one run each: 33 success, 2 skipped (Console Pin Gate, Packed-tarball smoke (opt-in)), 0 red. Green includes Check Changeset, Lint and Repo Gates, the four Type Check jobs, Test Core 1-6 and its rollup, Build Core, Build Docs, Dogfood Regression Gate 1-3 and Verify CLI, Temporal Conformance, Validate Package Dependencies, Governed Surface Queue Guard, the single-writer and card-claim guards.

② Semver level

Changeset .changeset/21762-install-local-protocol-handshake.md: @objectstack/metadata-core minor, @objectstack/cloud-connection patch, @objectstack/runtime patch. All three are in the fixed group and released (17.6.0, none marked private). Clause-②: yes (widening) stands on its own line in the changeset body and at the head of the PR body, so both gate readers see one spelling.

• metadata-core minor: right — the . entry widens by two names, and yes takes at least minor (AGENTS.md Post-Task Checklist step 3; execution-duties.md:71).
• cloud-connection patch: right — a bug fix in a released package whose built declarations do not move (step 3: a bug fix in a released package takes a patch, never none, never skip-changeset); the dependency move adds no package to the closure.
• runtime patch: right — source moved, surface and wire did not; a released package whose source changed owes a changeset, and skip-changeset would be wrong.

Clause-②: yes (widening) is the right single arm. The dev's open_questions[0] (A keep yes (widening) / B re-declare yes (narrowing)) and the seat's ACCEPT answer A were weighed against the rule text, not adopted:

• The line answers one question over the PUBLISHED contract surface (execution-duties.md:67, :105: Clause-② names only the published contract face; pulling back to a declared contract does not touch it). The published texts on whether this door admits an out-of-range manifest are: ManifestSchema.engines.protocol in @objectstack/spec (declared, ADR-0078 says a declared field is enforced or removed), ADR-0087 D1 ("the package installer checks engines.protocol ... before loading a package's metadata; major-incompatible and not convertible: fail fast with a structured diagnostic"), and the OS_PROTOCOL_INCOMPATIBLE ledger row at 422 in @objectstack/spec. All three said refuse before this PR. No published text said install-local admits such a manifest; the 200 was the declared-but-inert gap the card files as a class (b) defect, and the sibling door, the boot seam (AppPlugin) and the metadata-protocol install primitive already enforced the same sentence. So the 200 to 422 move is 拉回已声明契约, outside Clause-②. The rehydrate's refusal is the same D1 sentence at the load seam.
• The citation discipline :106-107 imposes on the mirror case (a pull-back must cite the declared text; a citation that does not fit demotes the reading) is met: the dev and the seat cite D1 and the sibling door; I add the ManifestSchema field and the ledger row at 422, and both fit.
• clause2-line.mjs gives yes (narrowing) to a diff that "widens one surface and narrows another"; the narrowed thing here is not a published accept set, so the arm does not apply, and taking it would register a BREAKING change with an ADR-0087 disposition marker for a diff that registers nothing new and removes nothing authorable. Option B is wrong. Option A is right.
• The changeset's closing sentence (a client that relied on install-local accepting an out-of-range package gets 422; install a compatible version or run migrateCommand) is the CHANGELOG text an upgrading agent greps and is right to keep; it does not make the change a Clause-② narrowing.

Changeset sentences against the diff: the range order matches resolveDeclaredRange; the five details members match the helper; "an installed earlier version stays as it was" is pinned byte-identical; the restart sentence matches the rehydrate skip and the one error line; the metadata-core export sentence names the two names; the runtime sentence ("response unchanged") is right.

③ Boundary flags

Dev open_questions[0] — answered: A. Keep Clause-②: yes (widening), metadata-core minor, cloud-connection and runtime patch. No re-declaration, no BREAKING banner, no disposition marker. Reasoning in ②.

Dev deviations, each answered:

1. Clause-② surface measured on built declarations — verified against the source (①.1-3); right.
2. Recogniser = existing predicate + new typed helper, not one function taking unknown — accepted: the ruling asked for one helper both doors call, with no second copy; the predicate is already the shared brand check, and ①.9 finds no copy.
3. Rehydrate acts on incompatible only, no new boot warning for no-range entries; the install door now warns on no-range — accepted. D1's "range absent: load with a warning" is now met at the install door; a silent rehydrate of a no-range entry is BASE posture and outside the card's pins. Fine to leave.
4. Cloud-snapshot refusal answers 422, not the id gate's 502 — right: the unrunnable-code refusal in the same handler answers one status on both branches for the same reason; the body is the thing refused, not the upstream.
5. main not merged — fine: verified at 0a348031, no file overlap, clean merge-tree.
6. Lockfile deprecated: annotations reverted — fine: the hunk is only the importer move.
7. --maxWorkers possibly dropped locally — immaterial: the Test Core shards on the head are the gate verdicts.
8. Commit trailer choice — not a review input.
9. Shallow-clone fetch of the teardown-shape control commit — local only.

PR body Acceptance notes, each graded:

• (a) packages/spec/src/api/error-code-ledger.zod.ts:639-642 still says "The one HTTP door that reaches the throw, POST /api/v1/packages" (verified on origin/main). Must be filed: prose in a published-contract file now states a falsehood this PR creates; the claim forbids a packages/spec path here; the seat's pointer on seat post [PM seat] domain:spec — 🟢 os-litant · session_01LAi5BVvQNiYzepSAcsoFLK #6017 is not a card. One-line comment fix in the domain:spec lane.
• (b) packages/runtime/src/app-plugin.test.ts:504 "The one other caller of assertProtocolCompat" — fine to leave: a test comment, and already inexact at BASE (the metadata-protocol install primitive at protocol.ts also calls it).
• (c) GET install-local still lists an entry the rehydrate refused — the dev's "same posture as an unreadable entry" does not hold on the wire: handleList drops an unreadable entry from items (its warning reads "MISSING from the installed-apps list served to the console"), while a protocol-refused entry is served as installed with no marker. Must be filed (p3, follow-up card): the listing owes a marker or omission for a ledger entry the rehydrate refused. Not this card's pin set; the error line carries it today and DELETE works.
• (d) Reseed and purge on a refused entry not measured — must be filed (p3, follow-up card): handleReseed reads the ledger entry and calls applySideEffects(seedNow: true), which loads manifest.translations into i18n and merges manifest.data into seed-datasets before seeding, so on a protocol-refused entry a public door performs part of the load D1 says not to perform, unguarded by the handshake; handlePurge acts on the same entry. Both doors are outside the card's surface and pins.
• (e) Top-level manifest only, per-package ranges unjudged — fine to leave: identical scope to POST /api/v1/packages and AppPlugin; a change would be cross-door and cross-card.
• (f) error.httpStatus dialect — fine to leave: BASE-wide on every install-local exit; both envelopes parse as ApiErrorSchema.

Escalations: none. No flag needs a ruling beyond the seat's; (a), (c) and (d) are filings the seat makes, not conditions on this head.

Implemented-by: claude/issue-21762-install-local-protocol-handshake
Reviewed-by: session_01RWZbGvPFcRKvUqASZtunCU
Independence: INDEPENDENT AGENT

VERDICT: PASS