harnery 0.34.1 → 0.36.0

package/src/core/semantic/storage.ts

@@ -0,0 +1,300 @@
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { canonicalJsonV3, sha256V3 } from "../events/v3/canonical.ts";
+import type { LedgerCursorV3 } from "../events/v3/reader.ts";
+import type {
+  SEMANTIC_EVIDENCE_CONTRACT_VERSION,
+  SEMANTIC_PROMPT_CONTRACT_VERSION,
+  SemanticAgentReadModelV2,
+  SemanticConfiguredModel,
+  SemanticHarness,
+  SemanticInvalidReasonCode,
+  SemanticUsageReceiptV1,
+} from "./contract.ts";
+import { validateSemanticReadModel } from "./validate.ts";
+
+export const SEMANTIC_MANIFEST_SCHEMA_VERSION = 2 as const;
+const MAX_JSON_BYTES = 512 * 1024;
+const MAX_CACHE_FILES = 500;
+const MAX_CACHE_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+
+export interface SemanticReaderResolution {
+  harness: SemanticHarness;
+  configured_model: SemanticConfiguredModel;
+  resolved_model_id?: string;
+  model_attestation?: "verified" | "requested-only";
+  available: boolean;
+  reason_code?:
+    | "harness_unavailable"
+    | "authentication_unavailable"
+    | "model_unavailable"
+    | "model_mismatch";
+  discovered_at: string;
+}
+
+export interface SemanticPendingItem {
+  generation_id: string;
+  evidence_digest: `sha256:${string}`;
+  band: 1 | 2;
+  pending_since: string;
+}
+
+export interface SemanticCallReceipt {
+  generation_id: string;
+  started_at: string;
+  source_harness?: SemanticHarness;
+  configured_model?: SemanticConfiguredModel;
+  resolved_model_id?: string;
+  model_attestation?: "verified" | "requested-only";
+  outcome?: "accepted" | "invalid" | "unavailable";
+  invalid_reason_codes?: SemanticInvalidReasonCode[];
+  duration_ms?: number;
+  input_bytes?: number;
+  output_bytes?: number;
+  usage?: SemanticUsageReceiptV1;
+}
+
+export interface SemanticManifestV2 {
+  schema_version: typeof SEMANTIC_MANIFEST_SCHEMA_VERSION;
+  ledger_genesis_id: string;
+  cursor?: LedgerCursorV3;
+  configuration_digest: `sha256:${string}`;
+  evidence_contract_version: typeof SEMANTIC_EVIDENCE_CONTRACT_VERSION;
+  prompt_contract_version: typeof SEMANTIC_PROMPT_CONTRACT_VERSION;
+  adapter_resolutions: Partial<Record<SemanticHarness, SemanticReaderResolution>>;
+  pending: SemanticPendingItem[];
+  call_history: SemanticCallReceipt[];
+  last_first_band_generation_id?: string;
+  newest_successful_pass?: string;
+  updated_at: string;
+}
+
+export interface SemanticCacheIdentity {
+  evidence_digest: `sha256:${string}`;
+  source_harness: SemanticHarness;
+  configured_model: SemanticConfiguredModel;
+  resolved_model_id: string;
+  evidence_contract_version: number;
+  prompt_contract_version: number;
+}
+
+export function semanticPaths(coordRootRaw: string) {
+  const root = join(resolve(coordRootRaw), ".harnery", "semantic", "v2");
+  return {
+    root,
+    manifest: join(root, "manifest.json"),
+    agents: join(root, "agents"),
+    cache: join(root, "cache"),
+    service: join(root, "service.json"),
+    stop: join(root, "stop.json"),
+    lease: join(root, "lease.json"),
+    log: join(root, "service.log"),
+  };
+}
+
+export function semanticConfigurationDigest(
+  resolutions: Partial<Record<SemanticHarness, SemanticReaderResolution>>,
+): `sha256:${string}` {
+  const stable = Object.fromEntries(
+    Object.entries(resolutions)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([harness, resolution]) => [
+        harness,
+        resolution
+          ? {
+              configured_model: resolution.configured_model,
+              ...(resolution.resolved_model_id
+                ? { resolved_model_id: resolution.resolved_model_id }
+                : {}),
+              ...(resolution.model_attestation
+                ? { model_attestation: resolution.model_attestation }
+                : {}),
+              available: resolution.available,
+              ...(resolution.reason_code ? { reason_code: resolution.reason_code } : {}),
+            }
+          : null,
+      ]),
+  );
+  return sha256V3(canonicalJsonV3(stable));
+}
+
+export function semanticCacheKey(identity: SemanticCacheIdentity): `sha256:${string}` {
+  return sha256V3(canonicalJsonV3(identity));
+}
+
+export function readSemanticManifest(coordRootRaw: string): SemanticManifestV2 | undefined {
+  const path = semanticPaths(coordRootRaw).manifest;
+  if (!existsSync(path)) return undefined;
+  const value = readBoundedJson<SemanticManifestV2>(path, "semantic manifest");
+  if (
+    value.schema_version !== SEMANTIC_MANIFEST_SCHEMA_VERSION ||
+    !Number.isSafeInteger(value.evidence_contract_version) ||
+    value.evidence_contract_version < 1 ||
+    !Number.isSafeInteger(value.prompt_contract_version) ||
+    value.prompt_contract_version < 1 ||
+    !Array.isArray(value.pending) ||
+    !Array.isArray(value.call_history)
+  ) {
+    throw new Error("semantic manifest has an unsupported schema");
+  }
+  return value;
+}
+
+export function writeSemanticManifest(coordRootRaw: string, manifest: SemanticManifestV2): void {
+  writePrivateJsonAtomic(semanticPaths(coordRootRaw).manifest, manifest);
+}
+
+export function readSemanticAgentDocument(
+  coordRootRaw: string,
+  generationId: string,
+): SemanticAgentReadModelV2 | undefined {
+  requireGenerationId(generationId);
+  const path = join(semanticPaths(coordRootRaw).agents, `${generationId}.json`);
+  if (!existsSync(path)) return undefined;
+  const value = readBoundedJson<unknown>(path, "semantic agent document");
+  const verdict = validateSemanticReadModel(value);
+  if (!verdict.ok)
+    throw new Error(`semantic agent document is invalid: ${verdict.issues.join(",")}`);
+  return verdict.value;
+}
+
+export function listSemanticAgentDocuments(coordRootRaw: string): SemanticAgentReadModelV2[] {
+  const dir = semanticPaths(coordRootRaw).agents;
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => /^gen_[a-zA-Z0-9-]+\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      try {
+        const value = readBoundedJson<unknown>(join(dir, name), "semantic agent document");
+        const verdict = validateSemanticReadModel(value);
+        return verdict.ok ? [verdict.value] : [];
+      } catch {
+        return [];
+      }
+    });
+}
+
+export function inspectSemanticDocument(
+  coordRootRaw: string,
+  instanceOrGeneration: string,
+): SemanticAgentReadModelV2 | undefined {
+  if (instanceOrGeneration.startsWith("gen_")) {
+    return readSemanticAgentDocument(coordRootRaw, instanceOrGeneration);
+  }
+  return listSemanticAgentDocuments(coordRootRaw)
+    .filter((document) => document.instance_id === instanceOrGeneration)
+    .sort((left, right) => right.generated_at.localeCompare(left.generated_at))[0];
+}
+
+export function writeSemanticAgentDocument(
+  coordRootRaw: string,
+  document: SemanticAgentReadModelV2,
+): void {
+  const verdict = validateSemanticReadModel(document);
+  if (!verdict.ok)
+    throw new Error(`refusing invalid semantic document: ${verdict.issues.join(",")}`);
+  writePrivateJsonAtomic(
+    join(semanticPaths(coordRootRaw).agents, `${document.generation_id}.json`),
+    document,
+  );
+}
+
+export function readSemanticCache(
+  coordRootRaw: string,
+  cacheKey: string,
+): SemanticAgentReadModelV2 | undefined {
+  requireDigest(cacheKey);
+  const path = join(semanticPaths(coordRootRaw).cache, `${cacheKey.slice("sha256:".length)}.json`);
+  if (!existsSync(path)) return undefined;
+  const value = readBoundedJson<unknown>(path, "semantic cache entry");
+  const verdict = validateSemanticReadModel(value);
+  return verdict.ok && verdict.value.reader_outcome === "accepted" ? verdict.value : undefined;
+}
+
+export function writeSemanticCache(
+  coordRootRaw: string,
+  cacheKey: string,
+  document: SemanticAgentReadModelV2,
+): void {
+  requireDigest(cacheKey);
+  if (document.reader_outcome !== "accepted") {
+    throw new Error("only accepted semantic documents may enter the cache");
+  }
+  writePrivateJsonAtomic(
+    join(semanticPaths(coordRootRaw).cache, `${cacheKey.slice("sha256:".length)}.json`),
+    document,
+  );
+}
+
+export function invalidateSemanticDerivedState(coordRootRaw: string): void {
+  const paths = semanticPaths(coordRootRaw);
+  rmSync(paths.agents, { recursive: true, force: true });
+  rmSync(paths.cache, { recursive: true, force: true });
+  rmSync(paths.manifest, { force: true });
+}
+
+export function pruneSemanticStorage(
+  coordRootRaw: string,
+  options: { keepGenerations: ReadonlySet<string>; now?: number; maxCacheFiles?: number },
+): void {
+  const paths = semanticPaths(coordRootRaw);
+  if (existsSync(paths.agents)) {
+    for (const name of readdirSync(paths.agents)) {
+      const generationId = name.endsWith(".json") ? name.slice(0, -5) : "";
+      if (generationId && !options.keepGenerations.has(generationId)) {
+        rmSync(join(paths.agents, name), { force: true });
+      }
+    }
+  }
+  if (!existsSync(paths.cache)) return;
+  const now = options.now ?? Date.now();
+  const maxFiles = Math.min(MAX_CACHE_FILES, Math.max(1, options.maxCacheFiles ?? MAX_CACHE_FILES));
+  const entries = readdirSync(paths.cache)
+    .filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+    .map((name) => ({ name, mtime: statSync(join(paths.cache, name)).mtimeMs }))
+    .sort((left, right) => right.mtime - left.mtime);
+  for (const [index, entry] of entries.entries()) {
+    if (index >= maxFiles || now - entry.mtime > MAX_CACHE_AGE_MS) {
+      rmSync(join(paths.cache, entry.name), { force: true });
+    }
+  }
+}
+
+function requireGenerationId(value: string): void {
+  if (!/^gen_[0-9a-zA-Z-]{1,128}$/.test(value)) throw new Error("invalid semantic generation id");
+}
+
+function requireDigest(value: string): void {
+  if (!/^sha256:[a-f0-9]{64}$/.test(value)) throw new Error("invalid semantic cache key");
+}
+
+function readBoundedJson<T>(path: string, label: string): T {
+  const size = statSync(path).size;
+  if (size <= 0 || size > MAX_JSON_BYTES) throw new Error(`${label} has invalid size ${size}`);
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+function writePrivateJsonAtomic(path: string, value: unknown): void {
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  if (Buffer.byteLength(body) > MAX_JSON_BYTES) {
+    throw new Error(`semantic file exceeds ${MAX_JSON_BYTES} bytes`);
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(path), 0o700);
+  const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}

package/src/core/semantic/usage.ts

@@ -0,0 +1,272 @@
+import { countTokens } from "gpt-tokenizer/model/gpt-4o";
+import {
+  SEMANTIC_USAGE_SCHEMA_VERSION,
+  SEMANTIC_VISIBLE_USAGE_ESTIMATOR_ID,
+  SEMANTIC_VISIBLE_USAGE_ESTIMATOR_VERSION,
+  type SemanticConfiguredModel,
+  type SemanticHarness,
+  type SemanticInvalidReasonCode,
+  type SemanticUsageReceiptV1,
+  type SemanticUsageToken,
+} from "./contract.ts";
+
+export const SEMANTIC_USAGE_TOKEN_FIELDS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "cache_creation_input_tokens",
+  "output_tokens",
+  "reasoning_tokens",
+  "total_tokens",
+] as const;
+
+export type SemanticUsageTokenField = (typeof SEMANTIC_USAGE_TOKEN_FIELDS)[number];
+export type SemanticUsageTokenTotals = Partial<Record<SemanticUsageTokenField, number>>;
+export type SemanticUsageOutcome = "accepted" | "invalid" | "unavailable" | "deferred";
+
+export interface SemanticUsageEvent {
+  source_harness?: SemanticHarness;
+  configured_model?: SemanticConfiguredModel;
+  resolved_model_id?: string;
+  model_attestation?: "verified" | "requested-only";
+  action?: string;
+  model_call: boolean;
+  usage?: SemanticUsageReceiptV1;
+  invalid_reason_codes?: SemanticInvalidReasonCode[];
+}
+
+export interface SemanticUsageBreakdown {
+  harness?: SemanticHarness;
+  configured_model?: SemanticConfiguredModel;
+  resolved_model_id?: string;
+  model_attestation?: "verified" | "requested-only";
+  call_count: number;
+  outcomes: Record<SemanticUsageOutcome, number>;
+  invalid_reasons: Partial<Record<SemanticInvalidReasonCode, number>>;
+  native_tokens: SemanticUsageTokenTotals;
+  estimated_tokens: SemanticUsageTokenTotals;
+  unreported_calls: number;
+}
+
+export interface SemanticUsageAggregate {
+  call_count: number;
+  outcomes: Record<SemanticUsageOutcome, number>;
+  invalid_reasons: Partial<Record<SemanticInvalidReasonCode, number>>;
+  native_tokens: SemanticUsageTokenTotals;
+  estimated_tokens: SemanticUsageTokenTotals;
+  unreported_calls: number;
+  breakdowns: SemanticUsageBreakdown[];
+}
+
+export function nativeSemanticUsage(
+  values: Partial<Record<SemanticUsageTokenField, unknown>>,
+): SemanticUsageReceiptV1 | undefined {
+  const tokens: Partial<Record<SemanticUsageTokenField, SemanticUsageToken>> = {};
+  for (const field of SEMANTIC_USAGE_TOKEN_FIELDS) {
+    const value = nonNegativeInteger(values[field]);
+    if (value !== undefined) tokens[field] = { value, provenance: "native" };
+  }
+  if (Object.keys(tokens).length === 0) return undefined;
+  return {
+    schema_version: SEMANTIC_USAGE_SCHEMA_VERSION,
+    source: "native",
+    scope: "harness-call",
+    tokens,
+  } as SemanticUsageReceiptV1;
+}
+
+export function estimateVisibleSemanticUsage(
+  prompt: string,
+  response: string,
+): SemanticUsageReceiptV1 {
+  const input = countTokens(prompt);
+  const output = countTokens(response);
+  return {
+    schema_version: SEMANTIC_USAGE_SCHEMA_VERSION,
+    source: "estimated",
+    scope: "visible-payload",
+    estimator: {
+      id: SEMANTIC_VISIBLE_USAGE_ESTIMATOR_ID,
+      version: SEMANTIC_VISIBLE_USAGE_ESTIMATOR_VERSION,
+    },
+    tokens: {
+      input_tokens: { value: input, provenance: "estimated" },
+      output_tokens: { value: output, provenance: "estimated" },
+      total_tokens: { value: input + output, provenance: "estimated" },
+    },
+  };
+}
+
+export function unreportedSemanticUsage(): SemanticUsageReceiptV1 {
+  return {
+    schema_version: SEMANTIC_USAGE_SCHEMA_VERSION,
+    source: "unreported",
+    scope: "unreported",
+  };
+}
+
+export function aggregateSemanticUsage(
+  events: readonly SemanticUsageEvent[],
+): SemanticUsageAggregate {
+  const aggregate = emptySemanticUsageAggregate();
+  const rows = new Map<string, SemanticUsageBreakdown>();
+  for (const event of events) {
+    const outcome = semanticUsageOutcome(event.action);
+    if (outcome) aggregate.outcomes[outcome] += 1;
+    addInvalidReasons(aggregate.invalid_reasons, event.invalid_reason_codes);
+    if (event.model_call) {
+      aggregate.call_count += 1;
+      addReceipt(aggregate, event.usage);
+    }
+    if (!outcome && !event.model_call) continue;
+    const key = [
+      event.source_harness ?? "unattributed",
+      event.configured_model ?? "unattributed",
+      event.resolved_model_id ?? "unresolved",
+      event.model_attestation ?? "unattested",
+    ].join("\u0000");
+    const row = rows.get(key) ?? {
+      ...(event.source_harness ? { harness: event.source_harness } : {}),
+      ...(event.configured_model ? { configured_model: event.configured_model } : {}),
+      ...(event.resolved_model_id ? { resolved_model_id: event.resolved_model_id } : {}),
+      ...(event.model_attestation ? { model_attestation: event.model_attestation } : {}),
+      call_count: 0,
+      outcomes: emptyOutcomes(),
+      invalid_reasons: {},
+      native_tokens: {},
+      estimated_tokens: {},
+      unreported_calls: 0,
+    };
+    if (outcome) row.outcomes[outcome] += 1;
+    addInvalidReasons(row.invalid_reasons, event.invalid_reason_codes);
+    if (event.model_call) {
+      row.call_count += 1;
+      addReceipt(row, event.usage);
+    }
+    rows.set(key, row);
+  }
+  aggregate.breakdowns = [...rows.values()].sort((left, right) =>
+    `${left.harness ?? ""}/${left.configured_model ?? ""}/${left.resolved_model_id ?? ""}`.localeCompare(
+      `${right.harness ?? ""}/${right.configured_model ?? ""}/${right.resolved_model_id ?? ""}`,
+    ),
+  );
+  return aggregate;
+}
+
+export function mergeSemanticUsageAggregates(
+  left: SemanticUsageAggregate,
+  right: SemanticUsageAggregate,
+): SemanticUsageAggregate {
+  const merged = emptySemanticUsageAggregate();
+  merged.call_count = left.call_count + right.call_count;
+  merged.unreported_calls = left.unreported_calls + right.unreported_calls;
+  for (const outcome of Object.keys(merged.outcomes) as SemanticUsageOutcome[]) {
+    merged.outcomes[outcome] = left.outcomes[outcome] + right.outcomes[outcome];
+  }
+  addInvalidReasons(merged.invalid_reasons, left.invalid_reasons);
+  addInvalidReasons(merged.invalid_reasons, right.invalid_reasons);
+  addTotals(merged.native_tokens, left.native_tokens);
+  addTotals(merged.native_tokens, right.native_tokens);
+  addTotals(merged.estimated_tokens, left.estimated_tokens);
+  addTotals(merged.estimated_tokens, right.estimated_tokens);
+  const rows = new Map<string, SemanticUsageBreakdown>();
+  for (const row of [...left.breakdowns, ...right.breakdowns]) {
+    const key = [
+      row.harness ?? "unattributed",
+      row.configured_model ?? "unattributed",
+      row.resolved_model_id ?? "unresolved",
+      row.model_attestation ?? "unattested",
+    ].join("\u0000");
+    const prior = rows.get(key);
+    if (!prior) {
+      rows.set(key, structuredClone(row));
+      continue;
+    }
+    prior.call_count += row.call_count;
+    prior.unreported_calls += row.unreported_calls;
+    addInvalidReasons(prior.invalid_reasons, row.invalid_reasons);
+    for (const outcome of Object.keys(prior.outcomes) as SemanticUsageOutcome[]) {
+      prior.outcomes[outcome] += row.outcomes[outcome];
+    }
+    addTotals(prior.native_tokens, row.native_tokens);
+    addTotals(prior.estimated_tokens, row.estimated_tokens);
+  }
+  merged.breakdowns = [...rows.values()];
+  return merged;
+}
+
+export function emptySemanticUsageAggregate(): SemanticUsageAggregate {
+  return {
+    call_count: 0,
+    outcomes: emptyOutcomes(),
+    invalid_reasons: {},
+    native_tokens: {},
+    estimated_tokens: {},
+    unreported_calls: 0,
+    breakdowns: [],
+  };
+}
+
+function addInvalidReasons(
+  target: Partial<Record<SemanticInvalidReasonCode, number>>,
+  source:
+    | readonly SemanticInvalidReasonCode[]
+    | Partial<Record<SemanticInvalidReasonCode, number>>
+    | undefined,
+): void {
+  if (!source) return;
+  if (Array.isArray(source)) {
+    for (const code of source as readonly SemanticInvalidReasonCode[]) {
+      target[code] = (target[code] ?? 0) + 1;
+    }
+    return;
+  }
+  for (const [code, count] of Object.entries(
+    source as Partial<Record<SemanticInvalidReasonCode, number>>,
+  )) {
+    if (typeof count === "number" && count > 0) {
+      const key = code as SemanticInvalidReasonCode;
+      target[key] = (target[key] ?? 0) + count;
+    }
+  }
+}
+
+function addReceipt(
+  target: Pick<SemanticUsageAggregate, "native_tokens" | "estimated_tokens" | "unreported_calls">,
+  usage: SemanticUsageReceiptV1 | undefined,
+): void {
+  if (!usage || usage.source === "unreported") {
+    target.unreported_calls += 1;
+    return;
+  }
+  for (const field of SEMANTIC_USAGE_TOKEN_FIELDS) {
+    const token = usage.tokens[field as keyof typeof usage.tokens] as
+      | SemanticUsageToken
+      | undefined;
+    if (!token) continue;
+    const totals = token.provenance === "native" ? target.native_tokens : target.estimated_tokens;
+    totals[field] = (totals[field] ?? 0) + token.value;
+  }
+}
+
+function addTotals(target: SemanticUsageTokenTotals, source: SemanticUsageTokenTotals): void {
+  for (const field of SEMANTIC_USAGE_TOKEN_FIELDS) {
+    if (source[field] !== undefined) target[field] = (target[field] ?? 0) + source[field]!;
+  }
+}
+
+function emptyOutcomes(): Record<SemanticUsageOutcome, number> {
+  return { accepted: 0, invalid: 0, unavailable: 0, deferred: 0 };
+}
+
+function semanticUsageOutcome(value: string | undefined): SemanticUsageOutcome | undefined {
+  return value === "accepted" ||
+    value === "invalid" ||
+    value === "unavailable" ||
+    value === "deferred"
+    ? value
+    : undefined;
+}
+
+function nonNegativeInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}