instar 1.3.90 → 1.3.92

package/dist/core/SessionOwnershipRegistry.js

@@ -0,0 +1,128 @@
+/**
+ * SessionOwnershipRegistry — the distributed per-session ownership registry
+ * (Multi-Machine Session Pool §L3). Holds a SessionOwnershipRecord per session;
+ * answers "which machine holds session X"; and mutates ownership via a per-session
+ * CAS at `ownershipEpoch+1`, reusing the §L−1 single-ref fast-forward discipline
+ * (the same pattern as GitLeaseStore/LeaseCoordinator) but at per-session
+ * granularity — thousands of independent CAS points, one ref-file per session.
+ *
+ * The dangerous parts (CAS contention, per-session replay) are driven through
+ * injected seams so they are unit-testable with in-memory fakes:
+ *  - `store` — the durable CAS substrate (git single-ref fast-forward push per
+ *    session). `casWrite(candidate)` returns ok:true if the candidate landed
+ *    (fast-forwarded from the current epoch), or ok:false + the freshly-observed
+ *    record after a reject+reread (a peer won the race). MUST NOT force-push.
+ *  - `seenNonce`/`recordNonce` — the per-session-scoped replay guard
+ *    (keyed on {sessionKey, sender, epoch} — see SessionOwnership.ownershipNonceKey).
+ *
+ * The FSM (legal transitions, run-fence, output-exclusion) lives in
+ * SessionOwnership.ts; this module enforces the CAS + replay + retry-backoff +
+ * lifecycle around it.
+ */
+import { applyOwnershipAction, ownershipNonceKey, } from './SessionOwnership.js';
+/**
+ * In-memory per-session ownership store with fast-forward CAS — correct for a
+ * single machine (no cross-machine contention) and for the dark v0.1 state.
+ * The CROSS-MACHINE durable store (git single-ref-per-session push, mirroring
+ * GitLeaseStore) swaps in for the Track-H real-hardware proof; the registry/FSM/
+ * CAS logic above is store-agnostic. A candidate lands only if it fast-forwards
+ * from the current epoch (`candidate.ownershipEpoch === current.epoch + 1`).
+ */
+export class InMemorySessionOwnershipStore {
+    recs = new Map();
+    read(sessionKey) {
+        return this.recs.get(sessionKey) ?? null;
+    }
+    casWrite(candidate) {
+        const current = this.recs.get(candidate.sessionKey) ?? null;
+        const curEpoch = current?.ownershipEpoch ?? 0;
+        if (candidate.ownershipEpoch === curEpoch + 1) {
+            this.recs.set(candidate.sessionKey, candidate);
+            return { ok: true, observed: candidate };
+        }
+        return { ok: false, observed: current };
+    }
+    all() {
+        return [...this.recs.values()];
+    }
+}
+export class SessionOwnershipRegistry {
+    d;
+    casConflicts = 0;
+    casRetryExhaustions = 0;
+    constructor(deps) {
+        this.d = deps;
+    }
+    now() {
+        return (this.d.now ?? Date.now)();
+    }
+    read(sessionKey) {
+        return this.d.store.read(sessionKey);
+    }
+    /** The current owner machine of a session (null if none / released). */
+    ownerOf(sessionKey) {
+        const r = this.d.store.read(sessionKey);
+        if (!r || r.status === 'released')
+            return null;
+        return r.ownerMachineId;
+    }
+    /**
+     * The machine the router last assigned for a session (§L4 RBAC `claim` check):
+     * the placed-owner while `placing`, or the transfer target while `transferring`.
+     */
+    placementTargetOf(sessionKey) {
+        const r = this.d.store.read(sessionKey);
+        if (!r)
+            return null;
+        if (r.status === 'placing')
+            return r.ownerMachineId;
+        if (r.status === 'transferring')
+            return r.transferTo ?? null;
+        return null;
+    }
+    /**
+     * Apply an ownership action via CAS (§L3). Runs the FSM transition, the
+     * per-session replay check, then the durable fast-forward CAS. On a lost CAS
+     * (a peer advanced the epoch first) returns `cas-lost` + the observed record —
+     * the caller backs off (ownershipCasRetryBackoffMs) or stands down. The nonce
+     * is recorded ONLY on a landed CAS (a rejected attempt never burns a nonce).
+     */
+    cas(action, ctx) {
+        const current = this.d.store.read(ctx.sessionKey);
+        const t = applyOwnershipAction(current, action, { sessionKey: ctx.sessionKey, nonce: ctx.nonce, now: this.now() });
+        if (!t.ok)
+            return { ok: false, reason: t.reason, observed: current };
+        const nkey = ownershipNonceKey(ctx.sessionKey, ctx.sender, t.next.ownershipEpoch, ctx.nonce);
+        if (this.d.seenNonce(nkey))
+            return { ok: false, reason: 'replayed-nonce', observed: current };
+        const res = this.d.store.casWrite(t.next);
+        if (!res.ok) {
+            this.casConflicts++;
+            this.d.logger?.(`[ownership] CAS lost for ${ctx.sessionKey} → observed epoch ${res.observed?.ownershipEpoch ?? 0}`);
+            return { ok: false, reason: 'cas-lost', observed: res.observed };
+        }
+        this.d.recordNonce(nkey);
+        return { ok: true, record: t.next };
+    }
+    /** Observability counters (spec §L3: /pool ownership.casConflicts/casRetryExhaustions). */
+    noteRetryExhaustion() {
+        this.casRetryExhaustions++;
+    }
+    metrics() {
+        return { casConflicts: this.casConflicts, casRetryExhaustions: this.casRetryExhaustions };
+    }
+}
+/**
+ * Exponential-jitter retry delay for a lost CAS (spec §L3): `ownershipCasRetryBackoffMs`
+ * 50→500ms, biased so the lowest-machineId contender retries first (a client-side
+ * ordering hint ONLY — never the CAS arbiter; the remote ref-update decides the winner).
+ */
+export function ownershipRetryDelayMs(retryCount, selfMachineId, contenderMachineId, opts = {}) {
+    const base = opts.baseMs ?? 50;
+    const max = opts.maxMs ?? 500;
+    const backoff = Math.min(max, base * 2 ** Math.max(0, retryCount - 1));
+    // Lowest machineId retries first (shorter delay) — ordering hint, not arbitration.
+    const yieldBias = selfMachineId > contenderMachineId ? backoff : Math.floor(backoff / 2);
+    return Math.min(max, yieldBias);
+}
+//# sourceMappingURL=SessionOwnershipRegistry.js.map

