@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0

package/dist/protocol/entities.js

@@ -0,0 +1,185 @@
+/**
+ * Generic exchange entity schemas (frozen v2).
+ *
+ * Payload bodies and result bodies are expected data and may be persisted by
+ * the host, but they are sensitive: keep them out of diagnostic logs and
+ * correlate via digests (IDs, digests, lengths, typed outcomes) instead.
+ * Never persist credentials or environment secrets; endpoint identity is
+ * opaque routing identity only.
+ */
+import { Type } from "@sinclair/typebox";
+import "./formats.js";
+import { ATTEMPT_ID_PATTERN, EVENT_ID_PATTERN, EXCHANGE_ID_PATTERN, MESSAGE_ID_PATTERN, RECEIPT_ID_PATTERN, RESULT_ID_PATTERN, } from "./identity.js";
+import { MESSAGE_STATES } from "./lifecycle.js";
+import { AttemptTransportSchema, DispatchMarkerSchema, RuntimeOutcomeSchema, TransportOutcomeSchema } from "./outcomes.js";
+export const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const Sha256Schema = Type.String({
+    pattern: SHA256_HEX_PATTERN.source,
+    description: "SHA-256 hex digest. Correlate via digest, never log the body.",
+});
+const idSchema = (pattern, description) => Type.String({ pattern: pattern.source, description });
+/**
+ * Opaque, non-secret routing identity for one adapter endpoint.
+ *
+ * - `adapter` names the adapter kind that understands `endpointId`;
+ * - `endpointId` is the DURABLE endpoint identity (survives restarts);
+ * - `instanceId` is the EPHEMERAL process incarnation, when one is live.
+ *
+ * EndpointRef deliberately carries no free-form routing metadata and no
+ * credentials: anything secret or adapter-specific beyond these three fields
+ * stays adapter-local. `additionalProperties: false` enforces this.
+ */
+export const EndpointRefSchema = Type.Object({
+    adapter: Type.String({ minLength: 1, maxLength: 64 }),
+    endpointId: Type.String({ minLength: 1, maxLength: 256 }),
+    instanceId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+}, { additionalProperties: false });
+/**
+ * Exchange aggregate root: OPEN governs correlation and message creation;
+ * CLOSED is an explicit owner action (core `closeExchange`), never implied by
+ * reads. Legacy `ho_` identity prefix retained from v1 (documented
+ * compatibility; no id migration).
+ */
+export const ExchangeSchema = Type.Object({
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Opaque immutable exchange identity: ho_ followed by a ULID (legacy v1 prefix, retained)."),
+    state: Type.Union([Type.Literal("OPEN"), Type.Literal("CLOSED")]),
+    createdAt: Type.String({ format: "date-time" }),
+    closedAt: Type.Optional(Type.String({ format: "date-time" })),
+}, { additionalProperties: false });
+/** A Message is an independently lifecycle-tracked entity inside one Exchange. */
+export const MessageSchema = Type.Object({
+    messageId: idSchema(MESSAGE_ID_PATTERN, "Opaque immutable message identity: msg_ followed by a ULID (additive v2)."),
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Owning exchange identity."),
+    from: EndpointRefSchema,
+    to: EndpointRefSchema,
+    state: Type.Union(MESSAGE_STATES.map((state) => Type.Literal(state))),
+    payloadDigest: Sha256Schema,
+    payloadLength: Type.Integer({ minimum: 0 }),
+    createdAt: Type.String({ format: "date-time" }),
+    idempotencyKey: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+}, { additionalProperties: false });
+/** Consumer lease: claim ownership with a fencing token and expiry. */
+export const LeaseSchema = Type.Object({
+    consumerId: Type.String({ minLength: 1, maxLength: 128 }),
+    instanceId: Type.String({ minLength: 1, maxLength: 256 }),
+    fencingToken: Type.Integer({ minimum: 1 }),
+    expiresAt: Type.String({ format: "date-time" }),
+}, { additionalProperties: false });
+/**
+ * DeliveryAttempt: the durable dispatch-evidence record. `dispatch` is marked
+ * `started` durably BEFORE any adapter side effect; `transport` records the
+ * generic outcome afterwards. The recorded `lease` is the fencing authority
+ * for every mutation that cites this attempt.
+ */
+export const DeliveryAttemptSchema = Type.Object({
+    attemptId: idSchema(ATTEMPT_ID_PATTERN, "Opaque immutable attempt identity: att_ followed by a ULID (additive v2)."),
+    messageId: idSchema(MESSAGE_ID_PATTERN, "Correlated message identity."),
+    endpoint: EndpointRefSchema,
+    lease: LeaseSchema,
+    dispatch: DispatchMarkerSchema,
+    transport: AttemptTransportSchema,
+    createdAt: Type.String({ format: "date-time" }),
+}, { additionalProperties: false });
+/** Adapter-observed runtime evidence, correlated independently of transport. */
+export const RuntimeEvidenceSchema = Type.Object({
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Correlated exchange identity."),
+    messageId: idSchema(MESSAGE_ID_PATTERN, "Correlated message identity."),
+    attemptId: idSchema(ATTEMPT_ID_PATTERN, "Correlated attempt identity."),
+    endpoint: EndpointRefSchema,
+    outcome: RuntimeOutcomeSchema,
+    observedAt: Type.String({ format: "date-time" }),
+}, { additionalProperties: false });
+/**
+ * Immutable Result with full correlation (exchange, message, attempt) and
+ * layered outcome discriminants. `applicationEvidence` is opaque JSON the
+ * protocol never interprets. Publication is once: exact replay or conflict.
+ */
+export const ResultSchema = Type.Object({
+    resultId: idSchema(RESULT_ID_PATTERN, "Opaque immutable result identity: hr_ followed by a ULID (unchanged from v1)."),
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Correlated exchange identity."),
+    messageId: idSchema(MESSAGE_ID_PATTERN, "Correlated message identity."),
+    attemptId: idSchema(ATTEMPT_ID_PATTERN, "Correlated attempt identity."),
+    source: EndpointRefSchema,
+    transport: TransportOutcomeSchema,
+    runtime: RuntimeOutcomeSchema,
+    body: Type.String({ maxLength: 1_000_000 }),
+    resultDigest: Sha256Schema,
+    settledAt: Type.String({ format: "date-time" }),
+    applicationEvidence: Type.Optional(Type.Unknown()),
+}, { additionalProperties: false });
+/** Non-mutating observation receipts (reads never change lifecycle state). */
+export const ReceiptSchema = Type.Object({
+    receiptId: idSchema(RECEIPT_ID_PATTERN, "Opaque immutable receipt identity: rcpt_ followed by a ULID (additive v2)."),
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Correlated exchange identity."),
+    messageId: idSchema(MESSAGE_ID_PATTERN, "Correlated message identity."),
+    endpoint: EndpointRefSchema,
+    kind: Type.Union([
+        Type.Literal("read"),
+        Type.Literal("delivery_ack"),
+        Type.Literal("duplicate_suppressed"),
+    ]),
+    createdAt: Type.String({ format: "date-time" }),
+}, { additionalProperties: false });
+/** Registered consumer (claim principal). Labels are non-secret diagnostics. */
+export const ConsumerSchema = Type.Object({
+    consumerId: Type.String({ minLength: 1, maxLength: 128 }),
+    label: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+    createdAt: Type.String({ format: "date-time" }),
+    lastSeenAt: Type.Optional(Type.String({ format: "date-time" })),
+}, { additionalProperties: false });
+export const EVENT_KINDS = [
+    "exchange_opened",
+    "exchange_closed",
+    "message_created",
+    "message_state_changed",
+    "attempt_recorded",
+    "result_published",
+    "receipt_recorded",
+];
+/**
+ * Bounded diagnostic event: IDs, digests, lengths, and typed outcomes only.
+ * Raw payload bodies are structurally rejected (no `payload` field exists).
+ */
+export const EventSchema = Type.Object({
+    eventId: idSchema(EVENT_ID_PATTERN, "Opaque immutable event identity: evt_ followed by a ULID (additive v2)."),
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Correlated exchange identity."),
+    sequence: Type.Integer({ minimum: 1 }),
+    kind: Type.Union(EVENT_KINDS.map((kind) => Type.Literal(kind))),
+    subjectId: Type.String({ minLength: 1, maxLength: 256 }),
+    createdAt: Type.String({ format: "date-time" }),
+    digest: Type.Optional(Sha256Schema),
+    length: Type.Optional(Type.Integer({ minimum: 0 })),
+    outcome: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+}, { additionalProperties: false });
+/**
+ * Explicit reconciliation evidence for quarantined (DELIVERY_UNKNOWN)
+ * resolution. Late correlated acceptance or a confirmed no-effect proof must
+ * travel with this record — an expired consumer lease is never sufficient.
+ */
+export const ReconciliationEvidenceSchema = Type.Object({
+    resolvedAt: Type.String({ format: "date-time" }),
+    basis: Type.String({ minLength: 1, maxLength: 512 }),
+}, { additionalProperties: false });
+/**
+ * Separate administrative archive, never an execution state or Result.
+ * OPEN/CLOSED semantics are unchanged. A disposition permanently disables
+ * protocol activity but preserves each original unresolved delivery fact.
+ * Owner identity must come from the authenticated host, not an adapter label.
+ */
+export const ExchangeDispositionSchema = Type.Object({
+    exchangeId: idSchema(EXCHANGE_ID_PATTERN, "Administratively archived exchange identity."),
+    status: Type.Literal("ABANDONED_UNRESOLVED"),
+    ownerId: Type.String({ minLength: 1, maxLength: 256 }),
+    recordedAt: Type.String({ format: "date-time" }),
+    reason: Type.String({ minLength: 1, maxLength: 1024 }),
+    // This is investigation/owner-intent metadata, not execution proof.
+    reconciliation: ReconciliationEvidenceSchema,
+    unresolved: Type.Array(Type.Object({
+        messageId: idSchema(MESSAGE_ID_PATTERN, "Original unresolved message identity."),
+        originalState: Type.Literal("DELIVERY_UNKNOWN"),
+        transport: Type.Literal("ambiguous"),
+        unresolvedSideEffects: Type.Literal(true),
+        attempt: DeliveryAttemptSchema,
+    }, { additionalProperties: false }), { minItems: 1 }),
+}, { additionalProperties: false });
+//# sourceMappingURL=entities.js.map

