pactium 0.2.0

package/src/aspects/licolite/aspect.js

@@ -0,0 +1,278 @@
+import { PACTIUM_PROTOCOL } from "../../protocol/constants.js";
+import { canonicalDecode } from "../../canonical/value.js";
+import { envelopeSigningHash, verifyProofEnvelope } from "../../proof/envelope.js";
+import { verifyProofBundle } from "../../proof/bundle.js";
+import { createIndexedBundleResolver } from "../../proof/bundle-format.js";
+import { createPactium } from "../../core/pactium-core.js";
+import { createRepairPlanner } from "../../repair/planner.js";
+import { createVerificationFailure } from "../../verification/failure.js";
+import { asArray, safeText } from "../../shared/records.js";
+import {
+  LICOLITE_ASPECT_PROTOCOL,
+  LICOLITE_CRITICAL_EXTENSIONS,
+  LICOLITE_POLICY_EXTENSION,
+  LICOLITE_SIGNATURE_EXTENSION,
+  LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS,
+  LICOLITE_WORKSPACE_EFFECT_EXTENSION
+} from "./constants.js";
+import { createLicoLiteSigner } from "./signing.js";
+import { materializeEvidenceExtension } from "./evidence.js";
+
+async function attachSignature({ pactium, envelope, signer }) {
+  if (!signer) return envelope;
+  const signedEnvelopeHash = envelopeSigningHash(envelope);
+  const signature = await signer.sign(signedEnvelopeHash);
+  const signatureExtension = await pactium.createExtension({
+    name: LICOLITE_SIGNATURE_EXTENSION,
+    critical: false,
+    value: {
+      protocol: LICOLITE_ASPECT_PROTOCOL,
+      signerId: signer.signerId || "licolite-signer",
+      algorithm: signer.algorithm || "hmac-sha256",
+      signedEnvelopeHash,
+      signature
+    }
+  });
+  return pactium.storeEnvelope({
+    ...envelope,
+    extensions: [...asArray(envelope.extensions), signatureExtension]
+  });
+}
+
+function bundleBlockMap(bundle) {
+  if (!bundle) return null;
+  return createIndexedBundleResolver(bundle);
+}
+
+async function resolveMaterialBlock({ core, cid, bundleMap }) {
+  const bundled = await bundleMap?.get(cid);
+  if (bundled) {
+    return {
+      ...bundled,
+      bytes: Buffer.from(String(bundled.payloadBase64 || ""), "base64")
+    };
+  }
+  return core.storage.getBlock(cid);
+}
+
+export function createLicoLiteAspect({
+  pactium = null,
+  dataDir = "",
+  userDataPath = "",
+  inMemory = false,
+  evidencePolicy = "production",
+  signer = null,
+  signerSecret = ""
+} = {}) {
+  const core = pactium || createPactium({ dataDir, userDataPath, inMemory });
+  const resolvedSigner = signer === false ? null : signer || createLicoLiteSigner({
+    secret: signerSecret || "licolite-development-signer"
+  });
+  const verifierSigner = resolvedSigner;
+  const repairPlanner = createRepairPlanner();
+
+  async function recordWorkspaceOperation(input = {}) {
+    const workspaceId = safeText(input.workspaceId || input.scope, "default");
+    const policyEvidence = input.policyEvidence ?? input.policy;
+    const effectEvidence = input.workspaceEffectEvidence ?? input.effectEvidence ?? input.workspaceEffect;
+    if (evidencePolicy === "production" && !policyEvidence) {
+      throw new Error("LicoLite production evidence policy requires policy evidence.");
+    }
+    if (evidencePolicy === "production" && !effectEvidence) {
+      throw new Error("LicoLite production evidence policy requires workspace effect evidence.");
+    }
+    const policyExtension = await materializeEvidenceExtension(core, {
+      name: LICOLITE_POLICY_EXTENSION,
+      evidence: policyEvidence || { missing: true, policy: "opportunistic" },
+      metadata: { workspaceId }
+    });
+    const effectExtension = await materializeEvidenceExtension(core, {
+      name: LICOLITE_WORKSPACE_EFFECT_EXTENSION,
+      evidence: effectEvidence || { missing: true, policy: "opportunistic" },
+      metadata: { workspaceId }
+    });
+    const envelope = await core.recordOperation({
+      ...input,
+      workspaceId,
+      extensions: [
+        policyExtension,
+        effectExtension,
+        ...asArray(input.extensions)
+      ],
+      stateMutations: input.stateMutations || input.state?.mutations || []
+    });
+    return attachSignature({ pactium: core, envelope, signer: resolvedSigner });
+  }
+
+  async function verifyLicoLiteEnvelope(envelope, options = {}) {
+    const bundleMap = bundleBlockMap(options.bundle || null);
+    const coreResult = await verifyProofEnvelope(envelope, {
+      storage: core.storage,
+      bundle: options.bundle || null,
+      supportedCriticalExtensions: LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS,
+      proofVerifiers: options.proofVerifiers || {},
+      requireAllProofs: options.requireAllProofs !== false,
+      verifierManifest: options.verifierManifest || null,
+      ledgerHeadSignatures: options.ledgerHeadSignatures || []
+    });
+    const failures = [...coreResult.failures];
+    const extensionNames = new Set(asArray(envelope?.extensions).map((extension) => extension.name));
+    for (const required of LICOLITE_CRITICAL_EXTENSIONS) {
+      if (!extensionNames.has(required)) {
+        failures.push(createVerificationFailure({
+          layer: "licolite",
+          code: `missing_${required.replace(/\W+/g, "_")}`,
+          message: `LicoLite Proof Envelope is missing required critical extension ${required}.`,
+          evidenceRef: envelope?.envelopeId || "",
+          repairable: evidencePolicy !== "production"
+        }));
+      }
+    }
+    for (const extension of asArray(envelope?.extensions).filter((candidate) =>
+      candidate.name === LICOLITE_POLICY_EXTENSION || candidate.name === LICOLITE_WORKSPACE_EFFECT_EXTENSION
+    )) {
+      const extensionBlock = await resolveMaterialBlock({ core, cid: extension.valueRef, bundleMap });
+      const extensionValue = extensionBlock ? canonicalDecode(extensionBlock.bytes || Buffer.from(extensionBlock.payloadBase64, "base64")) : null;
+      const evidenceRef = extensionValue?.evidenceRef || extension.metadata?.evidenceRef || "";
+      const evidenceHash = extensionValue?.evidenceHash || extension.metadata?.evidenceHash || "";
+      if (!evidenceRef || !evidenceHash) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.evidence",
+          code: "missing_evidence_ref",
+          evidenceRef: extension.valueRef,
+          repairable: true
+        }));
+        continue;
+      }
+      const evidenceBlock = await resolveMaterialBlock({ core, cid: evidenceRef, bundleMap });
+      if (!evidenceBlock) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.evidence",
+          code: "missing_evidence_material",
+          evidenceRef,
+          repairable: true
+        }));
+      } else if (evidenceBlock.payloadHash !== evidenceHash) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.evidence",
+          code: "bad_evidence_hash",
+          evidenceRef
+        }));
+      }
+    }
+    const signatureExtension = asArray(envelope?.extensions).find((extension) => extension.name === LICOLITE_SIGNATURE_EXTENSION);
+    if (!signatureExtension) {
+      failures.push(createVerificationFailure({
+        layer: "licolite.signing",
+        code: "missing_signature",
+        message: "LicoLite signing is enabled by default and no signature extension was found.",
+        evidenceRef: envelope?.envelopeId || "",
+        repairable: evidencePolicy !== "production"
+      }));
+    } else {
+      const block = await resolveMaterialBlock({ core, cid: signatureExtension.valueRef, bundleMap });
+      const value = block ? canonicalDecode(block.bytes || Buffer.from(block.payloadBase64, "base64")) : null;
+      if (!value) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.signing",
+          code: "missing_signature_material",
+          evidenceRef: signatureExtension.valueRef,
+          repairable: true
+        }));
+      } else if (value.signedEnvelopeHash !== envelopeSigningHash(envelope)) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.signing",
+          code: "bad_signed_envelope_hash",
+          evidenceRef: signatureExtension.valueRef
+        }));
+      } else if (verifierSigner && value.signerId !== (verifierSigner.signerId || "licolite-signer")) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.signing",
+          code: "bad_signature_signer",
+          evidenceRef: signatureExtension.valueRef
+        }));
+      } else if (verifierSigner && value.algorithm !== (verifierSigner.algorithm || "hmac-sha256")) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.signing",
+          code: "bad_signature_algorithm",
+          evidenceRef: signatureExtension.valueRef
+        }));
+      } else if (verifierSigner && !(await verifierSigner.verify(value.signedEnvelopeHash, value.signature))) {
+        failures.push(createVerificationFailure({
+          layer: "licolite.signing",
+          code: "bad_signature",
+          evidenceRef: signatureExtension.valueRef
+        }));
+      }
+    }
+    return {
+      protocol: PACTIUM_PROTOCOL,
+      aspect: LICOLITE_ASPECT_PROTOCOL,
+      envelopeId: envelope?.envelopeId || "",
+      ok: failures.length === 0,
+      failures,
+      checked: [
+        ...asArray(coreResult.checked),
+        "licolite-critical-policy-extension",
+        "licolite-critical-workspace-effect-extension",
+        "licolite-signature",
+        "licolite-workspace-projection"
+      ]
+    };
+  }
+
+  async function verifyLicoLiteBundle(bundle, options = {}) {
+    const bundleResult = await verifyProofBundle(bundle, {
+      supportedCriticalExtensions: LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS,
+      ...options
+    });
+    const envelopeResult = await verifyLicoLiteEnvelope(bundle?.envelope || {}, {
+      ...options,
+      bundle
+    });
+    return {
+      protocol: PACTIUM_PROTOCOL,
+      aspect: LICOLITE_ASPECT_PROTOCOL,
+      ok: bundleResult.ok && envelopeResult.ok,
+      failures: [...bundleResult.failures, ...envelopeResult.failures],
+      bundle: bundleResult,
+      envelope: envelopeResult
+    };
+  }
+
+  function planRepair(failures = []) {
+    return repairPlanner.plan(failures);
+  }
+
+  return Object.freeze({
+    protocol: LICOLITE_ASPECT_PROTOCOL,
+    core,
+    evidencePolicy,
+    workspaceProjectionDefault: true,
+    criticalExtensions: LICOLITE_CRITICAL_EXTENSIONS,
+    supportedCriticalExtensions: LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS,
+    signer: resolvedSigner,
+    recordWorkspaceOperation,
+    recordOperation: recordWorkspaceOperation,
+    verifyLicoLiteEnvelope,
+    verifyEnvelope: verifyLicoLiteEnvelope,
+    verifyLicoLiteBundle,
+    verifyBundle: verifyLicoLiteBundle,
+    planRepair,
+    getWorkspaceProjection: core.getWorkspaceProjection,
+    proveWorkspaceMembership: core.proveWorkspaceMembership,
+    exportProofBundle: core.exportProofBundle
+  });
+}
+
+export async function recordLicoLiteWorkspaceOperation(input = {}, options = {}) {
+  return createLicoLiteAspect(options).recordWorkspaceOperation(input);
+}
+
+export async function verifyLicoLiteEnvelope(envelope, options = {}) {
+  return createLicoLiteAspect(options).verifyLicoLiteEnvelope(envelope);
+}
+
+export async function verifyLicoLiteBundle(bundle, options = {}) {
+  return createLicoLiteAspect(options).verifyLicoLiteBundle(bundle);
+}