package/dist/core/SessionOwnershipRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionOwnershipRegistry.js","sourceRoot":"","sources":["../../src/core/SessionOwnershipRegistry.ts"],"names":[],"mappings":"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"}

package/dist/core/SessionPoolE2EResultStore.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SessionPoolE2EResultStore — the durable, signed, append-only record of each
+ * rollout stage's Tier-3 E2E outcome (Multi-Machine Session Pool §Rollout). It is
+ * the mechanical evidence the StageAdvancer gates on: a stage does NOT activate
+ * until its prior stage's E2E recorded `green` for the current commit. Per
+ * "Structure > Willpower" the gate is grounded in this implemented record, not a
+ * human's say-so.
+ *
+ * Append-only + signed (tamper-evident, AuditTrail-style): a reversion or a new run
+ * APPENDS a row, NEVER overwrites a prior one, so the full green/red history per
+ * commit is preserved. The Tier-3 E2E harness is the ONLY writer (`recordResult`).
+ */
+export type StageE2EOutcome = 'green' | 'red';
+export interface StageE2EResult {
+    stage: number;
+    result: StageE2EOutcome;
+    commitSha: string;
+    ranAt: string;
+    evidenceRef: string;
+    signature: string;
+}
+export interface SessionPoolE2EResultStoreDeps {
+    /** Absolute path to the append-only results file. */
+    filePath: string;
+    /** Sign the canonical (signature-excluded) row. Production: HMAC/Ed25519 over a state secret. */
+    sign: (canonical: string) => string;
+    /** Verify a signature against the canonical row. */
+    verifySig: (canonical: string, signature: string) => boolean;
+    now?: () => number;
+}
+/** Canonical bytes a row's signature covers — field-ordered, signature EXCLUDED. */
+export declare function canonicalE2ERow(r: Omit<StageE2EResult, 'signature'>): string;
+export declare class SessionPoolE2EResultStore {
+    private readonly d;
+    constructor(deps: SessionPoolE2EResultStoreDeps);
+    /** Append a signed result row. The ONLY writer (called by the Tier-3 E2E harness). */
+    recordResult(stage: number, result: StageE2EOutcome, commitSha: string, evidenceRef: string): StageE2EResult;
+    /** All rows (oldest→newest). Tolerant of a missing file / a torn trailing line. */
+    all(): StageE2EResult[];
+    /** The MOST RECENT row for a stage (a later `red` supersedes an earlier `green`). */
+    getLatestForStage(stage: number): StageE2EResult | null;
+    /** Verify a row's signature (tamper check). */
+    verify(row: StageE2EResult): boolean;
+}
+//# sourceMappingURL=SessionPoolE2EResultStore.d.ts.map

