instar 1.3.819 → 1.3.821

package/dist/monitoring/DuplicateSessionReconciler.d.ts

@@ -0,0 +1,225 @@
+/**
+ * DuplicateSessionReconciler — Layer B of ownership-gated-spawn-and-judgment-
+ * within-floors (§3.2): converge the OWNERSHIP RECORD when the same
+ * conversation is live on two or more machines, so the EXISTING gated closeout
+ * (SessionReaper's topic-moved sweeper) can close the non-owner copy through
+ * its normal path. **The reconciler never kills a session** — it repairs
+ * records; the closeout's own guards (fresh re-checks, veto breaker,
+ * terminate-time re-probe) do every close.
+ *
+ * The 2026-07-10 incident's healing gap in one line: the duplicate detector
+ * was observe-only and request-driven (only ran when a dashboard polled), and
+ * both machines' cleanup separately refused the duplicates (`not-lease-holder`
+ * on one side, `open-commitment` on the other) — two individually-correct
+ * guards jointly making a duplicate immortal.
+ *
+ * Deterministic core (all ambiguity ESCALATES, never guesses):
+ *  - §3.2.0 substrate gate: refuses to arm on an in-memory ownership store
+ *    (fleet default) — a loud `substrate-not-ready` status, never silent.
+ *  - §3.2.1 discovery on the serving-lease holder only, tick-paced, fresh
+ *    direct probe before ANY record write; per-tick caps (P17).
+ *  - §3.2.2 intended-owner evidence ladder: hard pin (never a quarantined
+ *    one) → highest ADMISSIBLE ownershipEpoch → server-registered live
+ *    autonomous run (probe-confirmed) → J2/escalate. Rule-2/rule-3
+ *    contradiction, both-self-with-equal-epochs, both-live-runs, and CAS
+ *    409s always escalate. "Most recent user interaction" is deliberately
+ *    NOT a rule — the non-owner duplicate often has the latest message
+ *    BECAUSE of the bug.
+ *  - §3.2.3 convergence: ONE fenced CAS naming the intended owner (journal
+ *    replication fast-forwards every peer), then peer-echo confirmation
+ *    within `echoConfirmTicks`; no echo → ONE aggregated
+ *    `convergence-not-observed` escalation (P17).
+ *  - §3.2.5 P19 breaker: a topic re-duplicating past the threshold stops
+ *    being auto-reconciled and raises ONE item; record FLIPS and
+ *    echoed-but-unhealed episodes count; transfer-traceable episodes are
+ *    excluded from the clamp (but ≥3/24h raise an observability-only item).
+ *  - Registry-error freeze: while the SpawnAdmission error episode is open,
+ *    the reconciler pauses (same fault domain — §3.1 row e).
+ *
+ * Increment-1 posture: dev-gated + dryRun — detection, evidence ladder, and
+ * would-converge decisions run and journal; NO CAS lands, NO closeout arms
+ * until a deliberate dryRun:false (and the substrate gate holds regardless).
+ */
+import type { BoundedJsonlAudit } from '../core/BoundedJsonlAudit.js';
+export interface DuplicateCandidate {
+    /** `${platform}:${platformId}` — the conversation identity. */
+    key: string;
+    platform: string;
+    platformId: string;
+    /** Machines with a LIVE session for this conversation. */
+    machines: Array<{
+        machineId: string;
+        sessions: string[];
+    }>;
+}
+export interface ReconcilerConfigView {
+    enabled: boolean;
+    dryRun: boolean;
+    reconcilerTickMs: number;
+    maxReconcilesPerTick: number;
+    maxConvergenceWritesPerTick: number;
+    echoConfirmTicks: number;
+    breakerThreshold: number;
+    breakerWindowMs: number;
+}
+export interface OwnershipViewRow {
+    machineId: string;
+    owner: string | null;
+    epoch: number;
+    /** Origin-stamp validated (§3 epoch hygiene) — inadmissible rows never count. */
+    admissible: boolean;
+}
+export type IntendedOwnerVerdict = {
+    kind: 'owner';
+    owner: string;
+    rule: 'hard-pin' | 'highest-epoch' | 'live-run';
+    detail: string;
+} | {
+    kind: 'escalate';
+    reason: string;
+};
+export interface ReconcilerDeps {
+    selfMachineId: () => string | null;
+    holdsLease: () => boolean;
+    /** §3.2.0 — durable + replicated ownership substrate live pool-wide. */
+    substrateReady: () => {
+        ready: boolean;
+        reason?: string;
+    };
+    /** §3.1 row e — freeze while a registry-error episode is open (same fault domain). */
+    errorEpisodeOpen: () => boolean;
+    /** One authority in motion per topic: in-flight transfer / open stale-owner episode / active hold. */
+    topicHasAuthorityInMotion: (sessionKey: string) => boolean;
+    /** Candidate discovery (lease-holder bounded fan-out, or the pool poll-cache where live). */
+    discoverCandidates: () => Promise<{
+        candidates: DuplicateCandidate[];
+        degraded?: string;
+    }>;
+    /**
+     * Fresh direct probe (5s budget in the wiring): does the machine still hold a
+     * LIVE copy of this conversation? Cache rows are never acted on (§3.2.1).
+     */
+    probeLiveCopy: (machineId: string, key: string) => Promise<{
+        ok: boolean;
+        live: boolean;
+    }>;
+    /** Pin store read — a quarantined pin never counts (§3.2.2 rule 1). */
+    readPin: (sessionKey: string) => {
+        pinned: boolean;
+        preferredMachine?: string | null;
+        quarantined?: boolean;
+    } | null;
+    /** Every machine's replicated registry view for this key (§3.2.2 rule 2). */
+    readOwnershipViews: (sessionKey: string) => OwnershipViewRow[];
+    /**
+     * §3.2.2 rule 3 — journal-replicated live-run registration, confirmed by an
+     * authenticated live probe to the hosting machine (never a bare poll row).
+     */
+    liveRunHosts: (sessionKey: string) => Promise<Array<{
+        machineId: string;
+        registeredAt: number;
+        confirmed: boolean;
+    }>>;
+    /** The fenced convergence CAS (lease epoch + record epoch ride the wiring). */
+    casConverge: (sessionKey: string, owner: string) => {
+        ok: boolean;
+        reason?: string;
+    };
+    /** Peer-echo: does `machineId`'s OWN registry view now name `owner`? */
+    peerEchoObserved: (sessionKey: string, owner: string, machineId: string) => Promise<boolean>;
+    /**
+     * Arm the existing closeout for the non-owner copy (reap-log reason
+     * `duplicate-reconciled`) — the sweeper's own guards still decide the close.
+     */
+    armCloseout: (sessionKey: string, owner: string) => void;
+    raiseAttention: (item: {
+        id: string;
+        title: string;
+        body: string;
+        priority: 'high' | 'medium';
+    }) => void;
+    journal: BoundedJsonlAudit;
+    provenance?: (row: {
+        component: string;
+        decisionPoint: string;
+        context: Record<string, unknown>;
+        optionsPresented: string[];
+        decision: string;
+        reason: string;
+        floor: string;
+        fallbackRung: string;
+    }) => void;
+    log: (msg: string) => void;
+    now?: () => number;
+}
+/** §3.2.5 — receive-side type clamp for replicated breaker rows. */
+export declare function clampBreakerRow(row: unknown): {
+    key: string;
+    count: number;
+    lastAt: string;
+} | null;
+export interface ReconcilerTickReport {
+    at: string;
+    ran: boolean;
+    skippedReason?: string;
+    candidates: number;
+    reconciled: number;
+    wouldConverge: number;
+    escalations: number;
+    echoConfirmed: number;
+    echoTimeouts: number;
+    breakerClamped: number;
+}
+export interface ReconcilerStatus {
+    enabled: boolean;
+    dryRun: boolean;
+    substrate: {
+        ready: boolean;
+        reason?: string;
+    };
+    lastTick: ReconcilerTickReport | null;
+    openEpisodes: number;
+    breaker: Array<{
+        key: string;
+        episodes: number;
+        clamped: boolean;
+    }>;
+    counters: Record<string, number>;
+    config: Omit<ReconcilerConfigView, 'enabled' | 'dryRun'>;
+}
+export declare class DuplicateSessionReconciler {
+    private readonly deps;
+    private cfg;
+    private readonly nowFn;
+    private episodes;
+    /** §3.2.5 per-topic re-duplication episode opens within the window. */
+    private breakerEpisodes;
+    /** Topics whose episode is transfer-traceable this window (excluded from the clamp). */
+    private transferTraceable;
+    private lastTick;
+    private substrateNotReadySince;
+    private substratePauseItemRaised;
+    private counters;
+    constructor(cfg: ReconcilerConfigView, deps: ReconcilerDeps);
+    setConfig(cfg: ReconcilerConfigView): void;
+    /** One reconciler pass. Returns the report (also retained for status()). */
+    tick(): Promise<ReconcilerTickReport>;
+    private finish;
+    private noteSubstrateNotReady;
+    /** Reconcile one duplicate candidate. */
+    private reconcileOne;
+    /** §3.2.2 — the evidence ladder. */
+    private intendedOwner;
+    private checkPendingEchoes;
+    private openOrGetEpisode;
+    /** Record a topic-moved (transfer-traceable) episode — excluded from the clamp. */
+    noteTransferTraceable(key: string): void;
+    private bumpBreaker;
+    /** §3.2.5 — also consulted by the owner-dark ladder (clamp to rung 3). */
+    breakerClamped(key: string, now?: number): boolean;
+    private escalateOnce;
+    private journalRow;
+    private provenanceRow;
+    status(): ReconcilerStatus;
+}
+//# sourceMappingURL=DuplicateSessionReconciler.d.ts.map

package/dist/monitoring/DuplicateSessionReconciler.d.ts.map

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