@saihm/shm 0.0.0-stage → 0.38.1

package/dist/erasure/reconcile.d.ts

@@ -0,0 +1,72 @@
+import type { IndexEntry, RecalledBody } from "../saihm_client/types.js";
+export interface ReconcileCandidate {
+    readonly cellId: string;
+    readonly substrateCellId: string;
+    readonly probe?: string;
+}
+export type ReconcileVerdict = "live" | "erased" | "suspect" | "unverifiable";
+export type ReconcileEvidence = "index" | "recall" | "listing" | "none";
+export interface ReconcileDecision {
+    readonly cellId: string;
+    readonly substrateCellId: string;
+    readonly verdict: ReconcileVerdict;
+    readonly evidence: ReconcileEvidence;
+    readonly reason?: string;
+    readonly refetch?: boolean;
+}
+export type ProbeResult = {
+    readonly ok: true;
+    readonly bodies: readonly RecalledBody[];
+    readonly cap: number;
+    readonly servedBy?: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface ReconcileSummary {
+    readonly method: ReconcileEvidence;
+    readonly checked: number;
+    readonly live: number;
+    readonly erased: number;
+    readonly suspect: number;
+    readonly unverifiable: number;
+    readonly deferred: number;
+    readonly decisions: readonly ReconcileDecision[];
+    readonly notes: readonly string[];
+}
+export declare function decideFromIndex(c: ReconcileCandidate, entries: ReadonlyMap<string, IndexEntry>): ReconcileDecision;
+export declare function decideFromProbe(c: ReconcileCandidate, r: ProbeResult | undefined): ReconcileDecision;
+export interface ListingCandidate extends ReconcileCandidate {
+    readonly heldSeq?: string;
+    readonly heldCommitment?: string;
+    readonly writtenAtMs?: number;
+}
+export interface ListingEvidence {
+    readonly complete: boolean;
+    readonly startedAtMs: number;
+    readonly cells: ReadonlyMap<string, {
+        readonly seq: string | null;
+        readonly commitment?: string;
+    }>;
+}
+export interface ListingPageInput {
+    readonly cells: readonly {
+        readonly cellId: string;
+        readonly seq: string | null;
+        readonly commitment?: string;
+    }[];
+    readonly next: string | null;
+    readonly servedBy?: string;
+}
+export interface CollectedListing extends ListingEvidence {
+    readonly pages: number;
+    readonly incompleteReason?: string;
+}
+export declare const DEFAULT_LISTING_MAX_PAGES = 1000;
+export declare function collectListing(fetchPage: (after: string | undefined) => Promise<ListingPageInput>, opts?: {
+    readonly maxPages?: number;
+    readonly now?: () => number;
+}): Promise<CollectedListing>;
+export declare function decideFromListing(c: ListingCandidate, l: ListingEvidence): ReconcileDecision;
+export declare function summarize(method: ReconcileEvidence, decisions: readonly ReconcileDecision[], deferred: number, extraNotes?: readonly string[]): ReconcileSummary;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/erasure/reconcile.d.ts.map

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

package/dist/erasure/reconcile.js

@@ -0,0 +1,125 @@
+export function decideFromIndex(c, entries) {
+    const e = entries.get(c.substrateCellId.toLowerCase());
+    const base = { cellId: c.cellId, substrateCellId: c.substrateCellId, evidence: "index" };
+    if (e === undefined)
+        return { ...base, verdict: "unverifiable", reason: "not listed in the substrate's index — a listing proves presence, never absence" };
+    if (e.forgotten)
+        return { ...base, verdict: "erased", reason: "the substrate's index carries forgotten: true" };
+    return { ...base, verdict: "live" };
+}
+export function decideFromProbe(c, r) {
+    const base = { cellId: c.cellId, substrateCellId: c.substrateCellId, evidence: "recall" };
+    if (c.probe === undefined || c.probe.trim().length === 0)
+        return { ...base, evidence: "none", verdict: "unverifiable", reason: "no probe: the transport exposes no index and the candidate names no text to recall by" };
+    if (r === undefined)
+        return { ...base, evidence: "none", verdict: "unverifiable", reason: "not probed" };
+    if (!r.ok)
+        return { ...base, verdict: "unverifiable", reason: `probe failed: ${r.reason}` };
+    const want = c.substrateCellId.toLowerCase();
+    if (r.bodies.some((b) => b.cellId.toLowerCase() === want))
+        return { ...base, verdict: "live" };
+    if (r.servedBy !== undefined && r.servedBy !== "origin")
+        return { ...base, verdict: "unverifiable", reason: "the probe was answered by a replica: its freshness bounds lag, not omission — absence there is not evidence" };
+    if (r.bodies.length >= r.cap)
+        return { ...base, verdict: "unverifiable", reason: `probe result reached the transport's cap (${r.cap}); absence beyond a cap is not evidence` };
+    return { ...base, verdict: "suspect", reason: "the substrate returned the probe's matches without this cell and no erasure line was seen: withheld, not erased" };
+}
+const DECIMAL_SEQ = /^\d+$/;
+export const DEFAULT_LISTING_MAX_PAGES = 1000;
+export async function collectListing(fetchPage, opts = {}) {
+    const maxPages = opts.maxPages ?? DEFAULT_LISTING_MAX_PAGES;
+    if (!Number.isInteger(maxPages) || maxPages < 1)
+        throw new RangeError("collectListing: maxPages must be a positive integer");
+    const startedAtMs = (opts.now ?? Date.now)();
+    const cells = new Map();
+    const seenNext = new Set();
+    let after;
+    let pages = 0;
+    const partial = (incompleteReason) => ({ complete: false, startedAtMs, cells, pages, incompleteReason });
+    for (;;) {
+        if (pages >= maxPages)
+            return partial(`the page budget (${maxPages}) ran out before the last page`);
+        let page;
+        try {
+            page = await fetchPage(after);
+        }
+        catch {
+            return partial("a page could not be fetched");
+        }
+        pages++;
+        if (page.servedBy !== undefined && page.servedBy !== "origin")
+            return partial("a page was answered by a replica: only the origin's listing may end anything");
+        for (const c of page.cells) {
+            if (cells.has(c.cellId))
+                return partial("an id was listed twice: the listing is not consistent");
+            cells.set(c.cellId, c.commitment !== undefined ? { seq: c.seq, commitment: c.commitment } : { seq: c.seq });
+        }
+        if (page.next === null)
+            return { complete: true, startedAtMs, cells, pages };
+        if (page.next === after || seenNext.has(page.next))
+            return partial("`next` did not move forward");
+        seenNext.add(page.next);
+        after = page.next;
+    }
+}
+export function decideFromListing(c, l) {
+    const base = { cellId: c.cellId, substrateCellId: c.substrateCellId, evidence: "listing" };
+    let listed = l.cells.get(c.substrateCellId);
+    if (listed === undefined) {
+        const want = c.substrateCellId.toLowerCase();
+        for (const [id, v] of l.cells)
+            if (id.toLowerCase() === want) {
+                listed = v;
+                break;
+            }
+    }
+    if (listed !== undefined) {
+        if (c.heldSeq === undefined)
+            return { ...base, verdict: "live" };
+        if (listed.seq === null)
+            return { ...base, verdict: "live", refetch: true, reason: "listed without a version: fetch it to verify" };
+        const sameSeq = DECIMAL_SEQ.test(c.heldSeq) && DECIMAL_SEQ.test(listed.seq) && BigInt(c.heldSeq) === BigInt(listed.seq);
+        const sameCommitment = c.heldCommitment === undefined || listed.commitment === undefined || c.heldCommitment === listed.commitment;
+        return sameSeq && sameCommitment ? { ...base, verdict: "live" } : { ...base, verdict: "live", refetch: true, reason: "listed at another version than the one this copy was made from: fetch it again" };
+    }
+    if (!l.complete)
+        return { ...base, verdict: "unverifiable", reason: "not in a partial listing — only a listing paged to its end proves absence" };
+    if (c.writtenAtMs !== undefined && c.writtenAtMs >= l.startedAtMs) {
+        return { ...base, verdict: "unverifiable", reason: "confirmed after the listing started: the listing may have passed its id before it existed" };
+    }
+    return { ...base, verdict: "erased", reason: "absent from a complete listing — erased, recorded incomplete: a listing cannot show how a cell disappeared" };
+}
+export function summarize(method, decisions, deferred, extraNotes = []) {
+    let live = 0, erased = 0, suspect = 0, unverifiable = 0;
+    for (const d of decisions) {
+        if (d.verdict === "live")
+            live++;
+        else if (d.verdict === "erased")
+            erased++;
+        else if (d.verdict === "suspect")
+            suspect++;
+        else
+            unverifiable++;
+    }
+    const notes = [];
+    if (decisions.length === 0 && deferred === 0)
+        notes.push("no candidates: nothing could have been reconciled — this run is vacuous, not clean");
+    if (erased > 0) {
+        notes.push(method === "listing"
+            ? `${erased} copied row(s) ERASED: absent from a complete version listing (no erasure line seen): purged here, recorded incomplete`
+            : `${erased} copied row(s) ERASED on the substrate's index (forgotten there, no erasure line seen): purged here`);
+    }
+    const refetch = decisions.filter((d) => d.refetch === true).length;
+    if (refetch > 0)
+        notes.push(`${refetch} copied row(s) live at a NEWER version: fetched again`);
+    if (suspect > 0)
+        notes.push(`${suspect} copied row(s) WITHHELD: the substrate no longer returns them for their own text and no erasure line was seen — served again when a later run finds them`);
+    if (unverifiable > 0)
+        notes.push(`${unverifiable} candidate(s) UNVERIFIABLE (not listed, a partial listing, written during the listing, capped or failed probe, or no probe): unchanged, still served`);
+    if (deferred > 0)
+        notes.push(`${deferred} candidate(s) DEFERRED by the per-run probe budget: unchanged, still served`);
+    for (const n of extraNotes)
+        notes.push(n);
+    return { method, checked: decisions.length, live, erased, suspect, unverifiable, deferred, decisions, notes };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/erasure/reconcile.js.map

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

package/dist/erasure/withheld_store.d.ts

@@ -0,0 +1,30 @@
+export declare const WITHHELD_FILE_VERSION = 1;
+export interface WithheldStore {
+    load(): Promise<readonly string[] | undefined>;
+    save(cellIds: readonly string[]): Promise<void>;
+    quarantine?(): Promise<string | undefined>;
+}
+export declare class MemoryWithheldStore implements WithheldStore {
+    private ids;
+    quarantine(): Promise<string | undefined>;
+    load(): Promise<readonly string[] | undefined>;
+    save(cellIds: readonly string[]): Promise<void>;
+}
+export declare class WithheldStoreCorruptError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+export interface FileWithheldStoreOptions {
+    readonly owner?: string;
+}
+export declare class FileWithheldStore implements WithheldStore {
+    readonly path: string;
+    readonly opts: FileWithheldStoreOptions;
+    lastLoadedOwner: string | null | undefined;
+    constructor(path: string, opts?: FileWithheldStoreOptions);
+    probeWritable(): Promise<void>;
+    load(): Promise<readonly string[] | undefined>;
+    quarantine(): Promise<string | undefined>;
+    save(cellIds: readonly string[]): Promise<void>;
+}
+//# sourceMappingURL=withheld_store.d.ts.map

package/dist/erasure/withheld_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withheld_store.d.ts","sourceRoot":"","sources":["../../src/erasure/withheld_store.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,UAAU,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5C;AAED,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,GAAG,CAAgC;IACrC,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAGzC,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAG9C,IAAI,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAGtD;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIlD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,iBAAkB,YAAW,aAAa;IAGzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAF1E,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAW,IAAI,GAAE,wBAA6B;IAIzE,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,IAAI,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IA4B9C,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAWzC,IAAI,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAItD"}

package/dist/erasure/withheld_store.js

@@ -0,0 +1,91 @@
+import { open, readFile, rename, unlink } from "node:fs/promises";
+import { writeFileAtomic } from "../store/atomic_write.js";
+import { assertStateDir, ensureStateDir } from "../store/state_dir.js";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+export const WITHHELD_FILE_VERSION = 1;
+export class MemoryWithheldStore {
+    ids;
+    async quarantine() {
+        return undefined;
+    }
+    async load() {
+        return this.ids;
+    }
+    async save(cellIds) {
+        this.ids = [...cellIds];
+    }
+}
+export class WithheldStoreCorruptError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`withheld store ${path}: ${detail}`);
+        this.path = path;
+        this.name = "WithheldStoreCorruptError";
+    }
+}
+export class FileWithheldStore {
+    path;
+    opts;
+    lastLoadedOwner;
+    constructor(path, opts = {}) {
+        this.path = path;
+        this.opts = opts;
+        assertStateDir("FileWithheldStore", dirname(path));
+    }
+    async probeWritable() {
+        await ensureStateDir("FileWithheldStore", dirname(this.path));
+        const probe = `${this.path}.probe.${process.pid}.${randomBytes(6).toString("hex")}`;
+        const fh = await open(probe, "wx", 0o600);
+        await fh.close();
+        await unlink(probe);
+    }
+    async load() {
+        assertStateDir("FileWithheldStore", dirname(this.path));
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                this.lastLoadedOwner = null;
+                return undefined;
+            }
+            throw new WithheldStoreCorruptError(this.path, `unreadable: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        let o;
+        try {
+            o = JSON.parse(text);
+        }
+        catch {
+            throw new WithheldStoreCorruptError(this.path, "not JSON");
+        }
+        if (typeof o !== "object" || o === null)
+            throw new WithheldStoreCorruptError(this.path, "not an object");
+        const { v, withheld, owner } = o;
+        if (v !== WITHHELD_FILE_VERSION)
+            throw new WithheldStoreCorruptError(this.path, `version ${String(v)} is not ${WITHHELD_FILE_VERSION}`);
+        if (!Array.isArray(withheld) || !withheld.every((x) => typeof x === "string" && x.length > 0)) {
+            throw new WithheldStoreCorruptError(this.path, "`withheld` is not a list of non-empty ids");
+        }
+        this.lastLoadedOwner = typeof owner === "string" && owner.length > 0 ? owner : null;
+        return [...new Set(withheld)].sort();
+    }
+    async quarantine() {
+        const to = `${this.path}.corrupt.${new Date().toISOString().replace(/[:.]/g, "-")}`;
+        try {
+            await rename(this.path, to);
+            return to;
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+    }
+    async save(cellIds) {
+        await ensureStateDir("FileWithheldStore", dirname(this.path));
+        await writeFileAtomic(this.path, JSON.stringify({ v: WITHHELD_FILE_VERSION, withheld: [...new Set(cellIds)].sort(), ...(this.opts.owner !== undefined ? { owner: this.opts.owner } : {}) }));
+    }
+}
+//# sourceMappingURL=withheld_store.js.map

package/dist/erasure/withheld_store.js.map

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

package/dist/fleet/index.d.ts

@@ -0,0 +1,2 @@
+export { assembleFleetReport, renderFleetReport, LARGEST_CLUSTERS, type FleetRow, type FleetPolicy, type FleetFlag, type FleetPartition, type ClusterSummary, type FleetConcentration, type FleetVerdict, type FleetReport, type FleetInput, } from "./knowledge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/fleet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fleet/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/fleet/index.js

@@ -0,0 +1,2 @@
+export { assembleFleetReport, renderFleetReport, LARGEST_CLUSTERS, } from "./knowledge.js";
+//# sourceMappingURL=index.js.map

package/dist/fleet/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fleet/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GAUjB,MAAM,gBAAgB,CAAC"}

package/dist/fleet/knowledge.d.ts

@@ -0,0 +1,74 @@
+import type { RedundancyCluster } from "../consolidate/consolidator.js";
+export interface FleetRow {
+    readonly cellId: string;
+    readonly ingestEpoch?: number;
+    readonly namespace: string;
+    readonly thread?: string;
+    readonly supersededBy?: string;
+    readonly retiredBy?: string;
+    readonly derived?: true;
+}
+export interface FleetPolicy {
+    readonly thinBelow?: number;
+    readonly staleAfterHours?: number;
+    readonly driftWindowHours?: number;
+}
+export type FleetFlag = "thin" | "stale";
+export interface FleetPartition {
+    readonly key: string;
+    readonly cells: number;
+    readonly share: number;
+    readonly unstamped: number;
+    readonly oldest?: number;
+    readonly newest?: number;
+    readonly ageHours?: number;
+    readonly superseded: number;
+    readonly supersessionRate: number;
+    readonly recentSupersessions?: number;
+    readonly retired: number;
+    readonly derived: number;
+    readonly flags: readonly FleetFlag[];
+}
+export interface ClusterSummary {
+    readonly namespace: string;
+    readonly size: number;
+    readonly minSim: number;
+    readonly cellIds: readonly string[];
+}
+export type FleetConcentration = {
+    readonly status: "computed";
+    readonly clusters: number;
+    readonly redundantCells: number;
+    readonly redundancyRate: number;
+    readonly byNamespace: readonly {
+        readonly namespace: string;
+        readonly clusters: number;
+        readonly redundantCells: number;
+    }[];
+    readonly largest: readonly ClusterSummary[];
+} | {
+    readonly status: "not-computed";
+};
+export type FleetVerdict = "assembled" | "empty";
+export interface FleetReport {
+    readonly verdict: FleetVerdict;
+    readonly fleet: FleetPartition;
+    readonly namespaces: readonly FleetPartition[];
+    readonly threads: readonly FleetPartition[];
+    readonly unthreaded: number;
+    readonly concentration: FleetConcentration;
+    readonly policy: FleetPolicy;
+    readonly nowEpoch?: number;
+    readonly notes: readonly string[];
+}
+export interface FleetInput {
+    readonly rows: readonly FleetRow[];
+    readonly clusters?: readonly RedundancyCluster[];
+    readonly nowEpoch?: number;
+    readonly policy?: FleetPolicy;
+    readonly epochOf?: (cellId: string) => number | undefined;
+}
+export declare const LARGEST_CLUSTERS = 5;
+export declare function assembleFleetReport(input: FleetInput): FleetReport;
+export declare function renderFleetReport(r: FleetReport): string;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/fleet/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/fleet/knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAExE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5H,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAExC,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3D;AAED,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAgGlC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAyBlE;AAoBD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAoBxD"}

package/dist/fleet/knowledge.js

@@ -0,0 +1,178 @@
+export const LARGEST_CLUSTERS = 5;
+const finitePos = (v) => v !== undefined && Number.isFinite(v) && v > 0;
+const finiteNonNeg = (v) => v !== undefined && Number.isFinite(v) && v >= 0;
+function partition(key, rows, fleetCells, input) {
+    const policy = input.policy ?? {};
+    let oldest;
+    let newest;
+    let unstamped = 0;
+    let superseded = 0;
+    let retired = 0;
+    let derived = 0;
+    const windowEvaluable = finiteNonNeg(input.nowEpoch) && finiteNonNeg(policy.driftWindowHours) && input.epochOf !== undefined;
+    let recent = 0;
+    for (const r of rows) {
+        if (finitePos(r.ingestEpoch)) {
+            if (oldest === undefined || r.ingestEpoch < oldest)
+                oldest = r.ingestEpoch;
+            if (newest === undefined || r.ingestEpoch > newest)
+                newest = r.ingestEpoch;
+        }
+        else {
+            unstamped++;
+        }
+        if (r.supersededBy !== undefined) {
+            superseded++;
+            if (windowEvaluable) {
+                const at = input.epochOf(r.supersededBy);
+                if (finitePos(at) && at >= input.nowEpoch - policy.driftWindowHours)
+                    recent++;
+            }
+        }
+        if (r.retiredBy !== undefined)
+            retired++;
+        if (r.derived === true)
+            derived++;
+    }
+    const cells = rows.length;
+    const ageHours = finiteNonNeg(input.nowEpoch) && newest !== undefined ? input.nowEpoch - newest : undefined;
+    const flags = [];
+    if (finiteNonNeg(policy.thinBelow) && cells < policy.thinBelow)
+        flags.push("thin");
+    if (finiteNonNeg(policy.staleAfterHours) && ageHours !== undefined && ageHours > policy.staleAfterHours)
+        flags.push("stale");
+    return {
+        key,
+        cells,
+        share: fleetCells === 0 ? 0 : cells / fleetCells,
+        unstamped,
+        ...(oldest !== undefined ? { oldest } : {}),
+        ...(newest !== undefined ? { newest } : {}),
+        ...(ageHours !== undefined ? { ageHours } : {}),
+        superseded,
+        supersessionRate: cells === 0 ? 0 : superseded / cells,
+        ...(windowEvaluable ? { recentSupersessions: recent } : {}),
+        retired,
+        derived,
+        flags,
+    };
+}
+function groupBy(rows, keyOf) {
+    const out = new Map();
+    for (const r of rows) {
+        const k = keyOf(r);
+        if (k === undefined)
+            continue;
+        const g = out.get(k);
+        if (g)
+            g.push(r);
+        else
+            out.set(k, [r]);
+    }
+    return out;
+}
+const bySizeThenKey = (a, b) => b.cells - a.cells || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+function concentration(clusters, fleetCells) {
+    if (clusters === undefined)
+        return { status: "not-computed" };
+    const byNs = new Map();
+    let redundantCells = 0;
+    for (const c of clusters) {
+        const extra = Math.max(0, c.cellIds.length - 1);
+        redundantCells += extra;
+        const g = byNs.get(c.namespace) ?? { clusters: 0, redundantCells: 0 };
+        g.clusters++;
+        g.redundantCells += extra;
+        byNs.set(c.namespace, g);
+    }
+    const largest = [...clusters]
+        .sort((a, b) => b.cellIds.length - a.cellIds.length || (a.namespace < b.namespace ? -1 : a.namespace > b.namespace ? 1 : 0))
+        .slice(0, LARGEST_CLUSTERS)
+        .map((c) => ({ namespace: c.namespace, size: c.cellIds.length, minSim: c.minSim, cellIds: c.cellIds }));
+    return {
+        status: "computed",
+        clusters: clusters.length,
+        redundantCells,
+        redundancyRate: fleetCells === 0 ? 0 : redundantCells / fleetCells,
+        byNamespace: [...byNs.entries()]
+            .map(([namespace, g]) => ({ namespace, ...g }))
+            .sort((a, b) => b.redundantCells - a.redundantCells || (a.namespace < b.namespace ? -1 : a.namespace > b.namespace ? 1 : 0)),
+        largest,
+    };
+}
+export function assembleFleetReport(input) {
+    const rows = input.rows;
+    const policy = input.policy ?? {};
+    const fleet = partition("fleet", rows, rows.length, input);
+    const namespaces = [...groupBy(rows, (r) => r.namespace).entries()].map(([k, g]) => partition(k, g, rows.length, input)).sort(bySizeThenKey);
+    const threads = [...groupBy(rows, (r) => r.thread).entries()].map(([k, g]) => partition(k, g, rows.length, input)).sort(bySizeThenKey);
+    const unthreaded = rows.filter((r) => r.thread === undefined).length;
+    const notes = [];
+    if (!finiteNonNeg(policy.thinBelow) && !finiteNonNeg(policy.staleAfterHours))
+        notes.push("no thinness/staleness policy supplied: no partition is flagged");
+    else if (finiteNonNeg(policy.staleAfterHours) && !finiteNonNeg(input.nowEpoch))
+        notes.push("staleAfterHours needs nowEpoch: no partition is flagged stale");
+    if (!finiteNonNeg(input.nowEpoch))
+        notes.push("no nowEpoch: ages not computed");
+    if (finiteNonNeg(policy.driftWindowHours) && (!finiteNonNeg(input.nowEpoch) || input.epochOf === undefined))
+        notes.push("driftWindowHours needs nowEpoch and epochOf: recent supersessions not counted");
+    if (input.clusters === undefined)
+        notes.push("clusters not supplied: concentration not computed");
+    if (fleet.unstamped > 0)
+        notes.push(`${fleet.unstamped} row(s) carry no ingest epoch and take part in no age`);
+    return {
+        verdict: rows.length === 0 ? "empty" : "assembled",
+        fleet,
+        namespaces,
+        threads,
+        unthreaded,
+        concentration: concentration(input.clusters, rows.length),
+        policy,
+        ...(finiteNonNeg(input.nowEpoch) ? { nowEpoch: input.nowEpoch } : {}),
+        notes,
+    };
+}
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+function partitionLine(p) {
+    const bits = [
+        `${p.cells} cell(s)`,
+        pct(p.share),
+        p.oldest !== undefined && p.newest !== undefined ? `@${p.oldest}h..@${p.newest}h` : "undated",
+        p.ageHours !== undefined ? `age ${p.ageHours}h` : "",
+        p.unstamped > 0 ? `unstamped ${p.unstamped}` : "",
+        `superseded ${p.superseded} (${pct(p.supersessionRate)})`,
+        p.recentSupersessions !== undefined ? `recent ${p.recentSupersessions}` : "",
+        p.retired > 0 ? `retired ${p.retired}` : "",
+        p.derived > 0 ? `derived ${p.derived}` : "",
+        p.flags.length > 0 ? `[${p.flags.join(",")}]` : "",
+    ].filter((b) => b !== "");
+    return `${p.key}: ${bits.join(" · ")}`;
+}
+export function renderFleetReport(r) {
+    const lines = [];
+    lines.push(`FLEET — ${r.verdict} · ${partitionLine(r.fleet)}`);
+    lines.push(`  namespaces (${r.namespaces.length}):`);
+    for (const p of r.namespaces)
+        lines.push(`    ${partitionLine(p)}`);
+    lines.push(`  threads (${r.threads.length}; unthreaded ${r.unthreaded}):`);
+    for (const p of r.threads)
+        lines.push(`    ${partitionLine(p)}`);
+    if (r.concentration.status === "computed") {
+        const c = r.concentration;
+        lines.push(`  concentration: ${c.clusters} cluster(s) · redundant ${c.redundantCells} (${pct(c.redundancyRate)})`);
+        for (const n of c.byNamespace)
+            lines.push(`    ${n.namespace}: ${n.clusters} cluster(s), redundant ${n.redundantCells}`);
+        for (const l of c.largest)
+            lines.push(`    largest: ${l.namespace} ×${l.size} minSim ${l.minSim.toFixed(3)} [${l.cellIds.join(", ")}]`);
+    }
+    else {
+        lines.push("  concentration: not computed");
+    }
+    if (r.notes.length > 0) {
+        lines.push("  notes:");
+        for (const n of r.notes)
+            lines.push(`    ${n}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=knowledge.js.map