@@ -15,12 +15,18 @@ Clause-②: yes (widening)
 - `PackageApiContracts.installPackage.path` — `'/api/v1/packages/install'` → `'/api/v1/packages'`. A caller that read the constant to build a URL was building one nothing serves; a caller that hard-coded the old string gets a `404` today and should send `POST /api/v1/packages`. The method (`POST`) is unchanged and is what distinguishes this entry from `listPackages`.
 - `PackageApiContracts.installPackage.input` — `PackageInstallRequestSchema` → the new `PackageInstallBodySchema`. The wrapped schema is still exported and still parses the wrapped form; the new export is a union that also parses a bare manifest.
 - `PackageInstallRequestSchema` gains **`overwrite?: boolean`**. This is a declaration of behaviour that already shipped: the door reads `overwrite` from the body (or `?overwrite=true`) to opt back in to replacing an already-installed id instead of answering `409 Conflict`, the first-party SDK sends it, and no schema declared it — so any parse at that door would have silently stripped it and turned a deliberate re-install into a conflict.
-- **`PackageInstallBodySchema`** / `PackageInstallBody` / `PackageInstallBodyParsed` are new. The door reads `body.manifest || body`, and first-party callers really do post a bare manifest as the whole body, so the contract declares both forms as a union of two whole closed declarations — never a tolerant shape. The bare form carries no install options: `settings`, `enableOnInstall` and `overwrite` are not manifest keys and the manifest surface is closed, so a bare-form caller reaches `overwrite` through the query string alone.
+- **`PackageInstallBodySchema`** / `PackageInstallBody` / `PackageInstallBodyParsed` are new. The door reads `body.manifest || body`, and first-party callers really do post a bare manifest as the whole body, so the contract declares both forms as a union — every parse is a full parse of one coherent form, never a tolerant shape. The two branches are disjoint, but only the BARE one is CLOSED: `PackageInstallRequestSchema` is a plain `z.object`, so an unknown key on the wrapped form is DROPPED (`{ manifest, bogus: 1 }` parses and `bogus` is gone) while the same key on a bare manifest is refused by name. That asymmetry matches the door, which reads four keys off the wrapper and ignores the rest — closing the wrapped branch would refuse bodies the door answers `201` to. The bare form carries no install options: `settings`, `enableOnInstall` and `overwrite` are not manifest keys and the manifest surface is closed, so a bare-form caller reaches `overwrite` through the query string alone.
 
 **What moved at the runtime**
 
 `POST /api/v1/packages` now honours `enableOnInstall: false` in the wrapped body: the package installs `disabled`, through the same registry flip and durable state write `PATCH /packages/:id/disable` uses, so a restart does not re-enable what the caller switched off. `true` and absent install enabled, which is the declared default. Previously the key was declared in three schemas, sent by the SDK, and read by no handler at all.
 
