chainlesschain 0.166.90 → 0.166.92

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

@@ -5,6 +5,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 {
   verifySkillDependencyLock,
   verifySkillRuntimeManifest,
@@ -171,6 +177,7 @@ const REGISTRY_OPTION_KEYS = new Set([
   "randomToken",
   "rootDir",
   "secure",
+  "storePolicyBinding",
   "tenantId",
   "targetMatrixAdmissionAuthority",
 ]);
@@ -1519,6 +1526,11 @@ function normalizeRegistryOptions(options) {
     randomToken,
     rootDir,
     secure,
+    storePolicyBinding: ownData(
+      options,
+      "storePolicyBinding",
+      "candidate registry options",
+    ),
     targetMatrixAdmissionAuthority,
     tenantId,
   };
@@ -1531,6 +1543,7 @@ function normalizeRegistryOptions(options) {
  * promotion controller can consume verified drafts through read().
  */
 const CANDIDATE_READERS = new WeakMap();
+const CANDIDATE_WRITERS = new WeakMap();
 
 export function captureSkillCandidateRegistryReader(registry) {
   const reader = CANDIDATE_READERS.get(registry);
@@ -1543,16 +1556,48 @@ export function captureSkillCandidateRegistryReader(registry) {
   return reader;
 }
 
+export function captureSkillCandidateRegistryWriterControl(registry) {
+  captureSkillCandidateRegistryReader(registry);
+  const control = CANDIDATE_WRITERS.get(registry);
+  if (!control)
+    throw new TypeError(
+      "a genuine candidate Registry writer control is required",
+    );
+  return control;
+}
+
 export class SkillCandidateRegistry {
+  #writerControl;
+  #storeBinding;
   constructor(options) {
     const {
       fsImpl,
       randomToken,
       rootDir,
       secure,
+      storePolicyBinding,
       targetMatrixAdmissionAuthority,
       tenantId,
     } = normalizeRegistryOptions(options);
+    const requestedBase = path.resolve(rootDir);
+    if (storePolicyBinding !== undefined) {
+      this.#storeBinding =
+        captureRrsiRegistryComponentBinding(storePolicyBinding);
+      const descriptor = this.#storeBinding.descriptor;
+      if (
+        new.target !== SkillCandidateRegistry ||
+        fsImpl !== fs ||
+        secure !== true ||
+        descriptor.component !== TENANT_MARKER_COMPONENT ||
+        descriptor.tenantId !== tenantId ||
+        !samePath(descriptor.baseDir, requestedBase)
+      )
+        throw registryError(
+          RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+          "candidate v2 binding or native storage options differ",
+        );
+      this.#storeBinding.recheckForOpen();
+    } else assertOutsideRrsiRegistryNamespace(requestedBase);
     this._fs = fsImpl;
     this._secure = secure;
     this._randomToken = randomToken;
@@ -1561,29 +1606,72 @@ export class SkillCandidateRegistry {
       targetMatrixAdmissionAuthority.descriptor;
     this.tenantId = tenantId;
     this.tenantKey = deriveSkillCandidateTenantKey(tenantId);
-    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._directories = deepFreeze({ base, tenantRoot, tenants });
-      this._assertDirectories();
-      this._markerPath = path.join(this.rootDir, TENANT_MARKER_FILE);
-      this._initializeTenantMarker();
-      this._assertBoundary();
-      this._assertNoMixedTenantArtifacts();
+      if (this.#storeBinding) {
+        this._directories = this.#storeBinding.boundaries;
+        this.baseDir = this._directories.base.path;
+        this.rootDir = this._directories.tenantRoot.path;
+        this._markerPath = path.join(this.rootDir, TENANT_MARKER_FILE);
+        this._markerIdentity = this.#storeBinding.marker.identity;
+        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._directories = deepFreeze({ base, tenantRoot, tenants });
+        this._assertDirectories();
+        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(() => {
+          // Bootstrap may create missing directories; existing-path ACL repair
+          // waits for writer exclusion and must preserve the captured identities.
+          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 registryError(
+                  "SKILL_CANDIDATE_STORE_UNSAFE",
+                  "candidate bootstrap identity changed before permission hardening",
+                );
+            }
+          }
+          this.#writerControl.assertIfWriting();
+          this._initializeTenantMarker();
+          this._assertBoundary();
+          this._assertNoMixedTenantArtifacts();
+        });
+      }
     } catch (error) {
+      if (error?.code === RRSI_REGISTRY_STORE_POLICY_HOLD_CODE) throw error;
       if (error instanceof SkillCandidateRegistryError) throw error;
       throw registryError(
         "SKILL_CANDIDATE_STORE_UNSAFE",
@@ -1596,18 +1684,31 @@ export class SkillCandidateRegistry {
       this,
       Object.freeze({
         tenantId,
-        read: Object.freeze(SkillCandidateRegistry.prototype.read.bind(this)),
-        readInventory: Object.freeze(
-          SkillCandidateRegistry.prototype.readInventory.bind(this),
+        storePolicyDescriptor: this.#storeBinding?.descriptor ?? null,
+        matchesStorePolicyBinding: Object.freeze(
+          (value) =>
+            value === storePolicyBinding && this.#storeBinding !== undefined,
         ),
+        read: Object.freeze((value) => this.#read(value)),
+        readInventory: Object.freeze(() => this.#readInventory()),
       }),
     );
+    CANDIDATE_WRITERS.set(this, this.#writerControl);
   }
 
   _initializeDirectory(
     requestedPath,
-    { parent = null, recursive = false } = {},
+    { parent = null, recursive = false, harden = true } = {},
   ) {
+    if (this.#storeBinding) {
+      this.#storeBinding.recheck();
+      const entry = Object.values(this.#storeBinding.boundaries).find((value) =>
+        samePath(value.path, path.resolve(requestedPath)),
+      );
+      if (!entry) this.#storeBinding.assertMutationAllowed();
+      return entry;
+    }
+    const namespaceTarget = assertOutsideRrsiRegistryNamespace(requestedPath);
     const before = lstatOrNull(this._fs, requestedPath);
     if (before && (!before.isDirectory() || before.isSymbolicLink())) {
       throw registryError(
@@ -1616,6 +1717,16 @@ export class SkillCandidateRegistry {
       );
     }
     if (!before) {
+      if (
+        !samePath(
+          assertOutsideRrsiRegistryNamespace(requestedPath),
+          namespaceTarget,
+        )
+      )
+        throw registryError(
+          RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+          "candidate initialization ancestor changed",
+        );
       this._fs.mkdirSync(requestedPath, { recursive, mode: 0o700 });
     }
     let stat = this._fs.lstatSync(requestedPath);
@@ -1627,6 +1738,12 @@ export class SkillCandidateRegistry {
     }
     const capturedIdentity = entryIdentity(stat);
     const canonical = realpath(this._fs, requestedPath);
+    assertOutsideRrsiRegistryNamespace(canonical);
+    if (!samePath(canonical, namespaceTarget))
+      throw registryError(
+        RRSI_REGISTRY_STORE_POLICY_HOLD_CODE,
+        "candidate canonical initialization target changed",
+      );
     const canonicalStat = this._fs.lstatSync(canonical);
     const canonicalParent = realpath(this._fs, path.dirname(requestedPath));
     const expectedCanonical = path.join(
@@ -1647,7 +1764,7 @@ export class SkillCandidateRegistry {
         "candidate registry directory escaped its canonical parent",
       );
     }
-    if (this._secure) {
+    if (this._secure && harden) {
       ensurePrivateDirectory(canonical, {
         applyWindowsAcl: true,
         failIfUnavailable: true,
@@ -1668,6 +1785,18 @@ export class SkillCandidateRegistry {
     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() {
     const legacyName = this._readDirectoryEntryNamesBounded(
       this.baseDir,
@@ -1794,6 +1923,8 @@ export class SkillCandidateRegistry {
   }
 
   _initializeTenantMarker() {
+    if (this.#storeBinding) return this._readAndVerifyTenantMarker();
+    this.#assertUnboundNamespace();
     return withEvolutionFileIdentity(
       this._fs,
       this._markerPath,
@@ -1803,6 +1934,7 @@ export class SkillCandidateRegistry {
   }
 
   #initializeTenantMarkerWithIdentity(sameStable) {
+    this.#assertMutationNamespace();
     const existing = lstatOrNull(this._fs, this._markerPath);
     if (existing) {
       const verified = this._readAndVerifyTenantMarker();
@@ -1980,6 +2112,10 @@ export class SkillCandidateRegistry {
   }
 
   _readAndVerifyTenantMarker() {
+    if (this.#storeBinding) {
+      this.#storeBinding.recheck();
+      return this.#storeBinding.marker;
+    }
     let stored;
     try {
       stored = this._readBoundedRegularFile(
@@ -2014,6 +2150,12 @@ export class SkillCandidateRegistry {
   }
 
   _assertBoundary() {
+    if (this.#storeBinding) {
+      this.#storeBinding.recheck();
+      return;
+    }
+    this.#assertUnboundNamespace();
+    this.#writerControl?.assertIfWriting();
     this._assertDirectories();
     const verified = this._readAndVerifyTenantMarker();
     if (
@@ -2179,11 +2321,23 @@ export class SkillCandidateRegistry {
   }
 
   migrateLegacy(legacyCandidate, executionArtifacts, migrationAuthority) {
+    this.#assertMutationNamespace();
     if (arguments.length !== 3) {
       throw migrationRequired(
         "legacy migration requires candidate, execution artifacts, and a durable audit authority",
       );
     }
+    return this.#writerControl.runSync(() =>
+      this.#migrateLegacy(
+        legacyCandidate,
+        executionArtifacts,
+        migrationAuthority,
+      ),
+    );
+  }
+
+  #migrateLegacy(legacyCandidate, executionArtifacts, migrationAuthority) {
+    this.#assertMutationNamespace();
     const legacy = verifyLegacySkillCandidateDraft(legacyCandidate);
     assertDataRecord(
       executionArtifacts,
@@ -2268,7 +2422,7 @@ export class SkillCandidateRegistry {
       );
     }
 
-    const publication = this.create({
+    const publication = this.#create({
       tenantId: this.tenantId,
       skillName: legacy.skillName,
       parentDigest: legacy.parentDigest,
@@ -2407,6 +2561,7 @@ export class SkillCandidateRegistry {
     resolveExecutionArtifacts,
     migrationAuthority,
   ) {
+    this.#assertMutationNamespace();
     if (
       arguments.length !== 3 ||
       typeof resolveExecutionArtifacts !== "function"
@@ -2415,6 +2570,21 @@ export class SkillCandidateRegistry {
         "legacy store migration requires one source root, one execution resolver, and one audit authority",
       );
     }
+    return this.#writerControl.runSync(() =>
+      this.#migrateLegacyStore(
+        sourceRootDir,
+        resolveExecutionArtifacts,
+        migrationAuthority,
+      ),
+    );
+  }
+
+  #migrateLegacyStore(
+    sourceRootDir,
+    resolveExecutionArtifacts,
+    migrationAuthority,
+  ) {
+    this.#assertMutationNamespace();
     assertDataRecord(
       migrationAuthority,
       MIGRATION_AUTHORITY_KEYS,
@@ -2599,7 +2769,7 @@ export class SkillCandidateRegistry {
           },
         );
       }
-      const migrated = this.migrateLegacy(
+      const migrated = this.#migrateLegacy(
         source.legacy,
         executionArtifacts,
         capturedMigrationAuthority,
@@ -2658,12 +2828,18 @@ export class SkillCandidateRegistry {
   }
 
   create(input) {
+    this.#assertMutationNamespace();
     if (arguments.length !== 1) {
       throw registryError(
         "SKILL_CANDIDATE_INVALID",
         "candidate create accepts only input; admission context is registry-owned",
       );
     }
+    return this.#writerControl.runSync(() => this.#create(input));
+  }
+
+  #create(input) {
+    this.#assertMutationNamespace();
     return withEvolutionFileIdentity(
       this._fs,
       this._markerPath,
@@ -2672,6 +2848,7 @@ export class SkillCandidateRegistry {
   }
 
   #createWithIdentity(input, sameStable) {
+    this.#assertMutationNamespace();
     this._assertNoMixedTenantArtifacts();
     const verificationContext = this._resolveAdmissionContext(input);
     const candidate = buildSkillCandidateDraft(input, verificationContext);
@@ -2879,12 +3056,18 @@ export class SkillCandidateRegistry {
   }
 
   read(candidateId) {
+    return this.#read(candidateId);
+  }
+
+  #read(candidateId) {
     const normalizedId = normalizeCandidateId(candidateId);
+    this.#storeBinding?.recheck();
     const filePath = this._candidatePath(normalizedId);
     let bytes;
     try {
       bytes = this._readBytes(filePath);
     } catch (error) {
+      if (error?.code === RRSI_REGISTRY_STORE_POLICY_HOLD_CODE) throw error;
       if (error instanceof SkillCandidateRegistryError) throw error;
       if (error?.code === "ENOENT") {
         throw registryError(
@@ -2955,12 +3138,16 @@ export class SkillCandidateRegistry {
   }
 
   readInventory() {
+    return this.#readInventory();
+  }
+
+  #readInventory() {
     const before = this._assertNoMixedTenantArtifacts()
       .filter((name) => CANDIDATE_FILE_PATTERN.test(name))
       .sort();
     const candidates = before.map((name) => {
       const match = CANDIDATE_FILE_PATTERN.exec(name);
-      return this.read(`sha256:${match[1]}`);
+      return this.#read(`sha256:${match[1]}`);
     });
     const after = this._assertNoMixedTenantArtifacts()
       .filter((name) => CANDIDATE_FILE_PATTERN.test(name))

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

@@ -0,0 +1,80 @@
+/** Live exclusion of participating Registry writers; no legacy drain or origin admission. */
+import { types as utilTypes } from "node:util";
+import { captureSkillCandidateRegistryWriterControl } from "./skill-candidate-registry.js";
+import { captureSkillReleaseRegistryWriterControl } from "./skill-release-registry.js";
+
+export async function withSkillRegistryMaintenance(input, operation) {
+  const names = ["candidateRegistry", "releaseRegistry"];
+  if (
+    !input ||
+    utilTypes.isProxy(input) ||
+    Object.getPrototypeOf(input) !== Object.prototype ||
+    Reflect.ownKeys(input).length !== names.length ||
+    typeof operation !== "function" ||
+    utilTypes.isProxy(operation)
+  )
+    throw new TypeError(
+      "Registry maintenance requires plain own registries and an operation",
+    );
+  const registries = Object.fromEntries(
+    names.map((name) => {
+      const field = Object.getOwnPropertyDescriptor(input, name);
+      if (!field?.enumerable || !("value" in field))
+        throw new TypeError("Registry maintenance cannot use option accessors");
+      return [name, field.value];
+    }),
+  );
+  const candidate = captureSkillCandidateRegistryWriterControl(
+    registries.candidateRegistry,
+  );
+  const release = captureSkillReleaseRegistryWriterControl(
+    registries.releaseRegistry,
+  );
+  if (
+    candidate.descriptor.tenantId !== release.descriptor.tenantId ||
+    candidate.orderKey === release.orderKey
+  )
+    throw new TypeError(
+      "Registry maintenance requires independent stores for the same tenant",
+    );
+  const ordered = [candidate, release].sort((left, right) =>
+    left.orderKey < right.orderKey ? -1 : 1,
+  );
+  return ordered[0].maintainAsync(() =>
+    ordered[1].maintainAsync(async () => {
+      let open = true;
+      const assertCurrent = () => {
+        if (!open)
+          throw Object.assign(
+            new Error("Registry maintenance capability is no longer live"),
+            { code: "CC_SKILL_REGISTRY_MAINTENANCE_EXPIRED" },
+          );
+        candidate.assertIfWriting();
+        release.assertIfWriting();
+        return true;
+      };
+      const context = Object.freeze({
+        descriptor: Object.freeze({
+          schema: "chainlesschain.skill-registry-maintenance/v1",
+          tenantId: candidate.descriptor.tenantId,
+          candidateWriter: candidate.descriptor,
+          releaseWriter: release.descriptor,
+          participatingWriterExclusionVerified: true,
+          preTransitionBinaryWritersExcluded: false,
+          persistentStoreIdentityAuthenticated: false,
+          originCutoverAuthenticated: false,
+          qualifiesForPromotion: false,
+        }),
+        assertCurrent,
+      });
+      try {
+        assertCurrent();
+        const result = await operation(context);
+        assertCurrent();
+        return result;
+      } finally {
+        open = false;
+      }
+    }),
+  );
+}

package/src/lib/evolution/skill-registry-writer-control.js

@@ -0,0 +1,138 @@
+/** Cooperative writer exclusion for the Registry transition release. */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { types as utilTypes } from "node:util";
+import { withFileLock, withFileLockAsync } from "../with-file-lock.js";
+
+export const SKILL_REGISTRY_WRITER_PROTOCOL_SCHEMA =
+  "chainlesschain.skill-registry-writer-protocol/v1";
+export const SKILL_REGISTRY_WRITER_BUSY_CODE = "CC_SKILL_REGISTRY_WRITER_BUSY";
+const ACTIVE = new Map();
+const canonicalPath = (value) =>
+  process.platform === "win32" ? value.toLowerCase() : value;
+const identity = (stat) => `${String(stat.dev)}:${String(stat.ino)}`;
+function fail(message, code = "CC_SKILL_REGISTRY_WRITER_UNSAFE") {
+  throw Object.assign(new Error(message), { code });
+}
+
+/** Called by real Registry constructors; this generic lock is not an origin authority. */
+export function createSkillRegistryWriterControl({
+  rootDir,
+  tenantId,
+  component,
+  fsImpl,
+}) {
+  const root = path.resolve(rootDir),
+    parent = path.dirname(root);
+  const realpath = fsImpl.realpathSync?.native ?? fsImpl.realpathSync;
+  if (typeof realpath !== "function")
+    fail("Registry writer requires canonical filesystem paths");
+  function capture(directory) {
+    const stat = fsImpl.lstatSync(directory);
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      canonicalPath(path.resolve(realpath(directory))) !==
+        canonicalPath(directory)
+    )
+      fail("Registry writer directory is not canonical");
+    return Object.freeze({ path: directory, identity: identity(stat) });
+  }
+  const directories = [capture(root), capture(parent)];
+  function assertDirectories() {
+    for (const directory of directories) {
+      const current = capture(directory.path);
+      if (current.identity !== directory.identity)
+        fail("Registry writer directory identity changed");
+    }
+  }
+  const rootPathDigest = createHash("sha256")
+    .update(canonicalPath(root))
+    .digest("hex");
+  // A sibling of the tenant root: existing artifact formats and strict root
+  // inventories stay unchanged. Canonical physical paths unify reopen/aliases.
+  const target = path.join(parent, `.registry-writer-${rootPathDigest}`);
+  const key = canonicalPath(target);
+  let held = null;
+  function assertIfWriting() {
+    if (held) {
+      held.context.assertOwnership();
+      assertDirectories();
+    }
+  }
+  function enter(role) {
+    assertDirectories();
+    // Sync reentry must never block a same-process async owner from finishing.
+    if (ACTIVE.has(key))
+      fail(
+        "Registry writer or maintenance operation is already active",
+        SKILL_REGISTRY_WRITER_BUSY_CODE,
+      );
+    const state = { role, context: null };
+    ACTIVE.set(key, state);
+    return state;
+  }
+  function leave(state) {
+    held = null;
+    if (ACTIVE.get(key) === state) ACTIVE.delete(key);
+  }
+  function execute(state, context, operation) {
+    if (context.locked !== true) fail("Registry writer lock was not acquired");
+    state.context = context;
+    held = state;
+    assertIfWriting();
+    return operation();
+  }
+  function runSync(operation) {
+    const state = enter("writer");
+    try {
+      return withFileLock(
+        target,
+        (context) => {
+          const result = execute(state, context, operation);
+          if (utilTypes.isPromise(result))
+            fail("Registry synchronous writer cannot return a Promise");
+          assertIfWriting();
+          return result;
+        },
+        { failIfUnavailable: true, timeoutMs: 0 },
+      );
+    } finally {
+      leave(state);
+    }
+  }
+  async function runAsync(operation, role = "writer") {
+    const state = enter(role);
+    try {
+      return await withFileLockAsync(
+        target,
+        async (context) => {
+          const result = await execute(state, context, operation);
+          assertIfWriting();
+          return result;
+        },
+        { failIfUnavailable: true, timeoutMs: 0 },
+      );
+    } finally {
+      leave(state);
+    }
+  }
+  return Object.freeze({
+    descriptor: Object.freeze({
+      schema: SKILL_REGISTRY_WRITER_PROTOCOL_SCHEMA,
+      tenantId,
+      component,
+      canonicalRootPathDigest: `sha256:${rootPathDigest}`,
+      participatingWriterProtocolRevision: 1,
+      coversPreTransitionBinaryWriters: false,
+      persistentStoreIdentityAuthenticated: false,
+      originCutoverAuthenticated: false,
+      grantsOriginOrPromotionAuthority: false,
+    }),
+    orderKey: key,
+    runSync,
+    runAsync,
+    maintainAsync: (operation) => runAsync(operation, "maintenance"),
+    assertIfWriting,
+  });
+}