instar 1.3.747 → 1.3.749

package/dist/monitoring/machineCoherenceEpisode.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Machine-coherence episode — the DURABLE state layer (machine-coherence-guard
+ * §4.1 + §4.6). Pure types + the persistence primitives only: episodeId
+ * minting, the atomic transition-write, and the read that distinguishes
+ * absent / ok / corrupt so the caller can re-baseline (N3/N4). The episode
+ * STATE MACHINE — open / join / suspend / resume / reopen / close / the
+ * pendingFix lifecycle / the recurrence damper (§4.2–§4.5) — is the CONSUMER
+ * of this layer and lands in the next sub-unit; nothing here raises, alarms,
+ * or transitions anything.
+ *
+ * Why a durable layer at all (§4.1): a server restart mid-episode must neither
+ * re-alarm nor forget. The file is written on state TRANSITIONS only (never
+ * per tick — confirm/resolve/verify COUNTERS stay in-memory, warm-up-absorbed,
+ * R2-N3); the recurrence block OUTLIVES episode close so the reopen window has
+ * memory (R2-N2).
+ *
+ * N7: `stateDir` is the per-agent state root — never a shared/global path.
+ * Supervision tier (N6): Tier 0 — deterministic file I/O, no LLM anywhere.
+ */
+import type { SkewDimension } from './machineCoherenceEvaluate.js';
+/** The pendingFix three-state lifecycle (§4.2.1-i, R3-M6 / R4-M2). */
+export type PendingFixState = 'proposed' | 'approved-holding' | 'executing-verifying';
+/**
+ * A single approved-or-proposed fix bound to ONE proposal (§4.2.1-i cardinality
+ * — at most one per episode). The proposal hash + message id is the AUTHORITY:
+ * a reply confirms ONLY the exact recorded proposal (display-integrity).
+ */
+export interface PendingFix {
+    state: PendingFixState;
+    /** The N1 skew-row identity this fix targets. */
+    rowIdentity: string;
+    /** The manifest flag / dimension key being equalized. */
+    key: string;
+    dimension: SkewDimension;
+    /** The divergent machine whose local config the fix rewrites (§4.2.1-iv). */
+    targetMachineId: string;
+    /** The concrete effective value the write yields (§4.2.1-ii direction). */
+    targetValue: string;
+    /** The server-authored proposal message id the reply chains to (§4.2.1-i). */
+    proposalMessageId?: string;
+    /** Hash over (episodeId|key|targetMachine|targetValue|proposalMessageId) — the
+     *  reply-recognition authority; nothing executes without matching it. */
+    proposalHash: string;
+    /** Approval anchor (executing-verifying verify-clock start, R5-L1). */
+    approvedAtMs?: number;
+    /** First post-restart beat from the divergent machine (verify-clock anchor). */
+    postRestartBeatAtMs?: number;
+    /** Accumulated suspended time excluded from the executing-verifying clocks
+     *  (§4.2.1-v; transition-written — suspend-start/resume-end are its writers). */
+    accumulatedSuspendedMs?: number;
+    /** Set while an executing-verifying fix is inside a suspension (pause anchor). */
+    suspendStartedAtMs?: number;
+}
+/**
+ * The §4.5 recurrence bookkeeping — a sibling block that OUTLIVES episode close
+ * (R2-N2) so the reopen window has memory. All brakes on a budget-exempt HIGH
+ * path (M2) live here durably; an in-memory implementation would reset the
+ * brake at exactly the restart-heavy moment a boot-flag flap needs it.
+ */
+export interface RecurrenceBlock {
+    /** Rolling new-item open timestamps for the per-day cap (maxEpisodeItemsPerDay). */
+    newItemTimestamps: number[];
+    /** Recently-closed row-identity sets (+ the item id, so a reopen reuses the
+     *  SAME item/topic) — the reopenWindowMs memory. */
+    recentlyClosed: Array<{
+        rowIdentities: string[];
+        closedAtMs: number;
+        itemId?: string;
+    }>;
+    /** Episode-reopen flapping latch (flappingLatchReopens within the window). */
+    reopenLatch?: {
+        latched: boolean;
+        reopenCount: number;
+        windowStartMs: number;
+    };
+    /** Shared per-episode append budget (episodeAppendBudget within the window);
+     *  reservedSuspendResumeAtMs guarantees ONE slot per window for the first
+     *  suspend/resume transition (R4-L6). */
+    appendBudget?: {
+        appendTimestamps: number[];
+        latched: boolean;
+        reservedSuspendResumeAtMs?: number;
+    };
+    /** When the per-day-cap give-up note last fired (once per rolling 24 h). */
+    capGiveupAtMs?: number;
+}
+/** A §4.3 close reason — only `restored` may ever claim restoration. */
+export type EpisodeCloseReason = 'restored' | 'suspended-peer-offline' | 'suspended-peer-unverifiable' | 'expired-peer-gone' | 'superseded-by-takeover' | 'resolved-after-reenable' | 'manifest-changed' | 'state-rebaselined';
+/** The durable episode state (§4.1). `mc-<openedAtEpochMs>` id (N4). */
+export interface EpisodeState {
+    /** `mc-<openedAtMs>` — machine-local view id, minted per §4.1. */
+    episodeId: string;
+    openedAtMs: number;
+    /** The N1 skew-row identity set this episode covers (§3.4 match key). */
+    skewRowIdentities: string[];
+    /** When the ONE attention item was raised (R4-M1); absent until raised. */
+    itemRaisedAt?: number;
+    /** The item id (`machine-coherence:<episodeId>`), once raised. */
+    attentionItemId?: string;
+    /** Predecessor episode id cross-referenced on a §3.4 takeover (R2-M2). */
+    predecessorEpisodeId?: string;
+    /** Durable suspended flag (§4.3; stale-until-latch-exit per R4-N5). */
+    suspended?: boolean;
+    suspendReason?: 'peer-offline' | 'peer-unverifiable';
+    /** The durable operator "leave it" ack (R4-N2) — suppresses §4.4 escalation. */
+    operatorAck?: boolean;
+    /** The single in-flight fix (§4.2.1 cardinality — one per episode). */
+    pendingFix?: PendingFix;
+    /** The §4.4 escalation-append latch fired flag (one per episode). */
+    escalationAppended?: boolean;
+    /** Re-open count carried on the episode (§4.5 damper). */
+    reopenCount?: number;
+    recurrence: RecurrenceBlock;
+}
+/** The on-disk file shape: the open episode (or null) + the outliving recurrence. */
+export interface EpisodeFile {
+    version: 1;
+    /** The currently-open episode, or null between episodes (recurrence persists). */
+    episode: EpisodeState | null;
+    /** Outlives episode close — the reopen window's memory (R2-N2). */
+    recurrence: RecurrenceBlock;
+}
+/** The result of a durable read — absent / ok / corrupt (§4.6 re-baseline gate). */
+export type EpisodeReadResult = {
+    status: 'absent';
+} | {
+    status: 'ok';
+    file: EpisodeFile;
+} | {
+    status: 'corrupt';
+    reason: string;
+};
+/** Mint a machine-local episode id (§4.1, N4): `mc-<openedAtEpochMs>`. */
+export declare function mintEpisodeId(openedAtMs: number): string;
+/** The durable file path (N7 — per-agent `state/` subdir, never global). */
+export declare function episodeStatePath(stateDir: string): string;
+/** An empty recurrence block (fresh baseline / no prior memory). */
+export declare function emptyRecurrence(): RecurrenceBlock;
+/**
+ * Read the durable episode file, distinguishing absent / ok / corrupt so the
+ * caller can re-baseline WITHOUT crashing (§4.6, the GuardPostureProbe pattern).
+ * A structurally-invalid file (bad JSON, wrong version, missing required shape)
+ * returns `corrupt` with a named reason — never a throw, never a silent {}.
+ */
+export declare function readEpisodeFile(stateDir: string): EpisodeReadResult;
+/**
+ * Atomically write the durable episode file (§4.1 transition-write; mirrors
+ * `writeConfigAtomic`'s tmp+rename). The `state/` subdir is created if absent.
+ * Callers write on TRANSITIONS only — never per tick.
+ */
+export declare function writeEpisodeFile(stateDir: string, file: EpisodeFile): void;
+//# sourceMappingURL=machineCoherenceEpisode.d.ts.map

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

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

