chainlesschain 0.166.90 → 0.166.92

package/src/lib/evolution/skill-release-registry.js

@@ -6,6 +6,12 @@ import { types as utilTypes } from "node:util";
 import { getHomeDir } from "../paths.js";
 import { ensurePrivateDirectory, ensurePrivateFile } from "../secure-fs.js";
 import { withEvolutionFileIdentity } from "./evolution-file-identity.js";
+import { createSkillRegistryWriterControl } from "./skill-registry-writer-control.js";
+import {
+  captureRrsiRegistryComponentBinding,
+  assertOutsideRrsiRegistryNamespace,
+  RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+} from "./rrsi-registry-store-policy.js";
 import {
   SKILL_CANDIDATE_MIGRATION_RECEIPT_SCHEMA,
   SKILL_CANDIDATE_MIGRATION_RECORD_SCHEMA,
@@ -62,6 +68,7 @@ export const SKILL_RELEASE_JOURNAL_ARCHIVE_SCHEMA =
 
 const JOURNAL_SCHEMA = "chainlesschain.skill-release-journal/v4";
 const REGISTRY_READERS = new WeakMap();
+const REGISTRY_WRITERS = new WeakMap();
 
 export function captureSkillReleaseRegistryReader(value) {
   const reader = REGISTRY_READERS.get(value);
@@ -72,6 +79,16 @@ export function captureSkillReleaseRegistryReader(value) {
     throw new TypeError("a genuine SkillReleaseRegistry reader is required");
   return reader;
 }
+
+export function captureSkillReleaseRegistryWriterControl(value) {
+  captureSkillReleaseRegistryReader(value);
+  const control = REGISTRY_WRITERS.get(value);
+  if (!control)
+    throw new TypeError(
+      "a genuine release Registry writer control is required",
+    );
+  return control;
+}
 const INTENT_SCHEMA = "chainlesschain.skill-release-transition-intent/v2";
 const RELEASE_DOMAIN = `${SKILL_RELEASE_SCHEMA}\0`;
 const STATE_DOMAIN = `${SKILL_RELEASE_STATE_SCHEMA}\0`;
@@ -1850,128 +1867,151 @@ export function archiveLegacySkillReleaseJournal(input) {
   ) {
     throw migrationRequired("legacy journal archive paths are invalid");
   }
-  const sourcePath = path.join(
-    sourceDirectory,
-    path.basename(requestedSourcePath),
-  );
-  if (input.secure) {
-    ensurePrivateDirectory(archiveDirectory, {
-      applyWindowsAcl: true,
-      failIfUnavailable: true,
-    });
-  }
-  const archivePath = path.join(
-    archiveDirectory,
-    `${disposition.planDigest.slice("sha256:".length)}.json`,
-  );
-  const expectedBytes = serialize(archive);
-  let created = false;
-  if (lstatOrNull(fsImpl, archivePath) === null) {
-    const source = readBoundedSingleLinkFile(
-      fsImpl,
-      sourcePath,
-      MAX_FILE_BYTES,
-      SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
-      "legacy release journal source",
+  // An independent archive helper can also retire bytes under a tenant's
+  // journals directory. It must participate in that physical root's writer
+  // protocol rather than bypassing the class-method maintenance boundary.
+  const writer = createSkillRegistryWriterControl({
+    rootDir: path.dirname(sourceDirectory),
+    tenantId: disposition.tenantId,
+    component: TENANT_MARKER_COMPONENT,
+    fsImpl,
+  });
+  return writer.runSync(() => {
+    const sourcePath = path.join(
+      sourceDirectory,
+      path.basename(requestedSourcePath),
     );
-    if (!source.bytes.equals(serialize(journal))) {
-      throw migrationRequired(
-        "legacy release journal source bytes differ from the verified input",
-      );
+    if (input.secure) {
+      ensurePrivateDirectory(archiveDirectory, {
+        applyWindowsAcl: true,
+        failIfUnavailable: true,
+      });
     }
-    const temporaryPath = path.join(
+    const archivePath = path.join(
       archiveDirectory,
-      `.journal-${process.pid}-${crypto.randomBytes(16).toString("hex")}.tmp`,
+      `${disposition.planDigest.slice("sha256:".length)}.json`,
     );
-    let descriptor = null;
-    try {
-      descriptor = fsImpl.openSync(temporaryPath, "wx", 0o600);
-      fsImpl.writeFileSync(descriptor, expectedBytes);
-      fsImpl.fsyncSync(descriptor);
-      fsImpl.closeSync(descriptor);
-      descriptor = null;
-      if (input.secure) {
-        ensurePrivateFile(temporaryPath, {
-          applyWindowsAcl: true,
-          failIfUnavailable: true,
-        });
-      }
-      const staged = readBoundedSingleLinkFile(
+    const expectedBytes = serialize(archive);
+    let created = false;
+    if (lstatOrNull(fsImpl, archivePath) === null) {
+      const source = readBoundedSingleLinkFile(
         fsImpl,
-        temporaryPath,
+        sourcePath,
         MAX_FILE_BYTES,
         SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
-        "legacy journal archive temporary",
+        "legacy release journal source",
       );
-      if (!staged.bytes.equals(expectedBytes)) {
-        throw migrationRequired("legacy journal archive write was incomplete");
+      if (!source.bytes.equals(serialize(journal))) {
+        throw migrationRequired(
+          "legacy release journal source bytes differ from the verified input",
+        );
       }
-      checkpoint("after-archive-fsync", {
-        archiveDigest: archive.archiveDigest,
-        dispositionPlanDigest: disposition.planDigest,
-      });
+      const temporaryPath = path.join(
+        archiveDirectory,
+        `.journal-${process.pid}-${crypto.randomBytes(16).toString("hex")}.tmp`,
+      );
+      let descriptor = null;
       try {
-        fsImpl.linkSync(temporaryPath, archivePath);
-        created = true;
-      } catch (error) {
-        if (error?.code !== "EEXIST") throw error;
-      }
-      fsImpl.unlinkSync(temporaryPath);
-      fsyncDirectory(fsImpl, archiveDirectory);
-      checkpoint("after-archive-publish", {
-        archiveDigest: archive.archiveDigest,
-        dispositionPlanDigest: disposition.planDigest,
-      });
-    } finally {
-      if (descriptor !== null) fsImpl.closeSync(descriptor);
-      if (lstatOrNull(fsImpl, temporaryPath) !== null)
+        descriptor = fsImpl.openSync(temporaryPath, "wx", 0o600);
+        fsImpl.writeFileSync(descriptor, expectedBytes);
+        fsImpl.fsyncSync(descriptor);
+        fsImpl.closeSync(descriptor);
+        descriptor = null;
+        if (input.secure) {
+          ensurePrivateFile(temporaryPath, {
+            applyWindowsAcl: true,
+            failIfUnavailable: true,
+          });
+        }
+        const staged = readBoundedSingleLinkFile(
+          fsImpl,
+          temporaryPath,
+          MAX_FILE_BYTES,
+          SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+          "legacy journal archive temporary",
+        );
+        if (!staged.bytes.equals(expectedBytes)) {
+          throw migrationRequired(
+            "legacy journal archive write was incomplete",
+          );
+        }
+        checkpoint("after-archive-fsync", {
+          archiveDigest: archive.archiveDigest,
+          dispositionPlanDigest: disposition.planDigest,
+        });
+        try {
+          writer.assertIfWriting();
+          fsImpl.linkSync(temporaryPath, archivePath);
+          created = true;
+        } catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+        }
         fsImpl.unlinkSync(temporaryPath);
+        fsyncDirectory(fsImpl, archiveDirectory);
+        checkpoint("after-archive-publish", {
+          archiveDigest: archive.archiveDigest,
+          dispositionPlanDigest: disposition.planDigest,
+        });
+      } finally {
+        if (descriptor !== null) fsImpl.closeSync(descriptor);
+        let cleanupOwned = false;
+        try {
+          writer.assertIfWriting();
+          cleanupOwned = true;
+        } catch {
+          /* Preserve private debris after lost ownership. */
+        }
+        if (cleanupOwned && lstatOrNull(fsImpl, temporaryPath) !== null)
+          fsImpl.unlinkSync(temporaryPath);
+      }
     }
-  }
-  const persisted = readBoundedSingleLinkFile(
-    fsImpl,
-    archivePath,
-    MAX_FILE_BYTES,
-    SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
-    "legacy journal archive",
-  );
-  if (
-    !persisted.bytes.equals(expectedBytes) ||
-    canonicalJson(
-      verifySkillReleaseJournalArchive(
-        JSON.parse(
-          new TextDecoder("utf-8", { fatal: true }).decode(persisted.bytes),
-        ),
-      ),
-    ) !== canonicalJson(archive)
-  ) {
-    throw migrationRequired("legacy journal archive readback differs");
-  }
-  checkpoint("after-archive-readback", {
-    archiveDigest: archive.archiveDigest,
-    dispositionPlanDigest: disposition.planDigest,
-  });
-  if (lstatOrNull(fsImpl, sourcePath) !== null) {
-    const source = readBoundedSingleLinkFile(
+    const persisted = readBoundedSingleLinkFile(
       fsImpl,
-      sourcePath,
+      archivePath,
       MAX_FILE_BYTES,
       SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
-      "legacy release journal source",
+      "legacy journal archive",
     );
-    if (!source.bytes.equals(serialize(journal))) {
-      throw migrationRequired(
-        "legacy release journal changed before retirement",
-      );
+    if (
+      !persisted.bytes.equals(expectedBytes) ||
+      canonicalJson(
+        verifySkillReleaseJournalArchive(
+          JSON.parse(
+            new TextDecoder("utf-8", { fatal: true }).decode(persisted.bytes),
+          ),
+        ),
+      ) !== canonicalJson(archive)
+    ) {
+      throw migrationRequired("legacy journal archive readback differs");
     }
-    fsImpl.unlinkSync(sourcePath);
-    fsyncDirectory(fsImpl, sourceDirectory);
-    checkpoint("after-source-retire", {
+    checkpoint("after-archive-readback", {
       archiveDigest: archive.archiveDigest,
       dispositionPlanDigest: disposition.planDigest,
     });
-  }
-  return deepFreeze({ archive, archivePath, created, sourceRetired: true });
+    if (lstatOrNull(fsImpl, sourcePath) !== null) {
+      const source = readBoundedSingleLinkFile(
+        fsImpl,
+        sourcePath,
+        MAX_FILE_BYTES,
+        SKILL_RELEASE_MIGRATION_REQUIRED_CODE,
+        "legacy release journal source",
+      );
+      if (!source.bytes.equals(serialize(journal))) {
+        throw migrationRequired(
+          "legacy release journal changed before retirement",
+        );
+      }
+      writer.assertIfWriting();
+      fsImpl.unlinkSync(sourcePath);
+      fsyncDirectory(fsImpl, sourceDirectory);
+      checkpoint("after-source-retire", {
+        archiveDigest: archive.archiveDigest,
+        dispositionPlanDigest: disposition.planDigest,
+      });
+    }
+    writer.assertIfWriting();
+    return deepFreeze({ archive, archivePath, created, sourceRetired: true });
+  });
 }
 
 /**
@@ -2472,6 +2512,7 @@ const REGISTRY_OPTION_KEYS = new Set([
   "randomToken",
   "rootDir",
   "secure",
+  "storePolicyBinding",
   "tenantId",
   "transactionLedger",
 ]);
@@ -2659,6 +2700,7 @@ function normalizeRegistryOptions(options) {
       data.rootDir ??
       path.join(getHomeDir(), "evolution", "registry", "releases"),
     secure: data.secure ?? true,
+    storePolicyBinding: data.storePolicyBinding,
     tenantId: tenantId(data.tenantId),
     transactionLedger: data.transactionLedger,
   };
@@ -2696,6 +2738,9 @@ export class SkillReleaseRegistry {
   #ledgerQuery;
 
   #pins = new WeakMap();
+  #writerControl;
+  #storeBinding;
+  #runtimeMode = "initialized";
 
   constructor(options) {
     const {
@@ -2706,9 +2751,32 @@ export class SkillReleaseRegistry {
       randomToken,
       rootDir,
       secure,
+      storePolicyBinding,
       tenantId: ownerTenantId,
       transactionLedger,
     } = normalizeRegistryOptions(options);
+    const requestedBase = path.resolve(rootDir);
+    if (storePolicyBinding !== undefined) {
+      this.#storeBinding =
+        captureRrsiRegistryComponentBinding(storePolicyBinding);
+      const descriptor = this.#storeBinding.descriptor;
+      if (
+        new.target !== SkillReleaseRegistry ||
+        fsImpl !== fs ||
+        secure !== true ||
+        descriptor.component !== TENANT_MARKER_COMPONENT ||
+        descriptor.tenantId !== ownerTenantId ||
+        !samePath(descriptor.baseDir, requestedBase)
+      )
+        throw failure(
+          RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+          "release v2 binding or native storage options differ",
+        );
+      // Authenticate the original port object before reading any caller method.
+      this.#storeBinding.assertTransactionLedger(transactionLedger);
+      this.#storeBinding.recheckForOpen();
+      this.#runtimeMode = "uninitialized";
+    } else assertOutsideRrsiRegistryNamespace(requestedBase);
     if (
       !transactionLedger ||
       typeof transactionLedger.prepare !== "function" ||
@@ -2742,57 +2810,103 @@ export class SkillReleaseRegistry {
     this.#now = now;
     this.#leaseTtlMs = leaseTtlMs;
     this.#crashHook = crashHook;
-    this.#ledgerPrepare = transactionLedger.prepare.bind(transactionLedger);
-    this.#ledgerFinalize = transactionLedger.finalize.bind(transactionLedger);
-    this.#ledgerMigrate =
-      typeof transactionLedger.migrate === "function"
-        ? transactionLedger.migrate.bind(transactionLedger)
+    const captureTransactionMethod = (name) => {
+      const method = transactionLedger[name];
+      return typeof method === "function"
+        ? (...args) => Reflect.apply(method, transactionLedger, args)
         : null;
-    this.#ledgerQuery = transactionLedger.query.bind(transactionLedger);
+    };
+    this.#ledgerPrepare = captureTransactionMethod("prepare");
+    this.#ledgerFinalize = captureTransactionMethod("finalize");
+    this.#ledgerMigrate = captureTransactionMethod("migrate");
+    this.#ledgerQuery = captureTransactionMethod("query");
     Object.freeze(transactionLedger);
 
     this.tenantId = ownerTenantId;
     this.tenantKey = deriveSkillReleaseTenantKey(ownerTenantId);
-    const requestedBase = path.resolve(rootDir);
     try {
-      const base = this.#initializeDirectory(requestedBase, {
-        recursive: true,
-      });
-      this.baseDir = base.path;
-      this.#assertNoLegacyBaseLayout();
-      const tenants = this.#initializeDirectory(
-        path.join(this.baseDir, "tenants"),
-        { parent: base },
-      );
-      const tenantRoot = this.#initializeDirectory(
-        path.join(tenants.path, this.tenantKey),
-        { parent: tenants },
-      );
-      this.rootDir = tenantRoot.path;
-      this.#boundaries = deepFreeze({ base, tenantRoot, tenants });
-      this.#rootIdentity = tenantRoot.identity;
-      this.#markerPath = path.join(this.rootDir, TENANT_MARKER_FILE);
-      this.#initializeTenantMarker();
-      this.#directories = {};
-      for (const name of [
-        "artifacts",
-        "active",
-        "journals",
-        "locks",
-        "state-migrations",
-        "staging",
-      ]) {
-        const directory = path.join(this.rootDir, name);
-        this.#directories[name] = this.#initializeDirectory(directory, {
-          parent: tenantRoot,
+      if (this.#storeBinding) {
+        this.#boundaries = this.#storeBinding.boundaries;
+        this.baseDir = this.#boundaries.base.path;
+        this.rootDir = this.#boundaries.tenantRoot.path;
+        this.#rootIdentity = this.#boundaries.tenantRoot.identity;
+        this.#markerPath = path.join(this.rootDir, TENANT_MARKER_FILE);
+        this.#markerIdentity = this.#storeBinding.marker.identity;
+        this.#directories = deepFreeze({});
+        this.#assertBoundary();
+      } else {
+        const base = this.#initializeDirectory(requestedBase, {
+          recursive: true,
+          harden: false,
+        });
+        this.baseDir = base.path;
+        this.#assertUnboundNamespace();
+        this.#assertNoLegacyBaseLayout();
+        const tenants = this.#initializeDirectory(
+          path.join(this.baseDir, "tenants"),
+          { parent: base, harden: false },
+        );
+        const tenantRoot = this.#initializeDirectory(
+          path.join(tenants.path, this.tenantKey),
+          { parent: tenants, harden: false },
+        );
+        this.rootDir = tenantRoot.path;
+        this.#assertUnboundNamespace();
+        this.#boundaries = deepFreeze({ base, tenantRoot, tenants });
+        this.#rootIdentity = tenantRoot.identity;
+        this.#markerPath = path.join(this.rootDir, TENANT_MARKER_FILE);
+        this.#writerControl = createSkillRegistryWriterControl({
+          rootDir: this.rootDir,
+          tenantId: this.tenantId,
+          component: TENANT_MARKER_COMPONENT,
+          fsImpl: this.#fs,
+        });
+        this.#writerControl.runSync(() => {
+          if (this.#secure) {
+            for (const [entry, parent] of [
+              [base, null],
+              [tenants, base],
+              [tenantRoot, tenants],
+            ]) {
+              this.#writerControl.assertIfWriting();
+              const hardened = this.#initializeDirectory(entry.path, {
+                parent,
+              });
+              if (
+                hardened.identity !== entry.identity ||
+                !samePath(hardened.path, entry.path)
+              )
+                throw failure(
+                  "SKILL_RELEASE_STORE_UNSAFE",
+                  "release bootstrap identity changed before permission hardening",
+                );
+            }
+          }
+          this.#writerControl.assertIfWriting();
+          this.#initializeTenantMarker();
+          this.#directories = {};
+          for (const name of [
+            "artifacts",
+            "active",
+            "journals",
+            "locks",
+            "state-migrations",
+            "staging",
+          ]) {
+            const directory = path.join(this.rootDir, name);
+            this.#directories[name] = this.#initializeDirectory(directory, {
+              parent: tenantRoot,
+            });
+          }
+          this.#directories = deepFreeze(this.#directories);
+          this.#assertBoundary();
+          this.#assertNoLegacyTenantSchemas();
+          this.#recoverAll();
+          this.#cleanupDebris();
         });
       }
-      this.#directories = deepFreeze(this.#directories);
-      this.#assertBoundary();
-      this.#assertNoLegacyTenantSchemas();
-      this.#recoverAll();
-      this.#cleanupDebris();
     } catch (cause) {
+      if (cause?.code === RRSI_REGISTRY_STORE_POLICY_HOLD_CODE) throw cause;
       if (cause instanceof SkillReleaseRegistryError) throw cause;
       throw failure(
         "SKILL_RELEASE_STORE_UNSAFE",
@@ -2804,20 +2918,28 @@ export class SkillReleaseRegistry {
       this,
       Object.freeze({
         tenantId: ownerTenantId,
-        readActive: SkillReleaseRegistry.prototype.readActive.bind(this),
-        readState: SkillReleaseRegistry.prototype.readState.bind(this),
-        readRelease: SkillReleaseRegistry.prototype.readRelease.bind(this),
-        readInventory: SkillReleaseRegistry.prototype.readInventory.bind(this),
+        storePolicyDescriptor: this.#storeBinding?.descriptor ?? null,
+        matchesStorePolicyBinding: (value) =>
+          value === storePolicyBinding && this.#storeBinding !== undefined,
+        // Private reads never dispatch through a genuine subclass or mutable
+        // function.bind property. Constructor recovery uses these paths too.
+        readActive: (name) => this.#readActive(name),
+        readState: (name) => this.#readState(name),
+        readRelease: (value) => this.#readRelease(value),
+        readInventory: () => this.#readInventory(),
         matchesTransactionLedger: (value) => value === transactionLedger,
       }),
     );
+    REGISTRY_WRITERS.set(this, this.#writerControl);
     Object.freeze(this);
   }
 
   #initializeDirectory(
     requestedPath,
-    { parent = null, recursive = false } = {},
+    { parent = null, recursive = false, harden = true } = {},
   ) {
+    this.#assertMutationNamespace();
+    const namespaceTarget = assertOutsideRrsiRegistryNamespace(requestedPath);
     const before = lstatOrNull(this.#fs, requestedPath);
     if (before && (!before.isDirectory() || before.isSymbolicLink())) {
       throw failure(
@@ -2826,6 +2948,16 @@ export class SkillReleaseRegistry {
       );
     }
     if (!before) {
+      if (
+        !samePath(
+          assertOutsideRrsiRegistryNamespace(requestedPath),
+          namespaceTarget,
+        )
+      )
+        throw failure(
+          RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+          "release initialization ancestor changed",
+        );
       this.#fs.mkdirSync(requestedPath, { recursive, mode: 0o700 });
     }
     let stat = this.#fs.lstatSync(requestedPath);
@@ -2837,6 +2969,12 @@ export class SkillReleaseRegistry {
     }
     const capturedIdentity = identity(stat);
     const canonical = realpath(this.#fs, requestedPath);
+    assertOutsideRrsiRegistryNamespace(canonical);
+    if (!samePath(canonical, namespaceTarget))
+      throw failure(
+        RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+        "release canonical initialization target changed",
+      );
     const canonicalStat = this.#fs.lstatSync(canonical);
     const canonicalParent = realpath(this.#fs, path.dirname(requestedPath));
     const expectedCanonical = path.join(
@@ -2857,7 +2995,7 @@ export class SkillReleaseRegistry {
         "release registry directory escaped its canonical parent",
       );
     }
-    if (this.#secure) {
+    if (this.#secure && harden) {
       ensurePrivateDirectory(canonical, {
         applyWindowsAcl: true,
         failIfUnavailable: true,
@@ -2878,6 +3016,18 @@ export class SkillReleaseRegistry {
     return deepFreeze({ path: canonical, identity: capturedIdentity });
   }
 
+  #assertUnboundNamespace() {
+    if (this.#storeBinding) return;
+    for (const directory of [this.baseDir, this.rootDir])
+      if (directory !== undefined)
+        assertOutsideRrsiRegistryNamespace(directory);
+  }
+
+  #assertMutationNamespace() {
+    this.#storeBinding?.assertMutationAllowed();
+    this.#assertUnboundNamespace();
+  }
+
   #assertNoLegacyBaseLayout() {
     for (const entry of this.#fs.readdirSync(this.baseDir)) {
       if (entry !== "tenants") {
@@ -2890,6 +3040,7 @@ export class SkillReleaseRegistry {
   }
 
   #initializeTenantMarker() {
+    this.#assertMutationNamespace();
     return withEvolutionFileIdentity(
       this.#fs,
       this.#markerPath,
@@ -2899,6 +3050,7 @@ export class SkillReleaseRegistry {
   }
 
   #initializeTenantMarkerWithIdentity(sameStable) {
+    this.#assertMutationNamespace();
     const existing = lstatOrNull(this.#fs, this.#markerPath);
     if (existing) {
       const verified = this.#readAndVerifyTenantMarker();
@@ -3002,6 +3154,10 @@ export class SkillReleaseRegistry {
   }
 
   #readAndVerifyTenantMarker() {
+    if (this.#storeBinding) {
+      this.#storeBinding.recheck();
+      return this.#storeBinding.marker;
+    }
     try {
       const stored = readBoundedSingleLinkFile(
         this.#fs,
@@ -3053,6 +3209,12 @@ export class SkillReleaseRegistry {
   }
 
   #assertBoundary() {
+    if (this.#storeBinding) {
+      this.#storeBinding.recheck();
+      return;
+    }
+    this.#assertUnboundNamespace();
+    this.#writerControl?.assertIfWriting();
     for (const entry of [
       ...Object.values(this.#boundaries),
       ...Object.values(this.#directories),
@@ -3253,6 +3415,7 @@ export class SkillReleaseRegistry {
   }
 
   #writeTemporary(fileName, value) {
+    this.#assertMutationNamespace();
     if (!TEMP_PATTERN.test(fileName)) {
       throw failure("SKILL_RELEASE_STORE_UNSAFE", "temporary name is invalid");
     }
@@ -3263,6 +3426,7 @@ export class SkillReleaseRegistry {
   }
 
   #writeTemporaryWithIdentity(filePath, value, sameStable) {
+    this.#assertMutationNamespace();
     const bytes = serialize(value);
     let descriptor = null;
     let writtenIdentity = null;
@@ -3312,6 +3476,7 @@ export class SkillReleaseRegistry {
   }
 
   #atomicWrite(area, destination, value) {
+    this.#assertMutationNamespace();
     const expectedBytes = serialize(value);
     const name = `.write-${process.pid}-${this.#token()}.tmp`;
     const temporary = this.#writeTemporary(name, value);
@@ -3357,6 +3522,7 @@ export class SkillReleaseRegistry {
   }
 
   #unlink(filePath, directory) {
+    this.#assertMutationNamespace();
     try {
       this.#fs.unlinkSync(filePath);
       fsyncDirectory(this.#fs, directory);
@@ -3366,6 +3532,7 @@ export class SkillReleaseRegistry {
   }
 
   #publishRelease(release) {
+    this.#assertMutationNamespace();
     const destination = this.#releasePath(release.releaseDigest);
     const name = `.release-${process.pid}-${this.#token()}.tmp`;
     const temporary = this.#writeTemporary(name, release);
@@ -3377,7 +3544,7 @@ export class SkillReleaseRegistry {
         this.#fs.linkSync(temporary, destination);
       } catch (error) {
         if (error?.code !== "EEXIST") throw error;
-        const existing = this.readRelease(release.releaseDigest);
+        const existing = this.#readRelease(release.releaseDigest);
         if (!serialize(existing).equals(bytes)) {
           throw failure("SKILL_RELEASE_CONFLICT", "release digest collision");
         }
@@ -3428,17 +3595,26 @@ export class SkillReleaseRegistry {
   }
 
   #createRelease(input) {
+    this.#assertMutationNamespace();
     const release = buildSkillRelease(input);
     const created = this.#publishRelease(release);
     return deepFreeze({ release, created });
   }
 
   migrateLegacyRelease(input, migrationAuthority) {
+    this.#assertMutationNamespace();
     if (arguments.length !== 2) {
       throw migrationRequired(
         "legacy release migration requires input and a durable audit authority",
       );
     }
+    return this.#writerControl.runSync(() =>
+      this.#migrateLegacyRelease(input, migrationAuthority),
+    );
+  }
+
+  #migrateLegacyRelease(input, migrationAuthority) {
+    this.#assertMutationNamespace();
     assertExactKeys(
       migrationAuthority,
       RELEASE_MIGRATION_AUTHORITY_KEYS,
@@ -3575,11 +3751,19 @@ export class SkillReleaseRegistry {
   }
 
   migrateLegacyState(planInput, migrationAuthority) {
+    this.#assertMutationNamespace();
     if (arguments.length !== 2 || this.#ledgerMigrate === null) {
       throw migrationRequired(
         "legacy state migration requires a plan, durable authority, and authenticated ledger migration port",
       );
     }
+    return this.#writerControl.runSync(() =>
+      this.#migrateLegacyState(planInput, migrationAuthority),
+    );
+  }
+
+  #migrateLegacyState(planInput, migrationAuthority) {
+    this.#assertMutationNamespace();
     const plan = verifySkillReleaseStateMigrationPlan(planInput);
     if (plan.tenantId !== this.tenantId) {
       throw migrationRequired("state migration plan belongs to another tenant");
@@ -3607,8 +3791,8 @@ export class SkillReleaseRegistry {
       migrationAuthority.handlerArtifactDigest,
       "stateMigrationAuthority.handlerArtifactDigest",
     );
-    const active = this.readRelease(plan.activeReleaseDigest);
-    const lastKnownGood = this.readRelease(plan.lastKnownGoodReleaseDigest);
+    const active = this.#readRelease(plan.activeReleaseDigest);
+    const lastKnownGood = this.#readRelease(plan.lastKnownGoodReleaseDigest);
     if (
       active.skillName !== plan.skillName ||
       lastKnownGood.skillName !== plan.skillName ||
@@ -3681,7 +3865,7 @@ export class SkillReleaseRegistry {
         { stateMigrationDigest: plan.stateMigrationDigest },
       );
     }
-    const existing = this.readState(plan.skillName);
+    const existing = this.#readState(plan.skillName);
     if (existing.revision > 0) {
       if (
         existing.transactionId !== plan.stateMigrationDigest ||
@@ -3783,7 +3967,15 @@ export class SkillReleaseRegistry {
   }
 
   readRelease(releaseDigest) {
+    return this.#readRelease(releaseDigest);
+  }
+
+  #readRelease(releaseDigest) {
     const expected = digest(releaseDigest, "releaseDigest");
+    if (this.#runtimeMode === "uninitialized") {
+      this.#assertBoundary();
+      throw failure("SKILL_RELEASE_NOT_FOUND", "release was not found");
+    }
     let value;
     try {
       value = this.#readJson(
@@ -3819,6 +4011,10 @@ export class SkillReleaseRegistry {
 
   #readStateRaw(name) {
     const normalizedName = skillName(name);
+    if (this.#runtimeMode === "uninitialized") {
+      this.#assertBoundary();
+      return initialState(normalizedName, this.tenantId);
+    }
     try {
       const state = verifySkillReleaseState(
         this.#readJson(
@@ -3888,8 +4084,8 @@ export class SkillReleaseRegistry {
         "active pointer is not finalized by the trusted transaction ledger",
       );
     }
-    const active = this.readRelease(state.activeReleaseDigest);
-    const lkg = this.readRelease(state.lastKnownGoodReleaseDigest);
+    const active = this.#readRelease(state.activeReleaseDigest);
+    const lkg = this.#readRelease(state.lastKnownGoodReleaseDigest);
     if (
       active.skillName !== state.skillName ||
       lkg.skillName !== state.skillName ||
@@ -3907,17 +4103,25 @@ export class SkillReleaseRegistry {
   }
 
   readState(name) {
+    return this.#readState(name);
+  }
+
+  #readState(name) {
     const state = this.#readStateRaw(name);
     return state.revision === 0 ? state : this.#verifyCommittedState(state);
   }
 
   readActive(name) {
-    const state = this.readState(name);
+    return this.#readActive(name);
+  }
+
+  #readActive(name) {
+    const state = this.#readState(name);
     return state.revision === 0
       ? null
       : deepFreeze({
           state,
-          release: this.readRelease(state.activeReleaseDigest),
+          release: this.#readRelease(state.activeReleaseDigest),
         });
   }
 
@@ -3981,7 +4185,13 @@ export class SkillReleaseRegistry {
   }
 
   readInventory() {
+    return this.#readInventory();
+  }
+
+  #readInventory() {
     this.#assertBoundary();
+    if (this.#runtimeMode === "uninitialized")
+      return deepFreeze({ active: [], releases: [] });
     const releasePattern = /^[a-f0-9]{64}\.json$/u;
     const statePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.json$/u;
     const beforeReleases = this.#readInventoryNames(
@@ -3999,11 +4209,11 @@ export class SkillReleaseRegistry {
       );
     }
     const releases = beforeReleases.map((name) =>
-      this.readRelease(`sha256:${name.slice(0, -".json".length)}`),
+      this.#readRelease(`sha256:${name.slice(0, -".json".length)}`),
     );
     const active = beforeStates.map((name) => {
       const skill = name.slice(0, -".json".length);
-      const value = this.readActive(skill);
+      const value = this.#readActive(skill);
       if (value === null) {
         throw failure(
           "SKILL_RELEASE_STATE_CORRUPT",
@@ -4041,7 +4251,7 @@ export class SkillReleaseRegistry {
     const afterReleases = this.#readInventoryNames("artifacts", releasePattern);
     const afterStates = this.#readInventoryNames("active", statePattern);
     const afterStateDigests = afterStates.map(
-      (name) => this.readState(name.slice(0, -".json".length)).stateDigest,
+      (name) => this.#readState(name.slice(0, -".json".length)).stateDigest,
     );
     if (
       canonicalJson(beforeReleases) !== canonicalJson(afterReleases) ||
@@ -4060,7 +4270,7 @@ export class SkillReleaseRegistry {
   }
 
   pinActive(name) {
-    const active = this.readActive(name);
+    const active = this.#readActive(name);
     if (!active)
       throw failure("SKILL_RELEASE_NOT_ACTIVE", "Skill has no active release");
     const pin = Object.freeze(Object.create(null));
@@ -4094,7 +4304,7 @@ export class SkillReleaseRegistry {
         "pinned activation is not committed",
       );
     }
-    return this.readRelease(binding.releaseDigest);
+    return this.#readRelease(binding.releaseDigest);
   }
 
   #owner(kind, token, { skill = null, transactionId = null, fence = 0 } = {}) {
@@ -4210,6 +4420,7 @@ export class SkillReleaseRegistry {
   }
 
   #createLock(lockPath, owner) {
+    this.#assertMutationNamespace();
     this.#fs.mkdirSync(lockPath, { mode: 0o700 });
     let descriptor = null;
     try {
@@ -4239,6 +4450,7 @@ export class SkillReleaseRegistry {
   }
 
   #removeLock(lockPath, expectedToken = null) {
+    this.#assertMutationNamespace();
     let owner;
     try {
       owner = this.#readOwner(lockPath);
@@ -4300,6 +4512,7 @@ export class SkillReleaseRegistry {
   }
 
   #renewLease(lease) {
+    this.#assertMutationNamespace();
     const current = this.#readOwner(lease.lockPath);
     if (
       current.token !== lease.token ||
@@ -4338,6 +4551,7 @@ export class SkillReleaseRegistry {
   }
 
   #acquireLease(name, transactionId, expectedRevision, expectedParentDigest) {
+    this.#assertMutationNamespace();
     const journalPath = this.#journalPath(name);
     if (this.#exists(journalPath)) {
       this.#withRecoveryLock(() => this.#recoverSkill(name));
@@ -4350,11 +4564,11 @@ export class SkillReleaseRegistry {
     }
     const lockPath = this.#leasePath(name);
     for (let attempt = 0; attempt < 2; attempt += 1) {
-      const state = this.readState(name);
+      const state = this.#readState(name);
       const active =
         state.activeReleaseDigest === null
           ? null
-          : this.readRelease(state.activeReleaseDigest);
+          : this.#readRelease(state.activeReleaseDigest);
       const actualParent = active?.contentDigest ?? EMPTY_SKILL_ACTIVE_DIGEST;
       if (
         state.revision !== expectedRevision ||
@@ -4805,6 +5019,7 @@ export class SkillReleaseRegistry {
   }
 
   #prepare(intent, targetRelease) {
+    this.#assertMutationNamespace();
     let projection;
     try {
       projection = this.#ledgerPrepare(intent, targetRelease);
@@ -4836,6 +5051,7 @@ export class SkillReleaseRegistry {
   }
 
   #finalize(journal, prepareReceipt) {
+    this.#assertMutationNamespace();
     const request = deepFreeze({
       authorityReceiptDigest: journal.intent.authorityReceiptDigest,
       expectedPrepareReceiptDigest: prepareReceipt.receiptDigest,
@@ -4882,6 +5098,7 @@ export class SkillReleaseRegistry {
   }
 
   #writePointer(state, stagedFile) {
+    this.#assertMutationNamespace();
     const stagedPath = this.#path("staging", stagedFile);
     if (!this.#exists(stagedPath)) this.#writeTemporary(stagedFile, state);
     const expectedBytes = serialize(state);
@@ -4994,7 +5211,7 @@ export class SkillReleaseRegistry {
         );
       }
 
-      const verifiedRelease = this.readRelease(release.releaseDigest);
+      const verifiedRelease = this.#readRelease(release.releaseDigest);
       if (
         verifiedRelease.tenantId !== this.tenantId ||
         verifiedRelease.skillName !== state.skillName ||
@@ -5022,7 +5239,7 @@ export class SkillReleaseRegistry {
   #assertJournalFinalizationArtifacts(journal) {
     let release;
     try {
-      release = this.readRelease(journal.nextState.activeReleaseDigest);
+      release = this.#readRelease(journal.nextState.activeReleaseDigest);
     } catch (cause) {
       throw failure(
         "SKILL_RELEASE_FINALIZATION_INPUT_INVALID",
@@ -5091,6 +5308,7 @@ export class SkillReleaseRegistry {
   }
 
   #recoverJournal(journal) {
+    this.#assertMutationNamespace();
     const expected = {
       authorityReceiptDigest: journal.intent.authorityReceiptDigest,
       intentDigest: journal.intent.intentDigest,
@@ -5132,6 +5350,7 @@ export class SkillReleaseRegistry {
   }
 
   #recoverSkill(name, { force = false } = {}) {
+    this.#assertMutationNamespace();
     const journalPath = this.#journalPath(name);
     const lockPath = this.#leasePath(name);
     if (!this.#exists(journalPath)) {
@@ -5174,6 +5393,7 @@ export class SkillReleaseRegistry {
   }
 
   #recoverStateMigration(journal, { force = false } = {}) {
+    this.#assertMutationNamespace();
     const lockPath = this.#leasePath(journal.skillName);
     if (this.#exists(lockPath)) {
       const owner = this.#readOwner(lockPath);
@@ -5222,13 +5442,14 @@ export class SkillReleaseRegistry {
         journal.state,
       );
     }
-    const release = this.readRelease(journal.state.activeReleaseDigest);
+    const release = this.#readRelease(journal.state.activeReleaseDigest);
     this.#assertFinalizationArtifacts(journal.state, release);
     this.#cleanupStateMigration(journal);
     return "committed";
   }
 
   #recoverAll() {
+    this.#assertMutationNamespace();
     this.#withRecoveryLock(() => {
       for (const name of this.#fs.readdirSync(
         this.#directories["state-migrations"].path,
@@ -5275,6 +5496,7 @@ export class SkillReleaseRegistry {
   }
 
   #cleanupDebris() {
+    this.#assertMutationNamespace();
     const referenced = new Set();
     for (const name of this.#fs.readdirSync(this.#directories.journals.path)) {
       if (name.endsWith(".json")) {
@@ -5463,6 +5685,14 @@ export class SkillReleaseRegistry {
   }
 
   async applyTransition(capability) {
+    this.#assertMutationNamespace();
+    return this.#writerControl.runAsync(() =>
+      this.#applyTransition(capability),
+    );
+  }
+
+  async #applyTransition(capability) {
+    this.#assertMutationNamespace();
     const payload = this.#validateTransitionPayload(
       consumeRegistryTransitionCapability(capability, this),
     );
@@ -5477,7 +5707,7 @@ export class SkillReleaseRegistry {
       target = created.release;
       releaseCreated = created.created;
     } else {
-      target = this.readRelease(payload.targetReleaseDigest);
+      target = this.#readRelease(payload.targetReleaseDigest);
     }
     if (
       target.skillName !== payload.skillName ||