package/src/aspects/licolite/constants.js

@@ -0,0 +1,13 @@
+export const LICOLITE_ASPECT_PROTOCOL = "pactium.v0.2.licolite-aspect";
+export const LICOLITE_POLICY_EXTENSION = "licolite.policy";
+export const LICOLITE_WORKSPACE_EFFECT_EXTENSION = "licolite.workspaceEffect";
+export const LICOLITE_SIGNATURE_EXTENSION = "licolite.signature";
+export const LICOLITE_CRITICAL_EXTENSIONS = Object.freeze([
+  LICOLITE_POLICY_EXTENSION,
+  LICOLITE_WORKSPACE_EFFECT_EXTENSION
+]);
+export const LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS = Object.freeze([
+  LICOLITE_POLICY_EXTENSION,
+  LICOLITE_WORKSPACE_EFFECT_EXTENSION,
+  LICOLITE_SIGNATURE_EXTENSION
+]);

package/src/aspects/licolite/evidence.js

@@ -0,0 +1,47 @@
+import { protocolHash } from "../../protocol/hashing.js";
+import { asRecord } from "../../shared/records.js";
+import { LICOLITE_ASPECT_PROTOCOL, LICOLITE_POLICY_EXTENSION, LICOLITE_WORKSPACE_EFFECT_EXTENSION } from "./constants.js";
+
+export async function materializeEvidenceExtension(pactium, {
+  name,
+  evidence,
+  critical = true,
+  metadata = {}
+}) {
+  const block = await pactium.storage.putBlock(evidence || {}, {
+    kind: `licolite-evidence:${name}`
+  });
+  return pactium.createExtension({
+    name,
+    critical,
+    value: {
+      protocol: LICOLITE_ASPECT_PROTOCOL,
+      evidenceType: name,
+      evidenceRef: block.cid,
+      evidenceHash: block.payloadHash,
+      metadata
+    },
+    metadata: {
+      evidenceRef: block.cid,
+      evidenceHash: block.payloadHash
+    }
+  });
+}
+
+export function licoLitePolicyExtensionValue(input = {}) {
+  return {
+    protocol: LICOLITE_ASPECT_PROTOCOL,
+    evidenceType: LICOLITE_POLICY_EXTENSION,
+    decision: asRecord(input.decision),
+    evidenceHash: protocolHash("proof.extension", input.evidence || {})
+  };
+}
+
+export function licoLiteWorkspaceEffectExtensionValue(input = {}) {
+  return {
+    protocol: LICOLITE_ASPECT_PROTOCOL,
+    evidenceType: LICOLITE_WORKSPACE_EFFECT_EXTENSION,
+    effect: asRecord(input.effect),
+    evidenceHash: protocolHash("proof.extension", input.evidence || {})
+  };
+}