+The durable write happens on **both** arms, not just the disable. `POST /packages` is a create that an already-installed id reaches through `overwrite`, and `DELETE /packages/:id` does not clear this record either, so an install could answer `201` with `enabled: true` while the state file still listed the id as disabled — and `SchemaRegistry.installPackage` reads that file at boot, re-installing the package DISABLED one restart later with nothing red in between. Every install now persists the state it returned.
+
+**What the declaration does NOT cover — the measured residual**
+
+This is a subset description of the live door, deliberately, and it is recorded rather than implied. Measured through `HttpDispatcher.handlePackages`, the door also answers `201` to: a manifest missing `type` and/or `version` (both of the runtime's own door drives post one); unknown keys on either form (refused by name on the bare branch, dropped on the wrapped one, `201` either way); a string-typed `enableOnInstall` / `overwrite`, which is compared against `true`/`false`/`'true'` and therefore treated as absent — `enableOnInstall: 'false'` installs ENABLED; and install options spelled on the bare form, which are ignored. In the opposite direction the door answers `400` to a whitespace-only `id` this declaration admits. `ManifestSchema` is not relaxed to close any of that.
+
 **Documentation**
 
 `packages/client`'s README install example could not parse against the manifest contract — no `id`, no `type`, and a `label` key the closed manifest surface refuses by name — and the live door answered it `400 Package id is required`. It is now a manifest that parses, and the example names the `overwrite` opt-in beside it.
@@ -0,0 +1,123 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#18058] The published README's install example, parsed against the contract
+ * the door it is copied into actually enforces.
+ *
+ * ## Why this file exists — the fixture that could not fail
+ *
+ * #18058 fixed `packages/client/README.md`: its `client.packages.install(…)`
+ * example was a body the live door answers `400 Package id is required` to —
+ * no `id`, no `type`, and a `label` key the closed manifest surface refuses by
+ * name. The fix was pinned in `packages/spec/src/api/package-api.test.ts`, but
+ * pinned as a HAND-TRANSCRIBED literal: reverting the README to its old text
+ * left that suite 56/56 green, because nothing in the repository read the
+ * README at all. An acceptance fixture that can drift back to the refused text
+ * with nothing turning red is not an acceptance fixture — it is a copy of one.
+ *
+ * So this test reads the README itself, extracts the object literal a reader
+ * would copy, wraps it exactly as `index.ts`'s `packages.install` wraps it on
+ * the wire, and parses that. Revert the README and this file goes red; edit
+ * the example into something the door refuses and it goes red; and the
+ * pre-#18058 literal is pinned as REFUSED beside it so a schema relaxation
+ * cannot make the whole thing vacuous.
+ *
+ * ⛔ The extraction is deliberately loud: a README that no longer contains an
+ * `install(` call with an object literal FAILS here rather than silently
+ * testing nothing. "Could not run" is a failure, not a skip.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { PackageInstallBodySchema } from '@objectstack/spec/api';
+
+/** This package's own published README — `packages/client/README.md`. */
+const README = readFileSync(fileURLToPath(new URL('../README.md', import.meta.url)), 'utf8');
+
+/**
+ * The `// Package Management` block, bounded by the next top-level comment
+ * group in the same fence. Scoping matters: `install(` also appears in the
+ * overwrite line right below the example, and that one passes an identifier.
+ */
+function packageManagementBlock(source: string): string {
+  const start = source.indexOf('// Package Management');
+  if (start < 0) throw new Error('packages/client/README.md no longer has a `// Package Management` block');
+  const rest = source.slice(start + 1);
+  const end = rest.indexOf('\n\n');
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+/**
+ * The first object literal passed to `client.packages.install(` — brace-matched
+ * rather than regex-matched, so a nested object in the example cannot truncate
+ * it. Throws when the call or the literal is gone.
+ */
+function firstInstallObjectLiteral(block: string): string {
+  const call = block.indexOf('client.packages.install({');
+  if (call < 0) {
+    throw new Error('the README\'s Package Management block no longer calls `client.packages.install({ … })` with an object literal');
+  }
+  const open = block.indexOf('{', call);
+  let depth = 0;
+  for (let i = open; i < block.length; i += 1) {
+    if (block[i] === '{') depth += 1;
+    else if (block[i] === '}') {
+      depth -= 1;
+      if (depth === 0) return block.slice(open, i + 1);
+    }
+  }
+  throw new Error('the README\'s install example has an unbalanced object literal');
+}
+
+const LITERAL = firstInstallObjectLiteral(packageManagementBlock(README));
+
+/** The literal as a value. It is ordinary JS — single quotes, bare keys. */
+const README_MANIFEST = new Function(`return (${LITERAL});`)() as Record<string, unknown>;
+
+/**
+ * `index.ts`'s `packages.install` body, spelled out: `manifest`, `settings`,
+ * `enableOnInstall`, and `overwrite` only when the caller passed one. This is
+ * the body that leaves the process, which is what the door parses.
+ */
+const asTheSdkSends = (
+  manifest: unknown,
+  options?: { settings?: Record<string, unknown>; enableOnInstall?: boolean; overwrite?: boolean },
+) => ({
+  manifest,
+  settings: options?.settings,
+  enableOnInstall: options?.enableOnInstall,
+  ...(options?.overwrite !== undefined ? { overwrite: options.overwrite } : {}),
+});
+
+describe('#18058 — the README install example is parsed, not transcribed', () => {
+  it('the extraction really found a manifest — this file is not testing an empty object', () => {
+    // The non-vacuity guard for the extractor itself: the three keys the
+    // pre-#18058 text was missing are exactly the ones a reader needs.
+    expect(Object.keys(README_MANIFEST).length).toBeGreaterThanOrEqual(3);
+    expect(README_MANIFEST).toHaveProperty('id');
+    expect(LITERAL.startsWith('{')).toBe(true);
+  });
+
+  it('parses green, wrapped exactly as `packages.install` wraps it on the wire', () => {
+    const verdict = PackageInstallBodySchema.safeParse(asTheSdkSends(README_MANIFEST));
+    expect(verdict.error?.issues ?? []).toEqual([]);
+    expect(verdict.success).toBe(true);
+  });
+
+  it('parses green BARE too — `body.manifest || body` is how the door reads it', () => {
+    expect(PackageInstallBodySchema.safeParse(README_MANIFEST).success).toBe(true);
+  });
+
+  it('the overwrite opt-in beside it parses too', () => {
+    expect(PackageInstallBodySchema.safeParse(asTheSdkSends(README_MANIFEST, { overwrite: true })).success).toBe(true);
+  });
+
+  it('⛔ the pre-#18058 text is still REFUSED — a schema relaxation cannot make this vacuous', () => {
+    // No `id`, no `type`, and `label` is not a manifest key. If this ever turns
+    // green the manifest contract was relaxed, not the example fixed.
+    const asShipped = { name: 'vendor_plugin', label: 'Vendor Plugin', version: '1.0.0' };
+    expect(PackageInstallBodySchema.safeParse(asTheSdkSends(asShipped)).success).toBe(false);
+    expect(PackageInstallBodySchema.safeParse(asShipped).success).toBe(false);
+  });
+});
@@ -167,3 +167,118 @@ describe('#18058 — the install door honours `enableOnInstall`', () => {
         expect(persistedDisabled().has('com.acme.bare')).toBe(false);
     });
 });
