instar 1.3.91 → 1.3.92

package/dist/core/RebalancePlanner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * RebalancePlanner — the pure Stage-3 load-rebalance decision (Multi-Machine Session
+ * Pool §L4 "Load-rebalance trigger conditions"). Given the machine capacities + the
+ * current session→machine assignments, it proposes a BOUNDED set of transfers off
+ * over-saturated machines. It is evaluated ONLY on the heartbeat interval by the
+ * caller (never per message), and is deliberately conservative to avoid a cascade:
+ *
+ *  - A machine is a rebalance SOURCE only if its session ratio exceeds
+ *    `rebalanceThresholdPercent` (default 0.85 of maxSessions).
+ *  - Only NON-pinned, low-priority sessions that are off cool-down
+ *    (`now - lastTransferredAt > placementCooldownMs`) are movable; a hard pin or a
+ *    critical session is NEVER proactively rebalanced.
+ *  - At most ONE move per source per cycle (capped overall by `maxMovesPerCycle`), and
+ *    a working copy of capacities is updated as moves are proposed so the planner never
+ *    piles every session onto one target.
+ *  - The TARGET is chosen by the same `PlacementExecutor.decide(reason:'rebalance')`
+ *    the router uses — a move is proposed only if it lands on a DIFFERENT, eligible
+ *    machine. No move ⇒ empty result (rebalance never forces a churn).
+ *
+ * Pure over its inputs; the caller performs the actual transfers (TransferOrchestrator).
+ */
+import type { PlacementExecutor, TopicPlacement } from './PlacementExecutor.js';
+import type { MachineCapacity } from './types.js';
+export interface RebalanceSession {
+    sessionKey: string;
+    ownerMachineId: string;
+    pinned?: boolean;
+    lowPriority?: boolean;
+    lastTransferredAt?: number;
+    topicMetadata?: TopicPlacement;
+}
+export interface RebalanceInput {
+    machines: MachineCapacity[];
+    sessions: RebalanceSession[];
+    rebalanceThresholdPercent: number;
+    placementCooldownMs: number;
+    now: number;
+    /** Hard cap on moves proposed per cycle (default = number of saturated sources). */
+    maxMovesPerCycle?: number;
+}
+export interface RebalanceMove {
+    sessionKey: string;
+    fromMachine: string;
+    toMachine: string;
+    reason: string;
+}
+export declare function planRebalance(input: RebalanceInput, placement: PlacementExecutor): RebalanceMove[];
+//# sourceMappingURL=RebalancePlanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RebalancePlanner.d.ts","sourceRoot":"","sources":["../../src/core/RebalancePlanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,yBAAyB,EAAE,MAAM,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,GAAG,aAAa,EAAE,CA+ClG"}

package/dist/core/RebalancePlanner.js

