@saihm/shm 0.0.0-stage → 0.38.0

package/dist/saihm_client/timing.js

@@ -0,0 +1,250 @@
+import { isFeatureLabel } from "./server_features.js";
+export const DEFAULT_SAMPLES_PER_OPERATION = 4096;
+export const DEFAULT_MAX_OPERATIONS = 32;
+export const SAMPLES_PER_OPERATION_LIMIT = 1_048_576;
+export const OPERATIONS_LIMIT = 1024;
+export const DEFAULT_MIN_ATTAINMENT_SAMPLES = 20;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const own = (o, key) => (Object.hasOwn(o, key) ? o[key] : undefined);
+const isMillis = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0;
+const absentTiming = (reason) => Object.freeze({ kind: "absent", reason });
+const malformedTiming = (field, reason) => Object.freeze({ kind: "malformed", field, reason });
+export function parseTiming(toolResult) {
+    try {
+        if (!isObject(toolResult))
+            return absentTiming("the tool result is not an object, so it carries no timing");
+        const raw = own(toolResult, "timing");
+        if (raw === undefined)
+            return absentTiming("the tool result carries no timing");
+        if (raw === null)
+            return absentTiming("timing is null");
+        if (!isObject(raw))
+            return malformedTiming("timing", "timing is not an object");
+        const totalMs = own(raw, "totalMs");
+        if (totalMs === undefined)
+            return malformedTiming("timing.totalMs", "timing.totalMs is missing");
+        if (!isMillis(totalMs))
+            return malformedTiming("timing.totalMs", "timing.totalMs is not a finite, non-negative number of milliseconds");
+        const serverMs = own(raw, "serverMs");
+        if (serverMs === undefined)
+            return malformedTiming("timing.serverMs", "timing.serverMs is missing (null states that the service gave no time)");
+        if (serverMs !== null && !isMillis(serverMs)) {
+            return malformedTiming("timing.serverMs", "timing.serverMs is not null or a finite, non-negative number of milliseconds");
+        }
+        if (serverMs !== null && serverMs > totalMs)
+            return malformedTiming("timing.serverMs", "timing.serverMs is larger than timing.totalMs, which contains it");
+        const admission = own(raw, "admission");
+        if (admission === undefined)
+            return malformedTiming("timing.admission", "timing.admission is missing (null states that the service did not say)");
+        if (admission !== null && admission !== "reserved" && admission !== "shared") {
+            return malformedTiming("timing.admission", 'timing.admission is not "reserved", "shared" or null');
+        }
+        return Object.freeze({ kind: "present", timing: Object.freeze({ serverMs, totalMs, admission }) });
+    }
+    catch {
+        return malformedTiming("timing", "timing could not be read");
+    }
+}
+export function nearestRank(n, p) {
+    if (!Number.isSafeInteger(n) || n < 1 || typeof p !== "number" || !Number.isFinite(p) || p <= 0 || p > 100)
+        return Number.NaN;
+    const x = (p * n) / 100;
+    const whole = Math.round(x);
+    const rank = Math.abs(x - whole) <= RANK_TOLERANCE ? whole : Math.ceil(x);
+    return Math.min(n, Math.max(1, rank));
+}
+const RANK_TOLERANCE = 1e-9;
+const ADMISSION_UNKNOWN = 0;
+const ADMISSION_RESERVED = 1;
+const ADMISSION_SHARED = 2;
+const RECORDED = Object.freeze({ recorded: true });
+function newRing(capacity) {
+    return {
+        at: new Float64Array(capacity),
+        total: new Float64Array(capacity),
+        server: new Float64Array(capacity),
+        admission: new Uint8Array(capacity),
+        next: 0,
+        size: 0,
+        newestOverwrittenAt: Number.NEGATIVE_INFINITY,
+    };
+}
+function checkedSample(timing) {
+    try {
+        if (!isObject(timing))
+            return null;
+        const total = own(timing, "totalMs");
+        const server = own(timing, "serverMs");
+        const admission = own(timing, "admission");
+        if (!isMillis(total))
+            return null;
+        if (server !== null && (!isMillis(server) || server > total))
+            return null;
+        const code = admission === "reserved" ? ADMISSION_RESERVED : admission === "shared" ? ADMISSION_SHARED : admission === null ? ADMISSION_UNKNOWN : -1;
+        if (code < 0)
+            return null;
+        return { total, server: server === null ? Number.NaN : server, admission: code };
+    }
+    catch {
+        return null;
+    }
+}
+function percentiles(values) {
+    const n = values.length;
+    if (n === 0)
+        return null;
+    values.sort();
+    const at = (p) => values[nearestRank(n, p) - 1];
+    return Object.freeze({ n, p50: at(50), p95: at(95), p99: at(99) });
+}
+function requireNow(nowMs) {
+    if (typeof nowMs !== "number" || !Number.isFinite(nowMs))
+        throw new RangeError("TimingCollector: nowMs must be a finite number of milliseconds");
+}
+function requireWholeOption(name, value, limit) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > limit) {
+        throw new RangeError(`TimingCollector: ${name} must be a whole number from 1 to ${limit}`);
+    }
+    return value;
+}
+export class TimingCollector {
+    samplesPerOperation;
+    maxOperations;
+    rings = new Map();
+    refusals = { operation: 0, timing: 0, time: 0, operationLimit: 0 };
+    constructor(opts = {}) {
+        this.samplesPerOperation = requireWholeOption("samplesPerOperation", opts.samplesPerOperation ?? DEFAULT_SAMPLES_PER_OPERATION, SAMPLES_PER_OPERATION_LIMIT);
+        this.maxOperations = requireWholeOption("maxOperations", opts.maxOperations ?? DEFAULT_MAX_OPERATIONS, OPERATIONS_LIMIT);
+    }
+    refuse(refusal) {
+        if (refusal === "operation-limit")
+            this.refusals.operationLimit++;
+        else
+            this.refusals[refusal]++;
+        return Object.freeze({ recorded: false, refusal });
+    }
+    record(operation, timing, atMs) {
+        if (!isFeatureLabel(operation))
+            return this.refuse("operation");
+        const sample = checkedSample(timing);
+        if (sample === null)
+            return this.refuse("timing");
+        if (typeof atMs !== "number" || !Number.isFinite(atMs))
+            return this.refuse("time");
+        let ring = this.rings.get(operation);
+        if (ring === undefined) {
+            if (this.rings.size >= this.maxOperations)
+                return this.refuse("operation-limit");
+            ring = newRing(this.samplesPerOperation);
+            this.rings.set(operation, ring);
+        }
+        const slot = ring.next;
+        if (ring.size === this.samplesPerOperation) {
+            const overwritten = ring.at[slot];
+            if (overwritten > ring.newestOverwrittenAt)
+                ring.newestOverwrittenAt = overwritten;
+        }
+        else {
+            ring.size++;
+        }
+        ring.at[slot] = atMs;
+        ring.total[slot] = sample.total;
+        ring.server[slot] = sample.server;
+        ring.admission[slot] = sample.admission;
+        ring.next = (slot + 1) % this.samplesPerOperation;
+        return RECORDED;
+    }
+    report(nowMs, windowMs) {
+        requireNow(nowMs);
+        if (typeof windowMs !== "number" || !Number.isFinite(windowMs) || windowMs <= 0) {
+            throw new RangeError("TimingCollector: windowMs must be a finite number of milliseconds above 0");
+        }
+        const fromMs = nowMs - windowMs;
+        const operations = [...this.rings.keys()].sort().map((operation) => this.summarize(operation, this.rings.get(operation), fromMs, nowMs));
+        return Object.freeze({ fromMs, toMs: nowMs, operations: Object.freeze(operations), refused: Object.freeze({ ...this.refusals }) });
+    }
+    summarize(operation, ring, fromMs, toMs) {
+        let reserved = 0;
+        let shared = 0;
+        let unknown = 0;
+        const totals = [];
+        const servers = [];
+        const networks = [];
+        for (let i = 0; i < ring.size; i++) {
+            const at = ring.at[i];
+            if (!(at > fromMs && at <= toMs))
+                continue;
+            const admission = ring.admission[i];
+            if (admission === ADMISSION_RESERVED)
+                reserved++;
+            else if (admission === ADMISSION_SHARED)
+                shared++;
+            else
+                unknown++;
+            const total = ring.total[i];
+            const server = ring.server[i];
+            totals.push(total);
+            if (!Number.isNaN(server)) {
+                servers.push(server);
+                networks.push(total - server);
+            }
+        }
+        return Object.freeze({
+            operation,
+            counts: Object.freeze({ all: totals.length, reserved, shared, unknown }),
+            totalMs: percentiles(Float64Array.from(totals)),
+            serverMs: percentiles(Float64Array.from(servers)),
+            networkMs: percentiles(Float64Array.from(networks)),
+            windowHeld: ring.newestOverwrittenAt <= fromMs,
+        });
+    }
+    attainment(objective, nowMs, opts = {}) {
+        requireNow(nowMs);
+        const minSamples = opts.minSamples ?? DEFAULT_MIN_ATTAINMENT_SAMPLES;
+        if (!Number.isSafeInteger(minSamples) || minSamples < 1)
+            throw new RangeError("TimingCollector: minSamples must be a whole number above 0");
+        if (minSamples > this.samplesPerOperation) {
+            throw new RangeError("TimingCollector: minSamples is above samplesPerOperation, so no verdict could ever be given");
+        }
+        const isValue = typeof objective === "object" && objective !== null;
+        const entries = isValue ? objective.objectives : undefined;
+        const windowMs = isValue ? objective.windowMs : undefined;
+        if (!Array.isArray(entries) || typeof windowMs !== "number" || !Number.isFinite(windowMs) || windowMs <= 0) {
+            throw new TypeError("TimingCollector: attainment needs a latency objective: the value of an available parseLatencyObjective read");
+        }
+        return Object.freeze(entries.map((entry) => this.judge(entry, windowMs, nowMs, minSamples)));
+    }
+    judge(entry, windowMs, nowMs, minSamples) {
+        const e = isObject(entry) ? entry : {};
+        const operation = typeof e["operation"] === "string" ? e["operation"] : "";
+        const percentile = typeof e["percentile"] === "number" ? e["percentile"] : Number.NaN;
+        const thresholdMs = typeof e["thresholdMs"] === "number" ? e["thresholdMs"] : Number.NaN;
+        const gap = (n, reason) => Object.freeze({ operation, percentile, thresholdMs, n, observedMs: null, met: null, reason });
+        const usablePercentile = Number.isFinite(percentile) && percentile > 0 && percentile <= 100;
+        if (!isFeatureLabel(operation) || !usablePercentile || !Number.isSafeInteger(thresholdMs) || thresholdMs <= 0) {
+            return gap(0, "entry-unusable");
+        }
+        const fromMs = nowMs - windowMs;
+        const ring = this.rings.get(operation);
+        const compared = [];
+        if (ring !== undefined) {
+            for (let i = 0; i < ring.size; i++) {
+                const at = ring.at[i];
+                const server = ring.server[i];
+                if (at > fromMs && at <= nowMs && ring.admission[i] === ADMISSION_RESERVED && !Number.isNaN(server))
+                    compared.push(server);
+            }
+        }
+        const n = compared.length;
+        if (n === 0)
+            return gap(0, "no-reserved-samples");
+        if (n < minSamples)
+            return gap(n, "insufficient-samples");
+        if (ring !== undefined && ring.newestOverwrittenAt > fromMs)
+            return gap(n, "window-not-held");
+        const sorted = Float64Array.from(compared).sort();
+        const observedMs = sorted[nearestRank(n, percentile) - 1];
+        return Object.freeze({ operation, percentile, thresholdMs, n, observedMs, met: observedMs <= thresholdMs });
+    }
+}
+//# sourceMappingURL=timing.js.map