package/dist/core/SessionPoolE2EResultStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionPoolE2EResultStore.d.ts","sourceRoot":"","sources":["../../src/core/SessionPoolE2EResultStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,KAAK,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,6BAA6B;IAC5C,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,oDAAoD;IACpD,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,MAAM,CAE5E;AAED,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAgC;gBACtC,IAAI,EAAE,6BAA6B;IAI/C,sFAAsF;IACtF,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc;IAS5G,mFAAmF;IACnF,GAAG,IAAI,cAAc,EAAE;IAWvB,qFAAqF;IACrF,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAMvD,+CAA+C;IAC/C,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO;CAGrC"}

package/dist/core/SessionPoolE2EResultStore.js

@@ -0,0 +1,66 @@
+/**
+ * SessionPoolE2EResultStore — the durable, signed, append-only record of each
+ * rollout stage's Tier-3 E2E outcome (Multi-Machine Session Pool §Rollout). It is
+ * the mechanical evidence the StageAdvancer gates on: a stage does NOT activate
+ * until its prior stage's E2E recorded `green` for the current commit. Per
+ * "Structure > Willpower" the gate is grounded in this implemented record, not a
+ * human's say-so.
+ *
+ * Append-only + signed (tamper-evident, AuditTrail-style): a reversion or a new run
+ * APPENDS a row, NEVER overwrites a prior one, so the full green/red history per
+ * commit is preserved. The Tier-3 E2E harness is the ONLY writer (`recordResult`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Canonical bytes a row's signature covers — field-ordered, signature EXCLUDED. */
+export function canonicalE2ERow(r) {
+    return JSON.stringify([r.stage, r.result, r.commitSha, r.ranAt, r.evidenceRef]);
+}
+export class SessionPoolE2EResultStore {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    /** Append a signed result row. The ONLY writer (called by the Tier-3 E2E harness). */
+    recordResult(stage, result, commitSha, evidenceRef) {
+        const ranAt = new Date(this.d.now ? this.d.now() : Date.now()).toISOString();
+        const unsigned = { stage, result, commitSha, ranAt, evidenceRef };
+        const row = { ...unsigned, signature: this.d.sign(canonicalE2ERow(unsigned)) };
+        fs.mkdirSync(path.dirname(this.d.filePath), { recursive: true });
+        fs.appendFileSync(this.d.filePath, JSON.stringify(row) + '\n');
+        return row;
+    }
+    /** All rows (oldest→newest). Tolerant of a missing file / a torn trailing line. */
+    all() {
+        let content;
+        try {
+            content = fs.readFileSync(this.d.filePath, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip a torn line */ }
+        }
+        return out;
+    }
+    /** The MOST RECENT row for a stage (a later `red` supersedes an earlier `green`). */
+    getLatestForStage(stage) {
+        let latest = null;
+        for (const r of this.all())
+            if (r.stage === stage)
+                latest = r;
+        return latest;
+    }
+    /** Verify a row's signature (tamper check). */
+    verify(row) {
+        return this.d.verifySig(canonicalE2ERow(row), row.signature);
+    }
+}
+//# sourceMappingURL=SessionPoolE2EResultStore.js.map

