fix(cloud-connection,cli): install a .custom export into the target's writable pair - #30207

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/cloud-connection, touching 38 documentable anchor(s).

36 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json dfafae81324e508cc666171d3385a15b89f31050.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

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

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

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 dfafae81324e508cc666171d3385a15b89f31050 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6be0aea6a64d61bac1d2831d33da398c967deee7
Local-runs: none
Scope: packages/cloud-connection/src/marketplace-install-local-plugin.ts, packages/cloud-connection/src/marketplace-install-local-customization-pair.ts, packages/cloud-connection/src/marketplace-install-local-customization-pair.test.ts, packages/cloud-connection/src/marketplace-install-local-customization-pair-install.test.ts, packages/cloud-connection/src/marketplace-install-local-override-gate.test.ts, packages/cloud-connection/src/marketplace-install-local-extension-field-suffix.test.ts, packages/cli/src/commands/package/install.ts, packages/cli/test/package-install-customization-pair.test.ts, packages/cli/test/package-export.test.ts + packages/metadata-protocol/src/package-writability.ts, packages/metadata-protocol/src/protocol-customization-package.ts, packages/metadata-protocol/src/protocol-save.ts, packages/metadata-protocol/src/protocol-packaged-base-refusal.ts, packages/spec/src/kernel/unmanaged-install.ts, packages/spec/src/meta-spelling/manifest-collection-spelling.ts, packages/spec/src/api/package-lifecycle.zod.ts, packages/spec/src/api/protocol.zod.ts, packages/spec/src/api/errors.zod.ts, packages/runtime/src/domains/packages.ts, packages/types/src/thrown-http-error.ts, packages/qa/dogfood/test/package-export-reinstall-custom-pair.dogfood.test.ts, packages/qa/dogfood/test/package-export-bundle-round-trip.dogfood.test.ts, docs/adr/0146-studio-designs-setup-administers-one-editor-per-item-paired-customize-package.md