@@ -0,0 +1,71 @@
+/**
+ * RebalancePlanner — the pure Stage-3 load-rebalance decision (Multi-Machine Session
+ * Pool §L4 "Load-rebalance trigger conditions"). Given the machine capacities + the
+ * current session→machine assignments, it proposes a BOUNDED set of transfers off
+ * over-saturated machines. It is evaluated ONLY on the heartbeat interval by the
+ * caller (never per message), and is deliberately conservative to avoid a cascade:
+ *
+ *  - A machine is a rebalance SOURCE only if its session ratio exceeds
+ *    `rebalanceThresholdPercent` (default 0.85 of maxSessions).
+ *  - Only NON-pinned, low-priority sessions that are off cool-down
+ *    (`now - lastTransferredAt > placementCooldownMs`) are movable; a hard pin or a
+ *    critical session is NEVER proactively rebalanced.
+ *  - At most ONE move per source per cycle (capped overall by `maxMovesPerCycle`), and
+ *    a working copy of capacities is updated as moves are proposed so the planner never
+ *    piles every session onto one target.
+ *  - The TARGET is chosen by the same `PlacementExecutor.decide(reason:'rebalance')`
+ *    the router uses — a move is proposed only if it lands on a DIFFERENT, eligible
+ *    machine. No move ⇒ empty result (rebalance never forces a churn).
+ *
+ * Pure over its inputs; the caller performs the actual transfers (TransferOrchestrator).
+ */
+function sessionRatio(m) {
+    return m.maxSessions && m.maxSessions > 0 ? (m.activeSessionCount ?? 0) / m.maxSessions : 0;
+}
+export function planRebalance(input, placement) {
+    // Working copy of capacities (mutated as moves are proposed → no pile-on).
+    const caps = new Map(input.machines.map((m) => [m.machineId, { ...m }]));
+    const threshold = input.rebalanceThresholdPercent;
+    const saturated = (id) => {
+        const m = caps.get(id);
+        return !!m && m.online && sessionRatio(m) > threshold;
+    };
+    const sources = input.machines.filter((m) => saturated(m.machineId)).sort((a, b) => sessionRatio(caps.get(b.machineId)) - sessionRatio(caps.get(a.machineId)));
+    const cap = input.maxMovesPerCycle ?? sources.length;
+    const moves = [];
+    const movedSessions = new Set();
+    for (const src of sources) {
+        if (moves.length >= cap)
+            break;
+        if (!saturated(src.machineId))
+            continue; // a prior move may have relieved it
+        // Eligible movable sessions on this source.
+        const candidates = input.sessions.filter((s) => s.ownerMachineId === src.machineId &&
+            !movedSessions.has(s.sessionKey) &&
+            !s.pinned && !s.topicMetadata?.pinned &&
+            (s.lowPriority ?? true) &&
+            input.now - (s.lastTransferredAt ?? 0) > input.placementCooldownMs);
+        for (const s of candidates) {
+            // One move per source per cycle (cascade guard).
+            const decision = placement.decide({
+                sessionKey: s.sessionKey,
+                topicMetadata: s.topicMetadata ?? {},
+                machineRegistry: [...caps.values()],
+                currentOwner: undefined, // rebalance ignores stickiness
+                reason: 'rebalance',
+            });
+            if (decision.outcome === 'placed' && decision.chosenMachine && decision.chosenMachine !== src.machineId) {
+                moves.push({ sessionKey: s.sessionKey, fromMachine: src.machineId, toMachine: decision.chosenMachine, reason: 'load-rebalance' });
+                movedSessions.add(s.sessionKey);
+                // Update the working copy: source −1, target +1.
+                const from = caps.get(src.machineId);
+                const to = caps.get(decision.chosenMachine);
+                from.activeSessionCount = Math.max(0, (from.activeSessionCount ?? 0) - 1);
+                to.activeSessionCount = (to.activeSessionCount ?? 0) + 1;
+                break; // one move per source this cycle
+            }
+        }
+    }
+    return moves;
+}
+//# sourceMappingURL=RebalancePlanner.js.map

package/dist/core/RebalancePlanner.js.map

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

package/dist/core/SessionOwnership.d.ts

