harnery 0.34.1 → 0.36.0

package/dist/core/semantic/scheduler.js

@@ -0,0 +1,91 @@
+export const SEMANTIC_HARD_CALLS_PER_HOUR = 120;
+export const SEMANTIC_INVALID_RETRY_COOLDOWN_MS = 5 * 60_000;
+export const SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS = 2 * 60_000;
+export const SEMANTIC_MIN_AMBIENT_GENERATION_CALL_INTERVAL_MS = 5 * 60_000;
+export const SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS = SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS;
+export function semanticPriorityBand(evidence) {
+    if (evidence.attention ||
+        (evidence.lifecycle && evidence.lifecycle.state !== "active") ||
+        evidence.recent.some((item) => item.kind === "terminal")) {
+        return 1;
+    }
+    return 2;
+}
+export function semanticPendingCallIntervalMs(pending) {
+    return pending.band === 1
+        ? SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS
+        : SEMANTIC_MIN_AMBIENT_GENERATION_CALL_INTERVAL_MS;
+}
+export function enqueueSemanticPending(pending, evidence, nowIso) {
+    const prior = pending.find((item) => item.generation_id === evidence.generation_id);
+    const next = {
+        generation_id: evidence.generation_id,
+        evidence_digest: evidence.evidence_digest,
+        band: semanticPriorityBand(evidence),
+        pending_since: prior?.evidence_digest === evidence.evidence_digest ? prior.pending_since : nowIso,
+    };
+    return [...pending.filter((item) => item.generation_id !== evidence.generation_id), next];
+}
+export function selectSemanticPending(pending, lastFirstBandGenerationId, callHistory = []) {
+    const sorted = [...pending].sort((left, right) => left.band - right.band ||
+        left.pending_since.localeCompare(right.pending_since) ||
+        left.generation_id.localeCompare(right.generation_id));
+    const recentlyCalled = new Set(callHistory.map((call) => call.generation_id));
+    const uncovered = sorted.filter((item) => !recentlyCalled.has(item.generation_id));
+    const eligible = uncovered.length > 0 ? uncovered : sorted;
+    const firstBand = eligible.filter((item) => item.band === 1);
+    if (firstBand.length > 0) {
+        const lastIndex = firstBand.findIndex((item) => item.generation_id === lastFirstBandGenerationId);
+        return firstBand[lastIndex >= 0 ? (lastIndex + 1) % firstBand.length : 0];
+    }
+    return eligible[0];
+}
+export function activeSemanticCallHistory(history, nowMs) {
+    return history.filter((call) => {
+        const started = Date.parse(call.started_at);
+        return Number.isFinite(started) && nowMs - started < 60 * 60_000;
+    });
+}
+export function semanticRateCap(history, nowMs, configuredLimit = SEMANTIC_HARD_CALLS_PER_HOUR) {
+    const active = activeSemanticCallHistory(history, nowMs).sort((left, right) => left.started_at.localeCompare(right.started_at));
+    const limit = Math.min(SEMANTIC_HARD_CALLS_PER_HOUR, Math.max(1, Math.floor(configuredLimit)));
+    if (active.length < limit)
+        return { available: limit - active.length };
+    return {
+        available: 0,
+        eligible_after: new Date(Date.parse(active[0].started_at) + 60 * 60_000).toISOString(),
+    };
+}
+export function semanticGenerationCallEligible(history, generationId, nowMs, minimumIntervalMs = SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS) {
+    const newest = history
+        .filter((call) => call.generation_id === generationId)
+        .map((call) => Date.parse(call.started_at))
+        .filter(Number.isFinite)
+        .sort((left, right) => right - left)[0];
+    return newest === undefined || nowMs - newest >= Math.max(0, minimumIntervalMs);
+}
+export function semanticPendingPassDue(input) {
+    const matured = input.pending.filter((item) => {
+        const pendingSince = Date.parse(item.pending_since);
+        return (!Number.isFinite(pendingSince) || input.nowMs - pendingSince >= Math.max(0, input.debounceMs));
+    });
+    if (matured.length === 0)
+        return false;
+    const cap = semanticRateCap(input.callHistory, input.nowMs, input.callsPerHour);
+    // One pass is still required at the cap so runSemanticOnce can publish
+    // deferred receipts and remove the matured items from the pending queue.
+    if (cap.available === 0)
+        return true;
+    return matured.some((item) => semanticGenerationCallEligible(input.callHistory, item.generation_id, input.nowMs, input.minimumGenerationCallIntervalMs ?? semanticPendingCallIntervalMs(item)));
+}
+export function semanticDocumentEligible(document, evidence, nowMs) {
+    if (!document || document.source.evidence_digest !== evidence.evidence_digest)
+        return true;
+    if (document.reader_outcome === "accepted")
+        return false;
+    if (document.reader_outcome === "deferred") {
+        return Date.parse(document.receipt.eligible_after) <= nowMs;
+    }
+    const generated = Date.parse(document.generated_at);
+    return !Number.isFinite(generated) || nowMs - generated >= SEMANTIC_INVALID_RETRY_COOLDOWN_MS;
+}