package/dist/core/SessionPoolE2EResultStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionPoolE2EResultStore.js","sourceRoot":"","sources":["../../src/core/SessionPoolE2EResultStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAuB7B,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,CAAoC;IAClE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,OAAO,yBAAyB;IACnB,CAAC,CAAgC;IAClD,YAAY,IAAmC;QAC7C,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,sFAAsF;IACtF,YAAY,CAAC,KAAa,EAAE,MAAuB,EAAE,SAAiB,EAAE,WAAmB;QACzF,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7E,MAAM,QAAQ,GAAsC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QACrG,MAAM,GAAG,GAAmB,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC/F,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/D,OAAO,GAAG,CAAC;IACb,CAAC;IAED,mFAAmF;IACnF,GAAG;QACD,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,EAAE,CAAC;QAAC,CAAC;QAChF,MAAM,GAAG,GAAqB,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,IAAI,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,qFAAqF;IACrF,iBAAiB,CAAC,KAAa;QAC7B,IAAI,MAAM,GAA0B,IAAI,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE;YAAE,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK;gBAAE,MAAM,GAAG,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+CAA+C;IAC/C,MAAM,CAAC,GAAmB;QACxB,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/core/SessionRouter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SessionRouter — the L4 inbound-message dispatch engine (Multi-Machine Session
+ * Pool §L4 "Message Routing to Owner" + "Ownership CAS at Dispatch"). For every
+ * inbound message the router resolves session ownership and dispatches:
+ *
+ *   1. Owned + owner alive + owner == self  → handle locally (no MeshRpc hop).
+ *   2. Owned + owner alive + owner != self  → forward via deliverMessage over MeshRpc
+ *      (signed, recipient-bound, idempotent on messageId; ACK before offset advance).
+ *   3. Owned + owner DEAD                    → owner-dead re-placement (re-place + claim).
+ *   4. Transient (placing/transferring)      → queue (ownership-contention).
+ *   5. Unowned (new)                         → PlacementExecutor.decide() → SYNCHRONOUS
+ *      CAS-claim → spawn on the winner (or, on CAS loss, forward to the winner / queue).
+ *
+ * Per-session ordering: messages for ONE sessionKey are dispatched strictly in
+ * inbound order, at-most-one-in-flight (a per-session promise chain). Different
+ * sessions dispatch concurrently. All I/O is injected so the dispatch logic itself
+ * is deterministic + unit-testable; the deliverMessage dep owns its own per-attempt
+ * timeout (it throws on timeout) — the router owns the retry/backoff/fallback loop.
+ */
+import type { PlacementExecutor, TopicPlacement } from './PlacementExecutor.js';
+import type { MachineCapacity } from './types.js';
+export interface OwnershipView {
+    owner: string | null;
+    epoch: number;
+    status: 'active' | 'placing' | 'transferring' | null;
+    target?: string;
+}
+export interface DeliverAck {
+    messageId: string;
+    accepted: 'queued' | 'duplicate' | 'stale-ownership';
+}
+export interface InboundMessage {
+    sessionKey: string;
+    messageId: string;
+    payload: unknown;
+    topicMetadata?: TopicPlacement;
+}
+export type RouteAction = 'handled-locally' | 'forwarded' | 'spawned' | 'queued' | 'duplicate' | 'owner-dead-replaced' | 'placement-blocked';
+export interface RouteOutcome {
+    action: RouteAction;
+    owner?: string | null;
+    detail?: string;
+    /** True once the inbound is durably accepted (ledger ACK or local handling) — the
+     * caller may advance the platform offset ONLY when this is true (§L4 ACK protocol). */
+    acked: boolean;
+}
+export interface SessionRouterConfig {
+    deliverMessageMaxRetries: number;
+    deliverMessageRetryBackoffStartMs: number;
+    deliverMessageRetryBackoffMaxMs: number;
+    /** Bound on stale-ownership re-resolution to avoid an unbounded chase. */
+    maxReResolveDepth: number;
+}
+export declare const DEFAULT_ROUTER_CONFIG: SessionRouterConfig;
+export interface SessionRouterDeps {
+    selfMachineId: string;
+    placement: PlacementExecutor;
+    machineRegistry: () => MachineCapacity[];
+    resolveOwnership: (sessionKey: string) => OwnershipView;
+    isMachineAlive: (machineId: string) => boolean;
+    /** SYNCHRONOUS per-session CAS-claim (the §L−1 single-ref fast-forward push). */
+    casClaimOwnership: (sessionKey: string, machineId: string, expectedEpoch: number) => {
+        ok: boolean;
+        epoch: number;
+    };
+    /** ONE deliverMessage attempt over MeshRpc; throws on transport error/timeout. */
+    deliverMessage: (target: string, env: {
+        sessionKey: string;
+        messageId: string;
+        payload: unknown;
+        ownershipEpoch: number;
+    }) => Promise<DeliverAck>;
+    /** Router == owner: process the message on this machine. */
+    handleLocally: (msg: InboundMessage) => Promise<void>;
+    /** Instruct the chosen machine to spawn/resume the session. */
+    spawnOnMachine: (machineId: string, msg: InboundMessage) => Promise<void>;
+    queueMessage: (msg: InboundMessage, reason: string) => void;
+    raiseAttention: (title: string, body: string) => void;
+    markOwnerSuspect?: (machineId: string) => void;
+    sleep: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+}
+export declare class SessionRouter {
+    private readonly deps;
+    private readonly cfg;
+    private readonly chains;
+    constructor(deps: SessionRouterDeps, cfg?: SessionRouterConfig);
+    /** Dispatch an inbound message; serialized per-session (in-order, one-in-flight). */
+    route(msg: InboundMessage): Promise<RouteOutcome>;
+    private backoff;
+    private dispatchOne;
+    private forwardToOwner;
+    private placeAndClaim;
+}
+//# sourceMappingURL=SessionRouter.d.ts.map

