instar 1.3.365 → 1.3.367

package/dist/core/WorkingSetPullCoordinator.d.ts

@@ -0,0 +1,134 @@
+/**
+ * WorkingSetPullCoordinator — P2.2b of multi-machine coherence: the
+ * orchestration layer that makes the working-set transfer FIRE — on a topic
+ * move (the receiver's deliverMessage onAccepted seam), on demand (the
+ * reflex route), and on a returning producer (the staggered pending-pull
+ * drain).
+ *
+ * Spec: docs/specs/WORKING-SET-HANDOFF-SPEC.md §3.3 (trigger — receiver-side,
+ * epoch-gated, single-flight), §3.4 (durable pending-pull + staggered drain).
+ *
+ * Discipline (all inherited-invariant applications):
+ *  - Operation key (topic, epoch): at most one pull scheduled per key,
+ *    deduped against a DURABLE recent-key window (restart-proof).
+ *  - Skips: owner !== self (we are not the owner), owner === prevOwner
+ *    (placing-confirm, no real move), prevOwner === self (nothing to fetch
+ *    from ourselves).
+ *  - Single-flight per topic; ownership is rechecked inside the puller
+ *    before EVERY write (the stillCurrent seam).
+ *  - Nomination is PLURAL + bounded: every machine the journal (own +
+ *    replicas) shows as an artifact-producer for the topic, deduped, capped
+ *    at 3, most-recent-first — NOT "the prior owner". Replicas NOMINATE
+ *    only; each nominee's LIVE manifest is the authority.
+ *  - Staggered drain (§3.4): at most `rearmConcurrency` (default 1)
+ *    topic-pull in flight per returning peer — the EXO shape is ONE machine
+ *    holding MANY topics' files; N simultaneous pulls would slam a box that
+ *    just woke.
+ *  - Load-aware: scheduling defers under host pressure; the pull is always
+ *    async, NEVER in the message-delivery path.
+ */
+import type { CoherenceJournalReader } from './CoherenceJournalReader.js';
+import type { PendingPullLedger } from './PendingPullLedger.js';
+import type { PullReport, WorkingSetPuller } from './WorkingSetPull.js';
+export declare const DEFAULT_REARM_CONCURRENCY = 1;
+export declare const DEFAULT_NOMINEE_CAP = 3;
+/** Durable (topic,epoch) op-key window size — mirrors the journal's DEDUPE_WINDOW. */
+export declare const OPKEY_WINDOW = 200;
+/** Reflex route min interval per topic (rate limit; concurrent calls coalesce). */
+export declare const DEFAULT_REFLEX_MIN_INTERVAL_MS = 30000;
+export interface CoordinatorDeps {
+    /** Absolute path to the agent's `.instar/` directory. */
+    stateDir: string;
+    ownMachineId: string;
+    /** Merged own+replica journal reads — NOMINATION ONLY (Signal vs Authority). */
+    reader: CoherenceJournalReader;
+    ledger: PendingPullLedger;
+    /**
+     * Build a puller for one nominee peer (resolves its URL + signed client),
+     * or null when the peer is unknown/unreachable right now. topic+epoch are
+     * provided so the wiring can close the puller's stillCurrent recheck over
+     * the SCHEDULED epoch (§3.3 — ownership advanced → abort quietly).
+     */
+    makePuller: (nomineeMachineId: string, topic: number, epoch: number) => WorkingSetPuller | null;
+    /** Live ownership read — the ONLY actuation authority (§3.3). */
+    ownerOf: (topic: number) => {
+        owner: string | null;
+        epoch: number | null;
+    };
+    /** Host-pressure signal (§3.3 load-aware defer). Default: never. */
+    underPressure?: () => boolean;
+    rearmConcurrency?: number;
+    nomineeCap?: number;
+    reflexMinIntervalMs?: number;
+    now?: () => Date;
+    logger?: (msg: string) => void;
+}
+export interface FetchOutcome {
+    topic: number;
+    scheduled: boolean;
+    /** Why nothing was scheduled (dedupe/skip/pressure) — honest, counted. */
+    skipReason?: 'not-owner' | 'opkey-deduped' | 'no-producers' | 'in-flight-coalesced' | 'rate-limited' | 'pressure-deferred' | 'no-epoch';
+    /** Per-nominee pull reports (when the pull ran). */
+    reports?: {
+        nominee: string;
+        report: PullReport | null;
+        error?: string;
+    }[];
+    /** Journal-nominated producers that the cap excluded — named, not silent (§3.3). */
+    cappedNominees?: string[];
+}
+export declare class WorkingSetPullCoordinator {
+    private readonly d;
+    private readonly opKeyFile;
+    private opKeys;
+    /** Single-flight per topic — concurrent triggers coalesce onto one promise. */
+    private inFlight;
+    /** Per-peer drain gate (staggered re-arm, §3.4). */
+    private draining;
+    /** Reflex rate limit per topic. */
+    private lastReflexAt;
+    constructor(deps: CoordinatorDeps);
+    /**
+     * A forwarded message landed and THIS machine is (about to be) the owner.
+     * Fire-and-forget: never blocks message delivery. The epoch is read from
+     * the live ownership store; prevOwner evidence comes from the journal's
+     * placement history.
+     */
+    onTopicAccepted(topic: number): void;
+    /** The reflex (§3.3): POST /coherence/fetch-working-set — same pipeline, on demand. */
+    fetchWorkingSet(topic: number): Promise<FetchOutcome>;
+    /**
+     * Called when the presence pull records a peer online (every pass — the
+     * drain itself dedupes). Re-fires outstanding pending-pulls for that peer
+     * as a STAGGERED drain: at most rearmConcurrency in flight, the rest
+     * queued behind it most-recent-epoch-first.
+     */
+    onPeerRecorded(machineId: string): void;
+    private drainPeer;
+    private trigger;
+    private runPull;
+    private pullFromNominee;
+    /**
+     * Every machine the journal (own + replicas) shows as an autonomous-run
+     * producer for the topic, excluding self, deduped, most-recent-first,
+     * capped. Replicas NOMINATE only — the nominee's live manifest is the
+     * authority when the pull runs.
+     */
+    nominate(topic: number): {
+        nominees: string[];
+        capped: string[];
+    };
+    /** Previous owner from the journal's placement history (evidence, not authority). */
+    private prevOwnerOf;
+    private loadOpKeys;
+    private hasOpKey;
+    private recordOpKey;
+    /**
+     * TTL sweep + the run-stopped re-arm (§3.4): live-source records re-fire on
+     * a cadence — the pull itself is the live-ness check (a still-live run
+     * answers `liveSource` again and the record simply stays, attempt-free).
+     * Bounded: only existing live-source records for topics we still own.
+     */
+    sweep(): Promise<void>;
+}
+//# sourceMappingURL=WorkingSetPullCoordinator.d.ts.map

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

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