package/dist/core/semantic/service-status.d.ts

@@ -0,0 +1,51 @@
+import { SEMANTIC_READER_ROUTES } from "./routes.js";
+import { type SemanticUsageAggregate } from "./usage.js";
+export declare const SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION: 1;
+export type SemanticServiceState = "starting" | "running" | "stopping" | "stopped";
+export type SemanticServiceErrorCode = "ledger_unavailable" | "semantic_pass_failed";
+export interface SemanticServiceStatusRecord {
+    schema_version: typeof SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION;
+    pid: number;
+    host: string;
+    nonce: string;
+    state: SemanticServiceState;
+    started_at: string;
+    heartbeat_at: string;
+    calls_per_hour?: number;
+    sweep_count: number;
+    pass_count: number;
+    model_calls: number;
+    cache_hits: number;
+    process_usage?: SemanticUsageAggregate;
+    last_sweep_at?: string;
+    last_pass_at?: string;
+    last_error_code?: SemanticServiceErrorCode;
+    stopped_at?: string;
+}
+export interface SemanticServiceStatus {
+    running: boolean;
+    stale: boolean;
+    record?: SemanticServiceStatusRecord;
+    newest_successful_pass?: string;
+    pending_count: number;
+    rolling_calls?: {
+        used: number;
+        limit: number;
+        available: number;
+        eligible_after?: string;
+    };
+    routes?: Array<{
+        harness: keyof typeof SEMANTIC_READER_ROUTES;
+        configured_model: string;
+        invocation_model_id: string;
+        resolved_model_id?: string;
+        model_attestation?: "verified" | "requested-only";
+        available?: boolean;
+        reason_code?: string;
+    }>;
+    rolling_usage?: SemanticUsageAggregate;
+    process_usage?: SemanticUsageAggregate;
+}
+/** Read-only service health. This module cannot spawn, signal, or write. */
+export declare function readSemanticServiceStatus(coordRootRaw: string): SemanticServiceStatus;
+//# sourceMappingURL=service-status.d.ts.map

package/dist/core/semantic/service-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-status.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/service-status.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAOrD,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,sCAAsC,EAAG,CAAU,CAAC;AAIjE,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AACnF,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,GAAG,sBAAsB,CAAC;AAErF,MAAM,WAAW,2BAA2B;IAC1C,cAAc,EAAE,OAAO,sCAAsC,CAAC;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,oBAAoB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,2BAA2B,CAAC;IACrC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,OAAO,sBAAsB,CAAC;QAC7C,gBAAgB,EAAE,MAAM,CAAC;QACzB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;QAClD,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAqDrF"}

