@@ -0,0 +1,18 @@
+---
+'@objectstack/runtime': minor
+---
+
+fix(runtime)!: `POST /api/v1/packages` with `overwrite` refuses a read-only package with `422 WRITABLE_PACKAGE_REQUIRED`, as disable, publish, revert and delete already do
+
+ADR-0070 D2 makes a package the deployment ships read-only: one booted by code, one installed from the marketplace, and one whose manifest `scope` is `system` or `cloud`. `isWritablePackage` is that rule, and the four lifecycle doors that change a package (`PATCH /packages/:id/disable`, `POST /packages/:id/publish`, `POST /packages/:id/revert`, `DELETE /packages/:id`) refuse such a package with `422 WRITABLE_PACKAGE_REQUIRED`. The install door's `overwrite` option only bypassed the `409 … already exists` answer and never asked the rule. So an overwrite over a read-only package answered `201` and replaced its registry row with an authored one, and with a `protocol` service composed it also wrote that package's `sys_packages` row, while the server went on treating the package as read-only. The install door now asks the same rule, for the manifest's id, before either install path writes anything.
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, object definition or stored shape is added, removed, renamed or re-shaped, and no exported declaration is removed or narrowed, so there is nothing for `objectstack migrate meta` to rewrite. What changes is the answer one runtime REST door gives a caller who asks it to overwrite a package the deployment ships; the remedy is to install under an id the caller owns or to customise beside the shipped package, never a rewrite of a package source or a stored row. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
+
+**BREAKING** (a REST door's accept set narrows), shipped as `minor` under the launch-window convention for breaking changes.
+
+- **FROM:** `POST /api/v1/packages` with `overwrite: true` in the wrapped body, or `?overwrite=true`, and a manifest whose `id` names a read-only package, answered `201` and replaced that package's registry row.
+- **TO:** the same request answers `422` with `error.code: 'WRITABLE_PACKAGE_REQUIRED'` and `error.details.packageId`, and writes nothing: no registry row, no `sys_packages` row. It is the refusal the four lifecycle doors give.
+- **Unchanged:** an install of a new id, with or without `overwrite`, and an overwrite of a package an organization authored answer `201` as before. An install over an existing id without `overwrite` still answers `409`.
+- **The fix for an integrator:** a package the deployment ships is managed by the deployment (its code release, or a new marketplace version), not over this API. Install the manifest under an id you own, or customise what the shipped package provides beside it as environment-level state (ADR-0131 D6).
@@ -0,0 +1,261 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `POST /packages` with `overwrite` — the ADR-0070 D2 read-only rule at the
+ * install door (#24030).
+ *
+ * ## The defect
+ *
+ * `overwrite` only bypassed the `409 Package '…' already exists`; nothing
+ * asked whether the id was a read-only package. An overwrite naming an id that
+ * `registerApp` booted (code, or a marketplace install) answered `201` on
+ * both limbs and REPLACED the registry row, stamped `source: 'authored'`,
+ * while `engine.manifests` still held the id, so the served row read
+ * `writable: false`. Disable, publish, revert and delete already refused that
+ * same id `422 WRITABLE_PACKAGE_REQUIRED`.
+ *
+ * ## What is asserted, and why it is not the status alone
+ *
+ * The harm is the replaced row, so every refusal reads the observables: the
+ * registry row is the SAME object it was (the registry's `installPackage`
+ * replaces the row object), `engine.manifests` holds the same manifest, and no
+ * write was attempted: neither `registry.installPackage` nor, on the protocol
+ * limb, `protocol.installPackage` and the `package` service's `publish` (the
+ * `sys_packages` write). The engine is a REAL `ObjectQL`: the read-only ids are
+ * booted through its own `registerApp`, so `engine.manifests` and each row's
+ * `source` are what production stamps. The scope-only id is installed the way
+ * `sys_packages` hydration installs a stored row (`source: 'authored'`, no
+ * booted manifest), so its refusal can only come from the scope signal.
+ *
+ * ## Both limbs
+ *
+ * The door installs through the `protocol` service's `installPackage` when one
+ * resolves, and falls back to the bare registry write when none does. Every
+ * case runs on both.
+ *
+ * ## The gate is not an outage
+ *
+ * CONTROL: an install of a new id (with and without `overwrite`) and an
+ * overwrite of an authored package still answer `201` and really write, on the
+ * same spies, which is what makes the refusal rows' "nothing was written" a
+ * measurement rather than a vacuous truth.
+ */
+
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ObjectQL } from '@objectstack/objectql';
+import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
+import { HttpDispatcher } from '../http-dispatcher.js';
+
+/** Booted by the deployment's code: `registerApp`, default source `'code'`. */
+const CODE_BOOTED = 'com.acme.codepkg';
+/** Installed from the marketplace: `registerApp(…, 'marketplace')`. */
+const MARKETPLACE = 'com.acme.marketpkg';
+/** A stored row whose manifest declares `scope: 'cloud'`; nothing booted it. */
+const CLOUD_SCOPED = 'com.acme.cloudpkg';
+/** An org's own base, installed through this door. */
+const AUTHORED = 'com.acme.authoredpkg';
+/** An id nothing has installed. */
+const FRESH = 'com.acme.freshpkg';
+
+const manifest = (id: string, version: string, extra: Record<string, unknown> = {}) => ({
+    id,
+    name: id,
+    version,
+    type: 'app',
+    ...extra,
+});
+
+const silentLogger: any = {
+    debug() {}, info() {}, warn() {}, error() {}, trace() {}, fatal() {},
+    child() { return silentLogger; },
+};
+
+type Limb = 'protocol' | 'fallback';
+const LIMBS: Limb[] = ['protocol', 'fallback'];
+
+/**
+ * The composed door over a real engine. `protocol` resolves the real protocol
+ * primitive with a `package` service double standing in for `sys_packages`;
+ * `fallback` resolves no protocol service, so the door takes its bare
+ * registry write.
+ */
+function door(limb: Limb) {
+    const engine = new ObjectQL({ logger: silentLogger });
+    (engine.registry as unknown as { logLevel: string }).logLevel = 'silent';
+    engine.registerApp(manifest(CODE_BOOTED, '1.0.0'));
+    engine.registerApp(manifest(MARKETPLACE, '1.0.0'), undefined, 'marketplace');
+    engine.registry.installPackage(manifest(CLOUD_SCOPED, '1.0.0', { scope: 'cloud' }) as any, 'authored');
+
+    const packageService = { publish: vi.fn(async () => ({ success: true })) };
+    const services = new Map<string, unknown>([['package', packageService]]);
+    const protocol = limb === 'protocol'
+        ? new ObjectStackProtocolImplementation(engine as any, () => services)
+        : null;
+    const kernel: any = {
+        getService: (name: string) => {
+            if (name === 'protocol') return protocol ? Promise.resolve(protocol) : null;
+            if (name === 'objectql') return Promise.resolve(engine);
+            return null;
+        },
+        context: { getService: (name: string) => (name === 'objectql' ? engine : null) },
+    };
+    const registryInstall = vi.spyOn(engine.registry, 'installPackage');
+    const protocolInstall = protocol ? vi.spyOn(protocol, 'installPackage') : undefined;
+    const manifests = (engine as unknown as { manifests: Map<string, unknown> }).manifests;
+    return {
+        dispatcher: new HttpDispatcher(kernel),
+        engine,
+        manifests,
+        registryInstall,
+        protocolInstall,
+        publish: packageService.publish,
+    };
+}
+
+const ADMIN = (): any => ({
+    request: {},
+    environmentId: 'pkg-install-overwrite-readonly-test',
+    executionContext: {
+        userId: 'u_pkg_admin',
+        systemPermissions: ['manage_metadata', 'studio.access', 'setup.access'],
+    },
+});
+
+type Door = ReturnType<typeof door>;
+const install = (d: Door, body: unknown, query: Record<string, unknown> = {}) =>
+    d.dispatcher.handlePackages('', 'POST', body, query, ADMIN());
+
+// The allow path persists enable state under OS_HOME; keep it out of the
+// developer's own home.
+let home: string;
+let priorHome: string | undefined;
+beforeAll(() => {
+    priorHome = process.env.OS_HOME;
+    home = mkdtempSync(join(tmpdir(), 'os-pkg-overwrite-readonly-'));
+    process.env.OS_HOME = home;
+});
+afterAll(() => {
+    if (priorHome === undefined) delete process.env.OS_HOME;
+    else process.env.OS_HOME = priorHome;
+    rmSync(home, { recursive: true, force: true });
+});
+
+/** The refusal's envelope, and that nothing on either limb was written. */
+function expectRefusedUnwritten(d: Door, r: any, id: string) {
+    expect(r.response?.status).toBe(422);
+    expect(r.response?.body?.success).toBe(false);
+    expect(r.response?.body?.error?.code).toBe('WRITABLE_PACKAGE_REQUIRED');
+    expect(r.response?.body?.error?.httpStatus).toBe(422);
+    expect(r.response?.body?.error?.details?.packageId).toBe(id);
+    expect(d.registryInstall).not.toHaveBeenCalled();
+    if (d.protocolInstall) expect(d.protocolInstall).not.toHaveBeenCalled();
+    expect(d.publish).not.toHaveBeenCalled();
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+// 1. REFUSED: an overwrite over a read-only id, on both limbs
+// ══════════════════════════════════════════════════════════════════════════════
+
+const READ_ONLY: Array<{ label: string; id: string; source: string; booted: boolean }> = [
+    { label: 'code-booted (registerApp)', id: CODE_BOOTED, source: 'code', booted: true },
+    { label: 'marketplace-installed (registerApp, marketplace)', id: MARKETPLACE, source: 'marketplace', booted: true },
+    { label: 'cloud-scoped stored row (scope signal only)', id: CLOUD_SCOPED, source: 'authored', booted: false },
+];
+
+for (const limb of LIMBS) {
+    describe(`POST /packages overwrite over a read-only id is refused (${limb} limb)`, () => {
+        for (const pkg of READ_ONLY) {
+            it(`422s the overwrite of the ${pkg.label} package and leaves its row and manifest as they were`, async () => {
+                const d = door(limb);
+                const rowBefore = d.engine.registry.getPackage(pkg.id);
+                const manifestBefore = d.manifests.get(pkg.id);
+                expect(rowBefore?.manifest?.version, 'precondition: the booted row').toBe('1.0.0');
+                expect(d.manifests.has(pkg.id), 'precondition: the boot signal').toBe(pkg.booted);
+
+                const r = await install(d, { manifest: manifest(pkg.id, '2.0.0'), overwrite: true });
+
+                expectRefusedUnwritten(d, r, pkg.id);
+                expect(d.engine.registry.getPackage(pkg.id)).toBe(rowBefore);
+                expect(d.engine.registry.getPackage(pkg.id)?.manifest?.version).toBe('1.0.0');
+                expect(d.engine.registry.getPackage(pkg.id)?.source).toBe(pkg.source);
+                expect(d.manifests.get(pkg.id)).toBe(manifestBefore);
+                expect(d.manifests.has(pkg.id)).toBe(pkg.booted);
+            });
+        }
+
+        it('refuses the `?overwrite=true` query spelling the same way', async () => {
+            const d = door(limb);
+            const rowBefore = d.engine.registry.getPackage(CODE_BOOTED);
+
+            const r = await install(d, { manifest: manifest(CODE_BOOTED, '2.0.0') }, { overwrite: 'true' });
+
+            expectRefusedUnwritten(d, r, CODE_BOOTED);
+            expect(d.engine.registry.getPackage(CODE_BOOTED)).toBe(rowBefore);
+            expect(d.manifests.has(CODE_BOOTED)).toBe(true);
+        });
+
+        it('keeps the 409 for an install over a read-only id that does not ask to overwrite', async () => {
+            const d = door(limb);
+            const rowBefore = d.engine.registry.getPackage(CODE_BOOTED);
+
+            const r = await install(d, { manifest: manifest(CODE_BOOTED, '2.0.0') });
+
+            expect(r.response?.status).toBe(409);
+            expect(d.registryInstall).not.toHaveBeenCalled();
+            expect(d.publish).not.toHaveBeenCalled();
+            expect(d.engine.registry.getPackage(CODE_BOOTED)).toBe(rowBefore);
+        });
+    });
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+// 2. CONTROL: the gate is not an outage
+// ══════════════════════════════════════════════════════════════════════════════
+
+for (const limb of LIMBS) {
+    describe(`POST /packages still installs and overwrites what an org owns (${limb} limb)`, () => {
+        it('installs a new id: 201, and the row is written', async () => {
+            const d = door(limb);
+
+            const r = await install(d, { manifest: manifest(FRESH, '1.0.0') });
+
+            expect(r.response?.status).toBe(201);
+            expect(d.registryInstall).toHaveBeenCalledTimes(1);
+            expect(d.engine.registry.getPackage(FRESH)?.source).toBe('authored');
+            if (limb === 'protocol') expect(d.publish).toHaveBeenCalledTimes(1);
+        });
+
+        it('installs a new id with `overwrite: true` set: nothing to overwrite, still 201', async () => {
+            const d = door(limb);
+
+            const r = await install(d, { manifest: manifest(FRESH, '1.0.0'), overwrite: true });
+
+            expect(r.response?.status).toBe(201);
+            expect(d.registryInstall).toHaveBeenCalledTimes(1);
+            expect(d.engine.registry.getPackage(FRESH)?.manifest?.version).toBe('1.0.0');
+            if (limb === 'protocol') expect(d.publish).toHaveBeenCalledTimes(1);
+        });
+
+        it('overwrites an authored base: 201, and the row is replaced', async () => {
+            const d = door(limb);
+            const first = await install(d, { manifest: manifest(AUTHORED, '1.0.0') });
+            expect(first.response?.status, 'precondition: the base is installed').toBe(201);
+            const rowBefore = d.engine.registry.getPackage(AUTHORED);
+
+            const r = await install(d, { manifest: manifest(AUTHORED, '2.0.0'), overwrite: true });
+
+            expect(r.response?.status).toBe(201);
+            expect(d.registryInstall).toHaveBeenCalledTimes(2);
+            expect(d.engine.registry.getPackage(AUTHORED)).not.toBe(rowBefore);
+            expect(d.engine.registry.getPackage(AUTHORED)?.manifest?.version).toBe('2.0.0');
+            expect(d.engine.registry.getPackage(AUTHORED)?.source).toBe('authored');
+            if (limb === 'protocol') {
+                expect(d.protocolInstall).toHaveBeenCalledTimes(2);
+                expect(d.publish).toHaveBeenCalledTimes(2);
+            }
+        });
+    });
+}
@@ -1381,6 +1381,23 @@ export async function handlePackagesRequest(deps: DomainHandlerDeps, path: strin
                     response: deps.error(`Package '${pkgId}' already exists`, 409),
                 };
             }
+            // [#24030] ADR-0070 D2 — the READ-ONLY gate, asked for the manifest's
+            // id before either install limb below writes. `overwrite` only ever
+            // bypassed the 409 above; nothing asked whether the id is a package
+            // the deployment ships, so an overwrite over a code-booted or
+            // marketplace-installed id answered 201, replaced its registry row
+            // with an authored one (and, on the protocol limb, wrote its
+            // `sys_packages` row) while `engine.manifests` kept judging it
+            // read-only. Disable, publish, revert and delete refuse that id with
+            // this same answer; ⛔ the rule is not re-derived here — it is
+            // {@link requireWritablePackage}, i.e. {@link isWritablePackage}.
+            //
+            // Placed AFTER the 409, so an install that does not ask to overwrite
+            // keeps its 409 answer for any existing id. An id nothing installed
+            // is writable by the predicate's own rule, so a fresh install —
+            // `overwrite` set or not — answers as before.
+            const readOnly = requireWritablePackage(deps, qlService, pkgId, overwrite ? 'overwrite' : 'install');
+            if (readOnly) return readOnly;
             // ⚠️ The MANIFEST handed on is the one the caller sent, ⛔ not the
             // parsed copy. `ManifestSchema` applies defaults at parse time
             // (`scope`, `defaultDatasource`), and this door has always stored