package/dist/core/WorkingSetPullCoordinator.js

@@ -0,0 +1,306 @@
+/**
+ * WorkingSetPullCoordinator — P2.2b of multi-machine coherence: the
+ * orchestration layer that makes the working-set transfer FIRE — on a topic
+ * move (the receiver's deliverMessage onAccepted seam), on demand (the
+ * reflex route), and on a returning producer (the staggered pending-pull
+ * drain).
+ *
+ * Spec: docs/specs/WORKING-SET-HANDOFF-SPEC.md §3.3 (trigger — receiver-side,
+ * epoch-gated, single-flight), §3.4 (durable pending-pull + staggered drain).
+ *
+ * Discipline (all inherited-invariant applications):
+ *  - Operation key (topic, epoch): at most one pull scheduled per key,
+ *    deduped against a DURABLE recent-key window (restart-proof).
+ *  - Skips: owner !== self (we are not the owner), owner === prevOwner
+ *    (placing-confirm, no real move), prevOwner === self (nothing to fetch
+ *    from ourselves).
+ *  - Single-flight per topic; ownership is rechecked inside the puller
+ *    before EVERY write (the stillCurrent seam).
+ *  - Nomination is PLURAL + bounded: every machine the journal (own +
+ *    replicas) shows as an artifact-producer for the topic, deduped, capped
+ *    at 3, most-recent-first — NOT "the prior owner". Replicas NOMINATE
+ *    only; each nominee's LIVE manifest is the authority.
+ *  - Staggered drain (§3.4): at most `rearmConcurrency` (default 1)
+ *    topic-pull in flight per returning peer — the EXO shape is ONE machine
+ *    holding MANY topics' files; N simultaneous pulls would slam a box that
+ *    just woke.
+ *  - Load-aware: scheduling defers under host pressure; the pull is always
+ *    async, NEVER in the message-delivery path.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_REARM_CONCURRENCY = 1;
+export const DEFAULT_NOMINEE_CAP = 3;
+/** Durable (topic,epoch) op-key window size — mirrors the journal's DEDUPE_WINDOW. */
+export const OPKEY_WINDOW = 200;
+/** Reflex route min interval per topic (rate limit; concurrent calls coalesce). */
+export const DEFAULT_REFLEX_MIN_INTERVAL_MS = 30_000;
+export class WorkingSetPullCoordinator {
+    d;
+    opKeyFile;
+    opKeys = null;
+    /** Single-flight per topic — concurrent triggers coalesce onto one promise. */
+    inFlight = new Map();
+    /** Per-peer drain gate (staggered re-arm, §3.4). */
+    draining = new Set();
+    /** Reflex rate limit per topic. */
+    lastReflexAt = new Map();
+    constructor(deps) {
+        this.d = deps;
+        this.opKeyFile = path.join(deps.stateDir, 'state', 'coherence-journal', 'pull-opkeys.json');
+    }
+    // ── The move trigger (§3.3) — called from the onAccepted seam ────────────
+    /**
+     * A forwarded message landed and THIS machine is (about to be) the owner.
+     * Fire-and-forget: never blocks message delivery. The epoch is read from
+     * the live ownership store; prevOwner evidence comes from the journal's
+     * placement history.
+     */
+    onTopicAccepted(topic) {
+        void this.trigger(topic, 'move').catch((e) => {
+            this.d.logger?.(`trigger failed for topic ${topic}: ${e instanceof Error ? e.message : String(e)}`);
+        });
+    }
+    /** The reflex (§3.3): POST /coherence/fetch-working-set — same pipeline, on demand. */
+    async fetchWorkingSet(topic) {
+        const nowMs = (this.d.now?.() ?? new Date()).getTime();
+        const last = this.lastReflexAt.get(topic) ?? 0;
+        const inflight = this.inFlight.get(topic);
+        if (inflight)
+            return inflight; // coalesce into the single-flight pull
+        if (nowMs - last < (this.d.reflexMinIntervalMs ?? DEFAULT_REFLEX_MIN_INTERVAL_MS)) {
+            return { topic, scheduled: false, skipReason: 'rate-limited' };
+        }
+        this.lastReflexAt.set(topic, nowMs);
+        // The reflex bypasses the (topic,epoch) op-key dedupe (an explicit ask
+        // re-fetches even when the move already pulled) but keeps every other
+        // gate — ownership, single-flight, nomination bounds.
+        return this.trigger(topic, 'reflex');
+    }
+    // ── The returning-peer drain (§3.4) ───────────────────────────────────────
+    /**
+     * Called when the presence pull records a peer online (every pass — the
+     * drain itself dedupes). Re-fires outstanding pending-pulls for that peer
+     * as a STAGGERED drain: at most rearmConcurrency in flight, the rest
+     * queued behind it most-recent-epoch-first.
+     */
+    onPeerRecorded(machineId) {
+        if (this.draining.has(machineId))
+            return; // a drain is already running
+        void this.drainPeer(machineId).catch((e) => {
+            this.d.logger?.(`drain failed for ${machineId}: ${e instanceof Error ? e.message : String(e)}`);
+        });
+    }
+    async drainPeer(machineId) {
+        const pending = await this.d.ledger.pendingForPeer(machineId);
+        if (!pending.length)
+            return;
+        this.draining.add(machineId);
+        try {
+            // Sequential (rearmConcurrency 1) most-recent-epoch-first — pendingForPeer
+            // pre-sorts. A >1 setting would batch; the default stays single-file.
+            for (const rec of pending) {
+                // Live-source records re-arm only when the producer's run has stopped —
+                // checked against the nominee's LIVE manifest by the pull itself (a
+                // still-live run answers liveSource and the record stays).
+                const { owner, epoch } = this.d.ownerOf(rec.topic);
+                if (owner !== this.d.ownMachineId) {
+                    // We no longer own the topic — the current owner's own pull covers
+                    // truth; clear our stale record.
+                    await this.d.ledger.clear(rec.topic, rec.epoch, rec.nominee);
+                    continue;
+                }
+                if (epoch != null && epoch > rec.epoch) {
+                    await this.d.ledger.supersede(rec.topic, epoch);
+                    continue;
+                }
+                await this.pullFromNominee(rec.topic, rec.epoch ?? 0, rec.nominee);
+            }
+        }
+        finally {
+            this.draining.delete(machineId);
+        }
+    }
+    // ── The shared pipeline ────────────────────────────────────────────────────
+    async trigger(topic, source) {
+        const existing = this.inFlight.get(topic);
+        if (existing)
+            return existing; // single-flight per topic (§3.3)
+        const { owner, epoch } = this.d.ownerOf(topic);
+        if (owner !== this.d.ownMachineId)
+            return { topic, scheduled: false, skipReason: 'not-owner' };
+        if (epoch == null)
+            return { topic, scheduled: false, skipReason: 'no-epoch' };
+        if (source === 'move') {
+            // Durable (topic,epoch) op-key dedupe — restart-proof (§3.3).
+            const key = `${topic}:${epoch}`;
+            if (this.hasOpKey(key))
+                return { topic, scheduled: false, skipReason: 'opkey-deduped' };
+            // Skip placing-confirms + self-moves via journal placement evidence.
+            const prevOwner = this.prevOwnerOf(topic, epoch);
+            if (prevOwner === this.d.ownMachineId) {
+                this.recordOpKey(key);
+                return { topic, scheduled: false, skipReason: 'no-producers' };
+            }
+            if (this.d.underPressure?.()) {
+                // Deferred, not dropped: file a pending-pull per nominee below would
+                // need nomination; the cheap honest defer is to leave the op-key
+                // unrecorded so the next accept (or the reflex) re-triggers.
+                return { topic, scheduled: false, skipReason: 'pressure-deferred' };
+            }
+            this.recordOpKey(key);
+        }
+        const run = this.runPull(topic, epoch);
+        this.inFlight.set(topic, run);
+        try {
+            return await run;
+        }
+        finally {
+            this.inFlight.delete(topic);
+        }
+    }
+    async runPull(topic, epoch) {
+        const { nominees, capped } = this.nominate(topic);
+        if (!nominees.length) {
+            return { topic, scheduled: false, skipReason: 'no-producers', ...(capped.length ? { cappedNominees: capped } : {}) };
+        }
+        const reports = [];
+        for (const nominee of nominees) {
+            const r = await this.pullFromNominee(topic, epoch, nominee);
+            reports.push(r);
+        }
+        return { topic, scheduled: true, reports, ...(capped.length ? { cappedNominees: capped } : {}) };
+    }
+    async pullFromNominee(topic, epoch, nominee) {
+        const puller = this.d.makePuller(nominee, topic, epoch);
+        if (!puller) {
+            await this.d.ledger.file_({ topic, epoch, nominee, reason: 'peer-unreachable' });
+            await this.d.ledger.recordAttempt(topic, epoch, nominee);
+            return { nominee, report: null, error: 'peer unreachable' };
+        }
+        try {
+            const report = await puller.pullTopic(topic);
+            if (report.needsPendingPull) {
+                // liveSource / busyExhausted / transport — durable record, re-fired
+                // on reappearance or run-stopped. busy does NOT consume an attempt.
+                const reason = report.files.some((f) => f.outcome === 'liveSourceDeferred')
+                    ? 'live-source'
+                    : report.files.some((f) => f.outcome === 'busyExhausted')
+                        ? 'busy-exhausted'
+                        : 'peer-unreachable';
+                await this.d.ledger.file_({ topic, epoch, nominee, reason });
+                if (reason === 'peer-unreachable') {
+                    await this.d.ledger.recordAttempt(topic, epoch, nominee); // genuine failure only
+                }
+            }
+            else {
+                await this.d.ledger.clear(topic, epoch, nominee);
+            }
+            return { nominee, report };
+        }
+        catch (e) {
+            await this.d.ledger.file_({ topic, epoch, nominee, reason: 'peer-unreachable' });
+            await this.d.ledger.recordAttempt(topic, epoch, nominee);
+            return { nominee, report: null, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    // ── Nomination (§3.3 — plural, bounded, journal-evidenced) ────────────────
+    /**
+     * Every machine the journal (own + replicas) shows as an autonomous-run
+     * producer for the topic, excluding self, deduped, most-recent-first,
+     * capped. Replicas NOMINATE only — the nominee's live manifest is the
+     * authority when the pull runs.
+     */
+    nominate(topic) {
+        const cap = this.d.nomineeCap ?? DEFAULT_NOMINEE_CAP;
+        let entries;
+        try {
+            entries = this.d.reader.query({ kind: 'autonomous-run', topic, limit: 100 }).entries;
+        }
+        catch (e) {
+            this.d.logger?.(`nomination read failed for topic ${topic}: ${e instanceof Error ? e.message : String(e)}`);
+            return { nominees: [], capped: [] };
+        }
+        const seen = new Set();
+        const ordered = [];
+        for (const e of entries) {
+            // newest-first already (reader merge order)
+            if (e.machine === this.d.ownMachineId || seen.has(e.machine))
+                continue;
+            seen.add(e.machine);
+            ordered.push(e.machine);
+        }
+        return { nominees: ordered.slice(0, cap), capped: ordered.slice(cap) };
+    }
+    /** Previous owner from the journal's placement history (evidence, not authority). */
+    prevOwnerOf(topic, epoch) {
+        try {
+            const entries = this.d.reader.query({ kind: 'topic-placement', topic, limit: 20 }).entries;
+            for (const e of entries) {
+                const data = e.data;
+                if (data.epoch === epoch && typeof data.prevOwner === 'string')
+                    return data.prevOwner;
+            }
+        }
+        catch { /* @silent-fallback-ok: missing placement evidence means no prevOwner skip — the pull proceeds and the manifest decides (WORKING-SET-HANDOFF-SPEC §3.3) */
+        }
+        return null;
+    }
+    // ── Durable (topic,epoch) op-key window (§3.3 — restart-proof) ────────────
+    loadOpKeys() {
+        if (this.opKeys)
+            return this.opKeys;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.opKeyFile, 'utf-8'));
+            this.opKeys = Array.isArray(parsed?.keys) ? parsed.keys.filter((k) => typeof k === 'string') : [];
+        }
+        catch { /* @silent-fallback-ok: an absent/corrupt op-key window only weakens dedupe for one pull (re-pull is idempotent via skippedExisting) — never a failure (WORKING-SET-HANDOFF-SPEC §3.3) */
+            this.opKeys = [];
+        }
+        return this.opKeys;
+    }
+    hasOpKey(key) {
+        return this.loadOpKeys().includes(key);
+    }
+    recordOpKey(key) {
+        const keys = this.loadOpKeys();
+        keys.push(key);
+        while (keys.length > OPKEY_WINDOW)
+            keys.shift();
+        try {
+            fs.mkdirSync(path.dirname(this.opKeyFile), { recursive: true });
+            const tmp = `${this.opKeyFile}.tmp-${process.pid}`;
+            fs.writeFileSync(tmp, JSON.stringify({ version: 1, keys }));
+            fs.renameSync(tmp, this.opKeyFile);
+        }
+        catch (e) { /* @silent-fallback-ok: a failed op-key persist only weakens dedupe across a restart (re-pull is idempotent); logged, never thrown (WORKING-SET-HANDOFF-SPEC §3.3) */
+            this.d.logger?.(`op-key persist failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // ── The slow tick (the server calls this every ~10 min) ───────────────────
+    /**
+     * TTL sweep + the run-stopped re-arm (§3.4): live-source records re-fire on
+     * a cadence — the pull itself is the live-ness check (a still-live run
+     * answers `liveSource` again and the record simply stays, attempt-free).
+     * Bounded: only existing live-source records for topics we still own.
+     */
+    async sweep() {
+        await this.d.ledger.sweepExpired();
+        const all = await this.d.ledger.all();
+        for (const rec of all) {
+            if (rec.reason !== 'live-source')
+                continue;
+            const { owner, epoch } = this.d.ownerOf(rec.topic);
+            if (owner !== this.d.ownMachineId) {
+                await this.d.ledger.clear(rec.topic, rec.epoch, rec.nominee);
+                continue;
+            }
+            if (epoch != null && epoch > rec.epoch) {
+                await this.d.ledger.supersede(rec.topic, epoch);
+                continue;
+            }
+            await this.pullFromNominee(rec.topic, rec.epoch, rec.nominee);
+        }
+    }
+}
+//# sourceMappingURL=WorkingSetPullCoordinator.js.map

package/dist/core/WorkingSetPullCoordinator.js.map

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

package/dist/core/types.d.ts

@@ -1795,11 +1795,36 @@ export interface CoherenceJournalUserConfig {
     flushIntervalMs?: number;
     /** Autonomous-run journal scanner cadence (§3.3). Default 60s. */
     scannerIntervalMs?: number;
-    /** Replication tunables; `enabled` follows the same dark-ship gate. */
+    /**
+     * Replication tunables. NOTE: replication SEND/drive requires the EXPLICIT
+     * `enabled === true` (never the `?? developmentAgent` dark-ship gate) — and
+     * the working-set feature below activates IFF this same gate is on
+     * (WORKING-SET-HANDOFF-SPEC §3.7: the pull is meaningless without
+     * replication's mesh path and must never out-activate it).
+     */
     replication?: {
         enabled?: boolean;
         maxBatchBytes?: number;
     };
+    /**
+     * Working-Set Handoff tunables (WORKING-SET-HANDOFF-SPEC §3.7). All
+     * optional; ConfigDefaults carries the shipped literal. Gated on
+     * `replication.enabled === true` — there is no separate enable flag.
+     */
+    workingSet?: {
+        maxFileBytes?: number;
+        headlineFileBytes?: number;
+        maxFiles?: number;
+        maxTotalBytes?: number;
+        pullMaxBatchBytes?: number;
+        pullOnMove?: boolean;
+        pendingPullTtlDays?: number;
+        chunkRestartCap?: number;
+        chunksPerTick?: number;
+        serveConcurrency?: number;
+        rearmConcurrency?: number;
+        busyRetryCap?: number;
+    };
     /**
      * Per-kind retention. rotateKeep N>0 = rotate at maxFileBytes, keep N
      * archives, delete older; 0 = rotate at maxFileBytes but NEVER delete
@@ -3520,6 +3545,23 @@ export interface MonitoringConfig {
         /** Master kill switch (default: false). Gates the observe-only check entirely. */
         enabled: boolean;
     };
+    /**
+     * Phase-2 LLM judge for ORG-INTENT governance verdicts (CMT-1128). When
+     * enabled AND an intelligence provider is configured, a keyword-heuristic
+     * MISS on POST /intent/org/test-action escalates to one bounded LLM call
+     * that judges the action against the constraints by MEANING — closing the
+     * keyword matcher's false-negative side (semantically-related constraints
+     * whose wording differs). Verdicts carry their method ('llm-judge' only for
+     * a real, parsed LLM verdict; judge problems keep the heuristic verdict and
+     * say so). Signal-only — the route answers a question, never blocks. Ships
+     * DARK (default false).
+     */
+    orgIntentLlmJudge?: {
+        /** Master kill switch (default: false). */
+        enabled: boolean;
+        /** Per-judge-call timeout in ms (default: 8000). */
+        timeoutMs?: number;
+    };
     /**
      * ApprenticeshipCycleSlaMonitor — observe-only signal for open apprenticeship
      * differential cycles older than the configured SLA. Ships OFF; when enabled