package/dist/protocol/formats.js

@@ -0,0 +1,13 @@
+/**
+ * Shared JSON Schema format validators for frozen protocol schemas.
+ *
+ * TypeBox's `Value.Check` rejects `format` keywords that have no registered
+ * validator, so the `date-time` formats used across the protocol are
+ * registered exactly once, here. Validation is strict ISO 8601 with an
+ * explicit zone designator (Z or ±hh:mm); the protocol always serializes
+ * timestamps in UTC `Z` form.
+ */
+import { FormatRegistry } from "@sinclair/typebox";
+const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+FormatRegistry.Set("date-time", (value) => typeof value === "string" && DATE_TIME_PATTERN.test(value));
+//# sourceMappingURL=formats.js.map

package/dist/protocol/idempotency.js

@@ -0,0 +1,93 @@
+/**
+ * Idempotency contract (frozen v2; strengthened from v1).
+ *
+ * A retried create (e.g. after a caller-side timeout) must never silently
+ * produce a second entity. Keys are scoped to an explicit NAMESPACE, so
+ * distinct callers cannot collide on the same key string:
+ *
+ *   record(ns, key=A, digest=D) -> entity 1
+ *   record(ns, key=A, digest=D) -> entity 1   (same record replayed)
+ *   record(ns, key=A, digest=E) -> IDEMPOTENCY_KEY_CONFLICT (never a new id)
+ *   record(otherNs, key=A, ...)  -> independent record
+ *
+ * The store contract is keyed by (namespace, key) and returns IMMUTABLE
+ * records. This module defines the contract and the canonical digest; the
+ * in-memory REFERENCE implementation lives in core (`core/reference.ts`) —
+ * it is a semantics reference, not a durable store. A durable host must
+ * preserve these semantics transactionally.
+ */
+import { createHash } from "node:crypto";
+export const IDEMPOTENCY_KEY_MAX_LENGTH = 256;
+export const NAMESPACE_MAX_LENGTH = 256;
+export class IdempotencyKeyConflictError extends Error {
+    code = "IDEMPOTENCY_KEY_CONFLICT";
+    idempotencyKey;
+    constructor(namespace, idempotencyKey) {
+        super(`idempotency key conflict: ${namespace}:${idempotencyKey}`);
+        this.name = "IdempotencyKeyConflictError";
+        this.idempotencyKey = idempotencyKey;
+    }
+}
+/** Canonical-digest input is unsupported (or cyclic) JSON-ish data. */
+export class DigestInputError extends Error {
+    code = "DIGEST_INPUT_UNSUPPORTED";
+    constructor(detail) {
+        super(`canonical digest input rejected: ${detail}`);
+        this.name = "DigestInputError";
+    }
+}
+/**
+ * Deterministic content digest (SHA-256 hex) over a canonicalized JSON form:
+ * object keys are sorted recursively so logically equal requests produce
+ * equal digests regardless of key order. Unsupported values (undefined,
+ * functions, symbols, bigints, non-finite numbers) and cyclic structures are
+ * rejected with {@link DigestInputError} instead of silently degrading.
+ */
+export function canonicalDigest(value) {
+    return createHash("sha256").update(canonicalJson(value, new Set())).digest("hex");
+}
+function canonicalJson(value, ancestors) {
+    if (value === null)
+        return "null";
+    const type = typeof value;
+    if (type === "string")
+        return JSON.stringify(value);
+    if (type === "number") {
+        if (!Number.isFinite(value)) {
+            throw new DigestInputError("numbers must be finite");
+        }
+        return JSON.stringify(value);
+    }
+    if (type === "boolean")
+        return value ? "true" : "false";
+    if (type === "undefined" || type === "function" || type === "symbol" || type === "bigint") {
+        throw new DigestInputError(`unsupported value of type ${type}`);
+    }
+    if (ancestors.has(value)) {
+        throw new DigestInputError("cyclic structure");
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.keys(value).length !== value.length || Reflect.ownKeys(value).length !== value.length + 1) {
+                throw new DigestInputError("sparse arrays or extra array properties are unsupported");
+            }
+            return `[${value.map((item) => canonicalJson(item, ancestors)).join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new DigestInputError("only plain JSON objects are supported");
+        }
+        if (Reflect.ownKeys(value).length !== Object.keys(value).length) {
+            throw new DigestInputError("symbol or non-enumerable properties are unsupported");
+        }
+        const record = value;
+        const keys = Object.keys(record).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const entries = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], ancestors)}`);
+        return `{${entries.join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/protocol/identity.js

@@ -0,0 +1,130 @@
+/**
+ * Exchange entity identity (frozen v2 contract; encoder frozen since v1).
+ *
+ * Identity prefixes (opaque, unique, immutable, non-secret, safe to log):
+ *
+ * - `ho_<ULID>` — Exchange. Legacy prefix retained from protocol v1 for
+ *   documented compatibility: the v1 "handoff" entity becomes the Exchange
+ *   aggregate root and no existing id is migrated.
+ * - `hr_<ULID>` — Result (unchanged from v1).
+ * - `msg_`, `att_`, `rcpt_`, `evt_` — additive Message, DeliveryAttempt,
+ *   Receipt, and Event identities introduced by protocol v2.
+ *
+ * Every id is a Crockford Base32 ULID: 48-bit millisecond timestamp + 80-bit
+ * CSPRNG randomness, encoded losslessly by {@link encodeUlid}.
+ *
+ * Human-friendly shortened display IDs may exist for UI convenience, but they
+ * are never authoritative (see {@link displayId}).
+ */
+import { randomBytes } from "node:crypto";
+/** Legacy v1 name retained: handoff ids are Exchange ids (`ho_`). */
+export const HANDOFF_ID_PREFIX = "ho_";
+export const HANDOFF_ID_PATTERN = /^ho_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const EXCHANGE_ID_PREFIX = HANDOFF_ID_PREFIX;
+export const EXCHANGE_ID_PATTERN = HANDOFF_ID_PATTERN;
+export const MESSAGE_ID_PREFIX = "msg_";
+export const MESSAGE_ID_PATTERN = /^msg_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const ATTEMPT_ID_PREFIX = "att_";
+export const ATTEMPT_ID_PATTERN = /^att_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const RESULT_ID_PREFIX = "hr_";
+export const RESULT_ID_PATTERN = /^hr_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const RECEIPT_ID_PREFIX = "rcpt_";
+export const RECEIPT_ID_PATTERN = /^rcpt_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const EVENT_ID_PREFIX = "evt_";
+export const EVENT_ID_PATTERN = /^evt_[0-9A-HJKMNP-TV-Z]{26}$/;
+export const ENTITY_ID_PREFIXES = [
+    EXCHANGE_ID_PREFIX,
+    MESSAGE_ID_PREFIX,
+    ATTEMPT_ID_PREFIX,
+    RESULT_ID_PREFIX,
+    RECEIPT_ID_PREFIX,
+    EVENT_ID_PREFIX,
+];
+const CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_BITS = 48;
+const RANDOM_BITS = 80;
+const ENCODED_LENGTH = 26;
+export function isHandoffId(value) {
+    return typeof value === "string" && HANDOFF_ID_PATTERN.test(value);
+}
+export function assertHandoffId(value) {
+    if (!isHandoffId(value)) {
+        throw new Error(`invalid handoff id: expected ${HANDOFF_ID_PATTERN}`);
+    }
+    return value;
+}
+/**
+ * Encode a ULID from a millisecond timestamp and 10 random bytes, per the
+ * ULID specification (Crockford Base32, big-endian, first char 0-7).
+ */
+export function encodeUlid(timestampMs, random) {
+    if (!Number.isInteger(timestampMs) || timestampMs < 0 || timestampMs >= 2 ** TIME_BITS) {
+        throw new Error(`timestamp out of range for ULID: ${timestampMs}`);
+    }
+    if (random.length !== RANDOM_BITS / 8) {
+        throw new Error(`ULID requires ${RANDOM_BITS / 8} random bytes, got ${random.length}`);
+    }
+    const chars = new Array(ENCODED_LENGTH);
+    // 48-bit time, 5 bits per char: chars 0..9 (char 0 masked to 3 bits below).
+    let remainder = timestampMs;
+    for (let i = 9; i >= 1; i -= 1) {
+        chars[i] = alphabetChar(remainder & 31);
+        remainder = Math.floor(remainder / 32);
+    }
+    // After nine divisions the top 3 bits remain for the masked first char.
+    chars[0] = alphabetChar(remainder & 7);
+    // Consume all ten bytes as one 80-bit big-endian value, then emit sixteen
+    // disjoint five-bit groups. Pairing two chars per byte overlaps bits and
+    // silently discards the final two bytes.
+    let entropy = 0n;
+    for (const byte of random)
+        entropy = (entropy << 8n) | BigInt(byte);
+    for (let i = 25; i >= 10; i -= 1) {
+        chars[i] = alphabetChar(Number(entropy & 31n));
+        entropy >>= 5n;
+    }
+    return chars.join("");
+}
+function alphabetChar(index) {
+    const char = CROCKFORD_ALPHABET[index];
+    if (char === undefined) {
+        throw new Error(`Crockford alphabet index out of range: ${index}`);
+    }
+    return char;
+}
+/** Generate a new exchange id (`ho_`). `now` is injectable for deterministic tests. */
+export function generateHandoffId(now = Date.now()) {
+    return assertHandoffId(HANDOFF_ID_PREFIX + encodeUlid(now, randomBytes(RANDOM_BITS / 8)));
+}
+/** Generate a new entity id for any declared prefix. Additive v2 ids use this. */
+export function generateEntityId(prefix, now = Date.now()) {
+    return prefix + encodeUlid(now, randomBytes(RANDOM_BITS / 8));
+}
+/** Structural check for any declared entity id prefix. */
+export function isEntityId(prefix, value) {
+    return typeof value === "string" && entityIdPattern(prefix).test(value);
+}
+export function entityIdPattern(prefix) {
+    switch (prefix) {
+        case "ho_":
+            return EXCHANGE_ID_PATTERN;
+        case "msg_":
+            return MESSAGE_ID_PATTERN;
+        case "att_":
+            return ATTEMPT_ID_PATTERN;
+        case "hr_":
+            return RESULT_ID_PATTERN;
+        case "rcpt_":
+            return RECEIPT_ID_PATTERN;
+        case "evt_":
+            return EVENT_ID_PATTERN;
+    }
+}
+/**
+ * Non-authoritative short label for display. Derived from the immutable id,
+ * but must never be used for persistence, correlation, or API identity.
+ */
+export function displayId(handoffId) {
+    return handoffId.slice(-8);
+}
+//# sourceMappingURL=identity.js.map

package/dist/protocol/index.js

@@ -0,0 +1,8 @@
+export * from "./identity.js";
+export * from "./lifecycle.js";
+export * from "./outcomes.js";
+export * from "./entities.js";
+export * from "./capabilities.js";
+export * from "./idempotency.js";
+export * from "./endpoint-capabilities.js";
+//# sourceMappingURL=index.js.map

package/dist/protocol/lifecycle.js

@@ -0,0 +1,125 @@
+/**
+ * Message lifecycle state machine (frozen v2 contract).
+ *
+ * PH-0002 correction: a Message is an independent entity inside an Exchange
+ * aggregate. Its lifecycle tracks delivery and runtime settlement; it does
+ * NOT track reads. There is deliberately no CONSUMED state: reading a Result
+ * is a non-mutating observation (see core `readResult`), never a lifecycle
+ * event, and "no read" never means "not done".
+ *
+ * Outcome layers are never collapsed:
+ * - transport: did the payload reach the adapter boundary of the destination?
+ *   (generic trichotomy delivered | ambiguous | failed)
+ * - runtime: did the destination invocation accept, run, and settle?
+ * - application: is the requested task semantically correct? The protocol
+ *   never decides this (opaque `applicationEvidence` on the Result).
+ *
+ * Fail-closed rules (frozen):
+ * - Entering DISPATCHING requires the durable dispatch-start evidence on the
+ *   attempt record BEFORE any adapter side effect can be attempted.
+ * - Any potentially attempted dispatch that cannot be confirmed quarantines
+ *   the message as DELIVERY_UNKNOWN. DELIVERY_UNKNOWN has NO transition back
+ *   to QUEUED/CLAIMED/DISPATCHING and no automatic retry: a duplicated
+ *   exchange payload may cause irreversible effects at the destination.
+ * - Safe requeue (CLAIMED → QUEUED) is legal only with a validated
+ *   definitely-not-attempted attempt record — evidence, not assertion.
+ * - Cancellation is split: a request (CANCEL_REQUESTED) is never a
+ *   confirmation. After dispatch may have begun, independently authorized
+ *   runtime evidence must confirm CANCELLED. Owner abandonment is a separate administrative
+ *   disposition; it never resolves execution ambiguity or cancels a runtime.
+ *
+ * Transitions split into two groups:
+ * - evidence-free moves, licensed by state shape alone ({@link canTransition});
+ * - evidence-gated moves, listed in {@link TRANSITION_REQUIREMENTS} and
+ *   enforced by the pure core rules, which correlate the exact message,
+ *   attempt, endpoint, and lease.
+ */
+export const MESSAGE_STATES = [
+    "CREATED",
+    "QUEUED",
+    "CLAIMED",
+    "DISPATCHING",
+    "DELIVERY_UNKNOWN",
+    "ACCEPTED",
+    "RUNNING",
+    "SETTLED",
+    "RESULT_AVAILABLE",
+    "CANCEL_REQUESTED",
+    "CANCELLED",
+    "FAILED",
+];
+/**
+ * Finished (terminal) message states: nothing further may happen to the
+ * message and an Exchange may close over it. RESULT_AVAILABLE is reached by
+ * publishing the immutable Result, never by reading it.
+ */
+export const FINISHED_MESSAGE_STATES = [
+    "RESULT_AVAILABLE",
+    "CANCELLED",
+    "FAILED",
+];
+/** Quarantined: neither finished nor retryable; requires reconciliation. */
+export const QUARANTINED_MESSAGE_STATES = ["DELIVERY_UNKNOWN"];
+/**
+ * The single source of truth for transition legality, keyed `"FROM>TO"`.
+ * Core rules validate every row's evidence; the shape-level helpers below
+ * expose the two legality tiers.
+ */
+export const TRANSITION_REQUIREMENTS = {
+    "CREATED>QUEUED": { actions: ["exchange_send"], lease: "none", evidence: "none" },
+    "QUEUED>CLAIMED": { actions: ["message_claim"], lease: "none", evidence: "none" },
+    "QUEUED>CANCELLED": { actions: ["exchange_cancel"], lease: "none", evidence: "none" },
+    "CLAIMED>CANCEL_REQUESTED": { actions: ["exchange_cancel"], lease: "none", evidence: "none" },
+    "DISPATCHING>CANCEL_REQUESTED": { actions: ["exchange_cancel"], lease: "none", evidence: "none" },
+    "ACCEPTED>CANCEL_REQUESTED": { actions: ["exchange_cancel"], lease: "none", evidence: "none" },
+    "RUNNING>CANCEL_REQUESTED": { actions: ["exchange_cancel"], lease: "none", evidence: "none" },
+    // Safe release/cancellation still requires proven no attempt.
+    "CLAIMED>QUEUED": { actions: ["lease_release"], lease: "recorded", evidence: "not_attempted" },
+    "CLAIMED>CANCELLED": { actions: ["cancel_confirm"], lease: "recorded", evidence: "not_attempted" },
+    // Pre-effect marker and live fencing remain required.
+    "CLAIMED>DISPATCHING": { actions: ["dispatch_mark_started"], lease: "current", evidence: "dispatch_started" },
+    "CLAIMED>DELIVERY_UNKNOWN": { actions: ["delivery_report"], lease: "recorded", evidence: "transport_ambiguous" },
+    "DISPATCHING>ACCEPTED": { actions: ["delivery_report", "activity_report"], lease: "current", evidence: "transport_delivered" },
+    "DISPATCHING>DELIVERY_UNKNOWN": { actions: ["delivery_report"], lease: "recorded", evidence: "transport_ambiguous" },
+    "DISPATCHING>FAILED": { actions: ["delivery_report"], lease: "current", evidence: "transport_failed" },
+    "ACCEPTED>RUNNING": { actions: ["activity_report"], lease: "current", evidence: "runtime_progress" },
+    "ACCEPTED>SETTLED": { actions: ["settlement_report"], lease: "current", evidence: "runtime_progress" },
+    "RUNNING>SETTLED": { actions: ["settlement_report"], lease: "current", evidence: "runtime_progress" },
+    "SETTLED>RESULT_AVAILABLE": { actions: ["result_publish"], lease: "current", evidence: "result_published" },
+    // Started cancellation additionally requires scoped runtime-settlement authority
+    // in core; proven never-attempted cancellation does not create a runtime fact.
+    "CANCEL_REQUESTED>CANCELLED": { actions: ["cancel_confirm"], lease: "current", evidence: "cancel_confirmed" },
+    "CANCEL_REQUESTED>DELIVERY_UNKNOWN": { actions: ["delivery_report"], lease: "recorded", evidence: "transport_ambiguous" },
+    "CANCEL_REQUESTED>FAILED": { actions: ["delivery_report"], lease: "current", evidence: "transport_failed" },
+    "CANCEL_REQUESTED>SETTLED": { actions: ["settlement_report"], lease: "current", evidence: "runtime_progress" },
+    // Factual reconciliation is never retry permission or owner abandonment.
+    "DELIVERY_UNKNOWN>ACCEPTED": { actions: ["ambiguity_resolve", "activity_report"], lease: "recorded", evidence: "reconciled_delivered" },
+    "DELIVERY_UNKNOWN>FAILED": { actions: ["ambiguity_resolve"], lease: "recorded", evidence: "reconciled_not_executed" },
+};
+/**
+ * Shape-only legality: true when the move is licensed by the state machine
+ * without any further evidence. Evidence-gated moves (safe requeue,
+ * quarantine exits, dispatch and settlement progress) return false here and
+ * must go through the core rule validation.
+ */
+export function canTransition(from, to) {
+    const requirement = TRANSITION_REQUIREMENTS[`${from}>${to}`];
+    return requirement !== undefined && requirement.lease === "none" && requirement.evidence === "none";
+}
+/** Full legality: true when any requirement row licenses the move. */
+export function isLegalTransition(from, to) {
+    return TRANSITION_REQUIREMENTS[`${from}>${to}`] !== undefined;
+}
+/** All legal targets from a state (evidence-free and evidence-gated). */
+export function legalTargets(from) {
+    return MESSAGE_STATES.filter((to) => isLegalTransition(from, to));
+}
+/** Requirement table indexed by origin state (documentation convenience). */
+export const MESSAGE_TRANSITIONS = Object.fromEntries(MESSAGE_STATES.map((state) => [state, legalTargets(state)]));
+export function isFinishedMessageState(state) {
+    return FINISHED_MESSAGE_STATES.includes(state);
+}
+export function isQuarantinedMessageState(state) {
+    return QUARANTINED_MESSAGE_STATES.includes(state);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/protocol/outcomes.js

@@ -0,0 +1,55 @@
+/**
+ * Generic outcome vocabularies (frozen v2).
+ *
+ * Transport and runtime outcomes are separate layers and never borrow each
+ * other's vocabulary: a transport success is not runtime acceptance, and a
+ * socket-level acknowledgment is never evidence of execution. Application
+ * outcome is not modeled here at all — it stays opaque
+ * (`applicationEvidence` on the Result).
+ */
+import { Type } from "@sinclair/typebox";
+/**
+ * Generic transport trichotomy for a dispatch attempt:
+ * - `delivered`: the adapter boundary positively confirmed hand-off;
+ * - `ambiguous`: the attempt may have taken effect (timeout, crash, unknown);
+ * - `failed`: the adapter certifies the attempt provably had no effect.
+ *
+ * An adapter may report `failed` ONLY when it can prove no side effect
+ * occurred; otherwise it must report `ambiguous`. `ambiguous` and `failed`
+ * both fail closed in core rules (`DELIVERY_UNKNOWN` quarantine / terminal
+ * FAILED with no automatic retry).
+ */
+export const TransportOutcomeSchema = Type.Union([
+    Type.Literal("delivered"),
+    Type.Literal("ambiguous"),
+    Type.Literal("failed"),
+]);
+/** Transport state of a DeliveryAttempt; `pending` before any outcome is known. */
+export const AttemptTransportSchema = Type.Union([
+    Type.Literal("pending"),
+    TransportOutcomeSchema,
+]);
+/**
+ * Durable dispatch marker on a DeliveryAttempt. `started` is written durably
+ * BEFORE any adapter side effect; `not_attempted` is the only evidence that
+ * licenses a safe requeue or clean release.
+ */
+export const DispatchMarkerSchema = Type.Union([
+    Type.Literal("not_attempted"),
+    Type.Literal("started"),
+]);
+/**
+ * Generic runtime outcome ladder of the destination invocation. `settled` and
+ * the failure kinds are settlement-grade; `accepted`/`running` describe
+ * observed progress. A published immutable Result typically carries a
+ * settlement-grade value.
+ */
+export const RuntimeOutcomeSchema = Type.Union([
+    Type.Literal("accepted"),
+    Type.Literal("running"),
+    Type.Literal("settled"),
+    Type.Literal("runtime_error"),
+    Type.Literal("cancelled"),
+    Type.Literal("interrupted"),
+]);
+//# sourceMappingURL=outcomes.js.map