harnery 0.32.0 → 0.34.0

package/dist/core/events/v3/advance.js

@@ -0,0 +1,134 @@
+import { canonicalJsonV3 } from "./canonical.js";
+/**
+ * Mechanical half of ADR 0080's in-place advance gate. It proves that every
+ * value accepted by the prior JSON Schema remains accepted by the next schema.
+ * Semantic reinterpretations remain breaking even when this structural check
+ * passes and require genesis review.
+ */
+export function validateAdditiveSchemaAdvanceV3(prior, next) {
+    const issues = [];
+    const result = isSuperset(prior, next, "$", issues);
+    return {
+        eligible: result.compatible && result.strict,
+        strict: result.strict,
+        issues: [...new Set(issues)].sort(),
+    };
+}
+function isSuperset(prior, next, path, issues) {
+    const priorAnyOf = schemaArray(prior.anyOf);
+    const nextAnyOf = schemaArray(next.anyOf);
+    if (priorAnyOf || nextAnyOf) {
+        if (!priorAnyOf || !nextAnyOf)
+            return incompatible(path, "union_shape_changed", issues);
+        const used = new Set();
+        let strict = nextAnyOf.length > priorAnyOf.length;
+        for (const [priorIndex, priorBranch] of priorAnyOf.entries()) {
+            let match;
+            for (const [nextIndex, nextBranch] of nextAnyOf.entries()) {
+                if (used.has(nextIndex))
+                    continue;
+                const branchIssues = [];
+                const result = isSuperset(priorBranch, nextBranch, `${path}/anyOf/${priorIndex}`, branchIssues);
+                if (result.compatible) {
+                    match = { index: nextIndex, result };
+                    break;
+                }
+            }
+            if (!match)
+                return incompatible(`${path}/anyOf/${priorIndex}`, "branch_removed_or_narrowed", issues);
+            used.add(match.index);
+            strict ||= match.result.strict;
+        }
+        return { compatible: true, strict };
+    }
+    if (prior.type === "object" || next.type === "object") {
+        if (prior.type !== "object" || next.type !== "object") {
+            return incompatible(path, "type_changed", issues);
+        }
+        if (prior.additionalProperties !== next.additionalProperties) {
+            return incompatible(path, "additional_properties_changed", issues);
+        }
+        const priorProperties = schemaMap(prior.properties);
+        const nextProperties = schemaMap(next.properties);
+        const priorRequired = stringSet(prior.required);
+        const nextRequired = stringSet(next.required);
+        let strict = false;
+        for (const name of priorRequired) {
+            if (!nextRequired.has(name))
+                strict = true;
+        }
+        for (const name of nextRequired) {
+            if (!priorRequired.has(name)) {
+                return incompatible(`${path}/properties/${name}`, "optional_became_required", issues);
+            }
+        }
+        for (const [name, priorProperty] of Object.entries(priorProperties)) {
+            const nextProperty = nextProperties[name];
+            if (!nextProperty)
+                return incompatible(`${path}/properties/${name}`, "property_removed", issues);
+            const result = isSuperset(priorProperty, nextProperty, `${path}/properties/${name}`, issues);
+            if (!result.compatible)
+                return result;
+            strict ||= result.strict;
+        }
+        for (const name of Object.keys(nextProperties)) {
+            if (!(name in priorProperties)) {
+                if (nextRequired.has(name)) {
+                    return incompatible(`${path}/properties/${name}`, "new_property_is_required", issues);
+                }
+                strict = true;
+            }
+        }
+        return { compatible: true, strict };
+    }
+    if (prior.type === "array" || next.type === "array") {
+        if (prior.type !== "array" || next.type !== "array")
+            return incompatible(path, "type_changed", issues);
+        if (number(next.minItems, 0) < number(prior.minItems, 0)) {
+            // A lower minimum broadens acceptance.
+        }
+        else if (number(next.minItems, 0) > number(prior.minItems, 0)) {
+            return incompatible(path, "array_minimum_narrowed", issues);
+        }
+        const priorMax = number(prior.maxItems, Number.POSITIVE_INFINITY);
+        const nextMax = number(next.maxItems, Number.POSITIVE_INFINITY);
+        if (nextMax < priorMax)
+            return incompatible(path, "array_maximum_narrowed", issues);
+        const priorItems = prior.items;
+        const nextItems = next.items;
+        if (!!priorItems !== !!nextItems)
+            return incompatible(path, "array_items_changed", issues);
+        const itemResult = priorItems && nextItems
+            ? isSuperset(priorItems, nextItems, `${path}/items`, issues)
+            : { compatible: true, strict: false };
+        return {
+            compatible: itemResult.compatible,
+            strict: itemResult.strict ||
+                number(next.minItems, 0) < number(prior.minItems, 0) ||
+                nextMax > priorMax,
+        };
+    }
+    const ignored = new Set(["$id", "title", "description"]);
+    const priorComparable = Object.fromEntries(Object.entries(prior).filter(([key]) => !ignored.has(key)));
+    const nextComparable = Object.fromEntries(Object.entries(next).filter(([key]) => !ignored.has(key)));
+    if (canonicalJsonV3(priorComparable) !== canonicalJsonV3(nextComparable)) {
+        return incompatible(path, "constraint_changed", issues);
+    }
+    return { compatible: true, strict: false };
+}
+function incompatible(path, reason, issues) {
+    issues.push(`${path}:${reason}`);
+    return { compatible: false, strict: false };
+}
+function schemaArray(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+function schemaMap(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function stringSet(value) {
+    return new Set(Array.isArray(value) ? value.filter((item) => typeof item === "string") : []);
+}
+function number(value, fallback) {
+    return typeof value === "number" ? value : fallback;
+}

package/dist/core/events/v3/authority-outbox.d.ts

@@ -0,0 +1,78 @@
+import type { EventV3 } from "./contract.js";
+export type AuthorityMutationV3 = {
+    kind: "task.transition";
+    state: "set" | "cleared";
+    task_fingerprint?: `sha256:${string}`;
+} | {
+    kind: "lifecycle.transition";
+    state: "active" | "blocked" | "done";
+    reason_code?: string;
+} | {
+    kind: "claim.transition";
+    operation: "acquired" | "released";
+    target_fingerprint: `sha256:${string}`;
+    access: "read" | "write";
+} | {
+    kind: "identity.assume";
+    identity_id: string;
+} | {
+    kind: "decision.resolve";
+    decision_id: string;
+    outcome: "approved" | "denied" | "deferred";
+} | {
+    kind: "wait.start";
+    wait_id: string;
+    wait_kind: "permission" | "approval" | "decision" | "operator_input" | "dependency" | "scheduled";
+} | {
+    kind: "wait.end";
+    wait_id: string;
+    outcome: "succeeded" | "failed" | "cancelled" | "timed_out" | "denied" | "interrupted" | "unknown";
+};
+export interface PrepareAuthorityTransactionV3Input {
+    transaction_id?: `txn_${string}`;
+    expected_prior_state_digest: `sha256:${string}`;
+    desired_state_digest: `sha256:${string}`;
+    actor_instance_id: string;
+    subject_instance_id: string;
+    mutation: AuthorityMutationV3;
+    event: EventV3;
+}
+export interface AuthorityTransactionV3 {
+    format: "harnery-event-v3-authority-transaction";
+    format_version: 1;
+    transaction_id: `txn_${string}`;
+    expected_prior_state_digest: `sha256:${string}`;
+    desired_state_digest: `sha256:${string}`;
+    actor_instance_id: string;
+    subject_instance_id: string;
+    mutation: AuthorityMutationV3;
+    event_id: string;
+    event_row: string;
+}
+export interface AuthorityReceiptV3 {
+    format: "harnery-event-v3-authority-receipt";
+    format_version: 1;
+    transaction_id: `txn_${string}`;
+    transaction_digest: `sha256:${string}`;
+    desired_state_digest: `sha256:${string}`;
+    event_id: string;
+    event_row_digest: `sha256:${string}`;
+    committed_at: string;
+}
+export interface AuthorityReconcilerV3 {
+    readStateDigest: () => `sha256:${string}`;
+    apply: (mutation: AuthorityMutationV3, transactionId: string) => void;
+    now?: () => Date;
+}
+/** Durably publish the full transaction before any authority-bearing state mutation. */
+export declare function prepareAuthorityTransactionV3(coordRoot: string, input: PrepareAuthorityTransactionV3Input): AuthorityTransactionV3;
+/** Build and validate an authority transaction without touching durable state. */
+export declare function buildAuthorityTransactionV3(input: PrepareAuthorityTransactionV3Input): AuthorityTransactionV3;
+/** Publish an already-built transaction exactly, preserving its pre-minted event. */
+export declare function publishAuthorityTransactionV3(coordRoot: string, transaction: AuthorityTransactionV3): AuthorityTransactionV3;
+/** Apply or recognize the desired state, durably submit its event, then leave a hash-only receipt. */
+export declare function reconcileAuthorityTransactionV3(coordRoot: string, transactionId: string, reconciler: AuthorityReconcilerV3): AuthorityReceiptV3;
+export declare function listPendingAuthorityTransactionsV3(coordRoot: string): AuthorityTransactionV3[];
+export declare function readAuthorityTransactionV3(path: string): AuthorityTransactionV3;
+export declare function readAuthorityReceiptV3(path: string): AuthorityReceiptV3;
+//# sourceMappingURL=authority-outbox.d.ts.map

package/dist/core/events/v3/authority-outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-outbox.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/authority-outbox.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAU7C,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,gBAAgB,CAAC,EAAE,UAAU,MAAM,EAAE,CAAC;CACvC,GACD;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,kBAAkB,EAAE,UAAU,MAAM,EAAE,CAAC;IACvC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,GACD;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC7C,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EACL,YAAY,GACZ,UAAU,GACV,UAAU,GACV,gBAAgB,GAChB,YAAY,GACZ,WAAW,CAAC;CACjB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EACH,WAAW,GACX,QAAQ,GACR,WAAW,GACX,WAAW,GACX,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,kCAAkC;IACjD,cAAc,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IACjC,2BAA2B,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,wCAAwC,CAAC;IACjD,cAAc,EAAE,CAAC,CAAC;IAClB,cAAc,EAAE,OAAO,MAAM,EAAE,CAAC;IAChC,2BAA2B,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,oCAAoC,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC;IAClB,cAAc,EAAE,OAAO,MAAM,EAAE,CAAC;IAChC,kBAAkB,EAAE,UAAU,MAAM,EAAE,CAAC;IACvC,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,UAAU,MAAM,EAAE,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,UAAU,MAAM,EAAE,CAAC;IAC1C,KAAK,EAAE,CAAC,QAAQ,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wFAAwF;AACxF,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kCAAkC,GACxC,sBAAsB,CAExB;AAED,kFAAkF;AAClF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kCAAkC,GACxC,sBAAsB,CAgBxB;AAED,qFAAqF;AACrF,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,sBAAsB,GAClC,sBAAsB,CAoBxB;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,qBAAqB,GAChC,kBAAkB,CAsCpB;AAED,wBAAgB,kCAAkC,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB,EAAE,CAO9F;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAa/E;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAavE"}

package/dist/core/events/v3/authority-outbox.js

@@ -0,0 +1,399 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, linkSync, openSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.js";
+import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+import { assertEventV3 } from "./validate.js";
+import { ensureEventV3Layout, eventV3Paths, writeEventV3 } from "./writer.js";
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const INSTANCE_PATTERN = /^inst_[a-zA-Z0-9._-]{1,128}$/;
+const TX_PATTERN = /^txn_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SAFE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/;
+const REASON_PATTERN = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+/** Durably publish the full transaction before any authority-bearing state mutation. */
+export function prepareAuthorityTransactionV3(coordRoot, input) {
+    return publishAuthorityTransactionV3(coordRoot, buildAuthorityTransactionV3(input));
+}
+/** Build and validate an authority transaction without touching durable state. */
+export function buildAuthorityTransactionV3(input) {
+    assertEventV3(input.event);
+    const transaction = {
+        format: "harnery-event-v3-authority-transaction",
+        format_version: 1,
+        transaction_id: input.transaction_id ?? `txn_${randomUUID()}`,
+        expected_prior_state_digest: input.expected_prior_state_digest,
+        desired_state_digest: input.desired_state_digest,
+        actor_instance_id: input.actor_instance_id,
+        subject_instance_id: input.subject_instance_id,
+        mutation: input.mutation,
+        event_id: input.event.event_id,
+        event_row: `${canonicalJsonV3(input.event)}\n`,
+    };
+    validateTransaction(transaction);
+    return transaction;
+}
+/** Publish an already-built transaction exactly, preserving its pre-minted event. */
+export function publishAuthorityTransactionV3(coordRoot, transaction) {
+    validateTransaction(transaction);
+    const paths = ensureEventV3Layout(coordRoot);
+    const readyPath = authorityReadyPath(paths.authorityOutbox, transaction.transaction_id);
+    const serialized = `${canonicalJsonV3(transaction)}\n`;
+    if (existsSync(readyPath)) {
+        if (readFileSync(readyPath, "utf8") !== serialized) {
+            throw new Error("authority transaction ID conflicts with another ready transaction");
+        }
+        return transaction;
+    }
+    try {
+        publishExclusive(readyPath, serialized);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (readFileSync(readyPath, "utf8") !== serialized) {
+            throw new Error("authority transaction ID conflicts with another ready transaction");
+        }
+    }
+    return transaction;
+}
+/** Apply or recognize the desired state, durably submit its event, then leave a hash-only receipt. */
+export function reconcileAuthorityTransactionV3(coordRoot, transactionId, reconciler) {
+    assertTransactionId(transactionId);
+    const paths = ensureEventV3Layout(coordRoot);
+    const committedPath = authorityCommittedPath(paths.authorityOutbox, transactionId);
+    if (existsSync(committedPath))
+        return readAuthorityReceiptV3(committedPath);
+    const readyPath = authorityReadyPath(paths.authorityOutbox, transactionId);
+    const transaction = readAuthorityTransactionV3(readyPath);
+    const current = reconciler.readStateDigest();
+    if (current === transaction.expected_prior_state_digest) {
+        reconciler.apply(transaction.mutation, transaction.transaction_id);
+    }
+    else if (current !== transaction.desired_state_digest) {
+        throw new Error("authority transaction prior state conflicts with current state");
+    }
+    if (reconciler.readStateDigest() !== transaction.desired_state_digest) {
+        throw new Error("authority transaction did not reach its declared desired state");
+    }
+    const event = JSON.parse(transaction.event_row);
+    assertEventV3(event);
+    writeEventV3(coordRoot, event);
+    const receipt = {
+        format: "harnery-event-v3-authority-receipt",
+        format_version: 1,
+        transaction_id: transaction.transaction_id,
+        transaction_digest: sha256V3(`${canonicalJsonV3(transaction)}\n`),
+        desired_state_digest: transaction.desired_state_digest,
+        event_id: transaction.event_id,
+        event_row_digest: sha256V3(transaction.event_row),
+        committed_at: (reconciler.now ?? (() => new Date()))().toISOString(),
+    };
+    try {
+        publishExclusive(committedPath, `${canonicalJsonV3(receipt)}\n`);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return readAuthorityReceiptV3(committedPath);
+    }
+    unlinkSync(readyPath);
+    fsyncParentDirectory(readyPath);
+    return receipt;
+}
+export function listPendingAuthorityTransactionsV3(coordRoot) {
+    const outbox = eventV3Paths(coordRoot).authorityOutbox;
+    if (!existsSync(outbox))
+        return [];
+    return readdirSync(outbox)
+        .filter((name) => name.endsWith(".ready.json"))
+        .sort()
+        .map((name) => readAuthorityTransactionV3(join(outbox, name)));
+}
+export function readAuthorityTransactionV3(path) {
+    const serialized = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        throw new Error("authority transaction is malformed");
+    }
+    const transaction = validateTransaction(parsed);
+    if (`${canonicalJsonV3(transaction)}\n` !== serialized) {
+        throw new Error("authority transaction is not canonical");
+    }
+    return transaction;
+}
+export function readAuthorityReceiptV3(path) {
+    const serialized = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        throw new Error("authority receipt is malformed");
+    }
+    const receipt = validateReceipt(parsed);
+    if (`${canonicalJsonV3(receipt)}\n` !== serialized) {
+        throw new Error("authority receipt is not canonical");
+    }
+    return receipt;
+}
+function validateTransaction(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("authority transaction envelope is invalid");
+    }
+    const record = value;
+    if (Object.keys(record).sort().join("\0") !==
+        "actor_instance_id\0desired_state_digest\0event_id\0event_row\0expected_prior_state_digest\0format\0format_version\0mutation\0subject_instance_id\0transaction_id") {
+        throw new Error("authority transaction has unsupported fields");
+    }
+    if (record.format !== "harnery-event-v3-authority-transaction" ||
+        record.format_version !== 1 ||
+        typeof record.transaction_id !== "string" ||
+        typeof record.expected_prior_state_digest !== "string" ||
+        typeof record.desired_state_digest !== "string" ||
+        typeof record.actor_instance_id !== "string" ||
+        typeof record.subject_instance_id !== "string" ||
+        typeof record.event_id !== "string" ||
+        typeof record.event_row !== "string") {
+        throw new Error("authority transaction values are invalid");
+    }
+    assertTransactionId(record.transaction_id);
+    if (!SHA256_PATTERN.test(record.expected_prior_state_digest) ||
+        !SHA256_PATTERN.test(record.desired_state_digest) ||
+        !INSTANCE_PATTERN.test(record.actor_instance_id) ||
+        !INSTANCE_PATTERN.test(record.subject_instance_id)) {
+        throw new Error("authority transaction authority fields are invalid");
+    }
+    const mutation = validateMutation(record.mutation);
+    let event;
+    try {
+        event = JSON.parse(record.event_row);
+    }
+    catch {
+        throw new Error("authority transaction event row is malformed");
+    }
+    assertEventV3(event);
+    if (record.event_id !== event.event_id || `${canonicalJsonV3(event)}\n` !== record.event_row) {
+        throw new Error("authority transaction event row is not canonical or mismatched");
+    }
+    const transaction = { ...record, mutation };
+    validateTransactionBinding(transaction, event);
+    return transaction;
+}
+function validateMutation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("authority mutation is invalid");
+    }
+    const mutation = value;
+    if (mutation.kind === "task.transition") {
+        const allowed = mutation.task_fingerprint === undefined ? "kind\0state" : "kind\0state\0task_fingerprint";
+        if (Object.keys(mutation).sort().join("\0") !== allowed ||
+            !["set", "cleared"].includes(String(mutation.state)) ||
+            (mutation.state === "set" &&
+                (typeof mutation.task_fingerprint !== "string" ||
+                    !SHA256_PATTERN.test(mutation.task_fingerprint))) ||
+            (mutation.state === "cleared" && mutation.task_fingerprint !== undefined)) {
+            throw new Error("authority task mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "lifecycle.transition") {
+        const allowed = mutation.reason_code === undefined ? "kind\0state" : "kind\0reason_code\0state";
+        if (Object.keys(mutation).sort().join("\0") !== allowed ||
+            !["active", "blocked", "done"].includes(String(mutation.state)) ||
+            (mutation.reason_code !== undefined &&
+                (typeof mutation.reason_code !== "string" || !REASON_PATTERN.test(mutation.reason_code)))) {
+            throw new Error("authority lifecycle mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "claim.transition") {
+        if (Object.keys(mutation).sort().join("\0") !== "access\0kind\0operation\0target_fingerprint" ||
+            !["read", "write"].includes(String(mutation.access)) ||
+            !["acquired", "released"].includes(String(mutation.operation)) ||
+            typeof mutation.target_fingerprint !== "string" ||
+            !SHA256_PATTERN.test(mutation.target_fingerprint)) {
+            throw new Error("authority claim mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "identity.assume") {
+        if (Object.keys(mutation).sort().join("\0") !== "identity_id\0kind" ||
+            typeof mutation.identity_id !== "string" ||
+            !SAFE_ID_PATTERN.test(mutation.identity_id)) {
+            throw new Error("authority identity mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "decision.resolve") {
+        if (Object.keys(mutation).sort().join("\0") !== "decision_id\0kind\0outcome" ||
+            typeof mutation.decision_id !== "string" ||
+            !SAFE_ID_PATTERN.test(mutation.decision_id) ||
+            !["approved", "denied", "deferred"].includes(String(mutation.outcome))) {
+            throw new Error("authority decision mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "wait.start") {
+        if (Object.keys(mutation).sort().join("\0") !== "kind\0wait_id\0wait_kind" ||
+            typeof mutation.wait_id !== "string" ||
+            !SAFE_ID_PATTERN.test(mutation.wait_id) ||
+            !["permission", "approval", "decision", "operator_input", "dependency", "scheduled"].includes(String(mutation.wait_kind))) {
+            throw new Error("authority wait-start mutation is invalid");
+        }
+    }
+    else if (mutation.kind === "wait.end") {
+        if (Object.keys(mutation).sort().join("\0") !== "kind\0outcome\0wait_id" ||
+            typeof mutation.wait_id !== "string" ||
+            !SAFE_ID_PATTERN.test(mutation.wait_id) ||
+            ![
+                "succeeded",
+                "failed",
+                "cancelled",
+                "timed_out",
+                "denied",
+                "interrupted",
+                "unknown",
+            ].includes(String(mutation.outcome))) {
+            throw new Error("authority wait-end mutation is invalid");
+        }
+    }
+    else {
+        throw new Error("authority mutation kind is unsupported");
+    }
+    return mutation;
+}
+function validateTransactionBinding(transaction, event) {
+    if (event.scope.instance_id !== transaction.actor_instance_id ||
+        event.provenance.attribution.state !== "verified" ||
+        event.provenance.attribution.observer_instance_id !== transaction.actor_instance_id ||
+        event.provenance.attribution.subject_instance_id !== transaction.subject_instance_id) {
+        throw new Error("authority transaction attribution does not match its event");
+    }
+    const mutation = transaction.mutation;
+    if (mutation.kind === "task.transition") {
+        if (event.event_type !== "coord.task_changed" ||
+            event.payload.actor_instance_id !== transaction.actor_instance_id ||
+            event.payload.subject_instance_id !== transaction.subject_instance_id ||
+            event.payload.authority.transaction_id !== transaction.transaction_id ||
+            event.payload.new_state !== mutation.state ||
+            event.payload.reason_fingerprint?.digest !== mutation.task_fingerprint) {
+            throw new Error("authority task transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind === "lifecycle.transition") {
+        if (event.event_type !== "coord.lifecycle_changed" ||
+            event.payload.actor_instance_id !== transaction.actor_instance_id ||
+            event.payload.subject_instance_id !== transaction.subject_instance_id ||
+            event.payload.authority.transaction_id !== transaction.transaction_id ||
+            event.payload.new_state !== mutation.state ||
+            event.payload.reason !== (mutation.reason_code ?? "lifecycle_transition")) {
+            throw new Error("authority lifecycle transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind === "claim.transition") {
+        const operation = mutation.operation;
+        if (event.event_type !== "coord.claim_changed" ||
+            event.payload.actor_instance_id !== transaction.actor_instance_id ||
+            event.payload.subject_instance_id !== transaction.subject_instance_id ||
+            event.payload.authority.transaction_id !== transaction.transaction_id ||
+            event.payload.operation !== operation ||
+            event.payload.target.fingerprint.digest !== mutation.target_fingerprint ||
+            event.payload.access !== mutation.access) {
+            throw new Error("authority claim transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind === "identity.assume") {
+        if (event.event_type !== "coord.identity_attested" ||
+            event.payload.actor_instance_id !== transaction.actor_instance_id ||
+            event.payload.subject_instance_id !== transaction.subject_instance_id ||
+            event.payload.authority.transaction_id !== transaction.transaction_id ||
+            event.payload.identity_id !== mutation.identity_id) {
+            throw new Error("authority identity transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind === "decision.resolve") {
+        if (event.event_type !== "decision.state_changed" ||
+            event.payload.authority.transaction_id !== transaction.transaction_id ||
+            event.payload.decision_id !== mutation.decision_id ||
+            event.payload.new_state !== mutation.outcome) {
+            throw new Error("authority decision transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind === "wait.start") {
+        if (event.event_type !== "wait.started" ||
+            event.payload.authority_reference !== transaction.transaction_id ||
+            event.payload.wait_id !== mutation.wait_id ||
+            event.payload.kind !== mutation.wait_kind) {
+            throw new Error("authority wait-start transaction does not match its event");
+        }
+        return;
+    }
+    if (mutation.kind !== "wait.end") {
+        throw new Error("authority transaction mutation binding is unsupported");
+    }
+    if (event.event_type !== "wait.ended" ||
+        event.payload.resolution_reference !== transaction.transaction_id ||
+        event.payload.wait_id !== mutation.wait_id ||
+        event.payload.outcome !== mutation.outcome) {
+        throw new Error("authority wait-end transaction does not match its event");
+    }
+}
+function validateReceipt(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("authority receipt is invalid");
+    }
+    const receipt = value;
+    if (Object.keys(receipt).sort().join("\0") !==
+        "committed_at\0desired_state_digest\0event_id\0event_row_digest\0format\0format_version\0transaction_digest\0transaction_id" ||
+        receipt.format !== "harnery-event-v3-authority-receipt" ||
+        receipt.format_version !== 1 ||
+        typeof receipt.transaction_id !== "string" ||
+        typeof receipt.transaction_digest !== "string" ||
+        typeof receipt.desired_state_digest !== "string" ||
+        typeof receipt.event_id !== "string" ||
+        typeof receipt.event_row_digest !== "string" ||
+        typeof receipt.committed_at !== "string" ||
+        !SHA256_PATTERN.test(receipt.transaction_digest) ||
+        !SHA256_PATTERN.test(receipt.desired_state_digest) ||
+        !SHA256_PATTERN.test(receipt.event_row_digest) ||
+        Number.isNaN(Date.parse(receipt.committed_at))) {
+        throw new Error("authority receipt values are invalid");
+    }
+    assertTransactionId(receipt.transaction_id);
+    return receipt;
+}
+function publishExclusive(path, serialized) {
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    let fd;
+    try {
+        fd = openSync(temporary, "wx", 0o600);
+        writeFileSync(fd, serialized, "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        linkSync(temporary, path);
+        fsyncParentDirectory(path);
+        unlinkSync(temporary);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function authorityReadyPath(outbox, transactionId) {
+    assertTransactionId(transactionId);
+    return join(outbox, `${transactionId}.ready.json`);
+}
+function authorityCommittedPath(outbox, transactionId) {
+    assertTransactionId(transactionId);
+    return join(outbox, `${transactionId}.committed.json`);
+}
+function assertTransactionId(value) {
+    if (!TX_PATTERN.test(value))
+        throw new Error("authority transaction ID is invalid");
+}

package/dist/core/events/v3/base-builder.d.ts

@@ -0,0 +1,20 @@
+import type { EventOfTypeV3Base, EventPayloadV3Base, EventTypeV3Base } from "./base-contract.js";
+type EventWithoutDiscriminator<T extends EventTypeV3Base> = Omit<EventOfTypeV3Base<T>, "attestation_id" | "contract" | "event_id" | "event_type" | "payload" | "time">;
+type RootEventTypeV3Base = "ledger.genesis" | "ledger.activated" | "ledger.schema_advanced" | "ledger.comparability_advanced";
+type AttestationInputV3Base<T extends EventTypeV3Base> = T extends RootEventTypeV3Base ? {
+    attestation_id?: never;
+} : {
+    attestation_id: `att_${string}`;
+};
+export type BuildEventV3BaseInput<T extends EventTypeV3Base> = EventWithoutDiscriminator<T> & AttestationInputV3Base<T> & {
+    payload: EventPayloadV3Base<T>;
+    event_id?: `evt_${string}`;
+    observed_at?: string;
+    recorded_at?: string;
+    monotonic_ns?: string;
+    clock_id?: `clk_${string}`;
+    skew?: "normal" | "regressed" | "unknown";
+};
+export declare function buildEventV3Base<T extends EventTypeV3Base>(eventType: T, input: BuildEventV3BaseInput<T>): EventOfTypeV3Base<T>;
+export {};
+//# sourceMappingURL=base-builder.d.ts.map

package/dist/core/events/v3/base-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-builder.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/base-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKjG,KAAK,yBAAyB,CAAC,CAAC,SAAS,eAAe,IAAI,IAAI,CAC9D,iBAAiB,CAAC,CAAC,CAAC,EACpB,gBAAgB,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAC/E,CAAC;AAEF,KAAK,mBAAmB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,wBAAwB,GACxB,+BAA+B,CAAC;AAEpC,KAAK,sBAAsB,CAAC,CAAC,SAAS,eAAe,IAAI,CAAC,SAAS,mBAAmB,GAClF;IAAE,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1B;IAAE,cAAc,EAAE,OAAO,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,eAAe,IAAI,yBAAyB,CAAC,CAAC,CAAC,GACzF,sBAAsB,CAAC,CAAC,CAAC,GAAG;IAC1B,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEJ,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,eAAe,EACxD,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC9B,iBAAiB,CAAC,CAAC,CAAC,CAyBtB"}

package/dist/core/events/v3/base-builder.js

@@ -0,0 +1,29 @@
+import { EVENT_V3_BASE_CONTRACT_MAJOR, EVENT_V3_BASE_CONTRACT_NAME } from "./base-contract.js";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
+import { clockIdV3, eventIdV3 } from "./ids.js";
+export function buildEventV3Base(eventType, input) {
+    const now = input.recorded_at ?? new Date().toISOString();
+    const event = {
+        contract: {
+            name: EVENT_V3_BASE_CONTRACT_NAME,
+            major: EVENT_V3_BASE_CONTRACT_MAJOR,
+            schema_digest: EVENT_V3_SCHEMA_DIGEST,
+        },
+        event_id: input.event_id ?? eventIdV3(),
+        event_type: eventType,
+        time: {
+            observed_at: input.observed_at ?? now,
+            recorded_at: now,
+            ...(input.monotonic_ns ? { monotonic_ns: input.monotonic_ns } : {}),
+            clock_id: input.clock_id ?? clockIdV3(),
+            skew: input.skew ?? "unknown",
+        },
+        producer: input.producer,
+        scope: input.scope,
+        ...(input.attestation_id ? { attestation_id: input.attestation_id } : {}),
+        links: input.links,
+        provenance: input.provenance,
+        payload: input.payload,
+    };
+    return event;
+}