instar 1.3.515 → 1.3.516

package/dist/core/HybridLogicalClock.d.ts

@@ -0,0 +1,200 @@
+/**
+ * HybridLogicalClock — a pure, dependency-injected total-order clock (WS2
+ * replicated-store foundation, Component 1).
+ *
+ * Spec: docs/specs/multi-machine-replicated-store-foundation.md §3 (the whole
+ * section), §10.2 (the maxDriftMs clamp invariant), §13 build order step 1,
+ * §15 risk-5/risk-6 (maxDriftMs sourcing — BLOCKER-5).
+ *
+ * HLC combines physical wall-clock time (so order tracks real time and is
+ * human-readable) with a logical counter (so causality survives clock skew and
+ * equal-millisecond ties). It is the load-bearing total order WS2 merges rely
+ * on: "merges order by HLC, never raw wall-clock" (master spec line 229).
+ *
+ * Design contract (§3.6 Purity + testability):
+ *   - Imports NOTHING but its injected seams. No `fs`, no `Date` (only via the
+ *     injected `now`), no network. Every operation is a pure function of
+ *     `(last, input, now())`.
+ *   - The clock (`now`), the `node` id, and persistence (`persist.load/save`)
+ *     are constructor deps, so every dangerous property — monotonicity, the
+ *     skew bound, restart-monotonicity — is unit-testable with in-memory fakes.
+ *
+ * Posture (§11): machine-local-by-design. Each machine has its own clock; the
+ * clocks CONVERGE via receive() but are never shared state. The HLC TIMESTAMPS
+ * are replicated (one per record, §4); the clock OBJECT is not.
+ */
+/**
+ * An HLC value. Carried on each replicated record as the `hlc` field (§4).
+ * The triple `(physical, logical, node)` is a globally-unique, totally-ordered
+ * stamp (node ids are unique across the pool, so distinct-machine stamps are
+ * never "equal" in sort position — §3.3).
+ */
+export interface HlcTimestamp {
+    /** Physical time in ms since epoch (the LARGEST seen, not necessarily now). */
+    physical: number;
+    /** Logical counter — breaks ties at equal physical and advances under skew. */
+    logical: number;
+    /** Node (machine) id of the clock that STAMPED this timestamp. The
+     *  tie-breaker of LAST resort and the carrier of the origin tag (§7). */
+    node: string;
+}
+/**
+ * The persistence seam (§3.5). Injected so crash-safety is unit-testable with
+ * an in-memory fake. `save` is expected to be ATOMIC (temp + rename) in the
+ * real implementation; the clock calls it on EVERY advance.
+ */
+export interface HlcPersistence {
+    /** Load the last durable stamp, or null if fresh (first boot). */
+    load(): HlcTimestamp | null;
+    /** Persist the last issued stamp atomically. Called on every advance. */
+    save(t: HlcTimestamp): void;
+}
+/** Constructor config (§3.2). */
+export interface HybridLogicalClockConfig {
+    /** This machine's id — the `node` stamped on every timestamp this clock issues. */
+    node: string;
+    /** INJECTED physical-time source (ms since epoch). Tests pass a fake clock. */
+    now: () => number;
+    /**
+     * FIXED bounded-drift ceiling (§3.4, BLOCKER-5). Default 5 minutes, CLAMPED
+     * to [60s, 15min]. NOT derived from any "measured pool skew" — no such numeric
+     * quantity exists today (ClockSkewStatus is a 3-value categorical enum).
+     */
+    maxDriftMs?: number;
+    /** Persistence seam (§3.5). Omitted ⇒ the clock keeps `last` only in memory. */
+    persist?: HlcPersistence;
+    /**
+     * Optional structured logger for the at-most-once breadcrumbs the spec
+     * mandates (a regressed-wall-clock-on-load note, §3.5; a clamp note). Defaults
+     * to a no-op so the primitive stays import-free.
+     */
+    log?: (event: string, detail: Record<string, unknown>) => void;
+}
+/**
+ * A rejected receive (§3.4). Returned (never thrown into the hot path silently)
+ * when a remote timestamp exceeds the pool-relative reference by more than the
+ * clamped maxDriftMs. The local clock is NOT advanced and the caller MUST
+ * quarantine the record (§5, failure-class `skew-suspicious`).
+ */
+export interface SkewRejection {
+    rejected: true;
+    reason: 'skew-ahead';
+    /** The remote timestamp that was rejected. */
+    remote: HlcTimestamp;
+    /** The pool-relative reference R the remote was measured against. */
+    reference: number;
+    /** The clamped drift ceiling that R + ceiling was exceeded by. */
+    maxDriftMs: number;
+}
+/** The result of receive(): either the merged stamp, or a typed rejection. */
+export type ReceiveResult = {
+    rejected: false;
+    hlc: HlcTimestamp;
+} | SkewRejection;
+/** Options for a single receive() call (§3.4 pool-relative reference). */
+export interface ReceiveOptions {
+    /**
+     * An OBSERVED pool-relative physical-time floor (e.g. the observed-pool-median
+     * physical time carried in the capacity heartbeat, §3.4). The drift check
+     * references `R = max(last.physical, poolReference ?? 0)`, NOT the bare local
+     * `now()` — so a receiver whose own NTP is behind does not falsely reject
+     * ahead-but-honest peers. Omitted ⇒ R = last.physical.
+     */
+    poolReference?: number;
+}
+/** The default bounded-drift ceiling: 5 minutes (§3.4). */
+export declare const DEFAULT_MAX_DRIFT_MS: number;
+/** The floor of the maxDriftMs clamp (§3.4 / §10.2): 60 seconds. */
+export declare const MIN_MAX_DRIFT_MS: number;
+/** The ceiling of the maxDriftMs clamp (§3.4 / §10.2): 15 minutes. */
+export declare const MAX_MAX_DRIFT_MS: number;
+/**
+ * Clamp a configured maxDriftMs to the [60s, 15min] window (§3.4, §10.2).
+ *
+ * This is the helper `validateStateSyncInvariants` (§10.2) uses for the
+ * `maxDriftMs` knob: a value below the floor would start rejecting ordinary NTP
+ * jitter; a value above the ceiling would defeat the fast-clock defense. The
+ * spec's §10.2 invariant REJECTS an out-of-range value at config resolution;
+ * this clamp helper is the in-clock guard so the primitive is correct even if a
+ * caller hands it a raw value. A non-finite/undefined input falls back to the
+ * default.
+ */
+export declare function clampMaxDriftMs(value: number | undefined): number;
+/** Type guard: is a receive() result a skew rejection? */
+export declare function isSkewRejection(r: ReceiveResult): r is SkewRejection;
+/**
+ * Serialize an HlcTimestamp to the compact wire/disk form (§3.5).
+ *
+ * Default form is a 3-field JSON object (carried on each record as `hlc`). The
+ * string form `"<physical>:<logical>:<node>"` is for embedding in a key — and
+ * because a node id MAY contain a `:`, the node is the LAST segment and parse
+ * splits on the FIRST TWO colons only (physical and logical are numeric and
+ * colon-free), so the round-trip is lossless for any node id.
+ */
+export declare function serializeHlc(t: HlcTimestamp): string;
+/** Serialize to the compact key-string form `"<physical>:<logical>:<node>"`. */
+export declare function serializeHlcKey(t: HlcTimestamp): string;
+/**
+ * Parse the JSON object form (§3.5). Throws on malformed input — a record whose
+ * `hlc` cannot be parsed is a schema reject upstream, never a silent default.
+ */
+export declare function parseHlc(input: string): HlcTimestamp;
+/** Parse the key-string form `"<physical>:<logical>:<node>"` (§3.5). */
+export declare function parseHlcKey(input: string): HlcTimestamp;
+/**
+ * Validate + narrow an unknown value to an HlcTimestamp. The single chokepoint
+ * both parsers and receive() funnel untrusted input through (§3.5): physical and
+ * logical must be finite non-negative integers; node must be a non-empty string.
+ */
+export declare function coerceHlc(raw: unknown): HlcTimestamp;
+export declare class HybridLogicalClock {
+    private readonly node;
+    private readonly now;
+    private readonly maxDriftMs;
+    private readonly persist?;
+    private readonly log;
+    /** The largest stamp this clock has issued (the floor for every advance). */
+    private last;
+    constructor(config: HybridLogicalClockConfig);
+    /** The largest stamp issued so far (a copy — never the internal reference). */
+    current(): HlcTimestamp;
+    /** The clamped drift ceiling this clock enforces (§3.4). */
+    getMaxDriftMs(): number;
+    /**
+     * tick() — local-event advance (§3.2.1). Called when THIS machine AUTHORS a
+     * record. `pt = max(now(), last.physical)`; `logical = (pt === last.physical)
+     * ? last.logical + 1 : 0`. Persists and returns the new stamp.
+     *
+     * Monotonicity guarantee: the returned stamp is strictly greater (by compare)
+     * than every previous tick()/receive() result on this clock — even if the wall
+     * clock jumps backward, because physical never regresses.
+     */
+    tick(): HlcTimestamp;
+    /**
+     * receive(remote) — merge an inbound peer stamp (§3.2.2 + §3.4). Runs the
+     * bounded-drift check FIRST; on rejection the local clock does NOT advance and
+     * a typed SkewRejection is returned (the caller quarantines the record).
+     *
+     * Otherwise the canonical HLC merge (Kulkarni et al.):
+     *   pt = max(now(), last.physical, remote.physical)
+     *   - pt === last.physical === remote.physical → max(last.logical, remote.logical)+1
+     *   - pt === last.physical                     → last.logical + 1
+     *   - pt === remote.physical                   → remote.logical + 1
+     *   - else                                      → 0
+     *
+     * Monotonic vs BOTH local and remote: the receiving clock can never go
+     * backward, and a received record's causal position is preserved.
+     */
+    receive(remote: HlcTimestamp, options?: ReceiveOptions): ReceiveResult;
+    /** Advance `last` and persist atomically (§3.5 — persist on EVERY advance). */
+    private commit;
+    /**
+     * compare(a, b) — the STRICT TOTAL ORDER (§3.3, static + pure). Compares
+     * physical, then logical, then node id (lexicographic). Returns 0 ONLY for an
+     * identical triple — because node ids are unique, two distinct-machine stamps
+     * are NEVER "equal" in sort position. This totality is what makes a
+     * deterministic merge across the pool possible.
+     */
+    static compare(a: HlcTimestamp, b: HlcTimestamp): -1 | 0 | 1;
+}
+//# sourceMappingURL=HybridLogicalClock.d.ts.map

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

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

