instar 1.3.719 → 1.3.720

package/dist/core/SustainedOnlineTracker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SustainedOnlineTracker — U4.1 §2E hysteresis input ("pin persistence",
+ * docs/specs/u4-1-pin-persistence.md).
+ *
+ * Answers ONE question for pin-driven actuation: "has this machine been
+ * CONTINUOUSLY online for at least the sustained window?" — the anti-flap
+ * gate that keeps a returning-but-flapping pinned machine from triggering
+ * transfer ping-pong (mirror of U4.4's hysteresis), and keeps Case-A
+ * cooperative transfers from initiating toward a machine that only just
+ * blinked online (R-r2-2: the transfer→abort churn loop).
+ *
+ * Feeding: `observe(machines)` is called on the reconciler tick cadence with
+ * the live pool view. A machine seen online starts (or continues) its
+ * online-since clock; seen offline/absent resets it.
+ *
+ * Boot honesty (deliberate fail-open): the tracker cannot distinguish
+ * "stable for hours" from "just flapped on" until it has watched for at
+ * least one full window. While its own observation history is younger than
+ * the queried window, `sustainedOnline` falls back to the CURRENT online
+ * bit (today's behavior) — otherwise every pinned placement would queue for
+ * the window length after every boot, a routine-latency regression the
+ * anti-flap gate was never meant to buy. After the tracker has ≥ window of
+ * history the gate is fully meaningful.
+ */
+export interface SustainedOnlineView {
+    machineId: string;
+    online: boolean;
+}
+export declare class SustainedOnlineTracker {
+    /** machineId → epoch-ms the machine was first seen online in its CURRENT unbroken online run. */
+    private readonly onlineSince;
+    private readonly now;
+    /** When this tracker started observing (the boot fail-open boundary). */
+    private readonly trackingSince;
+    constructor(deps?: {
+        now?: () => number;
+    });
+    /** Fold one live pool view into the online-run clocks. */
+    observe(machines: ReadonlyArray<SustainedOnlineView>): void;
+    /**
+     * Has `machineId` been continuously online for ≥ `windowMs`?
+     * Boot fail-open: while the tracker's own history is younger than the
+     * window, this degrades to "is it online right now" (see header).
+     */
+    sustainedOnline(machineId: string, windowMs: number): boolean;
+}
+//# sourceMappingURL=SustainedOnlineTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SustainedOnlineTracker.d.ts","sourceRoot":"","sources":["../../src/core/SustainedOnlineTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,sBAAsB;IACjC,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAK7C,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAc3D;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;CAO9D"}

package/dist/core/SustainedOnlineTracker.js

@@ -0,0 +1,67 @@
+/**
+ * SustainedOnlineTracker — U4.1 §2E hysteresis input ("pin persistence",
+ * docs/specs/u4-1-pin-persistence.md).
+ *
+ * Answers ONE question for pin-driven actuation: "has this machine been
+ * CONTINUOUSLY online for at least the sustained window?" — the anti-flap
+ * gate that keeps a returning-but-flapping pinned machine from triggering
+ * transfer ping-pong (mirror of U4.4's hysteresis), and keeps Case-A
+ * cooperative transfers from initiating toward a machine that only just
+ * blinked online (R-r2-2: the transfer→abort churn loop).
+ *
+ * Feeding: `observe(machines)` is called on the reconciler tick cadence with
+ * the live pool view. A machine seen online starts (or continues) its
+ * online-since clock; seen offline/absent resets it.
+ *
+ * Boot honesty (deliberate fail-open): the tracker cannot distinguish
+ * "stable for hours" from "just flapped on" until it has watched for at
+ * least one full window. While its own observation history is younger than
+ * the queried window, `sustainedOnline` falls back to the CURRENT online
+ * bit (today's behavior) — otherwise every pinned placement would queue for
+ * the window length after every boot, a routine-latency regression the
+ * anti-flap gate was never meant to buy. After the tracker has ≥ window of
+ * history the gate is fully meaningful.
+ */
+export class SustainedOnlineTracker {
+    /** machineId → epoch-ms the machine was first seen online in its CURRENT unbroken online run. */
+    onlineSince = new Map();
+    now;
+    /** When this tracker started observing (the boot fail-open boundary). */
+    trackingSince;
+    constructor(deps = {}) {
+        this.now = deps.now ?? Date.now;
+        this.trackingSince = this.now();
+    }
+    /** Fold one live pool view into the online-run clocks. */
+    observe(machines) {
+        const t = this.now();
+        const seenOnline = new Set();
+        for (const m of machines) {
+            if (!m.online)
+                continue;
+            seenOnline.add(m.machineId);
+            if (!this.onlineSince.has(m.machineId))
+                this.onlineSince.set(m.machineId, t);
+        }
+        // A machine reported offline — or absent from the view — breaks its run.
+        for (const id of [...this.onlineSince.keys()]) {
+            if (!seenOnline.has(id))
+                this.onlineSince.delete(id);
+        }
+    }
+    /**
+     * Has `machineId` been continuously online for ≥ `windowMs`?
+     * Boot fail-open: while the tracker's own history is younger than the
+     * window, this degrades to "is it online right now" (see header).
+     */
+    sustainedOnline(machineId, windowMs) {
+        const since = this.onlineSince.get(machineId);
+        if (since === undefined)
+            return false; // not online right now — never sustained
+        const t = this.now();
+        if (t - this.trackingSince < windowMs)
+            return true; // fail-open boot window (online now)
+        return t - since >= windowMs;
+    }
+}
+//# sourceMappingURL=SustainedOnlineTracker.js.map

package/dist/core/SustainedOnlineTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SustainedOnlineTracker.js","sourceRoot":"","sources":["../../src/core/SustainedOnlineTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,MAAM,OAAO,sBAAsB;IACjC,iGAAiG;IAChF,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,GAAG,CAAe;IACnC,yEAAyE;IACxD,aAAa,CAAS;IAEvC,YAAY,OAA+B,EAAE;QAC3C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClC,CAAC;IAED,0DAA0D;IAC1D,OAAO,CAAC,QAA4C;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,CAAC,CAAC,MAAM;gBAAE,SAAS;YACxB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;gBAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,yEAAyE;QACzE,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,SAAiB,EAAE,QAAgB;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,CAAC,yCAAyC;QAChF,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,GAAG,QAAQ;YAAE,OAAO,IAAI,CAAC,CAAC,qCAAqC;QACzF,OAAO,CAAC,GAAG,KAAK,IAAI,QAAQ,CAAC;IAC/B,CAAC;CACF"}

package/dist/core/TopicPinFoldView.d.ts

@@ -0,0 +1,138 @@
+/**
+ * TopicPinFoldView — the STATEFUL answer-complete advisory-pin read
+ * (U4.1 §2C, docs/specs/u4-1-pin-persistence.md; R-r2-3 / R-r2-1 / R-r3-1 /
+ * R-r3-2).
+ *
+ * Replaces the `query({ kind: 'topic-pin-record', limit: 2000 })` newest-tail
+ * read (silently clamped to 500 by `READER_MAX_LIMIT`) with:
+ *
+ *  1. A BOOT-TIME FULL-STREAM FOLD over every retained `topic-pin-record`
+ *     entry — active file + archives, own stream AND every peer-replica
+ *     stream — into a per-key latest map by HLC (tombstone-respecting: a
+ *     winning delete stays in the map so a late-arriving OLDER put can never
+ *     resurrect the pin).
+ *  2. An INCREMENTAL OFFSET-TRACKED TAIL after boot: each refresh re-scans
+ *     only appended bytes (TokenLedgerPoller pattern); an unchanged journal
+ *     costs zero re-read; re-scans are idempotent (same records → same
+ *     winners).
+ *  3. The HLC SKEW GATE (fixes defect 6; R-r2-1): every record HLC passes
+ *     through the existing `HybridLogicalClock.receive()` contract (clamped
+ *     maxDriftMs). A future-skewed record is REJECTED FROM THE FOLD — never
+ *     merged, never able to win `compareHlc` — and quarantined STICKILY +
+ *     DURABLY via TopicPinSkewQuarantine (R-r3-2: the moving wall-clock
+ *     reference must never silently un-quarantine it). The fold-side gate is
+ *     the SOLE skew-exclusion authority (R-r3-1) — the JournalSyncApplier
+ *     deliberately ACCEPTS-AND-PERSISTS a skewed record, because its only
+ *     per-entry refusal path would suspect-halt the peer's ENTIRE stream.
+ *  4. The FOLD BYTE-GUARD (`ws13FoldMaxBytes`, R-r3-3): on breach the fold
+ *     reads newest-first up to the budget and LOUDLY escalates (ONE deduped
+ *     `u41:pin-fold-truncated` item naming the unfolded ranges) — never a
+ *     silent truncation. The episode closes when a full fold completes
+ *     within budget.
+ *
+ * Read-only over journal bytes; it actuates NOTHING (consumers are wired via
+ * server.ts closures exactly like the old tail read — the actuation-ban lint
+ * posture is unchanged).
+ */
+import { type HlcTimestamp } from './HybridLogicalClock.js';
+import { type MergedReplicatedPin } from './TopicPinReplicatedStore.js';
+import type { PinFoldOffsets, PinFoldResult } from './CoherenceJournalReader.js';
+import type { TopicPinSkewQuarantine } from './TopicPinSkewQuarantine.js';
+import type { TopicPlacement } from './PlacementExecutor.js';
+/** The reader seam (CoherenceJournalReader.foldPinRecords — injectable for tests). */
+export interface PinFoldReader {
+    foldPinRecords(opts: {
+        priorOffsets?: PinFoldOffsets;
+        maxBytes?: number;
+    }): PinFoldResult;
+}
+export interface TopicPinFoldViewDeps {
+    reader: PinFoldReader;
+    quarantine: TopicPinSkewQuarantine;
+    /** This machine's mesh id (late-bound; used as the fold clock's node id). */
+    selfNode: () => string | null;
+    /** The clamped HLC drift ceiling (§2C reuses the existing knob — no new key). */
+    maxDriftMs?: number;
+    /** ws13FoldMaxBytes, read live (default 64MB upstream). */
+    foldMaxBytes?: () => number;
+    /** Optional observed pool-relative physical-time floor (heartbeat median). */
+    poolReference?: () => number | undefined;
+    now?: () => number;
+    /** Fired ONCE per newly-quarantined record (upstream dedupes per-origin, P17). */
+    onSkewQuarantined?: (rec: {
+        key: string;
+        hlc: HlcTimestamp;
+        origin: string;
+    }) => void;
+    /** Fired ONCE per truncation EPISODE (byte-guard breach) with the unfolded ranges. */
+    onFoldTruncated?: (unfolded: Array<{
+        file: string;
+        fromByte: number;
+        toByte: number;
+    }>) => void;
+    /** Fired when a full fold completes within budget after a breach (episode close). */
+    onFoldRecovered?: () => void;
+    log?: (msg: string) => void;
+}
+export declare class TopicPinFoldView {
+    private readonly d;
+    /** Per-key HLC winner (puts AND tombstones — tombstone-respecting by construction). */
+    private readonly winners;
+    private offsets;
+    private clock;
+    private truncationEpisodeOpen;
+    private lastFoldAtMs;
+    private lastScannedBytes;
+    private totalFolds;
+    constructor(deps: TopicPinFoldViewDeps);
+    private now;
+    private foldClock;
+    /**
+     * Fold newly-appended journal bytes into the winner map. The FIRST call is
+     * the boot-time full-stream fold (offsets start empty); later calls are the
+     * incremental offset-tracked tail. Never throws (a fold fault leaves the
+     * last-good map serving — the next refresh retries).
+     */
+    refresh(): void;
+    /**
+     * The merged advisory pins (the §2C second pass — mirrors
+     * `mergeUnionToPins`): a winning tombstone or `pinned:false` put yields NO
+     * pin; a valid winning put yields one advisory pin carrying its HLC.
+     */
+    pins(): Map<number, MergedReplicatedPin>;
+    /** The fold pin as placement metadata for NEW placements (§2D seeding): the
+     *  hard-pin path handles an offline target honestly (queued, never re-routed),
+     *  so the pin is surfaced whenever a valid winner exists. */
+    asTopicMetadata(sessionKey: string): TopicPlacement | undefined;
+    /**
+     * §2D placement seeding with the FULL local-vs-replicated resolution (the
+     * N3 rule at the placement door): the LOCAL pin and the fold winner compare
+     * by HLC — a stale local pin never masks a fresher replicated move-intent,
+     * and a fresher replicated TOMBSTONE suppresses a stale local pin (the
+     * defect-2 fix applied to NEW placements, not just the reconciler). A local
+     * pin without an HLC uses the documented `updatedAt` fallback derivation.
+     */
+    effectiveTopicMetadata(sessionKey: string, local: {
+        preferredMachine: string;
+        pinned: boolean;
+        updatedAt: string;
+        hlc?: HlcTimestamp;
+    } | null): TopicPlacement | undefined;
+    /**
+     * Force the NEXT refresh to be a full-stream re-fold (offsets + winners
+     * cleared). Used by the explicit per-record re-admission surface (R-r4-1):
+     * a re-admitted record's bytes were already consumed by the incremental
+     * tail, so only a full re-fold can bring it back into the comparison.
+     */
+    resetFold(): void;
+    /** Read-only observability (route/status surfaces). */
+    status(): {
+        lastFoldAt: string | null;
+        totalFolds: number;
+        lastScannedBytes: number;
+        recordKeys: number;
+        truncationEpisodeOpen: boolean;
+        quarantined: number;
+    };
+}
+//# sourceMappingURL=TopicPinFoldView.d.ts.map

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

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

package/dist/core/TopicPinFoldView.js

@@ -0,0 +1,235 @@
+/**
+ * TopicPinFoldView — the STATEFUL answer-complete advisory-pin read
+ * (U4.1 §2C, docs/specs/u4-1-pin-persistence.md; R-r2-3 / R-r2-1 / R-r3-1 /
+ * R-r3-2).
+ *
+ * Replaces the `query({ kind: 'topic-pin-record', limit: 2000 })` newest-tail
+ * read (silently clamped to 500 by `READER_MAX_LIMIT`) with:
+ *
+ *  1. A BOOT-TIME FULL-STREAM FOLD over every retained `topic-pin-record`
+ *     entry — active file + archives, own stream AND every peer-replica
+ *     stream — into a per-key latest map by HLC (tombstone-respecting: a
+ *     winning delete stays in the map so a late-arriving OLDER put can never
+ *     resurrect the pin).
+ *  2. An INCREMENTAL OFFSET-TRACKED TAIL after boot: each refresh re-scans
+ *     only appended bytes (TokenLedgerPoller pattern); an unchanged journal
+ *     costs zero re-read; re-scans are idempotent (same records → same
+ *     winners).
+ *  3. The HLC SKEW GATE (fixes defect 6; R-r2-1): every record HLC passes
+ *     through the existing `HybridLogicalClock.receive()` contract (clamped
+ *     maxDriftMs). A future-skewed record is REJECTED FROM THE FOLD — never
+ *     merged, never able to win `compareHlc` — and quarantined STICKILY +
+ *     DURABLY via TopicPinSkewQuarantine (R-r3-2: the moving wall-clock
+ *     reference must never silently un-quarantine it). The fold-side gate is
+ *     the SOLE skew-exclusion authority (R-r3-1) — the JournalSyncApplier
+ *     deliberately ACCEPTS-AND-PERSISTS a skewed record, because its only
+ *     per-entry refusal path would suspect-halt the peer's ENTIRE stream.
+ *  4. The FOLD BYTE-GUARD (`ws13FoldMaxBytes`, R-r3-3): on breach the fold
+ *     reads newest-first up to the budget and LOUDLY escalates (ONE deduped
+ *     `u41:pin-fold-truncated` item naming the unfolded ranges) — never a
+ *     silent truncation. The episode closes when a full fold completes
+ *     within budget.
+ *
+ * Read-only over journal bytes; it actuates NOTHING (consumers are wired via
+ * server.ts closures exactly like the old tail read — the actuation-ban lint
+ * posture is unchanged).
+ */
+import { HybridLogicalClock, coerceHlc } from './HybridLogicalClock.js';
+import { compareHlc, isValidPinMachineId } from './TopicPinReplicatedStore.js';
+export class TopicPinFoldView {
+    d;
+    /** Per-key HLC winner (puts AND tombstones — tombstone-respecting by construction). */
+    winners = new Map();
+    offsets = {};
+    clock = null;
+    truncationEpisodeOpen = false;
+    lastFoldAtMs = 0;
+    lastScannedBytes = 0;
+    totalFolds = 0;
+    constructor(deps) {
+        this.d = deps;
+    }
+    now() {
+        return (this.d.now ?? Date.now)();
+    }
+    foldClock() {
+        if (!this.clock) {
+            this.clock = new HybridLogicalClock({
+                node: this.d.selfNode() ?? 'pin-fold',
+                now: this.d.now ?? Date.now,
+                ...(this.d.maxDriftMs !== undefined ? { maxDriftMs: this.d.maxDriftMs } : {}),
+            });
+        }
+        return this.clock;
+    }
+    /**
+     * Fold newly-appended journal bytes into the winner map. The FIRST call is
+     * the boot-time full-stream fold (offsets start empty); later calls are the
+     * incremental offset-tracked tail. Never throws (a fold fault leaves the
+     * last-good map serving — the next refresh retries).
+     */
+    refresh() {
+        let res;
+        try {
+            res = this.d.reader.foldPinRecords({
+                priorOffsets: this.offsets,
+                ...(this.d.foldMaxBytes ? { maxBytes: this.d.foldMaxBytes() } : {}),
+            });
+        }
+        catch (err) {
+            this.d.log?.(`[TopicPinFoldView] fold failed (serving last-good map): ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        this.offsets = res.offsets;
+        this.lastFoldAtMs = this.now();
+        this.lastScannedBytes = res.scannedBytes;
+        this.totalFolds++;
+        const clock = this.foldClock();
+        for (const entry of res.entries) {
+            const recordKey = typeof entry.data.recordKey === 'string' ? entry.data.recordKey : null;
+            if (recordKey === null)
+                continue;
+            let hlc;
+            try {
+                hlc = coerceHlc(entry.data.hlc);
+            }
+            catch {
+                continue; // malformed hlc — schema-reject class, never a winner
+            }
+            // Sticky exclusion FIRST (R-r3-2): a quarantined (key, hlc) stays excluded
+            // regardless of clock progress — the moving receive() reference must never
+            // silently re-admit it.
+            if (this.d.quarantine.has(recordKey, hlc))
+                continue;
+            // The skew gate (R-r2-1): the existing receive() contract. Rejection ⇒
+            // durable quarantine + loud (deduped upstream) escalation; NEVER merged.
+            const poolReference = this.d.poolReference?.();
+            const received = clock.receive(hlc, poolReference !== undefined ? { poolReference } : {});
+            if (received.rejected) {
+                const newlyAdded = this.d.quarantine.add({ key: recordKey, hlc, origin: entry.origin });
+                if (newlyAdded) {
+                    this.d.log?.(`[TopicPinFoldView] skew-quarantined pin record key=${recordKey} origin=${entry.origin} (physical ${hlc.physical} > reference ${received.reference} + ${received.maxDriftMs}ms)`);
+                    try {
+                        this.d.onSkewQuarantined?.({ key: recordKey, hlc, origin: entry.origin });
+                    }
+                    catch { /* escalation is observability — never gates the fold */ }
+                }
+                continue;
+            }
+            const cur = this.winners.get(recordKey);
+            if (!cur || compareHlc(hlc, cur.hlc) > 0) {
+                this.winners.set(recordKey, { data: entry.data, origin: entry.origin, hlc });
+                // Honest supersession (R-r3-2): a newer honest record makes older
+                // quarantined entries for the key dead by ordering — prune them.
+                try {
+                    this.d.quarantine.pruneSuperseded(recordKey, hlc);
+                }
+                catch { /* prune is hygiene — never gates */ }
+            }
+        }
+        // Byte-guard episode (R-r3-3): raise ONCE per episode; close on a clean full fold.
+        if (res.truncated) {
+            if (!this.truncationEpisodeOpen) {
+                this.truncationEpisodeOpen = true;
+                try {
+                    this.d.onFoldTruncated?.(res.unfolded);
+                }
+                catch { /* escalation never gates */ }
+            }
+        }
+        else if (this.truncationEpisodeOpen) {
+            this.truncationEpisodeOpen = false;
+            try {
+                this.d.onFoldRecovered?.();
+            }
+            catch { /* episode close is observability */ }
+        }
+    }
+    /**
+     * The merged advisory pins (the §2C second pass — mirrors
+     * `mergeUnionToPins`): a winning tombstone or `pinned:false` put yields NO
+     * pin; a valid winning put yields one advisory pin carrying its HLC.
+     */
+    pins() {
+        const out = new Map();
+        for (const [recordKey, w] of this.winners) {
+            if (w.data.op === 'delete')
+                continue;
+            if (w.data.pinned !== true)
+                continue;
+            const topic = Number(recordKey);
+            if (!Number.isFinite(topic))
+                continue;
+            if (!isValidPinMachineId(w.data.preferredMachine))
+                continue;
+            out.set(topic, { topic, preferredMachine: w.data.preferredMachine, pinned: true, origin: w.origin, hlc: w.hlc });
+        }
+        return out;
+    }
+    /** The fold pin as placement metadata for NEW placements (§2D seeding): the
+     *  hard-pin path handles an offline target honestly (queued, never re-routed),
+     *  so the pin is surfaced whenever a valid winner exists. */
+    asTopicMetadata(sessionKey) {
+        const topic = Number(sessionKey);
+        if (!Number.isFinite(topic))
+            return undefined;
+        const pin = this.pins().get(topic);
+        return pin ? { preferredMachine: pin.preferredMachine, pinned: true } : undefined;
+    }
+    /**
+     * §2D placement seeding with the FULL local-vs-replicated resolution (the
+     * N3 rule at the placement door): the LOCAL pin and the fold winner compare
+     * by HLC — a stale local pin never masks a fresher replicated move-intent,
+     * and a fresher replicated TOMBSTONE suppresses a stale local pin (the
+     * defect-2 fix applied to NEW placements, not just the reconciler). A local
+     * pin without an HLC uses the documented `updatedAt` fallback derivation.
+     */
+    effectiveTopicMetadata(sessionKey, local) {
+        const localMeta = local
+            ? { preferredMachine: local.preferredMachine, pinned: local.pinned }
+            : undefined;
+        const topic = Number(sessionKey);
+        const winner = Number.isFinite(topic) ? this.winners.get(String(topic)) : undefined;
+        if (!winner)
+            return localMeta;
+        const localHlc = local
+            ? (local.hlc ?? { physical: Date.parse(local.updatedAt) || 0, logical: 0, node: '' })
+            : null;
+        if (localHlc && compareHlc(localHlc, winner.hlc) >= 0)
+            return localMeta; // local is newer-or-equal
+        // The fold winner is newer: a tombstone / pinned:false resolves to NO pin
+        // (a stale local pin must not resurrect a cleared one); a valid put wins.
+        if (winner.data.op === 'delete' || winner.data.pinned !== true)
+            return undefined;
+        if (!isValidPinMachineId(winner.data.preferredMachine))
+            return localMeta;
+        return { preferredMachine: winner.data.preferredMachine, pinned: true };
+    }
+    /**
+     * Force the NEXT refresh to be a full-stream re-fold (offsets + winners
+     * cleared). Used by the explicit per-record re-admission surface (R-r4-1):
+     * a re-admitted record's bytes were already consumed by the incremental
+     * tail, so only a full re-fold can bring it back into the comparison.
+     */
+    resetFold() {
+        this.offsets = {};
+        this.winners.clear();
+    }
+    /** Read-only observability (route/status surfaces). */
+    status() {
+        let quarantined = 0;
+        try {
+            quarantined = this.d.quarantine.all().length;
+        }
+        catch { /* best-effort */ }
+        return {
+            lastFoldAt: this.lastFoldAtMs ? new Date(this.lastFoldAtMs).toISOString() : null,
+            totalFolds: this.totalFolds,
+            lastScannedBytes: this.lastScannedBytes,
+            recordKeys: this.winners.size,
+            truncationEpisodeOpen: this.truncationEpisodeOpen,
+            quarantined,
+        };
+    }
+}
+//# sourceMappingURL=TopicPinFoldView.js.map

package/dist/core/TopicPinFoldView.js.map

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

package/dist/core/TopicPinMutation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TopicPinMutation — the ONE-HLC pin mutation funnel (U4.1 §2B,
+ * docs/specs/u4-1-pin-persistence.md).
+ *
+ * THE CONTRACT (R-r2): every pin mutation mints ONE HLC and stamps BOTH the
+ * local `TopicPlacementPinStore.set()/clear()` AND the replicated journal
+ * emit (`buildTopicPinPut` / `buildTopicPinTombstone`) with that same stamp.
+ * The transfer route previously called `set()` WITHOUT the `hlc` argument
+ * (the routes.ts gap) — the local-vs-replicated comparison then degraded to a
+ * derived wall-clock and HLC-highest-wins was a symbol, not the state.
+ *
+ * UNPIN (fixes defect 2 — the live un-pin propagation bug): `clearPin` wires
+ * the previously ZERO-caller `buildTopicPinTombstone` at the clear()
+ * chokepoint, so a cleared pin can never be resurrected by a stale replicated
+ * PUT (`effectivePins()` / the fold honor tombstones by HLC order). A later
+ * re-pin is the same key with a newer HLC — the store's documented model.
+ *
+ * The emitter mints the HLC (its `clock.tick()` is the author-side authority);
+ * the funnel CAPTURES the minted stamp from inside the build closure and hands
+ * it to the local store. When emission is dark (`ws13PinReplicate` off /
+ * single-machine) the build closure never runs → no stamp is minted → the
+ * local write proceeds without one (today's exact behavior; the reconciler's
+ * documented `updatedAt` fallback derivation covers it).
+ */
+import type { HlcTimestamp } from './HybridLogicalClock.js';
+import type { TopicPlacementPinStore, TopicPinnedBy } from './TopicPlacementPinStore.js';
+/** The emitter seam (ReplicatedRecordEmitter.emit — synchronous, never throws). */
+export interface PinMutationEmitter {
+    emit(store: string, recordKey: string | null | undefined, build: (hlc: HlcTimestamp, origin: string, observed: HlcTimestamp | undefined) => Record<string, unknown> | null): void;
+}
+export interface PinMutationDeps {
+    pinStore: TopicPlacementPinStore;
+    /** Absent/null ⇒ replication un-wired (single-machine / early boot) — local-only write. */
+    emitter?: PinMutationEmitter | null;
+    now?: () => Date;
+}
+/** Pin a topic to a machine: ONE HLC stamps both the journal PUT and the local set(). */
+export declare function setPinWithOneHlc(deps: PinMutationDeps, sessionKey: string, preferredMachine: string, pinned?: boolean, pinnedBy?: TopicPinnedBy): {
+    hlc?: HlcTimestamp;
+};
+/** Unpin a topic: the tombstone rides the SAME stamp the local clear is ordered by. */
+export declare function clearPinWithTombstone(deps: PinMutationDeps, sessionKey: string): {
+    hadPin: boolean;
+    hlc?: HlcTimestamp;
+};
+//# sourceMappingURL=TopicPinMutation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TopicPinMutation.d.ts","sourceRoot":"","sources":["../../src/core/TopicPinMutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAQzF,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,IAAI,CACF,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,KAAK,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,SAAS,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAC/G,IAAI,CAAC;CACT;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,MAAM,UAAO,EACb,QAAQ,CAAC,EAAE,aAAa,GACvB;IAAE,GAAG,CAAC,EAAE,YAAY,CAAA;CAAE,CAgBxB;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,GACjB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,YAAY,CAAA;CAAE,CAkBzC"}

package/dist/core/TopicPinMutation.js

@@ -0,0 +1,66 @@
+/**
+ * TopicPinMutation — the ONE-HLC pin mutation funnel (U4.1 §2B,
+ * docs/specs/u4-1-pin-persistence.md).
+ *
+ * THE CONTRACT (R-r2): every pin mutation mints ONE HLC and stamps BOTH the
+ * local `TopicPlacementPinStore.set()/clear()` AND the replicated journal
+ * emit (`buildTopicPinPut` / `buildTopicPinTombstone`) with that same stamp.
+ * The transfer route previously called `set()` WITHOUT the `hlc` argument
+ * (the routes.ts gap) — the local-vs-replicated comparison then degraded to a
+ * derived wall-clock and HLC-highest-wins was a symbol, not the state.
+ *
+ * UNPIN (fixes defect 2 — the live un-pin propagation bug): `clearPin` wires
+ * the previously ZERO-caller `buildTopicPinTombstone` at the clear()
+ * chokepoint, so a cleared pin can never be resurrected by a stale replicated
+ * PUT (`effectivePins()` / the fold honor tombstones by HLC order). A later
+ * re-pin is the same key with a newer HLC — the store's documented model.
+ *
+ * The emitter mints the HLC (its `clock.tick()` is the author-side authority);
+ * the funnel CAPTURES the minted stamp from inside the build closure and hands
+ * it to the local store. When emission is dark (`ws13PinReplicate` off /
+ * single-machine) the build closure never runs → no stamp is minted → the
+ * local write proceeds without one (today's exact behavior; the reconciler's
+ * documented `updatedAt` fallback derivation covers it).
+ */
+import { TOPIC_PIN_STORE_KEY, deriveTopicPinRecordKey, buildTopicPinPut, buildTopicPinTombstone, } from './TopicPinReplicatedStore.js';
+/** Pin a topic to a machine: ONE HLC stamps both the journal PUT and the local set(). */
+export function setPinWithOneHlc(deps, sessionKey, preferredMachine, pinned = true, pinnedBy) {
+    const topicNum = Number(sessionKey);
+    let minted;
+    if (deps.emitter && Number.isFinite(topicNum)) {
+        const recordKey = deriveTopicPinRecordKey(topicNum);
+        if (recordKey) {
+            const build = buildTopicPinPut(topicNum, preferredMachine, pinned);
+            deps.emitter.emit(TOPIC_PIN_STORE_KEY, recordKey, (hlc, origin, observed) => {
+                const data = build(hlc, origin, observed);
+                if (data !== null)
+                    minted = hlc; // capture ONLY a stamp that actually rode a record
+                return data;
+            });
+        }
+    }
+    deps.pinStore.set(sessionKey, preferredMachine, pinned, minted, pinnedBy);
+    return minted !== undefined ? { hlc: minted } : {};
+}
+/** Unpin a topic: the tombstone rides the SAME stamp the local clear is ordered by. */
+export function clearPinWithTombstone(deps, sessionKey) {
+    const hadPin = deps.pinStore.get(sessionKey) !== null;
+    const topicNum = Number(sessionKey);
+    let minted;
+    if (deps.emitter && Number.isFinite(topicNum)) {
+        const recordKey = deriveTopicPinRecordKey(topicNum);
+        if (recordKey) {
+            const deletedAt = (deps.now ?? (() => new Date()))().toISOString();
+            const build = buildTopicPinTombstone(topicNum, deletedAt);
+            deps.emitter.emit(TOPIC_PIN_STORE_KEY, recordKey, (hlc, origin, observed) => {
+                const data = build(hlc, origin, observed);
+                if (data !== null)
+                    minted = hlc;
+                return data;
+            });
+        }
+    }
+    deps.pinStore.clear(sessionKey);
+    return minted !== undefined ? { hadPin, hlc: minted } : { hadPin };
+}
+//# sourceMappingURL=TopicPinMutation.js.map

package/dist/core/TopicPinMutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicPinMutation.js","sourceRoot":"","sources":["../../src/core/TopicPinMutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AAkBtC,yFAAyF;AACzF,MAAM,UAAU,gBAAgB,CAC9B,IAAqB,EACrB,UAAkB,EAClB,gBAAwB,EACxB,MAAM,GAAG,IAAI,EACb,QAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,MAAgC,CAAC;IACrC,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;YACnE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;gBAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAC1C,IAAI,IAAI,KAAK,IAAI;oBAAE,MAAM,GAAG,GAAG,CAAC,CAAC,mDAAmD;gBACpF,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1E,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CACnC,IAAqB,EACrB,UAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,MAAgC,CAAC;IACrC,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;YACnE,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAC1D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;gBAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAC1C,IAAI,IAAI,KAAK,IAAI;oBAAE,MAAM,GAAG,GAAG,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;AACrE,CAAC"}

package/dist/core/TopicPinReplicatedStore.d.ts

@@ -26,6 +26,9 @@ import type { HlcTimestamp } from './HybridLogicalClock.js';
 export declare const TOPIC_PIN_RECORD_KIND = "topic-pin-record";
 /** The store key used by the emitter dark-gate + the rollback-unmerge getByStore wiring. */
 export declare const TOPIC_PIN_STORE_KEY = "topicPins";
+/** The same clamp for consumers outside this module (the U4.1 fold view's second pass —
+ *  ONE validation authority, never a re-implemented regex). */
+export declare function isValidPinMachineId(id: unknown): id is string;
 /** recordKey = the cross-machine IDENTITY SURFACE = the topic id as a string (a pin is
  *  per-topic; a re-pin to a different machine is the SAME key with a newer HLC). */
 export declare function deriveTopicPinRecordKey(topic: number | string): string | null;