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

package/dist/core/rules.js

@@ -0,0 +1,468 @@
+/**
+ * Core exchange rules (frozen v2): pure invariant helpers over the protocol
+ * contracts. No I/O, no storage, no timers, no adapter/MCP/Pi/product
+ * semantics — every function takes its evidence as data and returns new
+ * values or throws. The durable host (out of scope for this phase) must call
+ * these rules inside its transactions; they are the single legality authority.
+ */
+import { Value } from "@sinclair/typebox/value";
+import { canonicalDigest } from "../protocol/idempotency.js";
+import { assertAuthorized } from "./authorization.js";
+import { ExchangeSchema, MessageSchema, ExchangeDispositionSchema, ResultSchema, RuntimeEvidenceSchema, DeliveryAttemptSchema, LeaseSchema, ReconciliationEvidenceSchema, } from "../protocol/entities.js";
+import { FINISHED_MESSAGE_STATES, TRANSITION_REQUIREMENTS, isLegalTransition, } from "../protocol/lifecycle.js";
+export class IllegalTransitionError extends Error {
+    code = "ILLEGAL_TRANSITION";
+    from;
+    to;
+    constructor(from, to) {
+        super(`illegal message state transition: ${from} -> ${to}`);
+        this.name = "IllegalTransitionError";
+        this.from = from;
+        this.to = to;
+    }
+}
+/** The move exists in the state machine but the presented evidence fails. */
+export class TransitionEvidenceError extends Error {
+    code = "TRANSITION_EVIDENCE_REJECTED";
+    from;
+    to;
+    reason;
+    constructor(from, to, reason) {
+        super(`transition evidence rejected (${from} -> ${to}): ${reason}`);
+        this.name = "TransitionEvidenceError";
+        this.from = from;
+        this.to = to;
+        this.reason = reason;
+    }
+}
+export class CloseRejectedError extends Error {
+    code = "EXCHANGE_CLOSE_REJECTED";
+    reason;
+    constructor(reason) {
+        super(`exchange close rejected: ${reason}`);
+        this.name = "CloseRejectedError";
+        this.reason = reason;
+    }
+}
+export class ResultConflictError extends Error {
+    code = "RESULT_CONFLICT";
+    resultId;
+    constructor(resultId) {
+        super(`result already published with different content: ${resultId}`);
+        this.name = "ResultConflictError";
+        this.resultId = resultId;
+    }
+}
+export class InvalidResultError extends Error {
+    code = "INVALID_RESULT";
+    constructor(detail) {
+        super(`result violates the frozen schema: ${detail}`);
+        this.name = "InvalidResultError";
+    }
+}
+/**
+ * Validate one message state transition against correlated evidence.
+ * Returns `to` when legal; throws {@link IllegalTransitionError} for moves
+ * the state machine does not license, or {@link TransitionEvidenceError}
+ * when authority, lease fencing, attempt correlation, or evidence fails.
+ */
+export function assertMessageTransition(message, to, guard) {
+    assertNotArchived(message.exchangeId, guard.disposition);
+    const requirement = TRANSITION_REQUIREMENTS[`${message.state}>${to}`];
+    if (requirement === undefined || !isLegalTransition(message.state, to)) {
+        throw new IllegalTransitionError(message.state, to);
+    }
+    if (!Number.isFinite(Date.parse(guard.now))) {
+        throw new TransitionEvidenceError(message.state, to, "invalid observation time");
+    }
+    assertTransitionAuthorization(requirement, guard, message, to);
+    if (message.state === "QUEUED" && to === "CANCELLED" && guard.attempt !== undefined && (!Value.Check(DeliveryAttemptSchema, guard.attempt) ||
+        guard.attempt.messageId !== message.messageId || !deepEqual(guard.attempt.endpoint, message.to) ||
+        guard.attempt.dispatch !== "not_attempted" || guard.attempt.transport !== "pending")) {
+        throw new TransitionEvidenceError(message.state, to, "queued cancellation contradicts presented dispatch evidence");
+    }
+    const attempt = assertAttemptCorrelation(requirement, message, to, guard);
+    if (attempt !== undefined) {
+        assertLeaseEvidence(requirement, attempt, guard, message.state, to);
+        assertEvidence(requirement, attempt, guard, message.state, to);
+    }
+    return to;
+}
+function assertTransitionAuthorization(requirement, guard, message, to) {
+    const actions = [...requirement.actions];
+    if (requirement.evidence === "cancel_confirmed" && guard.attempt?.dispatch === "started") {
+        actions.push("settlement_report");
+    }
+    for (const action of actions) {
+        let scope;
+        if (action === "exchange_send") {
+            scope = { kind: "exchange", exchangeId: message.exchangeId };
+        }
+        else if (action === "exchange_cancel") {
+            scope = { kind: "message", exchangeId: message.exchangeId, messageId: message.messageId };
+        }
+        else if (action === "message_claim") {
+            scope = { kind: "destination", exchangeId: message.exchangeId, messageId: message.messageId, endpoint: message.to };
+        }
+        else {
+            if (guard.attempt === undefined || !Value.Check(DeliveryAttemptSchema, guard.attempt))
+                throw new TransitionEvidenceError(message.state, to, "a valid correlated delivery attempt is required");
+            scope = { kind: "attempt", exchangeId: message.exchangeId, messageId: message.messageId, attemptId: guard.attempt.attemptId, endpoint: message.to };
+        }
+        try {
+            assertAuthorized(guard.authorization, action, scope);
+        }
+        catch {
+            throw new TransitionEvidenceError(message.state, to, `scoped authorization required: ${action}`);
+        }
+    }
+}
+function assertAttemptCorrelation(requirement, message, to, guard) {
+    if (requirement.lease === "none")
+        return undefined;
+    const { attempt } = guard;
+    if (attempt === undefined) {
+        throw new TransitionEvidenceError(message.state, to, "a correlated delivery attempt is required");
+    }
+    if (!Value.Check(DeliveryAttemptSchema, attempt)) {
+        throw new TransitionEvidenceError(message.state, to, "invalid attempt record");
+    }
+    if (guard.reconciliation !== undefined && !Value.Check(ReconciliationEvidenceSchema, guard.reconciliation)) {
+        throw new TransitionEvidenceError(message.state, to, "invalid reconciliation record");
+    }
+    if (attempt.messageId !== message.messageId) {
+        throw new TransitionEvidenceError(message.state, to, `attempt ${attempt.attemptId} belongs to message ${attempt.messageId}, not ${message.messageId}`);
+    }
+    if (!deepEqual(attempt.endpoint, message.to)) {
+        throw new TransitionEvidenceError(message.state, to, `attempt ${attempt.attemptId} cites a different destination endpoint than message ${message.messageId}`);
+    }
+    if (guard.runtime !== undefined && (!Value.Check(RuntimeEvidenceSchema, guard.runtime) ||
+        guard.runtime.exchangeId !== message.exchangeId ||
+        guard.runtime.messageId !== message.messageId ||
+        guard.runtime.attemptId !== attempt.attemptId ||
+        !deepEqual(guard.runtime.endpoint, message.to) ||
+        Date.parse(guard.runtime.observedAt) > Date.parse(guard.now))) {
+        throw new TransitionEvidenceError(message.state, to, "uncorrelated or invalid runtime evidence");
+    }
+    if (guard.result !== undefined && (guard.result.exchangeId !== message.exchangeId ||
+        guard.result.messageId !== message.messageId ||
+        guard.result.attemptId !== attempt.attemptId ||
+        !deepEqual(guard.result.source, message.to))) {
+        throw new TransitionEvidenceError(message.state, to, "uncorrelated result evidence");
+    }
+    return attempt;
+}
+function assertLeaseEvidence(requirement, attempt, guard, from, to) {
+    if (!Value.Check(LeaseSchema, guard.lease)) {
+        throw new TransitionEvidenceError(from, to, "invalid guard lease");
+    }
+    if (requirement.lease === "current" || requirement.evidence === "not_attempted") {
+        if (guard.currentLease === undefined || !Value.Check(LeaseSchema, guard.currentLease) || !deepEqual(guard.currentLease, attempt.lease)) {
+            throw new TransitionEvidenceError(from, to, "attempt no longer holds the authoritative fenced claim");
+        }
+    }
+    if (!deepEqual(guard.lease, attempt.lease)) {
+        throw new TransitionEvidenceError(from, to, "guard lease does not match the lease recorded on the attempt");
+    }
+    if (requirement.lease === "current" && Date.parse(guard.now) >= Date.parse(attempt.lease.expiresAt)) {
+        throw new TransitionEvidenceError(from, to, "lease is expired for this mutation");
+    }
+}
+function assertEvidence(requirement, attempt, guard, from, to) {
+    const reject = (reason) => {
+        throw new TransitionEvidenceError(from, to, reason);
+    };
+    switch (requirement.evidence) {
+        case "none":
+            return;
+        case "not_attempted":
+            if (attempt.dispatch !== "not_attempted" || attempt.transport !== "pending") {
+                reject(`safe requeue/release requires a pending not-attempted record, found (${attempt.dispatch}, ${attempt.transport})`);
+            }
+            return;
+        case "dispatch_started":
+            if (attempt.dispatch !== "started") {
+                reject(`entering DISPATCHING requires the durable dispatch-start marker, found "${attempt.dispatch}"`);
+            }
+            return;
+        case "transport_delivered":
+            if (attempt.dispatch !== "started" || attempt.transport !== "delivered" || guard.runtime?.outcome !== "accepted") {
+                reject("acceptance requires both transport delivery and correlated runtime acceptance evidence");
+            }
+            return;
+        case "transport_ambiguous":
+            if (attempt.dispatch !== "started" || attempt.transport !== "ambiguous") {
+                reject(`quarantine requires a started attempt with transport "ambiguous", found (${attempt.dispatch}, ${attempt.transport})`);
+            }
+            return;
+        case "transport_failed":
+            if (attempt.dispatch !== "started" || attempt.transport !== "failed") {
+                reject(`definitive failure requires a started attempt with transport "failed", found (${attempt.dispatch}, ${attempt.transport})`);
+            }
+            return;
+        case "runtime_progress":
+            if (attempt.dispatch !== "started" || attempt.transport !== "delivered" || guard.runtime === undefined) {
+                reject("runtime progress requires a delivered attempt and correlated runtime evidence");
+            }
+            if (to === "RUNNING" ? guard.runtime?.outcome !== "running" : !isSettlement(guard.runtime?.outcome)) {
+                reject("runtime evidence does not prove the requested state");
+            }
+            return;
+        case "result_published":
+            if (attempt.dispatch !== "started" || attempt.transport !== "delivered" || guard.result === undefined) {
+                reject("availability requires a delivered attempt and correlated immutable published result");
+            }
+            if (guard.result !== undefined)
+                assertResultShape(guard.result);
+            return;
+        case "cancel_confirmed":
+            if (attempt.dispatch === "not_attempted" && attempt.transport === "pending")
+                return;
+            if (attempt.dispatch !== "started" || attempt.transport !== "delivered" || guard.runtime?.outcome !== "cancelled") {
+                reject("cancellation requires no-attempt proof or correlated runtime cancellation confirmation");
+            }
+            return;
+        case "reconciled_delivered":
+            if (guard.reconciliation === undefined) {
+                reject("late correlated acceptance requires explicit reconciliation evidence, not lease reuse");
+            }
+            if (attempt.dispatch !== "started" || attempt.transport !== "delivered" || guard.runtime?.outcome !== "accepted") {
+                reject("reconciled acceptance requires transport delivery and correlated runtime acceptance");
+            }
+            return;
+        case "reconciled_not_executed":
+            if (guard.reconciliation === undefined) {
+                reject("confirming non-execution requires explicit reconciliation evidence, not lease reuse");
+            }
+            if (attempt.transport !== "failed") {
+                reject(`reconciled non-execution requires transport "failed", found "${attempt.transport}"`);
+            }
+            return;
+    }
+}
+export class ExchangeDispositionError extends Error {
+    code = "EXCHANGE_DISPOSITION_REJECTED";
+    constructor(detail) {
+        super(`administrative disposition rejected: ${detail}`);
+        this.name = "ExchangeDispositionError";
+    }
+}
+/** Admission precondition for the future host's every protocol mutation. */
+export function assertExchangeActive(exchange, disposition) {
+    assertNotArchived(exchange.exchangeId, disposition);
+    if (exchange.state !== "OPEN")
+        throw new ExchangeDispositionError("exchange is closed");
+}
+function assertNotArchived(exchangeId, disposition) {
+    if (disposition === undefined)
+        return;
+    assertDispositionShape(disposition);
+    if (disposition.exchangeId !== exchangeId)
+        throw new ExchangeDispositionError("foreign disposition guard");
+    throw new ExchangeDispositionError("ABANDONED_UNRESOLVED prohibits further protocol activity");
+}
+/**
+ * Administrative termination, NOT runtime cancellation or normal CLOSED.
+ * The authenticated host must load the complete message set, each current
+ * unresolved attempt, and any existing disposition and commit atomically.
+ * Owner/reconciliation text records intent only; unknown facts are unchanged.
+ */
+export function archiveUnresolvedExchange(exchange, messages, attempts, intent, authorization, existing) {
+    const reject = (detail) => { throw new ExchangeDispositionError(detail); };
+    try {
+        assertAuthorized(authorization, "exchange_archive", { kind: "owner", exchangeId: exchange.exchangeId, ownerId: intent.ownerId });
+    }
+    catch {
+        reject("scoped administrative owner authorization is required");
+    }
+    if (!Value.Check(ExchangeSchema, exchange) || exchange.state !== "OPEN")
+        reject("exchange must be open");
+    const seenMessages = new Set();
+    for (const message of messages) {
+        if (!Value.Check(MessageSchema, message) || message.exchangeId !== exchange.exchangeId)
+            reject("invalid or foreign message");
+        if (seenMessages.has(message.messageId))
+            reject("duplicate message");
+        seenMessages.add(message.messageId);
+        if (message.state !== "DELIVERY_UNKNOWN" && !FINISHED_MESSAGE_STATES.includes(message.state))
+            reject("in-flight activity must first be reconciled or quarantined");
+    }
+    const unresolvedMessages = messages.filter((message) => message.state === "DELIVERY_UNKNOWN");
+    if (unresolvedMessages.length === 0 || attempts.length !== unresolvedMessages.length)
+        reject("one active attempt per unresolved message is required");
+    const seenAttempts = new Set();
+    const seenAttemptMessages = new Set();
+    for (const attempt of attempts) {
+        if (!Value.Check(DeliveryAttemptSchema, attempt))
+            reject("invalid active attempt");
+        const message = unresolvedMessages.find((entry) => entry.messageId === attempt.messageId);
+        if (message === undefined || !deepEqual(message.to, attempt.endpoint))
+            reject("uncorrelated active attempt");
+        if (attempt.dispatch !== "started" || attempt.transport !== "ambiguous")
+            reject("original unknown/ambiguous evidence is required");
+        if (seenAttempts.has(attempt.attemptId) || seenAttemptMessages.has(attempt.messageId))
+            reject("duplicate active attempt");
+        seenAttempts.add(attempt.attemptId);
+        seenAttemptMessages.add(attempt.messageId);
+    }
+    const candidate = {
+        ...intent,
+        exchangeId: exchange.exchangeId,
+        status: "ABANDONED_UNRESOLVED",
+        unresolved: [...unresolvedMessages].sort((a, b) => a.messageId.localeCompare(b.messageId)).map((message) => ({
+            messageId: message.messageId,
+            originalState: "DELIVERY_UNKNOWN",
+            transport: "ambiguous",
+            unresolvedSideEffects: true,
+            attempt: attempts.find((attempt) => attempt.messageId === message.messageId),
+        })),
+    };
+    assertDispositionShape(candidate);
+    const recordedAt = Date.parse(candidate.recordedAt);
+    if (Date.parse(exchange.createdAt) > recordedAt || messages.some((message) => Date.parse(message.createdAt) > recordedAt))
+        reject("disposition predates the aggregate");
+    if (existing !== undefined) {
+        assertDispositionShape(existing);
+        if (!deepEqual(existing, candidate))
+            reject("immutable disposition conflicts with existing history");
+    }
+    return deepFreeze(clone(existing ?? candidate));
+}
+function assertDispositionShape(disposition) {
+    try {
+        canonicalDigest(disposition);
+    }
+    catch {
+        throw new ExchangeDispositionError("disposition must be plain JSON");
+    }
+    if (!Value.Check(ExchangeDispositionSchema, disposition))
+        throw new ExchangeDispositionError("invalid disposition schema");
+    const seenMessages = new Set();
+    const seenAttempts = new Set();
+    for (const entry of disposition.unresolved) {
+        if (entry.attempt.messageId !== entry.messageId || entry.attempt.dispatch !== "started" || entry.attempt.transport !== "ambiguous" || seenMessages.has(entry.messageId) || seenAttempts.has(entry.attempt.attemptId)) {
+            throw new ExchangeDispositionError("invalid original unresolved snapshot");
+        }
+        if (Date.parse(entry.attempt.createdAt) > Date.parse(disposition.recordedAt))
+            throw new ExchangeDispositionError("disposition predates the attempt");
+        seenMessages.add(entry.messageId);
+        seenAttempts.add(entry.attempt.attemptId);
+    }
+    if (Date.parse(disposition.reconciliation.resolvedAt) > Date.parse(disposition.recordedAt))
+        throw new ExchangeDispositionError("future reconciliation metadata");
+}
+/**
+ * Explicitly close an open exchange with a scoped owner close grant,
+ * and only when EVERY message of the exchange is finished
+ * (RESULT_AVAILABLE / CANCELLED / FAILED): nothing in flight, nothing
+ * quarantined, no pending cancellation. Reading results never contributes to
+ * closability. Returns a new closed exchange; the input is not mutated.
+ */
+export function closeExchange(exchange, messages, authorization, disposition) {
+    assertNotArchived(exchange.exchangeId, disposition);
+    try {
+        assertAuthorized(authorization, "exchange_close", { kind: "owner", exchangeId: exchange.exchangeId, ownerId: authorization?.principalId });
+    }
+    catch {
+        throw new CloseRejectedError("scoped owner close authorization is required");
+    }
+    if (exchange.state !== "OPEN") {
+        throw new CloseRejectedError(`exchange ${exchange.exchangeId} is already ${exchange.state}`);
+    }
+    for (const message of messages) {
+        if (message.exchangeId !== exchange.exchangeId) {
+            throw new CloseRejectedError(`message ${message.messageId} belongs to exchange ${message.exchangeId}, not ${exchange.exchangeId}`);
+        }
+        if (!FINISHED_MESSAGE_STATES.includes(message.state)) {
+            throw new CloseRejectedError(`message ${message.messageId} is still ${message.state}`);
+        }
+    }
+    return { ...exchange, state: "CLOSED" };
+}
+/**
+ * Read a Result: a non-mutating, repeatable observation. Returns a deeply
+ * frozen snapshot; the input is never modified and no lifecycle state
+ * changes anywhere. Reads are not consumption.
+ */
+export function readResult(result) {
+    assertResultShape(result);
+    return deepFreeze(clone(result));
+}
+/**
+ * Publish-once contract for the immutable Result: the first publication is
+ * accepted, an exactly equal republication is replayed, and any different
+ * content for the same result id is a conflict. Never mutates inputs.
+ */
+export function assertResultPublication(existing, candidate, authorization, disposition) {
+    assertNotArchived(candidate.exchangeId, disposition);
+    assertResultShape(candidate);
+    assertAuthorized(authorization, "result_publish", {
+        kind: "attempt", exchangeId: candidate.exchangeId, messageId: candidate.messageId,
+        attemptId: candidate.attemptId, endpoint: candidate.source,
+    });
+    if (existing === undefined) {
+        return deepFreeze(clone(candidate));
+    }
+    assertResultShape(existing);
+    if (!deepEqual(existing, candidate)) {
+        throw new ResultConflictError(candidate.resultId);
+    }
+    return deepFreeze(clone(existing));
+}
+function isSettlement(outcome) {
+    return outcome !== undefined && ["settled", "runtime_error", "cancelled", "interrupted"].includes(outcome);
+}
+function assertResultShape(result) {
+    try {
+        // Wire evidence is opaque JSON, not arbitrary mutable JavaScript objects.
+        canonicalDigest(result);
+    }
+    catch {
+        throw new InvalidResultError("result must contain only finite, acyclic plain JSON data");
+    }
+    if (!isSettlement(result.runtime)) {
+        throw new InvalidResultError("result requires settlement-grade runtime evidence");
+    }
+    if (!Value.Check(ResultSchema, result)) {
+        const errors = [...Value.Errors(ResultSchema, result)];
+        const first = errors[0];
+        throw new InvalidResultError(first ? `${first.path}: ${first.message}` : "unknown violation");
+    }
+}
+function clone(value) {
+    if (Array.isArray(value) || (typeof value === "object" && value !== null)) {
+        return structuredClone(value);
+    }
+    return value;
+}
+function deepFreeze(value) {
+    if (Array.isArray(value) || (typeof value === "object" && value !== null)) {
+        for (const key of Reflect.ownKeys(value)) {
+            const child = value[key];
+            if (child !== null && typeof child === "object")
+                deepFreeze(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+        return false;
+    }
+    const aKeys = Reflect.ownKeys(a);
+    const bKeys = Reflect.ownKeys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!Reflect.has(b, key))
+            return false;
+        if (!deepEqual(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=rules.js.map

package/dist/endpoints/pi/contract.js

@@ -0,0 +1,2 @@
+export const PI_ADAPTER_KIND = "pi";
+//# sourceMappingURL=contract.js.map

package/dist/endpoints/pi/session-host.js

@@ -0,0 +1,39 @@
+/**
+ * CE-0002 B3-P3B — Pi-type-free host integration seam (compatibility surface).
+ *
+ * HANDOFF-853274 moved the endpoint-neutral host authority chain into
+ * `src/host/endpoint-host.ts` without changing it. This module keeps the
+ * original Pi import path, names, and policy shape:
+ *
+ * - `CeSessionHost` is the shared host fixed to the Pi adapter. Its constructor
+ *   still refuses a non-Pi adapter and an empty `piSessionId` exactly as before.
+ * - Pi session ids remain untrusted lookup labels; they authorize nothing.
+ * - Lease lifecycle (`renew`, `end`) and `requireUnowned` exist on the shared
+ *   host but are opt-in; the Pi extension does not call them, so Pi Session
+ *   binding, restart recovery (`resume`), and lease-expiry fail-closed behavior
+ *   are unchanged.
+ * - Cross-adapter recipients are available only when the operator lists them
+ *   explicitly in `recipients`; without that list Pi sends exactly as before.
+ * - No automatic takeover recovery: expired Pi authority still fails closed; the
+ *   separate operator-only recovery caller is not reachable from this wrapper.
+ */
+import { PI_ADAPTER_KIND } from "./contract.js";
+import { CeEndpointHost, CeHostRefusal, } from "../../host/endpoint-host.js";
+export { CeHostRefusal, } from "../../host/endpoint-host.js";
+/**
+ * The trusted Pi host adapter. One instance per Pi process; one authority row
+ * per allowlisted Endpoint.
+ */
+export class CeSessionHost extends CeEndpointHost {
+    constructor(store, policy) {
+        if (policy.adapter !== PI_ADAPTER_KIND)
+            throw new CeHostRefusal("CE_HOST_INVALID_REQUEST");
+        for (const entry of policy.allowlist) {
+            if (typeof entry.piSessionId !== "string" || entry.piSessionId.length === 0) {
+                throw new CeHostRefusal("CE_HOST_INVALID_REQUEST");
+            }
+        }
+        super(store, policy);
+    }
+}
+//# sourceMappingURL=session-host.js.map