+
+/**
+ * [#18058 F1] The DURABLE half of the declared default, on the path the cases
+ * above structurally cannot reach: an id that is ALREADY INSTALLED.
+ *
+ * ## The defect these pin shut
+ *
+ * The handler wrote `setPackageDisabled(env, id, true)` and never `false`, so
+ * the three records this door is held to only agreed while every id was fresh:
+ *
+ * ```text
+ * POST {manifest, overwrite:true, enableOnInstall:false}  → 201, disabled, state file lists the id
+ * POST {manifest, overwrite:true}         (flag absent)   → 201, enabled:true, registry true,
+ *                                                           and the state file STILL lists it
+ * ```
+ *
+ * Nothing is red at that moment. The loss surfaces one restart later:
+ * `SchemaRegistry.installPackage` reads `initialDisabledPackageIds`, finds the
+ * id, and re-installs the package DISABLED — a door that answered correctly on
+ * the wire and wrongly on disk. `PATCH /packages/:id/enable` has always made
+ * exactly the `false` call these cases demand; the install door did not.
+ *
+ * ⚠️ The fix is deliberately UNCONDITIONAL rather than scoped to the overwrite
+ * path: `DELETE /packages/:id` does not clear the durable disable either, so a
+ * disable → uninstall → re-install lands on a FRESH registry id whose durable
+ * record still says disabled. Persisting the state the door actually returned,
+ * every time, is one call that cannot be out of step with the row.
+ */
+describe('#18058 — a re-install persists the state it RETURNS, not just a disable', () => {
+    let registry: SchemaRegistry;
+    let dispatcher: HttpDispatcher;
+
+    beforeEach(() => {
+        registry = freshRegistry();
+        dispatcher = makeDoor(registry);
+    });
+
+    /** Install once with `enableOnInstall: false`, and prove the disable really landed. */
+    const installDisabled = async (id: string, namespace: string) => {
+        const first = await install(dispatcher, {
+            manifest: manifest(id, namespace),
+            overwrite: true,
+            enableOnInstall: false,
+        });
+        expect(first.response?.status).toBe(201);
+        expect(first.response?.body?.data?.enabled, 'precondition: the first install really disabled it').toBe(false);
+        expect(persistedDisabled().has(id), 'precondition: the disable really reached disk').toBe(true);
+    };
+
+    it('re-installing with the flag ABSENT clears the durable disable — the declared default is `true`', async () => {
+        const id = 'com.acme.reinstall.absent';
+        await installDisabled(id, 'reinstallabsent');
+
+        const again = await install(dispatcher, { manifest: manifest(id, 'reinstallabsent'), overwrite: true });
+
+        expect(again.response?.status).toBe(201);
+        expect(again.response?.body?.data?.enabled, 'the row this door RETURNED').toBe(true);
+        expect(registry.getPackage(id)?.enabled, 'the registry the next read serves from').toBe(true);
+        // ⭐ The line this F item exists for: without it the next boot reads the
+        // stale id out of `initialDisabledPackageIds` and installs it DISABLED.
+        expect(
+            persistedDisabled().has(id),
+            'the durable state — a re-install that answered `enabled` must not leave `disabled` on disk',
+        ).toBe(false);
+    });
+
+    it('re-installing with `enableOnInstall: true` clears the durable disable', async () => {
+        const id = 'com.acme.reinstall.true';
+        await installDisabled(id, 'reinstalltrue');
+
+        const again = await install(dispatcher, {
+            manifest: manifest(id, 'reinstalltrue'),
+            overwrite: true,
+            enableOnInstall: true,
+        });
+
+        expect(again.response?.status).toBe(201);
+        expect(again.response?.body?.data?.enabled).toBe(true);
+        expect(registry.getPackage(id)?.enabled).toBe(true);
+        expect(persistedDisabled().has(id)).toBe(false);
+    });
+
+    it('a BARE re-install clears it too — that form cannot ask for `false`, so it installs enabled', async () => {
+        const id = 'com.acme.reinstall.bare';
+        await installDisabled(id, 'reinstallbare');
+
+        // No wrapper, so `enableOnInstall` is not a declared key here at all and
+        // the door installs at the default. The durable record must follow.
+        const again = await install(dispatcher, manifest(id, 'reinstallbare'));
+
+        expect(again.response?.status).toBe(409, 'the bare form reaches overwrite through the query string alone');
+
+        const forced = await dispatcher.handlePackages(
+            '', 'POST', manifest(id, 'reinstallbare'), { overwrite: 'true' }, PKG_ADMIN(),
+        );
+        expect(forced.response?.status).toBe(201);
+        expect(forced.response?.body?.data?.enabled).toBe(true);
+        expect(persistedDisabled().has(id)).toBe(false);
+    });
+
+    it('⛔ the disable direction is UNCHANGED — a re-install asking for `false` still persists it', async () => {
+        const id = 'com.acme.reinstall.stays-off';
+        await installDisabled(id, 'reinstallstaysoff');
+
+        const again = await install(dispatcher, {
+            manifest: manifest(id, 'reinstallstaysoff'),
+            overwrite: true,
+            enableOnInstall: false,
+        });
+
+        expect(again.response?.status).toBe(201);
+        expect(again.response?.body?.data?.enabled).toBe(false);
+        expect(persistedDisabled().has(id)).toBe(true);
+    });
+});