package/dist/saihm_client/timing.js.map

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

package/dist/saihm_client/types.d.ts

@@ -0,0 +1,108 @@
+export interface IndexEntry {
+    readonly cellId: string;
+    readonly label: string;
+    readonly epoch: number;
+    readonly byteSize: number;
+    readonly tier: string;
+    readonly forgotten: boolean;
+    readonly forgottenEpoch?: number;
+}
+export interface RecalledBody {
+    readonly cellId: string;
+    readonly plaintext: string;
+    readonly epoch: number;
+    readonly tier: string;
+    readonly partial?: boolean;
+    readonly seq?: string;
+}
+export interface OwnCellRead {
+    readonly cellId: string;
+    readonly seq: string;
+    readonly commitment: string;
+    readonly plaintext: string;
+}
+export interface RecallOptions {
+    readonly timeoutMs?: number;
+}
+export interface SaihmReadPort {
+    readonly tenantId: string;
+    readonly agentIdHash?: string | undefined;
+    readIndex(): Promise<IndexEntry[]>;
+    recallByQuery(query: string, opts?: RecallOptions): Promise<RecalledBody[]>;
+    recallByQueryWithMeta?(query: string, opts?: RecallOptions): Promise<RecallAnswer>;
+    listVersionsPage?(after?: string): Promise<ListingPage>;
+    recallOwn?(cellId: string): Promise<{
+        readonly found: OwnCellRead | null;
+        readonly servedBy?: string;
+        readonly asOf?: string;
+    }>;
+    readShared?(sharerAgentIdHash: string, sharerRecord: {
+        readonly mldsaPubKey: string;
+        readonly mlkemPubKey: string;
+        readonly mlkemPubKeySelfSig: string;
+    }, cellId: string): Promise<string | undefined>;
+}
+export interface ListingPage {
+    readonly cells: readonly {
+        readonly cellId: string;
+        readonly seq: string | null;
+        readonly commitment: string;
+    }[];
+    readonly next: string | null;
+    readonly asOf?: string;
+    readonly servedBy?: string;
+}
+export interface RecallAnswer {
+    readonly bodies: RecalledBody[];
+    readonly servedBy?: string;
+    readonly asOf?: string;
+}
+export interface RememberReceipt {
+    readonly cellId: string;
+    readonly shardId?: string;
+    readonly seq?: string;
+    readonly commitmentHash?: string;
+    readonly commitment?: string;
+    readonly at?: string;
+}
+export type ShareScope = "read" | "write" | "readwrite";
+export interface ShareRecipient {
+    readonly agentIdHash: string;
+    readonly record?: {
+        readonly mldsaPubKey: string;
+        readonly mlkemPubKey: string;
+        readonly mlkemPubKeySelfSig: string;
+    };
+}
+export interface ShareOptions {
+    readonly expiryEpoch?: string;
+    readonly kind?: "temporary" | "permanent" | "syndicate";
+}
+export interface ShareReceipt {
+    readonly cellId: string;
+    readonly recipientAgentIdHash: string;
+    readonly scope: ShareScope;
+    readonly contractId?: string;
+}
+export interface ForgetReceipt {
+    readonly complete?: boolean;
+    readonly reason?: string;
+    readonly destructionAnchor?: string;
+    readonly at?: string;
+}
+export interface SaihmWritePort {
+    remember(content: string): Promise<RememberReceipt>;
+    forget(cellId: string): Promise<ForgetReceipt | void>;
+    share(cellId: string, recipient: ShareRecipient, scope: ShareScope, opts?: ShareOptions): Promise<ShareReceipt>;
+}
+export type SaihmPort = SaihmReadPort & SaihmWritePort;
+export declare class SaihmTransportError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class IgnoredParameterError extends SaihmTransportError {
+    readonly parameter: string;
+    readonly code: "ignored-parameter";
+    constructor(parameter: string, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/saihm_client/types.d.ts.map

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

package/dist/saihm_client/types.js

@@ -0,0 +1,19 @@
+export class SaihmTransportError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "SaihmTransportError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+export class IgnoredParameterError extends SaihmTransportError {
+    parameter;
+    code = "ignored-parameter";
+    constructor(parameter, message) {
+        super(message);
+        this.parameter = parameter;
+        this.name = "IgnoredParameterError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/saihm_client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/saihm_client/types.ts"],"names":[],"mappings":"AAyGA,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,KAAK,CAAW;IACzB,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,mBAAmB;IAEvC;IADZ,IAAI,GAAG,mBAA4B,CAAC;IAC7C,YAAqB,SAAiB,EAAE,OAAe;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QADI,cAAS,GAAT,SAAS,CAAQ;QAEpC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/service/handlers.d.ts

@@ -0,0 +1,91 @@
+import type { ResidentSession, ResidentHealth } from "./resident.js";
+import type { InjectionBudget, InjectionResult } from "../inject/proactive_injector.js";
+import type { Scope, ScopeSpec } from "../retrieval/scope.js";
+import type { WorkstreamAccount } from "../session/memory_session.js";
+import { LatencyRecorder, type ServiceLevel, type ServiceLevelVerdict, type TierLevelVerdict } from "./service_level.js";
+import type { Tier } from "../tiers/membership.js";
+export declare class ServiceError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface ServiceOptions {
+    readonly guidanceScope?: Scope;
+    readonly injectBudget?: InjectionBudget;
+    readonly preactBudget?: InjectionBudget;
+    readonly nowEpoch?: () => number;
+    readonly serviceLevels?: Readonly<Record<string, ServiceLevel>>;
+    readonly latencyCapacity?: number;
+    readonly tierLevels?: Readonly<Partial<Record<Tier, ServiceLevel>>>;
+    readonly tierLatency?: LatencyRecorder;
+}
+export type ServiceHealth = ResidentHealth & {
+    readonly serviceLevels?: readonly ServiceLevelVerdict[];
+    readonly tierLevels?: readonly TierLevelVerdict[];
+};
+export interface RecallRequest {
+    readonly q: string;
+    readonly k?: number;
+    readonly asOfEpoch?: number;
+}
+export interface RecallHit {
+    readonly cellId: string;
+    readonly rank: number;
+    readonly derived?: true;
+    readonly supersededBy?: string;
+    readonly retiredBy?: string;
+}
+export interface RecallResponse {
+    readonly q: string;
+    readonly k: number;
+    readonly ms: number;
+    readonly hits: readonly RecallHit[];
+    readonly detailed: boolean;
+}
+export interface PreactRequest {
+    readonly name: string;
+    readonly input: unknown;
+}
+export interface PreactResponse {
+    readonly cue: string;
+    readonly result: InjectionResult;
+    readonly rendered: string;
+}
+export interface ThreadsResponse {
+    readonly threads: readonly {
+        readonly slug: string;
+        readonly members: number;
+        readonly status: string | null;
+    }[];
+    readonly scope?: string;
+}
+export declare function renderInjectionText(r: InjectionResult): string;
+export declare function parseScopeSpec(raw: unknown): ScopeSpec;
+export declare class ServiceHandlers {
+    private readonly resident;
+    private readonly opts;
+    readonly latency: LatencyRecorder;
+    constructor(resident: ResidentSession, opts?: ServiceOptions);
+    health(): ServiceHealth;
+    private timed;
+    recall(req: RecallRequest): Promise<RecallResponse>;
+    private recallBody;
+    inject(req: {
+        readonly taskContext: string;
+        readonly budget?: InjectionBudget;
+    }): Promise<InjectionResult>;
+    preact(req: PreactRequest): Promise<PreactResponse | undefined>;
+    threads(req?: {
+        readonly spec?: ScopeSpec;
+    }): Promise<ThreadsResponse>;
+    thread(req: {
+        readonly slug: string;
+        readonly spec?: ScopeSpec;
+    }): Promise<WorkstreamAccount>;
+    census(spec: ScopeSpec): Promise<{
+        readonly scope: string;
+        readonly admitted: number;
+        readonly excluded: number;
+        readonly total: number;
+    }>;
+}
+//# sourceMappingURL=handlers.d.ts.map

package/dist/service/handlers.d.ts.map

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