package/dist/core/SessionRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRouter.d.ts","sourceRoot":"","sources":["../../src/core/SessionRouter.ts"],"names":[],"mappings":"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"}

package/dist/core/SessionRouter.js

@@ -0,0 +1,151 @@
+/**
+ * SessionRouter — the L4 inbound-message dispatch engine (Multi-Machine Session
+ * Pool §L4 "Message Routing to Owner" + "Ownership CAS at Dispatch"). For every
+ * inbound message the router resolves session ownership and dispatches:
+ *
+ *   1. Owned + owner alive + owner == self  → handle locally (no MeshRpc hop).
+ *   2. Owned + owner alive + owner != self  → forward via deliverMessage over MeshRpc
+ *      (signed, recipient-bound, idempotent on messageId; ACK before offset advance).
+ *   3. Owned + owner DEAD                    → owner-dead re-placement (re-place + claim).
+ *   4. Transient (placing/transferring)      → queue (ownership-contention).
+ *   5. Unowned (new)                         → PlacementExecutor.decide() → SYNCHRONOUS
+ *      CAS-claim → spawn on the winner (or, on CAS loss, forward to the winner / queue).
+ *
+ * Per-session ordering: messages for ONE sessionKey are dispatched strictly in
+ * inbound order, at-most-one-in-flight (a per-session promise chain). Different
+ * sessions dispatch concurrently. All I/O is injected so the dispatch logic itself
+ * is deterministic + unit-testable; the deliverMessage dep owns its own per-attempt
+ * timeout (it throws on timeout) — the router owns the retry/backoff/fallback loop.
+ */
+export const DEFAULT_ROUTER_CONFIG = {
+    deliverMessageMaxRetries: 3,
+    deliverMessageRetryBackoffStartMs: 250,
+    deliverMessageRetryBackoffMaxMs: 2000,
+    maxReResolveDepth: 3,
+};
+export class SessionRouter {
+    deps;
+    cfg;
+    chains = new Map();
+    constructor(deps, cfg = DEFAULT_ROUTER_CONFIG) {
+        this.deps = deps;
+        this.cfg = cfg;
+    }
+    /** Dispatch an inbound message; serialized per-session (in-order, one-in-flight). */
+    route(msg) {
+        const prior = this.chains.get(msg.sessionKey) ?? Promise.resolve();
+        const next = prior.catch(() => undefined).then(() => this.dispatchOne(msg));
+        // Track the tail so the next message on this session waits for this one to settle.
+        this.chains.set(msg.sessionKey, next.then(() => undefined, () => undefined));
+        return next;
+    }
+    backoff(attempt) {
+        return Math.min(this.cfg.deliverMessageRetryBackoffStartMs * 2 ** attempt, this.cfg.deliverMessageRetryBackoffMaxMs);
+    }
+    async dispatchOne(msg) {
+        const own = this.deps.resolveOwnership(msg.sessionKey);
+        if (own.status === 'active' && own.owner) {
+            if (own.owner === this.deps.selfMachineId) {
+                await this.deps.handleLocally(msg);
+                return { action: 'handled-locally', owner: own.owner, acked: true };
+            }
+            if (this.deps.isMachineAlive(own.owner)) {
+                return this.forwardToOwner(msg, own.owner, own.epoch, 0);
+            }
+            // Owner is not alive → owner-dead re-placement (§L4 fallback).
+            this.deps.markOwnerSuspect?.(own.owner);
+            return this.placeAndClaim(msg, 'failover', true);
+        }
+        if (own.status === 'placing' || own.status === 'transferring') {
+            this.deps.queueMessage(msg, 'ownership-contention');
+            return { action: 'queued', detail: own.status, acked: false };
+        }
+        // Unowned → place + claim.
+        return this.placeAndClaim(msg, 'new', false);
+    }
+    async forwardToOwner(msg, owner, epoch, reResolveDepth) {
+        for (let attempt = 0; attempt <= this.cfg.deliverMessageMaxRetries; attempt++) {
+            try {
+                const ack = await this.deps.deliverMessage(owner, { sessionKey: msg.sessionKey, messageId: msg.messageId, payload: msg.payload, ownershipEpoch: epoch });
+                if (ack.accepted === 'duplicate')
+                    return { action: 'duplicate', owner, acked: true };
+                if (ack.accepted === 'queued')
+                    return { action: 'forwarded', owner, acked: true };
+                // stale-ownership → re-resolve (bounded) and route to the current owner.
+                if (reResolveDepth >= this.cfg.maxReResolveDepth) {
+                    return this.placeAndClaim(msg, 'failover', true);
+                }
+                const own2 = this.deps.resolveOwnership(msg.sessionKey);
+                if (own2.status === 'active' && own2.owner === this.deps.selfMachineId) {
+                    await this.deps.handleLocally(msg);
+                    return { action: 'handled-locally', owner: own2.owner, detail: 'after-stale', acked: true };
+                }
+                // Re-forward to the current owner when ownership is still active+alive AND
+                // something actually changed — a DIFFERENT owner, or the SAME owner whose
+                // epoch advanced (the stale-ownership ACK meant our epoch view was behind;
+                // re-deliver at the corrected epoch rather than needlessly re-placing). A
+                // same-owner/same-epoch stale ACK is spurious → fall through to re-place.
+                // Bounded by maxReResolveDepth. (2026-05-29 pre-merge review #7.)
+                if (own2.status === 'active' && own2.owner && this.deps.isMachineAlive(own2.owner) && (own2.owner !== owner || own2.epoch !== epoch)) {
+                    return this.forwardToOwner(msg, own2.owner, own2.epoch, reResolveDepth + 1);
+                }
+                // Ownership moved to a transient/dead state (or a spurious same-epoch stale) → re-place.
+                return this.placeAndClaim(msg, 'failover', true);
+            }
+            catch (err) {
+                this.deps.log?.(`deliverMessage attempt ${attempt} to ${owner} failed: ${String(err?.message ?? err)}`);
+                if (attempt < this.cfg.deliverMessageMaxRetries) {
+                    await this.deps.sleep(this.backoff(attempt));
+                    continue;
+                }
+            }
+        }
+        // Retries exhausted → owner is unreachable → owner-dead re-placement.
+        this.deps.markOwnerSuspect?.(owner);
+        return this.placeAndClaim(msg, 'failover', true);
+    }
+    async placeAndClaim(msg, reason, fromDead) {
+        const decision = this.deps.placement.decide({
+            sessionKey: msg.sessionKey,
+            topicMetadata: msg.topicMetadata ?? {},
+            machineRegistry: this.deps.machineRegistry(),
+            currentOwner: undefined,
+            reason,
+        });
+        if (decision.outcome === 'placement-blocked') {
+            this.deps.raiseAttention('Session placement blocked', `${msg.sessionKey}: ${decision.escalationReason ?? decision.reason}`);
+            this.deps.queueMessage(msg, `placement-blocked:${decision.escalationReason ?? decision.reason}`);
+            return { action: 'placement-blocked', detail: decision.escalationReason ?? decision.reason, acked: false };
+        }
+        if (decision.outcome === 'queued' || !decision.chosenMachine) {
+            this.deps.raiseAttention('No machine available for session', `${msg.sessionKey}: ${decision.escalationReason ?? decision.reason}`);
+            this.deps.queueMessage(msg, decision.escalationReason ?? 'no-capable-machine');
+            return { action: 'queued', detail: decision.escalationReason ?? decision.reason, acked: false };
+        }
+        // Synchronous CAS-claim (the dispatch BLOCKS on this — Invariant #2).
+        const pre = this.deps.resolveOwnership(msg.sessionKey);
+        const cas = this.deps.casClaimOwnership(msg.sessionKey, decision.chosenMachine, pre.epoch);
+        if (!cas.ok) {
+            // Contention — re-read; route to the confirmed winner or queue if transient.
+            const own2 = this.deps.resolveOwnership(msg.sessionKey);
+            if (own2.status === 'active' && own2.owner === this.deps.selfMachineId) {
+                await this.deps.handleLocally(msg);
+                return { action: 'handled-locally', owner: own2.owner, detail: 'cas-lost-self', acked: true };
+            }
+            if (own2.status === 'active' && own2.owner && this.deps.isMachineAlive(own2.owner)) {
+                return this.forwardToOwner(msg, own2.owner, own2.epoch, 0);
+            }
+            this.deps.queueMessage(msg, 'ownership-contention');
+            return { action: 'queued', detail: 'ownership-contention', acked: false };
+        }
+        // CAS won → spawn on the winner (or handle locally if that's us).
+        const action = fromDead ? 'owner-dead-replaced' : 'spawned';
+        if (decision.chosenMachine === this.deps.selfMachineId) {
+            await this.deps.handleLocally(msg);
+            return { action: fromDead ? 'owner-dead-replaced' : 'handled-locally', owner: decision.chosenMachine, detail: 'placed-self', acked: true };
+        }
+        await this.deps.spawnOnMachine(decision.chosenMachine, msg);
+        return { action, owner: decision.chosenMachine, acked: true };
+    }
+}
+//# sourceMappingURL=SessionRouter.js.map

