[objectstack-fleet]

Fixes #24030

Clause-②: no (narrowing)

What changed

POST /api/v1/packages now asks requireWritablePackage (that is, isWritablePackage, the ADR-0070 D2 read-only rule) for the manifest's id. It asks after the 409 … already exists check and before either install limb writes. An overwrite over a package the deployment ships is refused 422 WRITABLE_PACKAGE_REQUIRED: booted by code, installed from the marketplace, or a stored row whose manifest scope is system / cloud. Disable, publish, revert and delete already give that answer. The rule is not re-derived at this door.

• packages/runtime/src/domains/packages.ts: the guard, one call plus its comment, on the POST /packages install path only.
• packages/runtime/src/domains/packages-install-overwrite-readonly.test.ts: the pins, 16 cases over both limbs (the protocol service's installPackage, and the no-protocol fallback).
• .changeset/24030-install-overwrite-readonly-package.md: @objectstack/runtime minor under the launch-window convention for a breaking narrowing, with FROM / TO for an integrator, the Clause-② line, and the ADR-0087 disposition not-required (no-migration-prescription).

A CONTRACT_REVIEW_TIER review is owed before the queue (narrowing); the seat runs it.

Answers, path by path

Request	Before	After
Overwrite over a read-only id (overwrite: true in the body, or ?overwrite=true)	201, registry row replaced (and sys_packages written on the protocol limb)	422 WRITABLE_PACKAGE_REQUIRED, nothing written
Install over an existing id without overwrite (read-only or not)	409	409, unchanged: the guard sits after it
Install of a new id, with or without overwrite	201	201
Overwrite of an authored package	201	201

Measured

Reproduction at base b74434c58. A throwaway probe on the dispatcher harness (real ObjectQL with registerApp, real ObjectStackProtocolImplementation), deleted afterwards:

PROBE protocol code:        status=201 rowReplaced=true version=2.0.0 source=authored manifests.has=true sys_packages.publish=1
PROBE protocol marketplace: status=201 rowReplaced=true version=2.0.0 source=authored manifests.has=true sys_packages.publish=1
PROBE fallback code:        status=201 rowReplaced=true version=2.0.0 source=authored manifests.has=true sys_packages.publish=0
PROBE fallback marketplace: status=201 rowReplaced=true version=2.0.0 source=authored manifests.has=true sys_packages.publish=0

The new pin file at base: 8 failed | 8 passed. Every refusal row is red with expected 201 to be 422; every CONTROL row and the 409 row are green.

At head 8dd02793f: 16 passed (16).

Ablation, on the committed fix. scripts/ablation-replace.mjs replaced the guard call with null: anchor 1 to 0, marker 0 to 1, blob b0bb67c44296 to 4e5996f62b61. The test reaches packages.ts by relative import, so no rebuild was needed. Result: 8 failed | 8 passed. The 8 refusal rows went red; the 6 CONTROL rows and the two 409 rows stayed green. Restore: blob equals HEAD b0bb67c44296, and git diff HEAD is empty.

The dispatch's mechanism assumptions

1. Reproduction: reproduced on both limbs (above). The protocol limb also wrote the sys_packages row: the package service's publish was called once.
2. Unknown id: isWritablePackage answers writable for an id nothing installed. An install of a new id with overwrite: true answers 201, pinned on both limbs. So the guard runs on every path that reaches a write without refusing a fresh install.
3. 409 ordering: the guard sits after the 409. A non-overwrite install over a read-only id keeps its 409 (pinned on both limbs); an overwrite gets the 422.
4. Who sends overwrite: no first-party caller does.
   • packages/client exposes packages.install(m, { overwrite }); only its own tests send it.
   • The CLI has no caller of this door.
   • objectui at the .objectui-sha pin f8267df93 sends no overwrite: git grep for overwrite: true / overwrite=true finds 0 hits. Its package create posts { manifest } and expects the 409 on a duplicate.
   • No legitimate use was found that this narrowing breaks.

Tests and gates (local, at 8dd02793f)

• turbo run build --filter='@objectstack/runtime...' --concurrency=2: 31 of 31 tasks successful, verify-lock VERDICT command-exit 0.
• pnpm --filter @objectstack/runtime typecheck: exit 0, with check:test-typecheck: OK. The new test file is in the tsconfig.test.json program (--listFiles count 1) and has no tsc error.
• pnpm --filter @objectstack/runtime exec vitest run --project local --maxWorkers=2: 405 passed (405) files, 6157 passed | 19 skipped tests, exit 0.
• pnpm exec eslint --no-inline-config on the two changed .ts files: exit 0.
• node scripts/pm/dispatch-gates.mjs --commands (64 families, from merge base b74434c58): 62 exit 0. The other 2 are NOT MEASURED, each exit 3 (PREREQUISITE NOT MET):
  • check:dual-build-cjs-loads needs every package's dist/, and only the runtime closure was built locally.
  • check:type-check-debt: its closure build never acquired the shared verify lock (queue-timeout).
  • --ran reconciliation: 64 accounted, 0 UNRUN.
• Lint & Repo Gates (the repo-wide eslint run), TypeScript Type Check, Test Core and Build Core: CI on this PR. test:repo was not run locally; CI owns it.

Acceptance notes

• Finding, class (a): an authored package can declare a deployment-shipped scope and so lock itself.
  • POST /api/v1/packages with manifest.scope: 'cloud' (or 'system') answers 201 and stores an authored row. isWritablePackage judges that row read-only, so DELETE and PATCH …/disable then answer 422 WRITABLE_PACKAGE_REQUIRED.
  • Before this PR, an overwrite with scope: 'project' was the one API exit. After it, that overwrite is refused too, as the card's Done-when requires for the scope arm.
  • Measured at head with a throwaway probe, since deleted: create=201 source=authored storedScope=cloud delete=422 disable=422 overwriteToProject=422.
  • Handed to the seat for filing and not fixed here. This door does not refuse a key that the declaration (ManifestSchema.scope) admits, so the remedy is a contract decision.
• The spec's overwrite description ("Overwrite an already-installed package id instead of answering 409 Conflict") does not mention the read-only refusal. This is a note on the doc surface only.
• origin/main was not merged before opening. Main has gained two commits since the base (c4111c676, d731b89a6); they touch no file in packages/runtime, packages/metadata-protocol or packages/objectql. CI runs on the merge ref.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 1 documentable anchor(s).

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

• content/docs/permissions/system-context.mdx (via handlePackagesRequest (symbol, a top-level function))

What this run could not see

• 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 — 26 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 5c2ac83a230d2eec038502a23a8142153cad814d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 82f6a80c4300e1c4748abb0ab49d04e6ccaeeb61 — the merge of head 8dd02793f0f6b14c9d09098f278993944f350b9b into base 5c2ac83a230d2eec038502a23a8142153cad814d, 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 82f6a80c4300e1c4748abb0ab49d04e6ccaeeb61 && git checkout 82f6a80c4300e1c4748abb0ab49d04e6ccaeeb61
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5c2ac83a230d2eec038502a23a8142153cad814d 8dd02793f0f6b14c9d09098f278993944f350b9b && git checkout -B drift-repro 5c2ac83a230d2eec038502a23a8142153cad814d && git merge --no-ff 8dd02793f0f6b14c9d09098f278993944f350b9b

node scripts/docs-audit/affected-docs.mjs --json 5c2ac83a230d2eec038502a23a8142153cad814d

⚠️ 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 5c2ac83a230d2eec038502a23a8142153cad814d → 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: 8dd02793f0f6b14c9d09098f278993944f350b9b
Local-runs: none
Scope: packages/runtime/src/domains/packages.ts, packages/runtime/src/domains/packages-install-overwrite-readonly.test.ts, .changeset/24030-install-overwrite-readonly-package.md + packages/metadata-protocol/src/package-writability.ts, packages/metadata-protocol/src/protocol.ts, packages/objectql/src/engine.ts, packages/objectql/src/registry.ts, packages/runtime/src/http-dispatcher.ts, packages/spec/src/api/package-api.zod.ts, docs/adr/0070-package-first-authoring.md, scripts/check-changeset-no-major.mjs, scripts/check-adr-0087-registration.mjs

Inputs: card #24030 (body and all three comments: the triage grade 6223773566, the claim 6224439457, the dev report 6225324756), PR #24055 (body, file list, net diff against main at merge-base b74434c58), and the check-runs on the head. Not the dispatch order, not the dispatching seat's conclusions.

① Derived judgments

The diff is one guard call at one door (packages.ts:1399–:1400), 16 pins, and a changeset. Every accept-set change it implies, read in the cited code:

1. POST /api/v1/packages with overwrite (wrapped-body true or ?overwrite=true) over an id isWritablePackage judges read-only: 201 with the registry row replaced → 422 WRITABLE_PACKAGE_REQUIRED, nothing written. Right. The guard is requireWritablePackage(deps, qlService, pkgId, …) (packages.ts:1399), the same helper with the same qlService engine the four sibling doors pass (:1591 disable, :1618 publish, :2095 revert, :2290 delete), and that helper is isWritablePackage (packages.ts:527; package-writability.ts:85–:93): booted id in engine.manifests, or a stored row whose manifest scope is system/cloud. The rule is read, not re-derived, as the card's Done-when orders. The refusal envelope is the sibling doors' own (422, code: WRITABLE_PACKAGE_REQUIRED, details.packageId, the ADR-0070 docs link) — no new error code is minted, as the claim's Clause-② basis states. Pinned on both limbs for all three read-only kinds (code-booted, marketplace-installed, cloud-scoped stored row) plus the query-string spelling, with the row object, its source, and the engine.manifests entry asserted identical before and after, and the registry.installPackage / protocol.installPackage / package.publish spies asserted uncalled.
2. The guard sits before both limbs' writes. Right. It runs before resolveProtocol is even called (:1414), so the protocol limb's installPackage (protocol.ts:31295, which itself asks no writability) and the no-protocol fallback registry.installPackage(manifest, 'authored', settings) (:1431) are both behind it. The sys_packages write on the protocol limb (the package service's publish) is therefore refused too — the dev measured it at base and the pins assert it at head.
3. Install over an existing id without overwrite: 409 unchanged. Right. The guard is placed after the 409 (:1378–:1383), so a non-overwrite install keeps the duplicate answer for read-only and authored ids alike. Pinned on both limbs.
4. Install of a new id, with or without overwrite: 201 unchanged. Right. For an id neither in engine.manifests nor the registry, isWritablePackage answers writable (package-writability.ts:92), so the guard is a pass-through. Pinned on both limbs; the CONTROL rows prove the same spies fire on the allow path, which is what makes the refusal rows' "nothing written" a measurement.
5. Overwrite of an authored base: 201, row replaced. Right. Pinned on both limbs, with the protocol limb's installPackage and publish call counts.
6. One accept-set change beyond the card's four rows, disclosed by the dev (deviation 5): the guard is unconditional, not gated on overwrite. The one non-overwrite case it can refuse is an id that engine.manifests holds but the registry no longer does — verb install, 422. I read the reach: engine.manifests is written only at engine.ts:4348 (construction) and :7901 (registerApp), never deleted from; registry.uninstallPackage (registry.ts:5679) removes the row only; and DELETE /packages/:id refuses a read-only id at :2290 before it reaches protocol.deletePackage's registry.uninstallPackage (protocol.ts:27013). So the state is reachable only by an internal registry.uninstallPackage of a booted package, never over the API. In that state the old 201 installed an authored row over a booted id — the exact defect row this card names — so the 422 is the same ADR-0070 D2 rule, correctly applied. Judged right. Not pinned, and not named in the changeset's Unchanged clause; that clause is phrased on "a new id", which this id is not, so the clause stays true. Recorded as a note, not a finding.
7. Public surface. No export, type, spec schema, or error-vocabulary change; packages/metadata-protocol, the predicate, the sibling doors and the ADR-0087 conversion layer are untouched — every hold-off in the claim held. Governed Surface Queue Guard is green: no governed path in the file list.
8. The pins run where CI sees them. The new file matches the runtime local project's src/**/*.test.ts include (vitest.config.ts:218) and reaches packages.ts by relative import through ../http-dispatcher.js, so the ablation the dev reports (guard replaced with null: the 8 refusal rows red, the 8 CONTROL/409 rows green) measured the committed code. The harness is a real ObjectQL (registerApp for the booted ids, registry.installPackage(…, 'authored') for the scope-only row) and the real ObjectStackProtocolImplementation on the protocol limb.

② Semver level

@objectstack/runtime publishes (18.0.0-next.2, in the changeset fixed group), so a changeset is owed and skip-changeset would be wrong; one is present. The diff narrows a REST door's accept set, so the declaration Clause-②: no (narrowing) is the right arm — it widens nothing and adds no code — and (narrowing) is BREAKING (AGENTS.md Post-Task Checklist item 3). The level minor is right: during the launch window a breaking change ships as minor, and scripts/check-changeset-no-major.mjs refuses a major outside pre-mode. The changeset carries the BREAKING banner, the FROM → TO mapping, the integrator's one-line fix (install under an owned id, or customise beside per ADR-0131 D6), and exactly one ADR-0087 marker, not-required (no-migration-prescription) — right, since no spec key, authorable spelling, stored shape or export moves; only a runtime door's answer changes. Check Changeset and the Lint lanes that run check:adr-0087-registration are green.

Clause-②: no (narrowing) — on the PR body and in the changeset, matching the claim's line (6224439457).

③ Boundary flags

open_questions: none declared. Dev deviations (report 6225324756), each answered:

• origin/main not merged before opening. Answered: the two commits main gained since the base touch no file under packages/runtime, packages/metadata-protocol or packages/objectql; the PR reads mergeable; CI ran on the merge ref and is green. Accepted.
• First full-suite launch used the bare -- spelling and was stopped before any test ran; the numbers come from the relaunch. Process hygiene with no bearing on the diff. Accepted.
• check:dual-build-cjs-loads and check:type-check-debt not measured locally (exit 3). Closed by the check-runs: Lint & Repo Gates and Type Check · debt ledger are green on the head.
• test:repo and the repo-wide eslint not run locally. Closed by the check-runs: Test Core (all six shards and the aggregate) and Lint · ESLint are green.
• Guard placed unconditionally, after the 409. Judged right in ① item 6; the single extra refusal is the same rule on an API-unreachable state. Note recorded; nothing owed.
• Base probe printed served.writable=undefined. A probe artefact, not used as evidence. Accepted.

Out-of-scope findings, each escalated:

• Class (a): an authored install may declare scope: 'cloud' or 'system' and lock itself (ManifestSchema.scope admits it at the install door; isWritablePackage then reads the stored row's scope; DELETE and disable answer 422; this PR closes the overwrite-to-project exit the card's Done-when orders closed). Escalated to the seat for filing as its own card. It is a contract decision at the install declaration, not this PR's surface, and this PR delivers what the card orders for the scope arm. Not blocking.
• The spec's overwrite describe text (package-api.zod.ts:337) does not mention the read-only refusal. Noted for the seat; the sentence stays true (it names the 409 bypass), and a describe-text edit is a packages/spec touch owing regenerated artifacts, not owed on this card. Not blocking.

Check-runs on the head, re-read 2026-10-16T22:09Z after the Test Core aggregate finished: 40 runs, all completed — 34 success (Build Core, Test Core and its six shards, TypeScript Type Check and the four Type Check · lanes, Lint & Repo Gates and the eight Lint · lanes, Check Changeset, Governed Surface Queue Guard, Check PR Size, Dogfood Regression Gate, Auto Label, Check Documentation Links, Flag docs affected by code changes, filter, and the four claim/single-writer/part-of checks) and 6 skipped by path filter (Build Docs, Console Pin Gate, Dogfood Verify CLI, the dogfood shard matrix, Temporal Conformance, Packed-tarball smoke). None failed, none in progress.

Implemented-by: claude/issue-24030-overwrite-readonly-package
Reviewed-by: session_018t6a5rvqPRvEDMCVVW9kYT

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

席位核对

ACCEPT · #24030 · domain:cli seat 2 · os-tesla · session session_018t6a5rvqPRvEDMCVVW9kYT · 2026-10-16T22:11Z · reviewed head 8dd02793f0f6b14c9d09098f278993944f350b9b, against GitHub and the branch, not against the report's prose. Holder of claim 6224439457; report on #24030.

1. Shape.
   • Draft, base main, assignee os-tesla. Line 1 is Fixes #24030; Clause-②: no (narrowing) is in the body and the changeset.
   • 3 files, +296 / −0.
   • check-governed-merges --pr 24055: NOT governed; 296 changed lines. mergeable_state reads clean.
2. The change, read by this seat against the claim's surface.
   • POST /packages calls requireWritablePackage(deps, qlService, pkgId, overwrite ? 'overwrite' : 'install') after the 409 check and before either limb writes. It reads isWritablePackage, as the four sibling doors do, and adds no error code.
   • Only the claimed install path in packages.ts changes, plus one new pin file and one changeset.
   • The guard also runs without overwrite (dev deviation 5). The one extra refusal it can give is an id held in engine.manifests with no registry row. The same D2 rule judges that id read-only, and the review found the state reachable only through the internal registry.uninstallPackage. Accepted, not pinned.
3. Review of record: CONTRACT_REVIEW_TIER (the narrowing face), 6225666982 on this head: PASS, Local-runs: none, scope the three diff paths plus the eight files they cite.
4. Changeset: one, @objectstack/runtime minor (the launch-window spelling of a breaking change, scripts/check-changeset-no-major.mjs). It carries the BREAKING banner, FROM / TO, the integrator's fix and the ADR-0087 marker not-required (no-migration-prescription).
5. Gates, pinned to the head. Check-runs on 8dd02793f, read at this stamp, latest run per name: 40 names, 34 success, 6 skipped, 0 failure, nothing running.
   • The successes include Build Core, Test Core 1–6/6, TypeScript Type Check, Lint & Repo Gates, Check Changeset and Governed Surface Queue Guard.
   • The 6 skips are roster names.
   • The dev's local subset: 62 of 64 derived commands exit 0. check:dual-build-cjs-loads and check:type-check-debt are NOT MEASURED locally (exit 3), and CI covers both.
   • Runtime: 405 files, 6157 passed. The new pins: 16, red 8 / green 8 at base, with the refusal rows red under ablation and the CONTROL and 409 rows green.
   • At base, both limbs answered 201 and replaced the row; the protocol limb also published to sys_packages.
6. Accepted deviations:
   • no main merge (two upstream commits, no overlap);
   • the stopped first test launch (the -- trap), relaunched under its own process group;
   • the two local NOT-MEASURED gates;
   • test:repo and the repo-wide lint left to CI.

Escalated by the dev and the review, filed by this seat in this window: an authored install may declare scope: 'cloud' or 'system' and so lock itself, and this PR closes its one API exit, the overwrite. That is a contract decision at the install declaration, not this door.

Noted, not filed: the spec's overwrite describe text (packages/spec/src/api/package-api.zod.ts:337) does not mention the read-only refusal. It rides the card above.

Landing: pr_ready + automerge_enable through the relay, in this act. The card closes on the merge (Fixes).

---

Generated by Claude Code