@kungfu-tech/buildchain 3.0.9-alpha.9 → 4.0.0-alpha.0

package/packages/core/v4-canonical-contracts.js

@@ -0,0 +1,284 @@
+import crypto from "node:crypto";
+
+export const V4_CANONICAL_JSON_CONTRACT = "buildchain-canonical-json/v1";
+export const V4_EVENT_ENVELOPE_CONTRACT = "buildchain-v4-event-envelope/v1";
+export const V4_RECEIPT_ENVELOPE_CONTRACT = "buildchain-v4-receipt-envelope/v1";
+export const V4_CONTRACT_FAULT_CONTRACT = "buildchain-v4-contract-fault/v1";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const CLOCK_PATTERN = /^(?!0000)\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const ASCII_KEY_PATTERN = /^[\x20-\x7e]+$/u;
+const ASCII_TOKEN_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const ROOT_DOMAINS = new Set([
+  "queue-state",
+  "candidate-identity",
+  "fencing-token",
+  "transition-receipt",
+  "observation",
+  "semantic-diff",
+  "bootstrap-evidence",
+  "stage-capsule-identity",
+  "stage-capsule",
+  "stage-capsule-availability",
+  "stage-capsule-output-manifest",
+  "stage-capsule-retention-promise",
+  "stage-capsule-retention-state",
+  "stage-capsule-transport",
+  "stage-capsule-store-receipt",
+  "stage-capsule-quarantine",
+  "stage-capsule-resume-observation",
+  "stage-capsule-resume-plan",
+  "stage-capsule-artifact-manifest",
+  "stage-capsule-artifact-content",
+  "stage-capsule-fault-campaign",
+  "stage-capsule-seed-evidence",
+  "stage-capsule-resume-evidence",
+  "stage-capsule-platform-qualification",
+  "stage-capsule-qualification",
+  "stage-capsule-wave-reconciliation",
+  "provider-operation-identity",
+  "provider-operation-intent",
+  "provider-operation-attempt",
+  "provider-operation-observation",
+  "provider-operation-confirmation",
+  "provider-operation-reconciliation",
+  "provider-operation-journal",
+  "provider-operation-journal-state",
+  "provider-readback-sample",
+  "provider-readback-fold",
+  "release-activation-step",
+  "release-activation-plan",
+  "release-activation-state",
+  "stable-publication-candidate",
+  "stable-publication-qualification",
+  "stable-publication-target",
+  "stable-publication-plan",
+  "stable-publication-fence",
+  "partial-mutation-recovery-checkpoint",
+  "partial-mutation-recovery-plan",
+]);
+const FAULT_CLASSES = new Set([
+  "validation",
+  "concurrency",
+  "authority",
+  "idempotence",
+]);
+const RETRY_DECISIONS = new Set(["stop", "reread", "redecide", "reselect"]);
+const RECEIPT_OUTCOMES = new Set(["accepted", "rejected", "noop"]);
+
+export class V4ContractFault extends Error {
+  constructor(code, path, message) {
+    super(message);
+    this.name = "V4ContractFault";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+function fault(code, path, message) {
+  throw new V4ContractFault(code, path, message);
+}
+
+function exactKeys(value, keys, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fault("invalid-object", path, `${path} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((key, index) => key !== expected[index])
+  )
+    fault("invalid-envelope-shape", path, `${path} keys are not canonical`);
+}
+
+function canonicalize(value, path, active) {
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    for (let index = 0; index < value.length; index += 1) {
+      const code = value.charCodeAt(index);
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const next = value.charCodeAt(index + 1);
+        if (!(next >= 0xdc00 && next <= 0xdfff))
+          fault(
+            "unsupported-string",
+            path,
+            `${path} contains an unpaired surrogate`,
+          );
+        index += 1;
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        fault(
+          "unsupported-string",
+          path,
+          `${path} contains an unpaired surrogate`,
+        );
+      }
+    }
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || Object.is(value, -0))
+      fault(
+        "unsupported-number",
+        path,
+        `${path} must be a safe base-10 integer and must not be negative zero`,
+      );
+    return value;
+  }
+  if (!value || typeof value !== "object")
+    fault("unsupported-json-value", path, `${path} is not a JSON value`);
+  if (active.has(value))
+    fault("cyclic-json-value", path, `${path} contains a cycle`);
+  active.add(value);
+  try {
+    if (Array.isArray(value))
+      return Array.from(value, (entry, index) =>
+        canonicalize(entry, `${path}/${index}`, active),
+      );
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+      fault("unsupported-json-value", path, `${path} must be a plain object`);
+    const result = Object.create(null);
+    for (const key of Object.keys(value).sort((left, right) =>
+      left < right ? -1 : left > right ? 1 : 0,
+    )) {
+      if (!ASCII_KEY_PATTERN.test(key))
+        fault(
+          "unsupported-object-key",
+          `${path}/${key}`,
+          "object keys must be non-empty printable ASCII",
+        );
+      result[key] = canonicalize(value[key], `${path}/${key}`, active);
+    }
+    return result;
+  } finally {
+    active.delete(value);
+  }
+}
+
+export function v4CanonicalBytes(value) {
+  return Buffer.from(
+    `${JSON.stringify(canonicalize(value, "$", new Set()))}\n`,
+    "utf8",
+  );
+}
+
+export function v4ContentRoot(domain, value) {
+  if (!ROOT_DOMAINS.has(domain))
+    fault(
+      "unsupported-root-domain",
+      "$.domain",
+      `unsupported root domain: ${domain}`,
+    );
+  const hash = crypto.createHash("sha256");
+  hash.update(domain, "ascii");
+  hash.update(Buffer.from([0]));
+  hash.update(v4CanonicalBytes(value));
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function validateV4Root(value, path = "$.root") {
+  if (typeof value !== "string" || !ROOT_PATTERN.test(value))
+    fault("invalid-root", path, `${path} must be a lowercase sha256 root`);
+  return value;
+}
+
+export function validateV4Clock(value, path = "$.clock") {
+  if (typeof value !== "string" || !CLOCK_PATTERN.test(value))
+    fault(
+      "invalid-clock",
+      path,
+      `${path} must be RFC3339 UTC with millisecond precision`,
+    );
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value)
+    fault("invalid-clock", path, `${path} is not a real UTC instant`);
+  return value;
+}
+
+export function validateV4ContractFault(value, path = "$.fault") {
+  exactKeys(
+    value,
+    ["schema", "code", "class", "path", "message", "retry"],
+    path,
+  );
+  if (value.schema !== V4_CONTRACT_FAULT_CONTRACT)
+    fault("invalid-fault", `${path}/schema`, "unsupported fault schema");
+  if (!ASCII_TOKEN_PATTERN.test(value.code))
+    fault("invalid-fault", `${path}/code`, "fault code must be an ASCII token");
+  if (!FAULT_CLASSES.has(value.class))
+    fault("invalid-fault", `${path}/class`, "fault class is unsupported");
+  if (typeof value.path !== "string" || !value.path.startsWith("$"))
+    fault("invalid-fault", `${path}/path`, "fault path must start with $");
+  if (typeof value.message !== "string" || value.message.length === 0)
+    fault("invalid-fault", `${path}/message`, "fault message is required");
+  if (!RETRY_DECISIONS.has(value.retry))
+    fault(
+      "invalid-fault",
+      `${path}/retry`,
+      "fault retry decision is unsupported",
+    );
+  v4CanonicalBytes(value);
+  return value;
+}
+
+export function validateV4EventEnvelope(value) {
+  exactKeys(
+    value,
+    ["schema", "eventId", "eventType", "occurredAt", "subjectRoot", "payload"],
+    "$",
+  );
+  if (value.schema !== V4_EVENT_ENVELOPE_CONTRACT)
+    fault("invalid-event", "$/schema", "unsupported event schema");
+  validateV4Root(value.eventId, "$/eventId");
+  validateV4Root(value.subjectRoot, "$/subjectRoot");
+  validateV4Clock(value.occurredAt, "$/occurredAt");
+  if (!ASCII_TOKEN_PATTERN.test(value.eventType))
+    fault("invalid-event", "$/eventType", "event type must be an ASCII token");
+  v4CanonicalBytes(value.payload);
+  return value;
+}
+
+export function validateV4ReceiptEnvelope(value) {
+  exactKeys(
+    value,
+    [
+      "schema",
+      "receiptType",
+      "recordedAt",
+      "eventRoot",
+      "priorStateRoot",
+      "nextStateRoot",
+      "outcome",
+      "fault",
+    ],
+    "$",
+  );
+  if (value.schema !== V4_RECEIPT_ENVELOPE_CONTRACT)
+    fault("invalid-receipt", "$/schema", "unsupported receipt schema");
+  if (!ASCII_TOKEN_PATTERN.test(value.receiptType))
+    fault(
+      "invalid-receipt",
+      "$/receiptType",
+      "receipt type must be an ASCII token",
+    );
+  validateV4Clock(value.recordedAt, "$/recordedAt");
+  validateV4Root(value.eventRoot, "$/eventRoot");
+  if (value.priorStateRoot !== null)
+    validateV4Root(value.priorStateRoot, "$/priorStateRoot");
+  if (value.nextStateRoot !== null)
+    validateV4Root(value.nextStateRoot, "$/nextStateRoot");
+  if (!RECEIPT_OUTCOMES.has(value.outcome))
+    fault("invalid-receipt", "$/outcome", "receipt outcome is unsupported");
+  if (value.fault !== null) validateV4ContractFault(value.fault);
+  if ((value.outcome === "rejected") !== (value.fault !== null))
+    fault(
+      "invalid-receipt",
+      "$/fault",
+      "only rejected receipts carry a typed fault",
+    );
+  return value;
+}
+
+export function v4ContractDomains() {
+  return [...ROOT_DOMAINS];
+}

package/packages/core/v4-delivery-warrant-fixture-runner.js

@@ -0,0 +1,371 @@
+import { TextDecoder } from "node:util";
+
+import {
+  V4ContractFault,
+  v4CanonicalBytes,
+  v4ContentRoot,
+  validateV4ContractFault,
+  validateV4EventEnvelope,
+  validateV4ReceiptEnvelope,
+  validateV4Root,
+} from "./v4-canonical-contracts.js";
+
+export const V4_DELIVERY_WARRANT_TRACE_CONTRACT =
+  "buildchain-v4-delivery-warrant-trace-fixture/v1";
+export const V4_DELIVERY_WARRANT_RUNNER_CONTRACT =
+  "buildchain-v4-delivery-warrant-fixture-runner/v1";
+export const V4_DELIVERY_WARRANT_PROJECTION_CONTRACT =
+  "buildchain-v4-delivery-warrant-semantic-projection/v1";
+
+const ASCII_TOKEN_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+
+function fail(code, path, message) {
+  throw new V4ContractFault(code, path, message);
+}
+
+function exactKeys(value, keys, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail("invalid-object", path, `${path} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((key, index) => key !== expected[index])
+  )
+    fail("invalid-trace-shape", path, `${path} keys are not canonical`);
+}
+
+function token(value, path) {
+  if (typeof value !== "string" || !ASCII_TOKEN_PATTERN.test(value))
+    fail("invalid-trace-token", path, `${path} must be an ASCII token`);
+  return value;
+}
+
+function nonNegativeInteger(value, path) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    fail(
+      "invalid-trace-integer",
+      path,
+      `${path} must be a non-negative safe integer`,
+    );
+  return value;
+}
+
+function equalCanonical(left, right) {
+  return v4CanonicalBytes(left).equals(v4CanonicalBytes(right));
+}
+
+function declaredRoot(value, expected, path, code) {
+  validateV4Root(value, path);
+  if (value !== expected)
+    fail(code, path, `${path} does not match the retained canonical bytes`);
+  return value;
+}
+
+function readBytes(bytes) {
+  const input = Buffer.isBuffer(bytes)
+    ? bytes
+    : bytes instanceof Uint8Array
+      ? Buffer.from(bytes)
+      : typeof bytes === "string"
+        ? Buffer.from(bytes, "utf8")
+        : fail(
+            "invalid-trace-bytes",
+            "$",
+            "trace input must be UTF-8 bytes or a string",
+          );
+  if (input.length === 0 || input.at(-1) !== 0x0a)
+    fail(
+      "invalid-trace-bytes",
+      "$",
+      "retained trace bytes must end with one LF",
+    );
+  if (
+    input.length >= 3 &&
+    input[0] === 0xef &&
+    input[1] === 0xbb &&
+    input[2] === 0xbf
+  )
+    fail("invalid-trace-bytes", "$", "retained trace bytes must not use BOM");
+  let text;
+  try {
+    text = UTF8.decode(input);
+  } catch {
+    fail("invalid-trace-bytes", "$", "retained trace bytes are not UTF-8");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    fail("invalid-trace-json", "$", "retained trace bytes are not JSON");
+  }
+}
+
+function validateOrderedEntries(entries, path) {
+  if (!Array.isArray(entries))
+    fail("invalid-trace-shape", path, `${path} must be an array`);
+  return entries.map((entry, index) => {
+    exactKeys(entry, ["sequence", "type", "payload"], `${path}/${index}`);
+    if (entry.sequence !== index)
+      fail(
+        "reordered-trace",
+        `${path}/${index}/sequence`,
+        `${path} sequence must be contiguous and ordered`,
+      );
+    token(entry.type, `${path}/${index}/type`);
+    v4CanonicalBytes(entry.payload);
+    return entry;
+  });
+}
+
+function validateState(state, path) {
+  exactKeys(
+    state,
+    ["schema", "generation", "fencingCounter", "activeWarrant", "candidates"],
+    path,
+  );
+  if (state.schema !== "buildchain-v4-delivery-warrant-state/v1")
+    fail(
+      "unsupported-trace-version",
+      `${path}/schema`,
+      "unsupported Delivery Warrant state schema",
+    );
+  const generation = nonNegativeInteger(state.generation, `${path}/generation`);
+  const fencingCounter = nonNegativeInteger(
+    state.fencingCounter,
+    `${path}/fencingCounter`,
+  );
+  if (!Array.isArray(state.candidates))
+    fail(
+      "invalid-trace-shape",
+      `${path}/candidates`,
+      "state candidates must be an array",
+    );
+  const canonicalUtf8 = v4CanonicalBytes(state).toString("utf8");
+  return {
+    generation,
+    fencingCounter,
+    canonicalUtf8,
+    root: v4ContentRoot("queue-state", state),
+  };
+}
+
+function validateDecision(decision, receipt, path) {
+  exactKeys(decision, ["action", "fault"], path);
+  const hasAction = decision.action !== null;
+  const hasFault = decision.fault !== null;
+  if (hasAction === hasFault)
+    fail(
+      "invalid-trace-decision",
+      path,
+      "decision must contain exactly one action or typed fault",
+    );
+  if (hasAction) {
+    token(decision.action, `${path}/action`);
+    if (receipt.outcome === "rejected" || receipt.fault !== null)
+      fail(
+        "invalid-trace-decision",
+        path,
+        "an action cannot bind a rejected receipt",
+      );
+  } else {
+    validateV4ContractFault(decision.fault, `${path}/fault`);
+    if (
+      receipt.outcome !== "rejected" ||
+      receipt.fault === null ||
+      !equalCanonical(decision.fault, receipt.fault)
+    )
+      fail(
+        "invalid-trace-decision",
+        path,
+        "typed fault and rejected receipt must match exactly",
+      );
+  }
+  return decision;
+}
+
+function projectStep(step, index, priorStateRoot) {
+  const path = `$/trace/steps/${index}`;
+  exactKeys(
+    step,
+    [
+      "sequence",
+      "id",
+      "operation",
+      "event",
+      "decision",
+      "priorStateRoot",
+      "successorState",
+      "successorRoot",
+      "effects",
+      "observations",
+      "receipt",
+      "receiptRoot",
+    ],
+    path,
+  );
+  if (step.sequence !== index)
+    fail(
+      "reordered-trace",
+      `${path}/sequence`,
+      "trace step sequence must be contiguous and ordered",
+    );
+  token(step.id, `${path}/id`);
+  token(step.operation, `${path}/operation`);
+  declaredRoot(
+    step.priorStateRoot,
+    priorStateRoot,
+    `${path}/priorStateRoot`,
+    "stale-prior-root",
+  );
+
+  validateV4EventEnvelope(step.event);
+  if (step.event.subjectRoot !== priorStateRoot)
+    fail(
+      "stale-prior-root",
+      `${path}/event/subjectRoot`,
+      "event subjectRoot must bind the exact prior state",
+    );
+  const eventRoot = v4ContentRoot("observation", step.event);
+
+  const successor = validateState(
+    step.successorState,
+    `${path}/successorState`,
+  );
+  const successorRoot = declaredRoot(
+    step.successorRoot,
+    successor.root,
+    `${path}/successorRoot`,
+    "stale-successor-root",
+  );
+
+  validateV4ReceiptEnvelope(step.receipt);
+  if (
+    step.receipt.eventRoot !== eventRoot ||
+    step.receipt.priorStateRoot !== priorStateRoot ||
+    step.receipt.nextStateRoot !== successorRoot
+  )
+    fail(
+      "stale-receipt-root",
+      `${path}/receipt`,
+      "receipt roots must bind the event and exact state transition",
+    );
+  const decision = validateDecision(
+    step.decision,
+    step.receipt,
+    `${path}/decision`,
+  );
+  const effects = validateOrderedEntries(step.effects, `${path}/effects`);
+  if (decision.fault !== null && effects.length > 0)
+    fail(
+      "invalid-trace-effects",
+      `${path}/effects`,
+      "rejected decisions must not declare effects",
+    );
+  const observations = validateOrderedEntries(
+    step.observations,
+    `${path}/observations`,
+  );
+  const receiptCanonicalUtf8 = v4CanonicalBytes(step.receipt).toString("utf8");
+  const receiptRoot = declaredRoot(
+    step.receiptRoot,
+    v4ContentRoot("transition-receipt", step.receipt),
+    `${path}/receiptRoot`,
+    "stale-receipt-root",
+  );
+
+  return {
+    projection: {
+      sequence: step.sequence,
+      id: step.id,
+      operation: step.operation,
+      decision,
+      eventRoot,
+      successorCanonicalUtf8: successor.canonicalUtf8,
+      successorRoot,
+      generation: successor.generation,
+      fencingCounter: successor.fencingCounter,
+      effects: effects.map((effect) => ({
+        sequence: effect.sequence,
+        type: effect.type,
+        canonicalUtf8: v4CanonicalBytes(effect.payload).toString("utf8"),
+      })),
+      observations: observations.map((observation) => ({
+        sequence: observation.sequence,
+        type: observation.type,
+        canonicalUtf8: v4CanonicalBytes(observation.payload).toString("utf8"),
+        root: v4ContentRoot("observation", observation.payload),
+      })),
+      receiptCanonicalUtf8,
+      receiptRoot,
+    },
+    successorRoot,
+  };
+}
+
+export function runV4DeliveryWarrantTraceFixture(
+  bytes,
+  { verifyExpectedRoot = true } = {},
+) {
+  const fixture = readBytes(bytes);
+  exactKeys(
+    fixture,
+    ["schemaVersion", "contract", "runner", "trace", "expectedProjectionRoot"],
+    "$",
+  );
+  if (
+    fixture.schemaVersion !== 1 ||
+    fixture.contract !== V4_DELIVERY_WARRANT_TRACE_CONTRACT ||
+    fixture.runner !== V4_DELIVERY_WARRANT_RUNNER_CONTRACT
+  )
+    fail(
+      "unsupported-trace-version",
+      "$/schemaVersion",
+      "unsupported trace fixture contract",
+    );
+  exactKeys(
+    fixture.trace,
+    ["id", "kind", "initialState", "initialStateRoot", "steps"],
+    "$/trace",
+  );
+  token(fixture.trace.id, "$/trace/id");
+  if (!["golden", "property", "replay"].includes(fixture.trace.kind))
+    fail("invalid-trace-kind", "$/trace/kind", "unsupported trace kind");
+  if (!Array.isArray(fixture.trace.steps) || fixture.trace.steps.length === 0)
+    fail(
+      "incomplete-trace",
+      "$/trace/steps",
+      "trace must contain at least one step",
+    );
+  const initialState = validateState(
+    fixture.trace.initialState,
+    "$/trace/initialState",
+  );
+  const initialStateRoot = declaredRoot(
+    fixture.trace.initialStateRoot,
+    initialState.root,
+    "$/trace/initialStateRoot",
+    "stale-initial-root",
+  );
+  let priorStateRoot = initialStateRoot;
+  const steps = fixture.trace.steps.map((step, index) => {
+    const result = projectStep(step, index, priorStateRoot);
+    priorStateRoot = result.successorRoot;
+    return result.projection;
+  });
+  const projection = {
+    schema: V4_DELIVERY_WARRANT_PROJECTION_CONTRACT,
+    traceId: fixture.trace.id,
+    traceKind: fixture.trace.kind,
+    steps,
+  };
+  const projectionRoot = v4ContentRoot("semantic-diff", projection);
+  validateV4Root(fixture.expectedProjectionRoot, "$/expectedProjectionRoot");
+  if (verifyExpectedRoot && fixture.expectedProjectionRoot !== projectionRoot)
+    fail(
+      "stale-projection-root",
+      "$/expectedProjectionRoot",
+      "expected projection root does not match the semantic projection",
+    );
+  return { projection, projectionRoot };
+}