@emilia-protocol/gate 0.11.0 → 0.14.0

package/src/protocol-state.ts

@@ -0,0 +1,143 @@
+/**
+ * EP Protocol-State — brand-typed handshake lifecycle (GAP-4).
+ *
+ * Purpose: make an ILLEGAL protocol-state transition a COMPILE error, not a
+ * runtime failure. Each lifecycle state is a distinct nominal (branded) type,
+ * and every transition is a function whose parameter type admits ONLY its legal
+ * predecessor state(s) and whose return type is exactly its legal successor.
+ * Passing the wrong state to a transition (e.g. `consume(initiated)` — consuming
+ * before verification) is rejected by `tsc` before the code ever runs.
+ *
+ * ── Source of truth ─────────────────────────────────────────────────────────
+ * The state graph mirrors the formally-verified model, not a toy:
+ *   formal/ep_handshake.tla   — abstract lifecycle + transition guards
+ *   lib/handshake/invariants.js (HANDSHAKE_STATUSES) — the 6 persisted statuses
+ *   lib/handshake/create.js    — status:'initiated'          (T1 Initiate)
+ *   lib/handshake/present.js   — initiated → pending_verification (T2 Present)
+ *   lib/handshake/verify.js    — outcome accepted/rejected/expired (T3/T4/T7)
+ *   lib/handshake/consume.js   — verified → consumed            (T5 Consume)
+ *   lib/handshake/finalize.js  — → revoked                       (T6 Revoke)
+ *
+ * ── States (TLA `state` domain) ─────────────────────────────────────────────
+ *   none | initiated | pending_verification | verified
+ *   | rejected | expired | revoked | consumed
+ *
+ * Two of these are ABSTRACT lifecycle states, not DB status values:
+ *   - `none`     : pre-initiation. There is no persisted row yet.
+ *   - `consumed` : a verified handshake that has an entry in the
+ *                  `handshake_consumptions` table. Consumption does NOT rewrite
+ *                  `handshakes.status` (it stays 'verified'); it is recorded
+ *                  atomically in a side table by `consume_handshake_atomic`.
+ *                  The TLA model abstracts (status='verified' ∧ h∈consumptions)
+ *                  as the distinct terminal state `consumed`. This module keeps
+ *                  that abstraction so "consume-once" and "no-verify-after-consume"
+ *                  are expressible in the type system.
+ *
+ * The other six are exactly `HANDSHAKE_STATUSES` from invariants.js and carry a
+ * `dbStatus` field equal to the persisted `handshakes.status` value.
+ *
+ * ── Legal transition graph (the ONLY edges; everything else is a type error) ─
+ *   genesis()                                        -> None
+ *   initiate(None)                                   -> Initiated
+ *   present(Initiated)                               -> PendingVerification
+ *   verifyAccept(PendingVerification)                -> Verified
+ *   verifyReject(PendingVerification)                -> Rejected      (terminal)
+ *   consume(Verified)                                -> Consumed      (terminal)
+ *   revoke(Initiated|PendingVerification|Verified)   -> Revoked       (terminal)
+ *   expire(Initiated|PendingVerification|Verified)   -> Expired       (terminal)
+ *
+ * Terminal states (Rejected, Expired, Revoked, Consumed) are accepted by NO
+ * transition function, so any move out of a terminal state is a compile error.
+ *
+ * Branding note: each state is nominally distinguished by a private, readonly
+ * string-literal `tag`. Distinct tags make each state a distinct type, so no
+ * legal predecessor of one transition is accidentally assignable to another.
+ * The runtime value literally is `{ tag, dbStatus }`; there is no phantom-only
+ * field, so no casts are needed and the runtime and the types cannot drift.
+ *
+ * This module is intentionally free of I/O. It is the compile-time spine that
+ * the runtime state machine (verify.js / consume.js / finalize.js) is expected
+ * to obey; it does not replace those code paths' own DB-level guards.
+ *
+ * @license Apache-2.0
+ */
+
+/**
+ * The six persisted `handshakes.status` values (single source: invariants.js
+ * HANDSHAKE_STATUSES). `none` and `consumed` are abstract and have no row status.
+ */
+export type DbHandshakeStatus = 'initiated' | 'pending_verification' | 'verified' | 'rejected' | 'expired' | 'revoked';
+
+/** Pre-initiation. No persisted handshake exists yet. */
+export type None = { readonly tag: 'none'; readonly dbStatus: null };
+/** A handshake row was created (T1). DB status 'initiated'. */
+export type Initiated = { readonly tag: 'initiated'; readonly dbStatus: 'initiated' };
+/** A presentation was added and verification is pending (T2). DB 'pending_verification'. */
+export type PendingVerification = { readonly tag: 'pending_verification'; readonly dbStatus: 'pending_verification' };
+/** Verification accepted (T3). DB 'verified'. Only state from which consume is legal. */
+export type Verified = { readonly tag: 'verified'; readonly dbStatus: 'verified' };
+/** Verification rejected (T4). Terminal. DB 'rejected'. */
+export type Rejected = { readonly tag: 'rejected'; readonly dbStatus: 'rejected' };
+/** Binding expired (T7). Terminal. DB 'expired'. */
+export type Expired = { readonly tag: 'expired'; readonly dbStatus: 'expired' };
+/** Revoked by a party (T6). Terminal. DB 'revoked'. */
+export type Revoked = { readonly tag: 'revoked'; readonly dbStatus: 'revoked' };
+/**
+ * Consumed exactly once (T5). Terminal abstract state; the row keeps DB status
+ * 'verified' and gains a `handshake_consumptions` record.
+ */
+export type Consumed = { readonly tag: 'consumed'; readonly dbStatus: 'verified' };
+
+/** Any state in the lifecycle. */
+export type ProtocolState = None | Initiated | PendingVerification | Verified | Rejected | Expired | Revoked | Consumed;
+/** States a still-active handshake can be revoked or expired from (T6/T7 domain). */
+export type Active = Initiated | PendingVerification | Verified;
+
+/** T0: genesis — the empty pre-initiation state. */
+export function genesis(): None {
+  return { tag: 'none', dbStatus: null };
+}
+
+/** T1 Initiate: none -> initiated. Maps to create.js status:'initiated'. */
+export function initiate(_s: None): Initiated {
+  return { tag: 'initiated', dbStatus: 'initiated' };
+}
+
+/** T2 Present: initiated -> pending_verification. Maps to present.js. */
+export function present(_s: Initiated): PendingVerification {
+  return { tag: 'pending_verification', dbStatus: 'pending_verification' };
+}
+
+/** T3 VerifyAccept: pending_verification -> verified. verify.js outcome='accepted'. */
+export function verifyAccept(_s: PendingVerification): Verified {
+  return { tag: 'verified', dbStatus: 'verified' };
+}
+
+/** T4 VerifyReject: pending_verification -> rejected (terminal). verify.js outcome='rejected'. */
+export function verifyReject(_s: PendingVerification): Rejected {
+  return { tag: 'rejected', dbStatus: 'rejected' };
+}
+
+/**
+ * T5 Consume: verified -> consumed (terminal). consume.js requires 'verified' state
+ * and enforces consume-once at the DB level.
+ */
+export function consume(_s: Verified): Consumed {
+  return { tag: 'consumed', dbStatus: 'verified' };
+}
+
+/**
+ * T6 Revoke: {initiated|pending_verification|verified} -> revoked (terminal).
+ * finalize.js. Legal only from an active (pre-terminal) state.
+ */
+export function revoke(_s: Active): Revoked {
+  return { tag: 'revoked', dbStatus: 'revoked' };
+}
+
+/**
+ * T7 Expire: {initiated|pending_verification|verified} -> expired (terminal).
+ * verify.js outcome='expired'. Legal only from an active (pre-terminal) state.
+ */
+export function expire(_s: Active): Expired {
+  return { tag: 'expired', dbStatus: 'expired' };
+}