@@ -0,0 +1,103 @@
+/**
+ * SessionOwnership — per-session ownership state machine for the Multi-Machine
+ * Session Pool (spec §L3). Exactly one machine runs a session at any instant;
+ * ownership is movable and fenced by a (status, epoch) pair, advanced by a
+ * per-session CAS at `ownershipEpoch+1`.
+ *
+ * This module is PURE LOGIC — the legal transitions, the run-fence (who may run
+ * the agent), the output-exclusion contract (who may write to the user channel
+ * during a transfer), and the per-session nonce scoping. The durable CAS (the
+ * per-session git single-ref fast-forward push of §L−1) and the distributed
+ * registry sit on top and call these to validate every ownership change.
+ *
+ * The handoff is **claim-before-release, gated by the state machine** — NOT
+ * release-before-claim. Authoritative sequence for a transfer of session K from
+ * source S to target T:
+ *   active(owner=S, e) → transferring(from=S, to=T, e+1) → active(owner=T, e+2) → S tears down (local)
+ * Because the fence is (status, epoch) — not the physical release — there is no
+ * double-run (only one machine ever sees itself active at the top epoch) and no
+ * no-owner gap (transferring still names S as the draining owner until T is active).
+ */
+export type SessionOwnershipStatus = 'placing' | 'active' | 'transferring' | 'released';
+export interface SessionOwnershipRecord {
+    sessionKey: string;
+    ownerMachineId: string;
+    ownershipEpoch: number;
+    status: SessionOwnershipStatus;
+    /** During `transferring`: the target machine the session is moving to. */
+    transferTo?: string;
+    nonce: string;
+    timestamp: number;
+    updatedAt: string;
+    signature?: string;
+}
+export type OwnershipAction = {
+    type: 'place';
+    machineId: string;
+} | {
+    type: 'claim';
+    machineId: string;
+} | {
+    type: 'transfer';
+    to: string;
+} | {
+    type: 'release';
+    machineId: string;
+};
+export type OwnershipReason = 'ok' | 'already-placed' | 'claim-out-of-sequence' | 'claim-wrong-machine' | 'transfer-not-active' | 'release-not-owner' | 'release-requires-active' | 'no-record';
+/**
+ * Pure transition. Given the CURRENT record (or null for a never-seen session)
+ * and an action, returns the next record (the CAS candidate, at epoch+1) or a
+ * typed rejection. Epoch arithmetic + legal sequencing are enforced here; the
+ * CAS layer then attempts to land `next` via a fast-forward push.
+ */
+export declare function applyOwnershipAction(current: SessionOwnershipRecord | null, action: OwnershipAction, ctx: {
+    sessionKey: string;
+    nonce: string;
+    now: number;
+}): {
+    ok: true;
+    next: SessionOwnershipRecord;
+} | {
+    ok: false;
+    reason: OwnershipReason;
+};
+/**
+ * Run-fence (spec §L3): a worker may RUN the agent for a session ONLY while it
+ * observes itself as the `active` owner at the current epoch. During
+ * `transferring` NO machine runs new turns (the draining owner finishes via the
+ * output-exclusion contract; the target is not yet active).
+ */
+export declare function mayRun(record: SessionOwnershipRecord | null, machineId: string, effectiveEpoch: number): boolean;
+export interface EmitDecision {
+    /** May this machine write to the user channel at all right now? */
+    mayEmit: boolean;
+    /** If mayEmit, may it emit NEW output (vs only drain an in-flight reply)? */
+    newOutputAllowed: boolean;
+}
+/**
+ * Output-exclusion contract (spec §L3) — distinct from the run-fence. During a
+ * transfer the draining source and the freshly-active target overlap in time, so
+ * channel emission is gated separately so the user never sees interleaved/double
+ * output:
+ *  - The draining source (record `transferring`, from === machine) MAY emit the
+ *    TAIL of an in-flight reply within [transferringStartedAt, +cutoffMs], but no
+ *    NEW output, and nothing past the cutoff.
+ *  - The target (record `active`, owner === machine, after its CAS) emits only
+ *    once the cutoff has elapsed since `transferringStartedAt` (so the two
+ *    windows are disjoint by construction).
+ *  - The steady-state active owner (no transfer in flight) emits freely.
+ */
+export declare function mayEmit(record: SessionOwnershipRecord | null, machineId: string, opts: {
+    now: number;
+    transferringStartedAt?: number;
+    cutoffMs?: number;
+}): EmitDecision;
+/**
+ * Per-session nonce scoping (spec §L3): the replay-guard key is the tuple
+ * {sessionKey, sender, ownershipEpoch} — NOT a global nonce space. The same
+ * nonce value used in two different sessions does not collide; a replay WITHIN a
+ * session's CAS sequence is caught.
+ */
+export declare function ownershipNonceKey(sessionKey: string, sender: string, ownershipEpoch: number, nonce: string): string;
+//# sourceMappingURL=SessionOwnership.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionOwnership.d.ts","sourceRoot":"","sources":["../../src/core/SessionOwnership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAC;AAExF,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,MAAM,MAAM,eAAe,GACvB,IAAI,GACJ,gBAAgB,GAChB,uBAAuB,GACvB,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,yBAAyB,GACzB,WAAW,CAAC;AAEhB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAAG,IAAI,EACtC,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAqDrF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAGhH;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,sBAAsB,GAAG,IAAI,EACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,YAAY,CAkBd;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnH"}

package/dist/core/SessionOwnership.js.map

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