package/dist/core/HybridLogicalClock.js

@@ -0,0 +1,288 @@
+/**
+ * HybridLogicalClock — a pure, dependency-injected total-order clock (WS2
+ * replicated-store foundation, Component 1).
+ *
+ * Spec: docs/specs/multi-machine-replicated-store-foundation.md §3 (the whole
+ * section), §10.2 (the maxDriftMs clamp invariant), §13 build order step 1,
+ * §15 risk-5/risk-6 (maxDriftMs sourcing — BLOCKER-5).
+ *
+ * HLC combines physical wall-clock time (so order tracks real time and is
+ * human-readable) with a logical counter (so causality survives clock skew and
+ * equal-millisecond ties). It is the load-bearing total order WS2 merges rely
+ * on: "merges order by HLC, never raw wall-clock" (master spec line 229).
+ *
+ * Design contract (§3.6 Purity + testability):
+ *   - Imports NOTHING but its injected seams. No `fs`, no `Date` (only via the
+ *     injected `now`), no network. Every operation is a pure function of
+ *     `(last, input, now())`.
+ *   - The clock (`now`), the `node` id, and persistence (`persist.load/save`)
+ *     are constructor deps, so every dangerous property — monotonicity, the
+ *     skew bound, restart-monotonicity — is unit-testable with in-memory fakes.
+ *
+ * Posture (§11): machine-local-by-design. Each machine has its own clock; the
+ * clocks CONVERGE via receive() but are never shared state. The HLC TIMESTAMPS
+ * are replicated (one per record, §4); the clock OBJECT is not.
+ */
+/** The default bounded-drift ceiling: 5 minutes (§3.4). */
+export const DEFAULT_MAX_DRIFT_MS = 5 * 60 * 1000;
+/** The floor of the maxDriftMs clamp (§3.4 / §10.2): 60 seconds. */
+export const MIN_MAX_DRIFT_MS = 60 * 1000;
+/** The ceiling of the maxDriftMs clamp (§3.4 / §10.2): 15 minutes. */
+export const MAX_MAX_DRIFT_MS = 15 * 60 * 1000;
+/**
+ * Clamp a configured maxDriftMs to the [60s, 15min] window (§3.4, §10.2).
+ *
+ * This is the helper `validateStateSyncInvariants` (§10.2) uses for the
+ * `maxDriftMs` knob: a value below the floor would start rejecting ordinary NTP
+ * jitter; a value above the ceiling would defeat the fast-clock defense. The
+ * spec's §10.2 invariant REJECTS an out-of-range value at config resolution;
+ * this clamp helper is the in-clock guard so the primitive is correct even if a
+ * caller hands it a raw value. A non-finite/undefined input falls back to the
+ * default.
+ */
+export function clampMaxDriftMs(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return DEFAULT_MAX_DRIFT_MS;
+    if (value < MIN_MAX_DRIFT_MS)
+        return MIN_MAX_DRIFT_MS;
+    if (value > MAX_MAX_DRIFT_MS)
+        return MAX_MAX_DRIFT_MS;
+    return value;
+}
+/** Type guard: is a receive() result a skew rejection? */
+export function isSkewRejection(r) {
+    return r.rejected === true;
+}
+/**
+ * Serialize an HlcTimestamp to the compact wire/disk form (§3.5).
+ *
+ * Default form is a 3-field JSON object (carried on each record as `hlc`). The
+ * string form `"<physical>:<logical>:<node>"` is for embedding in a key — and
+ * because a node id MAY contain a `:`, the node is the LAST segment and parse
+ * splits on the FIRST TWO colons only (physical and logical are numeric and
+ * colon-free), so the round-trip is lossless for any node id.
+ */
+export function serializeHlc(t) {
+    return JSON.stringify({ physical: t.physical, logical: t.logical, node: t.node });
+}
+/** Serialize to the compact key-string form `"<physical>:<logical>:<node>"`. */
+export function serializeHlcKey(t) {
+    return `${t.physical}:${t.logical}:${t.node}`;
+}
+/**
+ * Parse the JSON object form (§3.5). Throws on malformed input — a record whose
+ * `hlc` cannot be parsed is a schema reject upstream, never a silent default.
+ */
+export function parseHlc(input) {
+    let raw;
+    try {
+        raw = JSON.parse(input);
+    }
+    catch {
+        throw new Error(`parseHlc: not valid JSON: ${truncateForError(input)}`);
+    }
+    return coerceHlc(raw);
+}
+/** Parse the key-string form `"<physical>:<logical>:<node>"` (§3.5). */
+export function parseHlcKey(input) {
+    if (typeof input !== 'string') {
+        throw new Error('parseHlcKey: input is not a string');
+    }
+    // Split on the FIRST TWO colons only — the node id may contain colons.
+    const firstColon = input.indexOf(':');
+    const secondColon = firstColon < 0 ? -1 : input.indexOf(':', firstColon + 1);
+    if (firstColon < 0 || secondColon < 0) {
+        throw new Error(`parseHlcKey: expected "<physical>:<logical>:<node>", got: ${truncateForError(input)}`);
+    }
+    const physical = Number(input.slice(0, firstColon));
+    const logical = Number(input.slice(firstColon + 1, secondColon));
+    const node = input.slice(secondColon + 1);
+    return coerceHlc({ physical, logical, node });
+}
+/**
+ * Validate + narrow an unknown value to an HlcTimestamp. The single chokepoint
+ * both parsers and receive() funnel untrusted input through (§3.5): physical and
+ * logical must be finite non-negative integers; node must be a non-empty string.
+ */
+export function coerceHlc(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error('coerceHlc: not an object');
+    }
+    const obj = raw;
+    const { physical, logical, node } = obj;
+    if (typeof physical !== 'number' || !Number.isInteger(physical) || physical < 0) {
+        throw new Error(`coerceHlc: physical must be a non-negative integer, got ${String(physical)}`);
+    }
+    if (typeof logical !== 'number' || !Number.isInteger(logical) || logical < 0) {
+        throw new Error(`coerceHlc: logical must be a non-negative integer, got ${String(logical)}`);
+    }
+    if (typeof node !== 'string' || node.length === 0) {
+        throw new Error('coerceHlc: node must be a non-empty string');
+    }
+    return { physical, logical, node };
+}
+function truncateForError(s) {
+    const str = String(s);
+    return str.length > 80 ? `${str.slice(0, 80)}…` : str;
+}
+export class HybridLogicalClock {
+    node;
+    now;
+    maxDriftMs;
+    persist;
+    log;
+    /** The largest stamp this clock has issued (the floor for every advance). */
+    last;
+    constructor(config) {
+        if (typeof config.node !== 'string' || config.node.length === 0) {
+            throw new Error('HybridLogicalClock: node id must be a non-empty string');
+        }
+        this.node = config.node;
+        this.now = config.now;
+        this.maxDriftMs = clampMaxDriftMs(config.maxDriftMs);
+        this.persist = config.persist;
+        this.log = config.log ?? (() => { });
+        const loaded = this.persist?.load() ?? null;
+        // Validate the durable stamp through the same chokepoint a parser uses. A
+        // CORRUPT (non-null but malformed) load must NOT crash construction (§3.5,
+        // "Distrust Temporary Success"): a poisoned/partially-written persistence row
+        // would otherwise brick every consumer that boots the clock. We fail TOWARD a
+        // fresh-but-monotonic clock (monotonic relative to wall time) and log once,
+        // mirroring the missing-file (null) path — never throw out of the constructor.
+        let safeLoaded;
+        if (loaded === null) {
+            safeLoaded = null;
+        }
+        else {
+            try {
+                safeLoaded = coerceHlc(loaded);
+            }
+            catch (err) {
+                // @silent-fallback-ok: a corrupt persisted stamp degrades to the same
+                // fresh-but-monotonic clock as the missing-file path (safeLoaded=null
+                // below) rather than throwing out of construction — fail toward a usable
+                // clock, the safe direction. The discard is logged with context
+                // ('hlc-load-corrupt'); it is not a DegradationReporter case.
+                this.log('hlc-load-corrupt', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                safeLoaded = null;
+            }
+        }
+        if (safeLoaded === null) {
+            // Fresh (no durable stamp, or a corrupt one we just discarded): start at
+            // { physical: now(), logical: 0, node } (§3.5).
+            this.last = { physical: this.now(), logical: 0, node: this.node };
+        }
+        else {
+            // Seed last from the durable stamp so a restart cannot rewind below it.
+            // We trust our OWN durable past over a regressed wall clock: if the loaded
+            // physical is ahead of now() by more than maxDriftMs (a backward wall-clock
+            // jump across the restart) we honor the durable floor and log once (§3.5).
+            this.last = { physical: safeLoaded.physical, logical: safeLoaded.logical, node: this.node };
+            const wall = this.now();
+            if (safeLoaded.physical - wall > this.maxDriftMs) {
+                this.log('hlc-load-ahead-of-wall', {
+                    loadedPhysical: safeLoaded.physical,
+                    wall,
+                    maxDriftMs: this.maxDriftMs,
+                });
+            }
+        }
+    }
+    /** The largest stamp issued so far (a copy — never the internal reference). */
+    current() {
+        return { ...this.last };
+    }
+    /** The clamped drift ceiling this clock enforces (§3.4). */
+    getMaxDriftMs() {
+        return this.maxDriftMs;
+    }
+    /**
+     * tick() — local-event advance (§3.2.1). Called when THIS machine AUTHORS a
+     * record. `pt = max(now(), last.physical)`; `logical = (pt === last.physical)
+     * ? last.logical + 1 : 0`. Persists and returns the new stamp.
+     *
+     * Monotonicity guarantee: the returned stamp is strictly greater (by compare)
+     * than every previous tick()/receive() result on this clock — even if the wall
+     * clock jumps backward, because physical never regresses.
+     */
+    tick() {
+        const pt = Math.max(this.now(), this.last.physical);
+        const logical = pt === this.last.physical ? this.last.logical + 1 : 0;
+        const next = { physical: pt, logical, node: this.node };
+        this.commit(next);
+        return next;
+    }
+    /**
+     * receive(remote) — merge an inbound peer stamp (§3.2.2 + §3.4). Runs the
+     * bounded-drift check FIRST; on rejection the local clock does NOT advance and
+     * a typed SkewRejection is returned (the caller quarantines the record).
+     *
+     * Otherwise the canonical HLC merge (Kulkarni et al.):
+     *   pt = max(now(), last.physical, remote.physical)
+     *   - pt === last.physical === remote.physical → max(last.logical, remote.logical)+1
+     *   - pt === last.physical                     → last.logical + 1
+     *   - pt === remote.physical                   → remote.logical + 1
+     *   - else                                      → 0
+     *
+     * Monotonic vs BOTH local and remote: the receiving clock can never go
+     * backward, and a received record's causal position is preserved.
+     */
+    receive(remote, options = {}) {
+        // Narrow untrusted input through the same chokepoint a parser uses.
+        const r = coerceHlc(remote);
+        // §3.4 — POOL-RELATIVE reference, never the bare local now(). A slow receiver
+        // must not quarantine a legitimately-ahead peer just because its own clock lags.
+        const reference = Math.max(this.last.physical, options.poolReference ?? 0);
+        if (r.physical - reference > this.maxDriftMs) {
+            // Clock NOT advanced — a fast peer cannot drag us into the future.
+            return {
+                rejected: true,
+                reason: 'skew-ahead',
+                remote: r,
+                reference,
+                maxDriftMs: this.maxDriftMs,
+            };
+        }
+        const pt = Math.max(this.now(), this.last.physical, r.physical);
+        let logical;
+        if (pt === this.last.physical && pt === r.physical) {
+            logical = Math.max(this.last.logical, r.logical) + 1;
+        }
+        else if (pt === this.last.physical) {
+            logical = this.last.logical + 1;
+        }
+        else if (pt === r.physical) {
+            logical = r.logical + 1;
+        }
+        else {
+            logical = 0;
+        }
+        const next = { physical: pt, logical, node: this.node };
+        this.commit(next);
+        return { rejected: false, hlc: next };
+    }
+    /** Advance `last` and persist atomically (§3.5 — persist on EVERY advance). */
+    commit(next) {
+        this.last = next;
+        this.persist?.save({ ...next });
+    }
+    /**
+     * compare(a, b) — the STRICT TOTAL ORDER (§3.3, static + pure). Compares
+     * physical, then logical, then node id (lexicographic). Returns 0 ONLY for an
+     * identical triple — because node ids are unique, two distinct-machine stamps
+     * are NEVER "equal" in sort position. This totality is what makes a
+     * deterministic merge across the pool possible.
+     */
+    static compare(a, b) {
+        if (a.physical !== b.physical)
+            return a.physical < b.physical ? -1 : 1;
+        if (a.logical !== b.logical)
+            return a.logical < b.logical ? -1 : 1;
+        if (a.node !== b.node)
+            return a.node < b.node ? -1 : 1;
+        return 0;
+    }
+}
+//# sourceMappingURL=HybridLogicalClock.js.map

package/dist/core/HybridLogicalClock.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.515",
+  "version": "1.3.516",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-13T07:02:36.364Z",
-  "instarVersion": "1.3.515",
+  "generatedAt": "2026-06-13T07:45:14.251Z",
+  "instarVersion": "1.3.516",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.516.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- **New `src/core/HybridLogicalClock.ts`** — the first primitive of the WS2
+  replicated-store foundation (spec `multi-machine-replicated-store-foundation.md` §3,
+  build-order Step 1). A pure, dependency-injected hybrid logical clock that will give
+  every cross-machine replicated change a well-defined total order:
+  - `tick()` — local-event advance (physical never regresses; same-ms bumps the logical
+    counter); strictly monotonic.
+  - `receive(remote, { poolReference })` — canonical HLC merge across all four
+    physical-comparison branches; monotonic vs both local and remote.
+  - `static compare(a, b)` — strict total order (physical → logical → node tie-break).
+  - **Skew-rejection** — a poison-future remote clock (physical beyond a POOL-RELATIVE
+    reference + a FIXED `maxDriftMs` clamped to [60s, 15min]) is rejected as a typed
+    result and never advances the clock; a legitimately-ahead peer or a slow local
+    receiver is never wrongly rejected.
+  - **Restart-monotonic** via injected atomic persistence; a corrupt durable stamp
+    fails toward a fresh-but-monotonic clock (never crashes construction).
+- Pure + injected (clock / nodeId / persistence are constructor seams) — no ambient
+  `Date.now()`/`fs` in the hot path.
+
+This primitive is **inert** — nothing imports it yet. Its consumers are the subsequent
+foundation steps (journal-kind envelope → snapshot-then-tail → quarantine ring →
+union-reader), sequenced in the spec's build order §13.
+
+## What to Tell Your User
+
+Nothing changes for you yet — this is internal groundwork. It's the clock that will let
+your agent keep one coherent memory across multiple machines (so a preference or
+relationship learned on one machine orders correctly against changes on another). The
+machine-spanning memory features that use it land in the following steps.
+
+## Summary of New Capabilities
+
+- Internal foundation primitive `HybridLogicalClock` (cross-machine total-order clock
+  with pool-relative skew-rejection + restart-monotonicity). Not yet wired to any
+  feature — it is the substrate the WS2 memory-replication steps build on.
+
+## Evidence
+
+- `tests/unit/HybridLogicalClock.test.ts` (44, new): tick monotonicity + same-ms
+  logical bump; receive merge correctness for all four branches + monotonicity vs both
+  sides; `compare()` total-order incl. node tie-break + identical-triple equality;
+  skew-rejection on a poison-future remote with both boundary sides; pool-relative
+  reference (a slow receiver does NOT reject a within-bound ahead peer); the
+  [60s,15min] clamp; restart-monotonicity from persisted state; persist-on-advance;
+  corrupt-persisted-stamp degradation across 8 malformed shapes; serialize/parse
+  round-trips + malformed-input rejection. `tsc --noEmit` clean; full lint chain green.
+- Adversarial review: distributed-correctness brute-forced 3456 merge tuples vs the
+  canonical Kulkarni HLC merge (zero mismatches); integration-purity MEDIUM (corrupt
+  stamp crash) fixed.

package/upgrades/side-effects/replicated-store-foundation-hlc-primitive.md

@@ -0,0 +1,98 @@
+# Side-Effects Review — Replicated-store foundation Step 1: HybridLogicalClock primitive
+
+**Version / slug:** `replicated-store-foundation-hlc-primitive`
+**Date:** `2026-06-13`
+**Author:** `Instar Agent (echo)`
+**Spec:** `docs/specs/multi-machine-replicated-store-foundation.md` §3 (converged + approved), build-order Step 1
+**Second-pass reviewer:** 2 adversarial lenses (distributed-correctness / integration-and-purity) — distributed-correctness CONCUR (brute-forced 3456 merge tuples vs the canonical Kulkarni HLC merge, zero mismatches); integration-purity raised 1 MEDIUM (corrupt persisted stamp crashed construction) — FIXED.
+
+## Summary of the change
+
+The first primitive of the WS2 replicated-store foundation: `src/core/HybridLogicalClock.ts` — a
+pure, dependency-injected hybrid logical clock that gives every replicated change a
+well-defined cross-machine total order. Operations: `tick()` (local-event advance,
+physical never regresses, same-ms bumps logical), `receive(remote, {poolReference})`
+(canonical HLC merge across all four physical-comparison branches), `static compare()`
+(strict total order: physical → logical → node tie-break). Skew-rejection is
+POOL-RELATIVE (reference = max(last.physical, poolReference), not the bare receiver
+now()) with a FIXED `maxDriftMs` clamped to [60s, 15min] — honoring the spec's
+BLOCKER-5 resolution (a 3-value enum is not a numeric skew source). Restart-monotonic
+via injected atomic persistence; a corrupt durable stamp fails toward a fresh-but-
+monotonic clock (never crashes construction). Files: `src/core/HybridLogicalClock.ts`
+(new), `tests/unit/HybridLogicalClock.test.ts` (new, 44 tests).
+
+This is a PURE LIBRARY with NO wiring yet — its consumers are the subsequent
+foundation steps (journal-kind envelope, snapshot-then-tail, quarantine ring,
+union-reader), per the spec's own build order §13. It is inert (changes no existing
+behavior) until a later step consumes it.
+
+## Decision-point inventory
+
+- No block/allow/gate surface. A clock primitive is mechanism, not authority. The only
+  "decision" is `receive()`'s skew-rejection — a typed return value, not a behavior
+  gate on anything that exists today (nothing calls it yet).
+
+---
+
+## 1. Over-block
+N/A — no gate. `receive()`'s skew-rejection rejects a poison-future remote clock
+(physical > pool-relative reference + clamped maxDriftMs); the pool-relative reference
++ [60s,15min] clamp ensure a legitimately-ahead peer or a slow receiver is never
+wrongly rejected (proven by tests on both sides of the boundary).
+
+## 2. Under-block
+A within-bound skewed clock is accepted (by design — the bound tolerates real drift).
+The primitive does not by itself defend against a sustained-malicious clock beyond the
+drift bound; that is the quarantine ring's job (a later step). Stated honestly.
+
+## 3. Level-of-abstraction fit
+Right layer — a self-contained core primitive with all I/O (clock, nodeId,
+persistence) injected, exactly the spec's §3 shape. It layers ON the existing
+CoherenceJournal transport without modifying it (this PR touches neither
+CoherenceJournal nor JournalSyncApplier).
+
+## 4. Signal vs authority compliance
+Pure mechanism. No blocking authority. The skew-rejection is a returned typed result
+the (future) caller decides on, not a gate the primitive enforces.
+
+## 5. Interactions
+None today — nothing imports it yet. It cannot shadow, double-fire, or race with any
+existing code because it is unconsumed. Designed so the later journal-kind step embeds
+its serialized form in the replicated-record envelope.
+
+## 6. External surfaces
+No route, no config flag, no mesh verb, no CLI. No change visible to other agents,
+users, or systems. Net-new module only.
+
+## Framework generality
+No framework-launch abstraction touched (does not modify `frameworkSessionLaunch.ts`).
+A clock primitive is framework-agnostic. N/A beyond that.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**machine-local BY DESIGN (this slice)** — each machine runs its own HLC; the clock is
+not itself replicated. Its PURPOSE is to become the cross-machine ordering substrate:
+later steps stamp replicated journal records with this HLC so the union-reader can
+order changes from all machines deterministically. Phase-C clean: the node-id space is
+unbounded (any string), skew handling is pool-relative (no 2-peer / no-LAN assumption),
+and there are no per-pool-size structures in the primitive.
+
+## 8. Rollback cost
+Trivial: a new unconsumed file. Reverting deletes `HybridLogicalClock.ts` + its test;
+nothing depends on it, no durable state, no migration.
+
+---
+
+## Second-pass review (2 adversarial lenses)
+
+- **distributed-correctness:** CONCUR. Brute-forced 3456 (lastP,lastL,remP,remL,now)
+  tuples against the canonical Kulkarni et al. HLC merge — zero mismatches; no
+  off-by-one in any of the four branches; `compare()` verified a strict total order
+  with deterministic node tie-break. Skew-rejection sound + pool-relative.
+- **integration-and-purity:** 1 MEDIUM — a non-null malformed persisted stamp threw
+  out of the constructor instead of degrading. FIXED: `coerceHlc(loaded)` is wrapped;
+  a corrupt durable stamp logs `hlc-load-corrupt` once and degrades to the same
+  fresh-clock path as the missing-file case, then ticks monotonically. Proven by an
+  8-corrupt-shape table-driven test. Purity confirmed: clock/nodeId/persistence all
+  injected; no ambient Date.now()/fs in the hot path.
+
+Verdict: correct + pure + bounded; ship.