package/src/aspects/licolite/index.d.ts

@@ -0,0 +1,51 @@
+import type {
+  PactiumCore,
+  PactiumProofBundle,
+  PactiumProofBundleExportOptions,
+  PactiumProofEnvelope,
+  PactiumRecord,
+  PactiumVerificationResult
+} from "../../index.js";
+
+export interface LicoLiteSigner {
+  protocol: string;
+  signerId: string;
+  algorithm: string;
+  sign(message: string): Promise<string>;
+  verify(message: string, signature: string): Promise<boolean>;
+}
+
+export interface LicoLiteAspect {
+  protocol: string;
+  core: PactiumCore;
+  evidencePolicy: string;
+  workspaceProjectionDefault: true;
+  criticalExtensions: readonly string[];
+  supportedCriticalExtensions: readonly string[];
+  signer: LicoLiteSigner | null;
+  recordWorkspaceOperation(input?: PactiumRecord): Promise<PactiumProofEnvelope>;
+  recordOperation(input?: PactiumRecord): Promise<PactiumProofEnvelope>;
+  verifyLicoLiteEnvelope(envelope: PactiumProofEnvelope, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+  verifyEnvelope(envelope: PactiumProofEnvelope, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+  verifyLicoLiteBundle(bundle: PactiumProofBundle, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+  verifyBundle(bundle: PactiumProofBundle, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+  planRepair(failures?: PactiumRecord[]): PactiumRecord;
+  getWorkspaceProjection(workspaceId?: string): Promise<PactiumRecord>;
+  proveWorkspaceMembership(input?: PactiumRecord): Promise<PactiumRecord>;
+  exportProofBundle(envelopeOrId: PactiumProofEnvelope | string, options?: PactiumProofBundleExportOptions): Promise<PactiumProofBundle>;
+}
+
+export const LICOLITE_ASPECT_PROTOCOL: string;
+export const LICOLITE_POLICY_EXTENSION: "licolite.policy";
+export const LICOLITE_WORKSPACE_EFFECT_EXTENSION: "licolite.workspaceEffect";
+export const LICOLITE_SIGNATURE_EXTENSION: "licolite.signature";
+export const LICOLITE_CRITICAL_EXTENSIONS: readonly string[];
+export const LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS: readonly string[];
+
+export function createLicoLiteSigner(options?: PactiumRecord): LicoLiteSigner;
+export function createLicoLiteAspect(options?: PactiumRecord & { pactium?: PactiumCore | null; signer?: LicoLiteSigner | false | null }): LicoLiteAspect;
+export function recordLicoLiteWorkspaceOperation(input?: PactiumRecord, options?: PactiumRecord): Promise<PactiumProofEnvelope>;
+export function verifyLicoLiteEnvelope(envelope: PactiumProofEnvelope, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+export function verifyLicoLiteBundle(bundle: PactiumProofBundle, options?: PactiumRecord): Promise<PactiumVerificationResult>;
+export function licoLitePolicyExtensionValue(input?: PactiumRecord): PactiumRecord;
+export function licoLiteWorkspaceEffectExtensionValue(input?: PactiumRecord): PactiumRecord;

package/src/aspects/licolite/index.js

@@ -0,0 +1,19 @@
+export {
+  LICOLITE_ASPECT_PROTOCOL,
+  LICOLITE_CRITICAL_EXTENSIONS,
+  LICOLITE_POLICY_EXTENSION,
+  LICOLITE_SIGNATURE_EXTENSION,
+  LICOLITE_SUPPORTED_CRITICAL_EXTENSIONS,
+  LICOLITE_WORKSPACE_EFFECT_EXTENSION
+} from "./constants.js";
+export { createLicoLiteSigner } from "./signing.js";
+export {
+  licoLitePolicyExtensionValue,
+  licoLiteWorkspaceEffectExtensionValue
+} from "./evidence.js";
+export {
+  createLicoLiteAspect,
+  recordLicoLiteWorkspaceOperation,
+  verifyLicoLiteBundle,
+  verifyLicoLiteEnvelope
+} from "./aspect.js";

package/src/aspects/licolite/signing.js

@@ -0,0 +1,78 @@
+import crypto from "node:crypto";
+
+import { LICOLITE_ASPECT_PROTOCOL } from "./constants.js";
+
+function hmac(secret, text) {
+  return crypto.createHmac("sha256", String(secret || "")).update(String(text || "")).digest("hex");
+}
+
+function ed25519Sign(privateKey, text) {
+  if (!privateKey) throw new Error("Ed25519 LicoLite signer requires a privateKey for signing.");
+  return crypto.sign(null, Buffer.from(String(text || "")), privateKey).toString("base64");
+}
+
+function ed25519Verify(publicKey, text, signature) {
+  if (!publicKey || !String(signature || "").startsWith("ed25519:")) return false;
+  return crypto.verify(
+    null,
+    Buffer.from(String(text || "")),
+    publicKey,
+    Buffer.from(String(signature).slice("ed25519:".length), "base64")
+  );
+}
+
+function publicKeyFromPrivateKey(privateKey) {
+  if (!privateKey) return "";
+  return crypto.createPublicKey(privateKey).export({ type: "spki", format: "pem" });
+}
+
+/* node:coverage disable */
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function safeText(value, fallback = "") {
+  const output = String(value ?? "").trim();
+  return output || fallback;
+}
+/* node:coverage enable */
+
+export function createLicoLiteSigner({
+  signerId = "licolite-local",
+  secret = "licolite-development-signer",
+  algorithm = "",
+  privateKey = "",
+  publicKey = ""
+} = {}) {
+  const resolvedAlgorithm = safeText(algorithm, privateKey || publicKey ? "ed25519" : "hmac-sha256");
+  if (resolvedAlgorithm === "ed25519") {
+    const verifierPublicKey = publicKey || publicKeyFromPrivateKey(privateKey);
+    return Object.freeze({
+      protocol: LICOLITE_ASPECT_PROTOCOL,
+      signerId,
+      algorithm: "ed25519",
+      publicKey: verifierPublicKey,
+      async sign(message) {
+        return `ed25519:${ed25519Sign(privateKey, message)}`;
+      },
+      async verify(message, signature) {
+        return ed25519Verify(verifierPublicKey, message, signature);
+      }
+    });
+  }
+  return Object.freeze({
+    protocol: LICOLITE_ASPECT_PROTOCOL,
+    signerId,
+    algorithm: "hmac-sha256",
+    async sign(message) {
+      return `hmac-sha256:${hmac(secret, message)}`;
+    },
+    async verify(message, signature) {
+      return signature === `hmac-sha256:${hmac(secret, message)}`;
+    }
+  });
+}

package/src/canonical/value.js

@@ -0,0 +1,40 @@
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+
+export function normalizeCanonicalValue(value) {
+  if (value === null) return null;
+  if (value === undefined) return null;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return { $bytes: Buffer.from(value).toString("base64") };
+  }
+  if (typeof value === "boolean" || typeof value === "string") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("Pactium Canonical Value only supports finite numbers.");
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (Array.isArray(value)) return value.map((item) => normalizeCanonicalValue(item));
+  if (typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .filter((key) => value[key] !== undefined)
+        .sort()
+        .map((key) => [key, normalizeCanonicalValue(value[key])])
+    );
+  }
+  throw new TypeError(`Unsupported Pactium Canonical Value type: ${typeof value}`);
+}
+
+export function canonicalString(value) {
+  return JSON.stringify(normalizeCanonicalValue(value));
+}
+
+export function canonicalEncode(value) {
+  return TEXT_ENCODER.encode(canonicalString(value));
+}
+
+export function canonicalDecode(bytes) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes || "");
+  return JSON.parse(TEXT_DECODER.decode(buffer));
+}

package/src/core/append-condition.js

@@ -0,0 +1,102 @@
+import { PACTIUM_PROTOCOL, PACTIUM_SCHEMA_VERSION } from "../protocol/constants.js";
+import { normalizeCanonicalValue } from "../canonical/value.js";
+import { createId, protocolHash } from "../protocol/hashing.js";
+import { asArray, asRecord, nowIso, safeText } from "../shared/records.js";
+import { createVerificationFailure, PactiumLifecycleError } from "../verification/failure.js";
+
+export function createAppendCondition(input = {}) {
+  const payload = {
+    protocol: PACTIUM_PROTOCOL,
+    schema: PACTIUM_SCHEMA_VERSION,
+    conditionType: "pactium.append-condition",
+    workspaceId: safeText(input.workspaceId, "default"),
+    requiredLedgerHead: safeText(input.requiredLedgerHead || input.ledgerHead),
+    requiredWorkspaceOrderRoot: safeText(input.requiredWorkspaceOrderRoot || input.workspaceOrderRoot),
+    requiredWorkspaceMembershipRoot: safeText(input.requiredWorkspaceMembershipRoot || input.workspaceMembershipRoot),
+    requiredOpenIntentState: normalizeCanonicalValue(asRecord(input.requiredOpenIntentState)),
+    requiredOutcomeState: normalizeCanonicalValue(asRecord(input.requiredOutcomeState)),
+    expectedCausalityRefs: asArray(input.expectedCausalityRefs).map(String),
+    allowMissingCausalityRefs: input.allowMissingCausalityRefs === true,
+    createdAt: input.createdAt || nowIso()
+  };
+  return {
+    ...payload,
+    conditionId: createId("append_condition", payload),
+    conditionHash: protocolHash("append.condition", payload)
+  };
+}
+
+function requiredStateMatches(required, actual) {
+  const state = asRecord(required);
+  if (Object.keys(state).length === 0) return true;
+  if (typeof state.exists === "boolean" && actual.exists !== state.exists) return false;
+  if (state.intentId && actual.intentId !== state.intentId) return false;
+  if (state.outcomeId && actual.outcomeId !== state.outcomeId) return false;
+  return true;
+}
+
+function fail(code, message, details = {}) {
+  throw new PactiumLifecycleError(message, createVerificationFailure({
+    layer: "append-condition",
+    code,
+    message,
+    repairable: false,
+    details
+  }));
+}
+
+export async function assertAppendCondition(condition, {
+  phase = "intent",
+  currentHead = {},
+  workspace = {},
+  openIntentState = null,
+  outcomeState = null,
+  knownCausalityRefs = new Set()
+} = {}) {
+  if (!condition) return true;
+  if (condition.requiredLedgerHead &&
+    condition.requiredLedgerHead !== currentHead.headId &&
+    condition.requiredLedgerHead !== currentHead.root &&
+    condition.requiredLedgerHead !== currentHead.rootHash) {
+    fail("ledger_head_conflict", "Append condition required a different Ledger head.", {
+      requiredLedgerHead: condition.requiredLedgerHead,
+      currentHeadId: currentHead.headId || "",
+      currentRoot: currentHead.root || "",
+      currentRootHash: currentHead.rootHash || ""
+    });
+  }
+  if (condition.requiredWorkspaceOrderRoot && condition.requiredWorkspaceOrderRoot !== workspace.orderRoot) {
+    fail("workspace_order_root_conflict", "Append condition required a different workspace order root.", {
+      requiredWorkspaceOrderRoot: condition.requiredWorkspaceOrderRoot,
+      currentWorkspaceOrderRoot: workspace.orderRoot || ""
+    });
+  }
+  if (condition.requiredWorkspaceMembershipRoot && condition.requiredWorkspaceMembershipRoot !== workspace.membershipRoot) {
+    fail("workspace_membership_root_conflict", "Append condition required a different workspace membership root.", {
+      requiredWorkspaceMembershipRoot: condition.requiredWorkspaceMembershipRoot,
+      currentWorkspaceMembershipRoot: workspace.membershipRoot || ""
+    });
+  }
+  if (phase === "intent" && openIntentState && !requiredStateMatches(condition.requiredOpenIntentState, openIntentState)) {
+    fail("open_intent_state_conflict", "Append condition required a different open-intent state.", {
+      requiredOpenIntentState: condition.requiredOpenIntentState,
+      actual: openIntentState
+    });
+  }
+  if (phase === "outcome" && outcomeState && !requiredStateMatches(condition.requiredOutcomeState, outcomeState)) {
+    fail("outcome_state_conflict", "Append condition required a different outcome state.", {
+      requiredOutcomeState: condition.requiredOutcomeState,
+      actual: outcomeState
+    });
+  }
+  if (!condition.allowMissingCausalityRefs) {
+    for (const ref of asArray(condition.expectedCausalityRefs)) {
+      if (!knownCausalityRefs.has(ref)) {
+        fail("unknown_causality_ref", "Append condition referenced unknown causality material.", {
+          causalityRef: ref
+        });
+      }
+    }
+  }
+  return true;
+}