Face, read off the committed tree (10 files, gh api .../pulls/30207/files): no packages/spec/src/** path, no governed path (record-recognisers.mjs --paths on the file list derives no face and defers to the changeset's Clause-②: line, which reads no with no arm). The review is owed to the dev's measured open_question (a possible narrowing arm), so it is served at this tier with ④ and the narrowing-face floor: every non-prose path of the diff is in Scope. The PR author is objectstack-fleet[bot] (relay); the implementing identity is the claim's branch.

① Derived judgments

Accept-set and public-surface changes the diff makes, each judged:

1. Pair id routed off the managed path (marketplace-install-local-plugin.ts, handleInstall after step 1d', customizationBasePackageId(manifestId) !== null ⇒ installCustomizationPair). Correct and the card's fix: ADR-0146 D3 says the pair is "an ordinary writable package", D2 that its items are stored rows a served read reads (protocol-served-overrides.ts#listServedOverrides selects package_id = pair, state: 'active', card comment 6633535319). Registering it as code (manifest.register + ledger + syncSchemas) was never the declared contract. Ordered after 1c' (dependency check, so a missing base is refused 422 before the pair branch), 1c'' (__c reservation), 1e (install mode), 1d (unrunnable code), 1d' (withheld maps): the pre-existing refusals still apply to a pair body. Judged right.

2. Pair body keys with no item form refused 422 VALIDATION_ERROR (marketplace-install-local-customization-pair.ts#planCustomizationPairInstall: a key not in PLURAL_TO_SINGULAR, not viewItems, not objectExtensions, carrying content, whose UNMANAGED_INSTALL_KEY_DISPOSITIONS entry is code/uncopyable/envelope/converted or absent). Read against what the export writes (packages/runtime/src/domains/packages.ts#assemblePackageManifest: the PLURAL_TO_SINGULAR collections minus datasources/emailTemplates, viewItems, objectExtensions, then id/name/version/label?/namespace/dependencies/withheldMaps?): every key a pair export writes is admitted (id/namespace = base, name/version = identity, label/withheldMaps/data/installModes = door). translations is not in PLURAL_TO_SINGULAR (manifest-collection-spelling.ts, ends at books) and is converted in the table, so it is refused as the test pins; the export never writes it for a pair. Not a narrowing of a published accept set: POST /api/v1/marketplace/install-local has no request/response schema in packages/spec/src/api/** (grep: only ledger prose and package-lifecycle.zod.ts comments name the route), and the refused bodies installed nothing that worked (0 overrides served, pair read-only, measured in 6633535319). Judged right; Clause-②: no holds.

3. Pair inside a multi-package artifact refused 422 (details.pairs). The published bundle flow (GET /packages/export, PackageExportBundleSchema) installs entries one at a time, { manifest: entry } (package-export-bundle-round-trip.dogfood.test.ts lines 202, 412), so no published consumer sends a pair inside packages[]. The refusal lists every pair, before any write. Judged right, not a narrowing of a published path.

4. Pair manifest refused 400 PLUGIN_MANIFEST_INVALID when it lacks the explicit namespace or the base dependency (customizationPairManifestRefusal, protocol-customization-package.ts line 206). The same predicate is asked on main by installPackage (protocol-package-install.ts:249), POST /packages (runtime/src/domains/packages.ts:1719) and the duplicate door (protocol-package-commits.ts:241); install-local asking it is the declared contract pulled back, not a new requirement. Current exports carry both keys (PackageExportManifestSchema.namespace / .dependencies). Judged right.

5. Pair already read-only refused 409 RESOURCE_CONFLICT before the ensure door (isWritablePackage(ql, manifestId) from package-writability.ts:73: engine.manifests.has first, then READ_ONLY_PACKAGE_SCOPES by manifest scope, else writable). The three remedies are derived from this.ledger.has, this.bootUserCodeIds, and manifest scope; the ensure door would otherwise answer 201 created: true, writable: false (dev measured). Judged right.

6. Writes through saveMetaItem with mode: 'publish', packageId: pair, actor: userId, in loadOrder (SaveMetaItemRequestSchema, protocol.zod.ts:1103: publish writes the active row; protocol-save.ts#saveMetaItemUnaudited line 498/1651 state: 'active'). The save door's own judges run on every item: isWritablePackage (line 1881, WRITABLE_PACKAGE_REQUIRED), overrideWriteVerdict/refusePackagedBaseOverride (the D2 declaration and closure), objectExtensionItemRefusal (line 1197, an object_extension named by its target, as the planner names it). So the dev-flagged gap in the install-time gate (overrideWriteItemsOf walks PLURAL_TO_SINGULAR keys only, protocol-packaged-base-refusal.ts, and so not viewItems) is closed by the save door for a pair. Judged right.

7. Answer shape: a pair answer carries customizationPair { basePackageId, packageId, created, writable }, writtenCount, written, note, optional seeded/withheldMaps, and no hotLoaded/storageDir. Public-surface reading: @objectstack/cloud-connection exports is . only, whose entry (src/index.ts) exports MarketplaceInstallLocalPlugin and MarketplaceInstallLocalPluginConfig; the route answers c.json(...) untyped, so no exported type reaches the body. @objectstack/cli exports (., ./console, ./hook-body) reach PackageInstallCommand (an oclif Command class, no response type on it). No spec response schema exists. Nothing published is widened; no new ErrorCode is minted (RESOURCE_CONFLICT, PLUGIN_MANIFEST_INVALID, SERVICE_UNAVAILABLE, NOT_OVERRIDABLE are ledger rows; VALIDATION_ERROR is errors.zod.ts:55). Judged right; Clause-②: no without an arm. A no (narrowing) arm would be BREAKING under AGENTS.md step 3 (ADR-0087 marker, migration) for shapes that never produced a working install: not warranted.

8. CLI (packages/cli/src/commands/package/install.ts): prints the pair answer; a pair id answered without customizationPair (older runtime) prints an error naming DELETE .../install-local/{id}, upgrade, restart, and exits 1. Correct reading of the mixed-version matrix; an older CLI against a new runtime prints the managed success lines (benign: the install did land). Judged right.

9. Metadata-protocol: none holds (AGENTS.md Post-Task Checklist step 3): no spec key, value or type added, removed or re-meant; the manifest requirement in item 4 is already the published predicate; the door refusals are install behavior, not authoring protocol.

② Semver level

.changeset/30106-install-custom-pair-into-writable-pair.md: @objectstack/cloud-connection: patch, @objectstack/cli: patch, both released (package.json has no private). Kind none ⇒ patch is the level step 3 prescribes; both line-initial declarations present and matching the PR body. No content/docs/releases/ edit, no file outside the card (packages/qa/dogfood/** untouched, the two pair dogfood files pass at head per the dev's report). Consistent.

③ Boundary flags

• open_question, Clause-② re-check (A keep no / B yes (narrowing)): A. Grounds in ① items 2, 3, 4, 7. B's spelling is also malformed under step 3 (the arm pairs as no (narrowing)), and the arm is BREAKING, which the facts do not support: nothing a consumer could rely on is taken away.
• Cached-manifest location not keyed by OS_HOME (LocalManifestSource default CWD/.objectstack/installed-packages): out of this card; a pair no longer writes one. Follow-up card owed (dev's out_of_scope class a); not a defect of this PR.
• engine.manifests keeps an uninstalled id until restart: read in package-writability.ts:77; the 409 remedy names the restart; the dogfood "stale code pair" sequence was measured. Out-of-scope class a, not a defect of this PR.
• Pair export omits emailTemplates and translation items: read in assemblePackageManifest (exportPluralKeys filter). Those overrides do not round-trip today; a card on the export side, not this door. Noted.
• --install-mode unmanaged on a pair takes the unmanaged copy path: only when the pair manifest declares installModes including unmanaged, which the ensure door never writes and the export never adds (6633535319: INSTALL_MODE_NOT_PERMITTED otherwise). Noted, not a defect here.
• Authorization of the pair write: install-local's route requires manage_metadata (INSTALL_LOCAL_CAPABILITY, plugin line 377, checked at 5392); the ensure door's docblock leaves the walled-posture judgment to the HTTP door. A managed install already changes environment-wide state under the same capability, so the pair path widens no permission boundary. Judged, not a defect.
• Observation, not must-fix: a pre-fix ledgered pair whose boot manifest.register failed (the lenient hotLoaded: false path) reads writable, so the new path writes rows and leaves the stale ledger entry, which a later boot may register as code again. Pre-fix state only; the 409 remedy (DELETE, restart) clears it. Suggest a follow-up card: refuse or auto-remove a ledger entry for a pair id at step 3.
• Observation: the answer's version echoes the export's version; the target pair's row keeps the ensure door's 0.1.0 or its existing version. Informational.
• Check-runs at the head when read: 21 success, 13 skipped, 12 in progress (Test Core 1-8, four Lint jobs). Landing waits on all green; this record does not substitute for that read.

④ Design judgment

Against ADR-0146 D2/D3 and the card's acceptance:

• Target serves the overrides / customizations read lists them: every item becomes a sys_metadata row of the pair in active state through the save door a Studio edit takes (① item 6); listServedOverrides reads exactly those rows. Pinned at the route (marketplace-install-local-customization-pair-install.test.ts "writes every item through the save door", asserting the exact saveMetaItem calls, register/syncSchemas never called, no ledger file) and measured e2e in the PR body (overrides: 2, both labels served across two restarts). Holds.
• Pair stays writable: nothing enters engine.manifests, the ledger or the cached-manifest directory for the pair id; the answer carries writable: true only after the ensure door answered it; writable !== true is refused 409. Measured ensure writable: true, a further save 200. Holds.
• Failure is not reported as success: a refused save answers the save's status and code (resolveThrownHttpError, thrown-http-error.ts:225, reads .status then .statusCode), naming the item and path; refusal tests assert status (422/409/400/503) and code (VALIDATION_ERROR, RESOURCE_CONFLICT, PLUGIN_MANIFEST_INVALID, SERVICE_UNAVAILABLE) per the ADR-0112 envelope; the CLI's non-OK path prints status and code and exits 1. Holds.
• Rollback: a pair this install created is deleted through deletePackage({ packageId, actor }) (protocol.zod.ts:1681 failedCount); a non-zero failedCount or a thrown delete is logged at error and said in the answer; a pre-existing pair is kept with details.written/details.notWritten, every item re-saved on the next run. Partial publish into a pre-existing pair is disclosed, not hidden. Holds.
• Nothing registered as code any more: the three pre-existing tests that pinned registered === [PAIR] now pin registered === [] with the saves named; the install path's installCustomizationPair returns before 1f/2a-2e's register, ledger write and syncSchemas. Holds.
• Refusals before any write: planner, override gate 2d, field-patch check 2e, manifest predicate, read-only pre-check, door presence (503) all precede the ensure call; the ensure door itself writes only through installPackage and is idempotent (PAIR_FLIGHTS). Holds.
• Narrowing against the published spec on main: the refused bodies and the bundled pair take no declared capability away at the consumer; they make D2/D3's own posture real at this door. The one-item-per-identity rule uses the save door's own key (itemDiscriminator, (name, locale) for email_template), so the planner and the row store agree.

No must-fix found.

Implemented-by: claude/project-thread-j915rv
Reviewed-by: session_01Utp6CbPxYq1wQmUNWvMZkC

VERDICT: PASS

domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC

席位核对

ACCEPT · head 6be0aea6a64d61bac1d2831d33da398c967deee7 · card #30106 (claim 6646484259) · 2026-11-05T02:28Z

• Shape: draft PR to main, author objectstack-fleet[bot] (relay pr_create), attribution block then Fixes #30106 on its own line; no other open card number sits next to a closing keyword. 10 files, +1325 −40 (below the 3000-line human-merge threshold). No governed path, no packages/spec/src/** path ⇒ not Tier H; the seat lands it.
• Premise measured: the dev confirmed the seat's assumption (the old path registered the pair as code and wrote no sys_metadata row) and found the pair also turned read-only; fix and pins in the PR body.
• Gates (check-runs on this head): 48 runs, 35 success, 13 skipped, 0 failed. Lint & Repo Gates success, TypeScript Type Check success. The 13 skips are path-gated UI/docs jobs, opt-in harnesses, push-only dogfood and the schedule gate; check-expected-skips.mjs could not run in this container (its yaml dependency is not installed), so the skip roster was read by name, not by the tool.
• Contract review: PASS at CONTRACT_REVIEW_TIER, record 6647885067 on this head. Clause-②: no stands (no published schema or exported type reaches the install-local body or answer); Metadata-protocol: none stands; changeset patch on both released packages, consistent.
• Prose read against the diff: the changeset's "Before", "Now", "Refusals, nothing written", "A save refused part-way" and "The CLI" bullets; each matches the code and tests.
• Accepted deviations: the file surface grew from the claim's packages/runtime/src/domains/packages.ts to the door it hands off to, packages/cloud-connection/src/marketplace-install-local-* (the actual install door). In the same package family and in the claim's "and the install door it calls"; no packages/spec.
• Out of scope: filed install-local: an uninstalled package still reads read-only until a restart, because engine.manifests keeps its id #30215 (an uninstalled package keeps reading read-only until a restart) and install-local: the cached-manifest directory is resolved from the working directory, not OS_HOME, so os dev --fresh rehydrates a previous install #30217 (the cached-manifest directory follows the working directory, not OS_HOME). Noted, not filed (read from code, not measured): pair export omits emailTemplates and translation items; --install-mode unmanaged on a pair; overrideWriteItemsOf not reading viewItems (covered at write time by the save door, per the review).
• Writes: api_writes 2, mcp_calls 5, all reads.
• Landing: pr_ready then automerge_enable through the relay.