package/dist/core/semantic/service-status.js

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import { SEMANTIC_READER_ROUTES } from "./routes.js";
+import { activeSemanticCallHistory, SEMANTIC_HARD_CALLS_PER_HOUR, semanticRateCap, } from "./scheduler.js";
+import { readSemanticManifest, semanticPaths } from "./storage.js";
+import { aggregateSemanticUsage, emptySemanticUsageAggregate, } from "./usage.js";
+export const SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION = 1;
+const FOREIGN_STATUS_STALE_MS = 2 * 60_000;
+const MAX_FILE_BYTES = 512 * 1024;
+/** Read-only service health. This module cannot spawn, signal, or write. */
+export function readSemanticServiceStatus(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const record = readStatusRecord(coordRoot);
+    const manifest = safeManifest(coordRoot);
+    const now = Date.now();
+    const history = activeSemanticCallHistory(manifest?.call_history ?? [], now);
+    const limit = Math.min(SEMANTIC_HARD_CALLS_PER_HOUR, Math.max(1, Math.floor(record?.calls_per_hour ?? SEMANTIC_HARD_CALLS_PER_HOUR)));
+    const cap = semanticRateCap(history, now, limit);
+    const rollingUsage = aggregateSemanticUsage(history.map((call) => ({
+        source_harness: call.source_harness,
+        configured_model: call.configured_model,
+        resolved_model_id: call.resolved_model_id,
+        model_attestation: call.model_attestation,
+        action: call.outcome,
+        model_call: true,
+        usage: call.usage,
+        invalid_reason_codes: call.invalid_reason_codes,
+    })));
+    const processUsage = record?.process_usage ?? legacyProcessUsage(record?.model_calls ?? 0);
+    const shared = {
+        ...(manifest?.newest_successful_pass
+            ? { newest_successful_pass: manifest.newest_successful_pass }
+            : {}),
+        pending_count: manifest?.pending.length ?? 0,
+        rolling_calls: {
+            used: history.length,
+            limit,
+            available: cap.available,
+            ...(cap.eligible_after ? { eligible_after: cap.eligible_after } : {}),
+        },
+        routes: semanticStatusRoutes(manifest?.adapter_resolutions),
+        rolling_usage: rollingUsage,
+        process_usage: processUsage,
+    };
+    if (!record) {
+        return {
+            running: false,
+            stale: false,
+            ...shared,
+        };
+    }
+    const running = statusOwnerIsLive(record);
+    return {
+        running,
+        stale: !running && record.state !== "stopped",
+        record,
+        ...shared,
+    };
+}
+function semanticStatusRoutes(resolutions) {
+    return Object.keys(SEMANTIC_READER_ROUTES).map((harness) => {
+        const route = SEMANTIC_READER_ROUTES[harness];
+        const resolution = resolutions?.[harness];
+        return {
+            harness,
+            configured_model: route.configured_model,
+            invocation_model_id: route.invocation_model_id,
+            ...(resolution?.resolved_model_id
+                ? { resolved_model_id: resolution.resolved_model_id }
+                : {}),
+            ...(resolution?.model_attestation
+                ? { model_attestation: resolution.model_attestation }
+                : {}),
+            ...(resolution ? { available: resolution.available } : {}),
+            ...(resolution?.reason_code ? { reason_code: resolution.reason_code } : {}),
+        };
+    });
+}
+function legacyProcessUsage(modelCalls) {
+    const aggregate = emptySemanticUsageAggregate();
+    aggregate.call_count = modelCalls;
+    aggregate.unreported_calls = modelCalls;
+    return aggregate;
+}
+function safeManifest(coordRoot) {
+    try {
+        return readSemanticManifest(coordRoot);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readStatusRecord(coordRoot) {
+    const path = semanticPaths(coordRoot).service;
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = readBoundedJson(path, "semantic service status");
+        if (value.schema_version !== SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION ||
+            !Number.isSafeInteger(value.pid) ||
+            value.pid < 1 ||
+            typeof value.host !== "string" ||
+            typeof value.nonce !== "string" ||
+            !validTimestamp(value.started_at) ||
+            !validTimestamp(value.heartbeat_at)) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function statusOwnerIsLive(record) {
+    if (record.state === "stopped")
+        return false;
+    if (record.host === hostname())
+        return pidAlive(record.pid);
+    const age = Date.now() - Date.parse(record.heartbeat_at);
+    return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function readBoundedJson(path, label) {
+    const size = statSync(path).size;
+    if (size <= 0 || size > MAX_FILE_BYTES)
+        throw new Error(`${label} has invalid size ${size}`);
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}

package/dist/core/semantic/service.d.ts

@@ -0,0 +1,52 @@
+import { readLedgerV3Since } from "../events/v3/index.js";
+import { type SemanticOnceReport } from "./once.js";
+import { type SemanticServiceStatus, type SemanticServiceStatusRecord } from "./service-status.js";
+export { readSemanticServiceStatus, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, type SemanticServiceErrorCode, type SemanticServiceState, type SemanticServiceStatus, type SemanticServiceStatusRecord, } from "./service-status.js";
+export declare const SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS = 5000;
+export declare const SEMANTIC_SERVICE_DEFAULT_WAKE_MS = 1000;
+export declare const SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS = 5000;
+export interface RunSemanticServiceDaemonInput {
+    coordRoot: string;
+    callsPerHour?: number;
+    debounceMs?: number;
+    wakeIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    maxSweeps?: number;
+    now?: () => Date;
+    readSince?: typeof readLedgerV3Since;
+    runOnce?: (input: {
+        coordRoot: string;
+        callsPerHour?: number;
+        debounceMs: number;
+        shouldStop: () => boolean;
+    }) => Promise<SemanticOnceReport>;
+    waitForWake?: (milliseconds: number) => Promise<void>;
+}
+export type EnsureSemanticServiceState = "running" | "started" | "paused" | "inactive" | "unavailable";
+export interface EnsureSemanticServiceResult {
+    state: EnsureSemanticServiceState;
+    status?: SemanticServiceStatus;
+    error?: string;
+}
+export interface EnsureSemanticServiceDependencies {
+    readStatus: (coordRoot: string) => SemanticServiceStatus;
+    start: (coordRoot: string) => Promise<SemanticServiceStatus>;
+    isPaused: (coordRoot: string) => boolean;
+    isActive: (coordRoot: string) => boolean;
+}
+export declare function spawnSemanticService(coordRootRaw: string, options?: {
+    callsPerHour?: number;
+}): Promise<SemanticServiceStatus>;
+/**
+ * Start semantic reading when V3 is active, unless an operator paused it.
+ *
+ * Dashboard hosts call this before launching their web process. A failed
+ * semantic launch is reported as data instead of throwing so the read-only
+ * dashboard remains available.
+ */
+export declare function ensureSemanticServiceRunning(coordRootRaw: string, overrides?: Partial<EnsureSemanticServiceDependencies>): Promise<EnsureSemanticServiceResult>;
+export declare function requestSemanticServiceStop(coordRootRaw: string): SemanticServiceStatus;
+export declare function runSemanticServiceDaemon(input: RunSemanticServiceDaemonInput): Promise<SemanticServiceStatusRecord>;
+export declare function acquireSemanticServiceLease(coordRootRaw: string): () => void;
+export declare function appendSemanticServiceDiagnostic(coordRoot: string, entry: Record<string, unknown>): "shared" | "legacy";
+//# sourceMappingURL=service.d.ts.map

package/dist/core/semantic/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/service.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAc7B,OAAO,EACL,yBAAyB,EACzB,sCAAsC,EACtC,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAC1D,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AACtD,eAAO,MAAM,qCAAqC,OAAQ,CAAC;AA2B3D,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,iBAAiB,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,OAAO,CAAC;KAC3B,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,MAAM,0BAA0B,GAClC,SAAS,GACT,SAAS,GACT,QAAQ,GACR,UAAU,GACV,aAAa,CAAC;AAElB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,0BAA0B,CAAC;IAClC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iCAAiC;IAChD,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,qBAAqB,CAAC;IACzD,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACtC,OAAO,CAAC,qBAAqB,CAAC,CAgDhC;AAED;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,OAAO,CAAC,iCAAiC,CAAM,GACzD,OAAO,CAAC,2BAA2B,CAAC,CAsBtC;AAED,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAgBtF;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,2BAA2B,CAAC,CAuLtC;AAED,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,IAAI,CAuC5E;AA8HD,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,QAAQ,GAAG,QAAQ,CAerB"}