package/dist/core/SessionRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRouter.js","sourceRoot":"","sources":["../../src/core/SessionRouter.ts"],"names":[],"mappings":"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"}

package/dist/core/StageAdvancer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * StageAdvancer — the SOLE writer of `multiMachine.sessionPool.stage` and the
+ * mechanical rollout gate (Multi-Machine Session Pool §Rollout). A stage activates
+ * ONLY when the prior stage's Tier-3 E2E recorded `green` for the CURRENT commit;
+ * otherwise the advance is refused and audited. If a live stage later records `red`,
+ * the advancer mechanically REVERTS to the prior (safe) stage. Per "Structure >
+ * Willpower" the gate is code, not prose: no other path may flip the stage (enforced
+ * by a Config.ts write-guard that only honors writes carrying this module's token).
+ */
+import type { SessionPoolE2EResultStore } from './SessionPoolE2EResultStore.js';
+export declare const STAGES: readonly ["dark", "shadow", "live-transfer", "rebalance"];
+export type SessionPoolStage = (typeof STAGES)[number];
+export declare function stageIndex(stage: SessionPoolStage): number;
+export type AdvanceResult = {
+    ok: true;
+    stage: SessionPoolStage;
+} | {
+    ok: false;
+    reason: 'e2e-gate-not-passed' | 'already-at-or-past' | 'invalid-stage';
+    detail?: string;
+};
+export interface StageAdvancerDeps {
+    resultStore: SessionPoolE2EResultStore;
+    /** The commit the running build is on — the E2E result must match it. */
+    currentCommitSha: () => string;
+    /** Read the current configured stage. */
+    readStage: () => SessionPoolStage;
+    /** The ONLY stage-config write path. Config.ts must reject writes that don't come through here. */
+    writeStageConfig: (stage: SessionPoolStage) => void;
+    audit?: (event: string, detail: Record<string, unknown>) => void;
+}
+export declare class StageAdvancer {
+    private readonly d;
+    constructor(d: StageAdvancerDeps);
+    /**
+     * Advance to `targetStage`, gated on a matching `green` E2E for the PRIOR stage at
+     * the current commit. A missing/`red`/stale-commit/tampered prior result → refused.
+     */
+    advanceTo(targetStage: SessionPoolStage): AdvanceResult;
+    /**
+     * Reconcile on each cycle: if the CURRENT stage's latest E2E is `red` (regression),
+     * mechanically revert to the prior stage until a fresh `green` is recorded. Returns
+     * the stage after reconciliation.
+     */
+    reconcile(): SessionPoolStage;
+}
+//# sourceMappingURL=StageAdvancer.d.ts.map

package/dist/core/StageAdvancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StageAdvancer.d.ts","sourceRoot":"","sources":["../../src/core/StageAdvancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAEhF,eAAO,MAAM,MAAM,2DAA4D,CAAC;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3G,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,yBAAyB,CAAC;IACvC,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,gBAAgB,CAAC;IAClC,mGAAmG;IACnG,gBAAgB,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAClE;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,iBAAiB;IAEjD;;;OAGG;IACH,SAAS,CAAC,WAAW,EAAE,gBAAgB,GAAG,aAAa;IAwBvD;;;;OAIG;IACH,SAAS,IAAI,gBAAgB;CAiB9B"}