package/dist/core/SessionOwnershipRegistry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { type OwnershipAction, type OwnershipReason, type SessionOwnershipRecord } 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 declare class InMemorySessionOwnershipStore {
+    private recs;
+    read(sessionKey: string): SessionOwnershipRecord | null;
+    casWrite(candidate: import('./SessionOwnership.js').SessionOwnershipRecord): {
+        ok: boolean;
+        observed: SessionOwnershipRecord | null;
+    };
+    all(): SessionOwnershipRecord[];
+}
+/** Durable per-session CAS substrate (git single-ref fast-forward push). */
+export interface SessionOwnershipStore {
+    /** Read the current committed record for a session (null if none). */
+    read(sessionKey: string): SessionOwnershipRecord | null;
+    /**
+     * Attempt to land `candidate` as the new record via a fast-forward push from
+     * the current epoch. ok:true if it landed; ok:false + observed (the
+     * freshly-reread record) if a peer advanced first (non-fast-forward reject).
+     */
+    casWrite(candidate: SessionOwnershipRecord): {
+        ok: boolean;
+        observed: SessionOwnershipRecord | null;
+    };
+}
+export interface SessionOwnershipRegistryDeps {
+    store: SessionOwnershipStore;
+    /** Has this per-session nonce been seen (replay guard)? */
+    seenNonce: (key: string) => boolean;
+    /** Record a per-session nonce as seen (called only on a successful CAS). */
+    recordNonce: (key: string) => void;
+    now?: () => number;
+    /** Eviction age (ms) for `released` records. Default 86400000 (24h). */
+    releasedEvictionMs?: number;
+    logger?: (msg: string) => void;
+}
+export type CasResult = {
+    ok: true;
+    record: SessionOwnershipRecord;
+} | {
+    ok: false;
+    reason: OwnershipReason | 'replayed-nonce' | 'cas-lost';
+    observed: SessionOwnershipRecord | null;
+};
+export declare class SessionOwnershipRegistry {
+    private readonly d;
+    private casConflicts;
+    private casRetryExhaustions;
+    constructor(deps: SessionOwnershipRegistryDeps);
+    private now;
+    read(sessionKey: string): SessionOwnershipRecord | null;
+    /** The current owner machine of a session (null if none / released). */
+    ownerOf(sessionKey: string): string | null;
+    /**
+     * 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: string): string | 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: OwnershipAction, ctx: {
+        sessionKey: string;
+        sender: string;
+        nonce: string;
+    }): CasResult;
+    /** Observability counters (spec §L3: /pool ownership.casConflicts/casRetryExhaustions). */
+    noteRetryExhaustion(): void;
+    metrics(): {
+        casConflicts: number;
+        casRetryExhaustions: number;
+    };
+}
+/**
+ * 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 declare function ownershipRetryDelayMs(retryCount: number, selfMachineId: string, contenderMachineId: string, opts?: {
+    baseMs?: number;
+    maxMs?: number;
+}): number;
+//# sourceMappingURL=SessionOwnershipRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionOwnershipRegistry.d.ts","sourceRoot":"","sources":["../../src/core/SessionOwnershipRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;GAOG;AACH,qBAAa,6BAA6B;IACxC,OAAO,CAAC,IAAI,CAA6E;IACzF,IAAI,CAAC,UAAU,EAAE,MAAM;IAGvB,QAAQ,CAAC,SAAS,EAAE,OAAO,uBAAuB,EAAE,sBAAsB;;;;IAS1E,GAAG;CAGJ;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,sBAAsB,GAAG;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAA;KAAE,CAAC;CACvG;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,qBAAqB,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,4EAA4E;IAC5E,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAA;CAAE,CAAC;AAEpH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA+B;IACjD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,mBAAmB,CAAK;gBAEpB,IAAI,EAAE,4BAA4B;IAG9C,OAAO,CAAC,GAAG;IAIX,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAIvD,wEAAwE;IACxE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAM1C;;;OAGG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQpD;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAkBnG,2FAA2F;IAC3F,mBAAmB,IAAI,IAAI;IAG3B,OAAO,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAE;CAGjE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,MAAM,CAOR"}

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"}