chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/progressive-canary-watchdog-file-store.js

@@ -0,0 +1,285 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import { lstat, mkdir, readdir, realpath } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { withFileLock } from "../with-file-lock.js";
+
+import {
+  createProgressiveCanaryHeartbeatSource,
+  createProgressiveCanaryWatchdogIncidentStore,
+} from "./progressive-canary-external-watchdog.js";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const MAX_RECORD_BYTES = 1024 * 1024;
+const MAX_HEARTBEATS = 10_000;
+
+function sha(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function digest(value, label) {
+  if (!DIGEST.test(value ?? "")) throw new TypeError(`${label} is invalid`);
+  return value;
+}
+
+function safeName(value) {
+  return digest(value, "record digest").slice(7);
+}
+
+async function assertDirectory(path, label) {
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink())
+    throw new Error(`${label} is not a physical directory`);
+  return realpath(path);
+}
+
+function readRecord(path, label) {
+  let info;
+  try {
+    info = fs.lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (
+    !info.isFile() ||
+    info.isSymbolicLink() ||
+    info.nlink !== 1 ||
+    info.size < 2 ||
+    info.size > MAX_RECORD_BYTES
+  )
+    throw new Error(`${label} is not an admissible regular file`);
+  const bytes = fs.readFileSync(path);
+  if (bytes.length !== info.size)
+    throw new Error(`${label} changed during readback`);
+  let value;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch (cause) {
+    throw new Error(`${label} is not JSON`, { cause });
+  }
+  // null denotes an absent file to callers, never a present JSON payload.
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must contain an object`);
+  return value;
+}
+
+function replaceRecord(path, value, label) {
+  const encoded = Buffer.from(JSON.stringify(value), "utf8");
+  if (encoded.length < 2 || encoded.length > MAX_RECORD_BYTES)
+    throw new TypeError(`${label} exceeds its size bound`);
+  const stagingPath = `${path}.staging-${randomBytes(32).toString("hex")}`;
+  let descriptor;
+  let staged = false;
+  try {
+    descriptor = fs.openSync(stagingPath, "wx", 0o600);
+    staged = true;
+    fs.writeFileSync(descriptor, encoded);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    // All writers hold the same strict cross-process lock. Readers only see
+    // the old complete record or the new complete record, never a wx-created
+    // empty/partial reservation. Staging names are outside the reader index.
+    fs.renameSync(stagingPath, path);
+    staged = false;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    if (staged) fs.unlinkSync(stagingPath);
+  }
+  const readback = readRecord(path, label);
+  if (JSON.stringify(readback) !== encoded.toString("utf8"))
+    throw new Error(`${label} durable readback differs`);
+}
+
+function writeOnce(path, value, label) {
+  return withFileLock(
+    path,
+    () => {
+      const prior = readRecord(path, label);
+      if (prior !== null) {
+        if (JSON.stringify(prior) !== JSON.stringify(value))
+          throw new Error(`${label} conflicts with an existing record`);
+        return false;
+      }
+      replaceRecord(path, value, label);
+      return true;
+    },
+    { failIfUnavailable: true },
+  );
+}
+
+function heartbeatName(receipt) {
+  if (!Number.isSafeInteger(receipt?.sequence) || receipt.sequence < 0)
+    throw new TypeError("heartbeat sequence is invalid");
+  digest(receipt.receiptDigest, "heartbeat receiptDigest");
+  return `${String(receipt.sequence).padStart(16, "0")}-${safeName(
+    receipt.receiptDigest,
+  )}.json`;
+}
+
+export async function createProgressiveCanaryWatchdogFileStore({
+  rootDir,
+  planDigest,
+  hostId,
+} = {}) {
+  if (typeof rootDir !== "string" || !isAbsolute(rootDir))
+    throw new TypeError("watchdog rootDir must be absolute");
+  digest(planDigest, "planDigest");
+  if (typeof hostId !== "string" || hostId.length < 1)
+    throw new TypeError("hostId is required");
+  const requestedRoot = resolve(rootDir);
+  await mkdir(requestedRoot, { recursive: true, mode: 0o700 });
+  const root = await assertDirectory(requestedRoot, "watchdog root");
+  const heartbeatsDir = join(root, "heartbeats");
+  const incidentsDir = join(root, "incidents");
+  const reservationsDir = join(root, "reservations");
+  await mkdir(heartbeatsDir, { recursive: true, mode: 0o700 });
+  await mkdir(incidentsDir, { recursive: true, mode: 0o700 });
+  await mkdir(reservationsDir, { recursive: true, mode: 0o700 });
+  await Promise.all([
+    assertDirectory(heartbeatsDir, "heartbeat directory"),
+    assertDirectory(incidentsDir, "incident directory"),
+    assertDirectory(reservationsDir, "reservation directory"),
+  ]);
+
+  async function publishHeartbeat(receipt) {
+    if (
+      receipt?.planDigest !== planDigest ||
+      receipt?.hostId !== hostId ||
+      !DIGEST.test(receipt?.receiptDigest ?? "")
+    )
+      throw new Error("heartbeat belongs to another watchdog store");
+    const path = join(heartbeatsDir, heartbeatName(receipt));
+    await writeOnce(path, receipt, "heartbeat record");
+    return Object.freeze({
+      authenticated: true,
+      durable: true,
+      receiptDigest: receipt.receiptDigest,
+    });
+  }
+
+  const heartbeatSource = createProgressiveCanaryHeartbeatSource({
+    async readLatest(binding) {
+      if (binding?.planDigest !== planDigest || binding?.hostId !== hostId)
+        throw new Error("heartbeat source binding differs");
+      const names = (await readdir(heartbeatsDir)).filter((name) =>
+        /^\d{16}-[a-f0-9]{64}\.json$/u.test(name),
+      );
+      if (names.length > MAX_HEARTBEATS)
+        throw new Error("heartbeat store exceeds its bounded history");
+      if (names.length === 0)
+        return Object.freeze({
+          authenticated: false,
+          durable: true,
+          receipt: null,
+        });
+      names.sort().reverse();
+      const receipt = await readRecord(
+        join(heartbeatsDir, names[0]),
+        "latest heartbeat",
+      );
+      if (
+        receipt?.planDigest !== planDigest ||
+        receipt?.hostId !== hostId ||
+        heartbeatName(receipt) !== names[0]
+      )
+        throw new Error("latest heartbeat filename binding differs");
+      if (names.length > 1 && names[1].slice(0, 16) === names[0].slice(0, 16))
+        throw new Error("latest heartbeat sequence is equivocated");
+      return Object.freeze({
+        authenticated: true,
+        durable: true,
+        receipt,
+      });
+    },
+  });
+
+  const incidentStore = createProgressiveCanaryWatchdogIncidentStore({
+    async reserve(binding) {
+      if (binding?.planDigest !== planDigest)
+        throw new Error("incident reservation belongs to another plan");
+      const incidentDigest = digest(binding.incidentDigest, "incidentDigest");
+      if (
+        !Number.isSafeInteger(binding.observedAt) ||
+        binding.observedAt < 0 ||
+        !Number.isSafeInteger(binding.leaseDurationMs) ||
+        binding.leaseDurationMs < 1_000
+      )
+        throw new TypeError("incident reservation lease is invalid");
+      const path = join(reservationsDir, `${safeName(incidentDigest)}.json`);
+      const reservation = {
+        planDigest,
+        incidentDigest,
+        nonce: randomBytes(32).toString("base64url"),
+        acquiredAt: binding.observedAt,
+        expiresAt: binding.observedAt + binding.leaseDurationMs,
+      };
+      const acquired = withFileLock(
+        path,
+        () => {
+          const current = readRecord(path, "incident reservation");
+          if (current !== null) {
+            if (
+              current.planDigest !== planDigest ||
+              current.incidentDigest !== incidentDigest ||
+              !Number.isSafeInteger(current.expiresAt)
+            )
+              throw new Error("incident reservation binding is invalid");
+            if (current.expiresAt >= binding.observedAt) return false;
+          }
+          replaceRecord(path, reservation, "incident reservation");
+          return true;
+        },
+        { failIfUnavailable: true },
+      );
+      return Object.freeze({
+        authenticated: true,
+        durable: true,
+        acquired,
+        incidentDigest,
+      });
+    },
+    async load(binding) {
+      if (binding?.planDigest !== planDigest)
+        throw new Error("incident load belongs to another plan");
+      const incidentDigest = digest(binding.incidentDigest, "incidentDigest");
+      const value = await readRecord(
+        join(incidentsDir, `${safeName(incidentDigest)}.json`),
+        "watchdog incident",
+      );
+      if (
+        value &&
+        (value.planDigest !== planDigest ||
+          value.incidentDigest !== incidentDigest)
+      )
+        throw new Error("watchdog incident filename binding differs");
+      return value;
+    },
+    async commit(incident) {
+      if (
+        incident?.planDigest !== planDigest ||
+        !DIGEST.test(incident?.incidentDigest ?? "")
+      )
+        throw new Error("watchdog incident belongs to another plan");
+      await writeOnce(
+        join(incidentsDir, `${safeName(incident.incidentDigest)}.json`),
+        incident,
+        "watchdog incident",
+      );
+      return Object.freeze({
+        authenticated: true,
+        durable: true,
+        incidentDigest: incident.incidentDigest,
+      });
+    },
+  });
+
+  return Object.freeze({
+    rootDir: root,
+    storeDigest: sha(`${planDigest}\0${hostId}\0${root}`),
+    publishHeartbeat,
+    heartbeatSource,
+    incidentStore,
+  });
+}

package/src/lib/evolution/progressive-canary-watchdog-node-pki.js

@@ -0,0 +1,265 @@
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  sign,
+  verify,
+} from "node:crypto";
+
+import {
+  createProgressiveCanaryExternalRollbackAuthority,
+  createProgressiveCanaryHeartbeatAuthority,
+} from "./progressive-canary-external-watchdog.js";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ACTION_RECEIPT_SCHEMA =
+  "chainlesschain.progressive-canary-watchdog-action-receipt/v1";
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function sha(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function domainDigest(value) {
+  return sha(`${ACTION_RECEIPT_SCHEMA}\0${canonical(value)}`);
+}
+
+function publicKeyObject(input, label) {
+  let key;
+  try {
+    key = input?.type === "public" ? input : createPublicKey(input);
+  } catch (cause) {
+    throw new TypeError(`${label} is invalid`, { cause });
+  }
+  if (key.asymmetricKeyType !== "ed25519")
+    throw new TypeError(`${label} must be Ed25519`);
+  return key;
+}
+
+function privateKeyObject(input, label) {
+  let key;
+  try {
+    key = input?.type === "private" ? input : createPrivateKey(input);
+  } catch (cause) {
+    throw new TypeError(`${label} is invalid`, { cause });
+  }
+  if (key.asymmetricKeyType !== "ed25519")
+    throw new TypeError(`${label} must be Ed25519`);
+  return key;
+}
+
+export function progressiveCanaryPublicKeySpkiDigest(publicKeyInput) {
+  const key = publicKeyObject(publicKeyInput, "publicKey");
+  return sha(key.export({ type: "spki", format: "der" }));
+}
+
+function signatureBytes(value) {
+  if (typeof value !== "string" || value.length < 32) return null;
+  const bytes = Buffer.from(value, "base64url");
+  return bytes.toString("base64url") === value ? bytes : null;
+}
+
+function signer(privateKeyInput, publicKeyInput, expectedDigest, label) {
+  const publicKey = publicKeyObject(publicKeyInput, `${label} publicKey`);
+  if (progressiveCanaryPublicKeySpkiDigest(publicKey) !== expectedDigest)
+    throw new Error(`${label} public key does not match the watchdog plan`);
+  const privateKey =
+    privateKeyInput === null || privateKeyInput === undefined
+      ? null
+      : privateKeyObject(privateKeyInput, `${label} privateKey`);
+  if (
+    privateKey &&
+    progressiveCanaryPublicKeySpkiDigest(createPublicKey(privateKey)) !==
+      expectedDigest
+  )
+    throw new Error(`${label} private key does not match its public key`);
+  return Object.freeze({ privateKey, publicKey });
+}
+
+export function createNodeProgressiveCanaryHeartbeatAuthority({
+  plan,
+  privateKey = null,
+  publicKey,
+  now = Date.now,
+} = {}) {
+  const keys = signer(
+    privateKey,
+    publicKey,
+    plan?.heartbeatAuthority?.publicKeySpkiDigest,
+    "heartbeat authority",
+  );
+  return createProgressiveCanaryHeartbeatAuthority({
+    plan,
+    now,
+    attestor: async (payload) => {
+      if (!keys.privateKey)
+        throw new Error("heartbeat signing key is unavailable in this process");
+      return sign(
+        null,
+        Buffer.from(canonical(payload), "utf8"),
+        keys.privateKey,
+      ).toString("base64url");
+    },
+    verifier: async ({ payload, signature }) => {
+      const bytes = signatureBytes(signature);
+      return (
+        bytes !== null &&
+        verify(
+          null,
+          Buffer.from(canonical(payload), "utf8"),
+          keys.publicKey,
+          bytes,
+        )
+      );
+    },
+  });
+}
+
+function validateEffect(value, action, plan, request) {
+  if (
+    value?.authenticated !== true ||
+    value?.durable !== true ||
+    value.incidentDigest !== request.incidentDigest ||
+    !DIGEST.test(value.effectDigest ?? "")
+  )
+    throw new Error(`${action} effect was not durably authenticated`);
+  if (
+    action === "kill" &&
+    (value.hostId !== plan.hostId || value.processAbsent !== true)
+  )
+    throw new Error("kill effect did not prove the host process is absent");
+  if (
+    action === "rollback" &&
+    (value.baselineDigest !== plan.baselineDigest ||
+      !DIGEST.test(value.activeStateDigest ?? ""))
+  )
+    throw new Error("rollback effect did not prove the LKG readback");
+  return value;
+}
+
+function actionCore(plan, request, action, effect) {
+  return {
+    schema: ACTION_RECEIPT_SCHEMA,
+    authenticated: true,
+    durable: true,
+    action,
+    planDigest: plan.planDigest,
+    incidentDigest: request.incidentDigest,
+    authorityId: plan.rollbackAuthority.id,
+    authorityRevision: plan.rollbackAuthority.revision,
+    handlerDigest: plan.rollbackAuthority.handlerDigest,
+    publicKeySpkiDigest: plan.rollbackAuthority.publicKeySpkiDigest,
+    effectDigest: effect.effectDigest,
+    ...(action === "kill"
+      ? { hostId: plan.hostId }
+      : {
+          baselineDigest: plan.baselineDigest,
+          activeStateDigest: effect.activeStateDigest,
+        }),
+  };
+}
+
+export function createNodeProgressiveCanaryExternalRollbackAuthority({
+  plan,
+  privateKey,
+  publicKey,
+  killHost,
+  rollbackToBaseline,
+} = {}) {
+  if (
+    typeof killHost !== "function" ||
+    typeof rollbackToBaseline !== "function"
+  )
+    throw new TypeError("Node watchdog effect ports are required");
+  const keys = signer(
+    privateKey,
+    publicKey,
+    plan?.rollbackAuthority?.publicKeySpkiDigest,
+    "rollback authority",
+  );
+  if (!keys.privateKey)
+    throw new TypeError("rollback authority privateKey is required");
+
+  async function issue(action, request, perform) {
+    const effect = validateEffect(
+      await perform(request),
+      action,
+      plan,
+      request,
+    );
+    const core = actionCore(plan, request, action, effect);
+    const signature = sign(
+      null,
+      Buffer.from(canonical(core), "utf8"),
+      keys.privateKey,
+    ).toString("base64url");
+    const signed = { ...core, signature };
+    return Object.freeze({
+      ...signed,
+      receiptDigest: domainDigest(signed),
+    });
+  }
+
+  async function verifyReceipt({ request, receipt }) {
+    if (
+      receipt?.schema !== ACTION_RECEIPT_SCHEMA ||
+      receipt.receiptDigest !==
+        domainDigest(
+          Object.fromEntries(
+            Object.entries(receipt).filter(([key]) => key !== "receiptDigest"),
+          ),
+        )
+    )
+      return false;
+    const signature = signatureBytes(receipt.signature);
+    if (!signature) return false;
+    const signed = structuredClone(receipt);
+    delete signed.receiptDigest;
+    const unsigned = structuredClone(signed);
+    delete unsigned.signature;
+    const expected = actionCore(
+      plan,
+      request,
+      receipt.action,
+      receipt.action === "kill"
+        ? {
+            effectDigest: receipt.effectDigest,
+          }
+        : {
+            effectDigest: receipt.effectDigest,
+            activeStateDigest: receipt.activeStateDigest,
+          },
+    );
+    return (
+      canonical(unsigned) === canonical(expected) &&
+      verify(
+        null,
+        Buffer.from(canonical(unsigned), "utf8"),
+        keys.publicKey,
+        signature,
+      )
+    );
+  }
+
+  return createProgressiveCanaryExternalRollbackAuthority({
+    plan,
+    killHost: (request) =>
+      issue("kill", request, (value) =>
+        killHost({ ...value, hostId: plan.hostId }),
+      ),
+    rollbackToBaseline: (request) =>
+      issue("rollback", request, (value) =>
+        rollbackToBaseline({ ...value, baselineDigest: plan.baselineDigest }),
+      ),
+    verifyKill: verifyReceipt,
+    verifyRollback: verifyReceipt,
+  });
+}

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

@@ -1529,6 +1529,19 @@ function normalizeRegistryOptions(options) {
  * This class deliberately has no active pointer or promotion API. A later
  * promotion controller can consume verified drafts through read().
  */
+const CANDIDATE_READERS = new WeakMap();
+
+export function captureSkillCandidateRegistryReader(registry) {
+  const reader = CANDIDATE_READERS.get(registry);
+  if (
+    !reader ||
+    Object.getPrototypeOf(registry) !== SkillCandidateRegistry.prototype
+  ) {
+    throw new TypeError("a genuine SkillCandidateRegistry reader is required");
+  }
+  return reader;
+}
+
 export class SkillCandidateRegistry {
   constructor(options) {
     const {
@@ -1578,6 +1591,13 @@ export class SkillCandidateRegistry {
       );
     }
     Object.freeze(this);
+    CANDIDATE_READERS.set(
+      this,
+      Object.freeze({
+        tenantId,
+        read: Object.freeze(SkillCandidateRegistry.prototype.read.bind(this)),
+      }),
+    );
   }
 
   _initializeDirectory(
@@ -2905,3 +2925,5 @@ export class SkillCandidateRegistry {
     return Object.freeze(candidates);
   }
 }
+
+Object.freeze(SkillCandidateRegistry.prototype);

package/src/lib/evolution/skill-promotion-controller.js

@@ -19,6 +19,7 @@ import {
   issueRegistryTransitionCapability,
 } from "./skill-registry-transition-capability.js";
 import { captureSkillPromotionReviewProvider } from "./skill-promotion-review.js";
+import { captureSkillReleaseRegistryReader } from "./skill-release-registry.js";
 
 const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 const EMPTY_ACTIVE_DOMAIN = "chainlesschain.skill-active/empty/v1\0";
@@ -47,6 +48,16 @@ const EVALUATED_CONTROL_PLANE_REQUIRED_KEYS = new Set([
 export const SKILL_EVALUATED_PROMOTION_CONTROL_PLANE_SCHEMA =
   "chainlesschain.skill-evaluated-promotion-control-plane/v1";
 const EVALUATED_PROMOTION_CONTROL_PLANES = new WeakSet();
+const ROLLBACK_PROVIDERS = new WeakMap();
+
+export function captureSkillRollbackProvider(value, releaseRegistry) {
+  const entry = ROLLBACK_PROVIDERS.get(value);
+  if (!entry || entry.registry !== releaseRegistry)
+    throw new TypeError(
+      "a branded rollback provider for the same release registry is required",
+    );
+  return entry.provider;
+}
 
 export class SkillPromotionControllerError extends Error {
   constructor(code, message, details = {}) {
@@ -546,6 +557,20 @@ export class SkillPromotionController {
     });
   }
 
+  createRollbackProvider() {
+    captureSkillReleaseRegistryReader(this.#registryIdentity);
+    const provider = Object.freeze({
+      tenantId: this.#tenantId,
+      rollback: (input) =>
+        SkillPromotionController.prototype.rollback.call(this, input),
+    });
+    ROLLBACK_PROVIDERS.set(provider, {
+      registry: this.#registryIdentity,
+      provider,
+    });
+    return provider;
+  }
+
   async rollback(input = {}) {
     assertDataRecord(
       input,