package/src/protocol-state.typecheck.ts

@@ -0,0 +1,94 @@
+/**
+ * EP Protocol-State — TYPE-LEVEL conformance test (GAP-4).
+ *
+ * This file is checked by `tsc` under tsconfig.core.json, not run as a unit
+ * test. It asserts, at compile time, that the ONLY legal transitions of the
+ * handshake lifecycle are the ones the formal model permits:
+ *
+ *   - The "legal sequences" section MUST type-check with no errors.
+ *   - Every `// @ts-expect-error` line guards a transition that MUST be illegal.
+ *     If any such transition ever becomes legal (a regression in the brand
+ *     types), tsc reports the `@ts-expect-error` as UNUSED and the type-gate
+ *     fails. This is the tripwire.
+ *
+ * These are type-only assertions; the functions are pure and the file is safe
+ * to load, but nothing here is intended to run.
+ *
+ * @license Apache-2.0
+ */
+
+import {
+  genesis, initiate, present, verifyAccept, verifyReject, consume, revoke, expire,
+} from './protocol-state.js';
+
+/* eslint-disable no-unused-vars */
+
+// ── LEGAL SEQUENCES (must compile) ──────────────────────────────────────────
+
+// Full happy path: none → initiated → pending_verification → verified → consumed
+const _consumed = consume(verifyAccept(present(initiate(genesis()))));
+
+// Reject branch: … → pending_verification → rejected
+const _rejected = verifyReject(present(initiate(genesis())));
+
+// Revoke is legal from every active (pre-terminal) state:
+const _revokedFromInitiated = revoke(initiate(genesis()));
+const _revokedFromPending = revoke(present(initiate(genesis())));
+const _revokedFromVerified = revoke(verifyAccept(present(initiate(genesis()))));
+
+// Expire is legal from every active (pre-terminal) state:
+const _expiredFromInitiated = expire(initiate(genesis()));
+const _expiredFromPending = expire(present(initiate(genesis())));
+const _expiredFromVerified = expire(verifyAccept(present(initiate(genesis()))));
+
+// Convenience handles to well-typed states for the illegal section below.
+const none = genesis();
+const initiated = initiate(none);
+const pending = present(initiated);
+const verified = verifyAccept(pending);
+const consumedState = consume(verified);
+const revokedState = revoke(initiated);
+const rejectedState = verifyReject(pending);
+const expiredState = expire(initiated);
+
+// ── ILLEGAL TRANSITIONS (each MUST be a type error) ─────────────────────────
+
+// Consume before verification — the canonical GAP-4 violation.
+// @ts-expect-error consume requires Verified, not None
+consume(none);
+// @ts-expect-error consume requires Verified, not Initiated
+consume(initiated);
+// @ts-expect-error consume requires Verified, not PendingVerification
+consume(pending);
+
+// Skipping the presentation step (initiated → verified directly).
+// @ts-expect-error verifyAccept requires PendingVerification, not Initiated
+verifyAccept(initiated);
+// @ts-expect-error verifyReject requires PendingVerification, not Initiated
+verifyReject(initiated);
+
+// Presenting after the handshake already left the initiated state.
+// @ts-expect-error present requires Initiated, not PendingVerification
+present(pending);
+// @ts-expect-error present requires Initiated, not Verified
+present(verified);
+
+// Re-initiating something that already exists.
+// @ts-expect-error initiate requires None, not Verified
+initiate(verified);
+
+// No transition may leave a TERMINAL state (consumed/revoked/rejected/expired).
+// @ts-expect-error cannot consume a Consumed handshake (consume-once)
+consume(consumedState);
+// @ts-expect-error cannot revoke a Consumed handshake
+revoke(consumedState);
+// @ts-expect-error cannot expire a Consumed handshake
+expire(consumedState);
+// @ts-expect-error cannot verify a Revoked handshake
+verifyAccept(revokedState);
+// @ts-expect-error cannot revoke an already-Revoked handshake
+revoke(revokedState);
+// @ts-expect-error cannot consume a Rejected handshake
+consume(rejectedState);
+// @ts-expect-error cannot revoke an Expired handshake
+revoke(expiredState);