package/dist/monitoring/machineCoherenceEpisode.js

@@ -0,0 +1,92 @@
+/**
+ * Machine-coherence episode — the DURABLE state layer (machine-coherence-guard
+ * §4.1 + §4.6). Pure types + the persistence primitives only: episodeId
+ * minting, the atomic transition-write, and the read that distinguishes
+ * absent / ok / corrupt so the caller can re-baseline (N3/N4). The episode
+ * STATE MACHINE — open / join / suspend / resume / reopen / close / the
+ * pendingFix lifecycle / the recurrence damper (§4.2–§4.5) — is the CONSUMER
+ * of this layer and lands in the next sub-unit; nothing here raises, alarms,
+ * or transitions anything.
+ *
+ * Why a durable layer at all (§4.1): a server restart mid-episode must neither
+ * re-alarm nor forget. The file is written on state TRANSITIONS only (never
+ * per tick — confirm/resolve/verify COUNTERS stay in-memory, warm-up-absorbed,
+ * R2-N3); the recurrence block OUTLIVES episode close so the reopen window has
+ * memory (R2-N2).
+ *
+ * N7: `stateDir` is the per-agent state root — never a shared/global path.
+ * Supervision tier (N6): Tier 0 — deterministic file I/O, no LLM anywhere.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Mint a machine-local episode id (§4.1, N4): `mc-<openedAtEpochMs>`. */
+export function mintEpisodeId(openedAtMs) {
+    return `mc-${openedAtMs}`;
+}
+/** The durable file path (N7 — per-agent `state/` subdir, never global). */
+export function episodeStatePath(stateDir) {
+    return path.join(stateDir, 'state', 'machine-coherence-episode.json');
+}
+/** An empty recurrence block (fresh baseline / no prior memory). */
+export function emptyRecurrence() {
+    return { newItemTimestamps: [], recentlyClosed: [] };
+}
+/**
+ * Read the durable episode file, distinguishing absent / ok / corrupt so the
+ * caller can re-baseline WITHOUT crashing (§4.6, the GuardPostureProbe pattern).
+ * A structurally-invalid file (bad JSON, wrong version, missing required shape)
+ * returns `corrupt` with a named reason — never a throw, never a silent {}.
+ */
+export function readEpisodeFile(stateDir) {
+    const p = episodeStatePath(stateDir);
+    let raw;
+    try {
+        if (!fs.existsSync(p))
+            return { status: 'absent' };
+        raw = fs.readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        return { status: 'corrupt', reason: `read-failed: ${e.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { status: 'corrupt', reason: 'invalid-json' };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return { status: 'corrupt', reason: 'not-an-object' };
+    const obj = parsed;
+    if (obj.version !== 1)
+        return { status: 'corrupt', reason: `bad-version:${String(obj.version)}` };
+    if (!obj.recurrence || typeof obj.recurrence !== 'object')
+        return { status: 'corrupt', reason: 'missing-recurrence' };
+    const ep = obj.episode;
+    if (ep !== null && ep !== undefined) {
+        if (typeof ep !== 'object')
+            return { status: 'corrupt', reason: 'episode-not-object' };
+        const e = ep;
+        if (typeof e.episodeId !== 'string' || typeof e.openedAtMs !== 'number' || !Array.isArray(e.skewRowIdentities)) {
+            return { status: 'corrupt', reason: 'episode-shape' };
+        }
+    }
+    const rec = obj.recurrence;
+    if (!Array.isArray(rec.newItemTimestamps) || !Array.isArray(rec.recentlyClosed)) {
+        return { status: 'corrupt', reason: 'recurrence-shape' };
+    }
+    return { status: 'ok', file: obj };
+}
+/**
+ * Atomically write the durable episode file (§4.1 transition-write; mirrors
+ * `writeConfigAtomic`'s tmp+rename). The `state/` subdir is created if absent.
+ * Callers write on TRANSITIONS only — never per tick.
+ */
+export function writeEpisodeFile(stateDir, file) {
+    const p = episodeStatePath(stateDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n');
+    fs.renameSync(tmp, p);
+}
+//# sourceMappingURL=machineCoherenceEpisode.js.map

package/dist/monitoring/machineCoherenceEpisode.js.map

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

package/dist/monitoring/machineCoherenceEpisodeManager.d.ts

@@ -0,0 +1,210 @@
+/**
+ * MachineCoherenceEpisodeManager — the §4 episode STATE MACHINE
+ * (machine-coherence-guard §4.1–§4.4, §4.6). Consumes the durable state layer
+ * (`machineCoherenceEpisode.ts`) and the confirmed skew rows from the sentinel's
+ * §3.3 confirmation engine, and drives the ONE-item, honest-lifecycle,
+ * bounded-recurrence episode contract.
+ *
+ * SLICE STATUS (C₁b-iii-b lands in sub-units — see the side-effects artifact):
+ *   - THIS FILE (b1): open / join / suspend / resume / close taxonomy (§4.3:
+ *     restored / suspended-peer-offline|unverifiable / expired-peer-gone /
+ *     manifest-changed) + §4.4 single escalation + the operator "leave it" ack +
+ *     the §4.2 VERBATIM attention-item body render. Durable file owned here
+ *     (§4.6 corrupt → re-baseline). Emits EFFECTS the sentinel executes; the
+ *     raise/append/resolve effects are gated on selfIsRaiser && live posture
+ *     (dry-run + non-raiser run the machine + jsonl, never speak).
+ *   - NOT YET (b2): §4.5 recurrence damper + per-day cap + the R3-M5 SHARED
+ *     per-episode append budget (this slice's appends are unbudgeted).
+ *   - NOT YET (b3): the §4.2.1 pendingFix reply-recognition flow.
+ *
+ * Supervision tier (N6): Tier 0 — deterministic; no LLM anywhere in this path
+ * (reply recognition, when it lands in b3, lives in the CONVERSATIONAL agent,
+ * never here — D17 intact).
+ */
+import type { SkewRow } from './machineCoherenceEvaluate.js';
+import type { MachineCoherenceResolvedConfig } from './MachineCoherenceSentinel.js';
+import { type EpisodeCloseReason, type EpisodeState, type PendingFixState } from './machineCoherenceEpisode.js';
+/** One effect the sentinel/server executes (the manager never does I/O beyond
+ *  its own durable file + jsonl — telegram effects are the caller's). */
+export type EpisodeEffect = {
+    kind: 'raise';
+    itemId: string;
+    title: string;
+    summary: string;
+    description: string;
+} | {
+    kind: 'append';
+    itemId: string;
+    text: string;
+} | {
+    kind: 'resolve';
+    itemId: string;
+    note: string;
+} | {
+    kind: 'execute-fix';
+    itemId: string;
+    key: string;
+    configPath: string;
+    targetValue: string;
+};
+/** The result of an operator approval attempt (§4.2.1-i). */
+export interface FixApprovalResult {
+    ok: boolean;
+    /** Why an approval was refused (lapsed / not-verified / in-flight / no-fix). */
+    reason?: string;
+    /** The pendingFix state AFTER a successful transition. */
+    state?: PendingFixState;
+}
+/** Per-reconcile inputs the sentinel assembles from its classification pass. */
+export interface EpisodeReconcileInput {
+    /** The currently-CONFIRMED skew rows (§3.3 confirmation engine output). */
+    confirmedRows: SkewRow[];
+    /** Machine ids currently in the `compared` (fresh + clamp-passed) set. */
+    comparedMachineIds: Set<string>;
+    /** Machine ids currently registered ONLINE (compared ∪ unknown ∪ stale ∪ rejected). */
+    onlineMachineIds: Set<string>;
+    /** This machine's id. */
+    selfMachineId: string;
+    /** The §3.4 elected raiser (may be self, a peer, or null). */
+    raiserMachineId: string | null;
+    /** The serving-lease holder (direction tiebreak; restart-honesty clause). */
+    leaseHolderMachineId: string | null;
+    /** machineId → operator-facing nickname (registry display label; escaped at render). */
+    nicknameOf: (machineId: string) => string;
+    now: number;
+}
+/** Observability counters (surfaced on the sentinel status snapshot / route). */
+export interface EpisodeManagerCounters {
+    episodesOpened: number;
+    wouldRaise: number;
+    itemsRaised: number;
+    suspends: number;
+    resumes: number;
+    closes: Record<EpisodeCloseReason, number> | Record<string, number>;
+    escalations: number;
+}
+export declare class MachineCoherenceEpisodeManager {
+    private readonly stateDir;
+    private readonly cfg;
+    private file;
+    /** In-memory tick counters (R2-N3 — never persisted; warm-up-absorbed on restart). */
+    private resolveCleanTicks;
+    /** The last self machine id seen on reconcile (for approveFix's raiser==divergent check). */
+    private lastSelfMachineId;
+    /** The last nickname resolver seen on reconcile (for out-of-tick approveFix notes). */
+    private lastNicknameOf?;
+    /** In-memory verify-tick counter for an executing-verifying fix (§4.2.1-v). */
+    private fixVerifyTicks;
+    private counters;
+    private readonly logPath;
+    constructor(stateDir: string, cfg: MachineCoherenceResolvedConfig);
+    /** The item id for an episode (§4.2 — idempotent on the createAttentionItem chokepoint). */
+    private itemId;
+    /** Only the elected raiser on a LIVE (enabled && !dryRun) guard actually speaks. */
+    private speaks;
+    /**
+     * One reconcile pass (rides the sentinel tick, AFTER confirmation). Returns
+     * the effects the caller executes; the durable file + jsonl are written here.
+     */
+    reconcile(input: EpisodeReconcileInput): EpisodeEffect[];
+    private episodeParticipants;
+    /** A row's manifest key retired from the intersection (only meaningful for flag rows). */
+    private rowKeyRetired;
+    private anyEpisodeKeyStillCompared;
+    private openEpisode;
+    /** §4.5 reopen: a newly-confirmed skew intersecting a recently-closed episode
+     *  re-opens it — SAME item un-resolved + one short append, no new item (reopens
+     *  don't count toward the per-day cap). Latched-flapping bounds the appends. */
+    private reopenEpisode;
+    private maybeCapGiveup;
+    private joinRows;
+    private applySuspend;
+    /** Record the FIRST auto-proposable row as a `proposed` pendingFix (§4.2.1). A
+     *  version/manifest/protocol row (no config override to write) and the two
+     *  excluded flag classes (§4.2.1-iii) are NEVER auto-proposed. */
+    private maybeProposeFix;
+    /** Only FLAG rows carry a config override to equalize; the two §4.2.1-iii root
+     *  classes are excluded (manual decision block instead). */
+    private isAutoProposable;
+    /**
+     * Operator approval of the recorded proposal (§4.2.1-i). The caller (the
+     * conversational reply path) has ALREADY verified the sender is the topic's
+     * verified operator (Know Your Principal) and passes `verifiedOperator`; the
+     * `proposalHash` is the display-integrity authority (a reply confirms ONLY the
+     * exact recorded proposal). Returns the transition + (for divergent==raiser)
+     * an `execute-fix` effect the caller runs through the atomic config funnel.
+     */
+    approveFix(args: {
+        proposalHash: string;
+        verifiedOperator: boolean;
+        now: number;
+    }): {
+        result: FixApprovalResult;
+        effects: EpisodeEffect[];
+    };
+    /** Invalidate a NOT-YET-EXECUTED pendingFix (§4.2.1-i). An executing-verifying
+     *  fix is exempt (its durable write already happened — R5-N2). */
+    private invalidatePendingFix;
+    /** §4.2.1-v verify: an executing-verifying fix whose row hasn't cleared within
+     *  fixVerifyTicks fires ONE loud failure append + clears (episode stays open). */
+    private verifyPendingFix;
+    private nick;
+    /**
+     * §4.5 SHARED per-episode append budget (R3-M5): all intra-episode FLAP-class
+     * appends (row-join, suspend/resume, takeover re-arm) share one rolling budget
+     * (`episodeAppendBudget` per `episodeAppendWindowMs`). ONE slot is RESERVED per
+     * window for the first suspend/resume transition (R4-L6 — the clock-changing
+     * note is never crowded out). Past the budget the episode enters latched
+     * flapping: ONE "flapping — recording silently" note, then jsonl-only until the
+     * rolling count falls back below budget (R4-N3/L7). Structural appends
+     * (escalation, cap give-up) do NOT ride this budget.
+     */
+    private pushFlapAppend;
+    /** Lazy rolling-window eviction (R3-L2 — never triggers a write on its own). */
+    private pruneRecurrence;
+    private findReopenTarget;
+    private applyResume;
+    private maybeEscalate;
+    private closeEpisode;
+    private closeNote;
+    /**
+     * Set (or clear) the durable operator "leave it" ack (§4.2 / R4-N2). Called by
+     * the conversational reply path. Suppresses the §4.4 escalation for this
+     * episode; cleared on a genuine §4.5 recurrence re-open (b2).
+     */
+    setOperatorAck(ack: boolean): void;
+    /** A suspended episode past the expiry closes `expired-peer-gone` (§4.3). Called each tick by the sentinel. */
+    expireIfStale(now: number, nicknameOf: (m: string) => string): EpisodeEffect[];
+    status(): {
+        openEpisode: {
+            episodeId: string;
+            rows: number;
+            suspended: boolean;
+            itemRaisedAt: string | null;
+            pendingFix: {
+                state: PendingFixState;
+                key: string;
+                targetMachineId: string;
+                targetValue: string;
+                proposalHash: string;
+            } | null;
+        } | null;
+        counters: EpisodeManagerCounters;
+    };
+    /** The current proposal's hash (the reply-recognition authority), or null. */
+    currentProposalHash(): string | null;
+    private persist;
+    private log;
+    /**
+     * Render the §4.2 attention-item body VERBATIM (M9 — impact first, plain
+     * language; a fix the agent performs on approval; technical detail last). The
+     * peer-influenced strings (nicknames, effective values) are clamp-bounded
+     * upstream (§4.2 exposure invariant) — rendered as data, never instructions.
+     */
+    renderBody(input: EpisodeReconcileInput, ep: EpisodeState): {
+        title: string;
+        summary: string;
+        description: string;
+    };
+}
+//# sourceMappingURL=machineCoherenceEpisodeManager.d.ts.map

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

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