harnery 0.34.1 → 0.36.0

package/dist/core/semantic/storage.js

@@ -0,0 +1,180 @@
+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.js";
+import { validateSemanticReadModel } from "./validate.js";
+export const SEMANTIC_MANIFEST_SCHEMA_VERSION = 2;
+const MAX_JSON_BYTES = 512 * 1024;
+const MAX_CACHE_FILES = 500;
+const MAX_CACHE_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+export function semanticPaths(coordRootRaw) {
+    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) {
+    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) {
+    return sha256V3(canonicalJsonV3(identity));
+}
+export function readSemanticManifest(coordRootRaw) {
+    const path = semanticPaths(coordRootRaw).manifest;
+    if (!existsSync(path))
+        return undefined;
+    const value = readBoundedJson(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, manifest) {
+    writePrivateJsonAtomic(semanticPaths(coordRootRaw).manifest, manifest);
+}
+export function readSemanticAgentDocument(coordRootRaw, generationId) {
+    requireGenerationId(generationId);
+    const path = join(semanticPaths(coordRootRaw).agents, `${generationId}.json`);
+    if (!existsSync(path))
+        return undefined;
+    const value = readBoundedJson(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) {
+    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(join(dir, name), "semantic agent document");
+            const verdict = validateSemanticReadModel(value);
+            return verdict.ok ? [verdict.value] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function inspectSemanticDocument(coordRootRaw, instanceOrGeneration) {
+    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, document) {
+    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, cacheKey) {
+    requireDigest(cacheKey);
+    const path = join(semanticPaths(coordRootRaw).cache, `${cacheKey.slice("sha256:".length)}.json`);
+    if (!existsSync(path))
+        return undefined;
+    const value = readBoundedJson(path, "semantic cache entry");
+    const verdict = validateSemanticReadModel(value);
+    return verdict.ok && verdict.value.reader_outcome === "accepted" ? verdict.value : undefined;
+}
+export function writeSemanticCache(coordRootRaw, cacheKey, document) {
+    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) {
+    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, options) {
+    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) {
+    if (!/^gen_[0-9a-zA-Z-]{1,128}$/.test(value))
+        throw new Error("invalid semantic generation id");
+}
+function requireDigest(value) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(value))
+        throw new Error("invalid semantic cache key");
+}
+function readBoundedJson(path, label) {
+    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"));
+}
+function writePrivateJsonAtomic(path, value) {
+    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/dist/core/semantic/usage.d.ts

@@ -0,0 +1,43 @@
+import { type SemanticConfiguredModel, type SemanticHarness, type SemanticInvalidReasonCode, type SemanticUsageReceiptV1 } from "./contract.js";
+export declare const SEMANTIC_USAGE_TOKEN_FIELDS: readonly ["input_tokens", "cached_input_tokens", "cache_creation_input_tokens", "output_tokens", "reasoning_tokens", "total_tokens"];
+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 declare function nativeSemanticUsage(values: Partial<Record<SemanticUsageTokenField, unknown>>): SemanticUsageReceiptV1 | undefined;
+export declare function estimateVisibleSemanticUsage(prompt: string, response: string): SemanticUsageReceiptV1;
+export declare function unreportedSemanticUsage(): SemanticUsageReceiptV1;
+export declare function aggregateSemanticUsage(events: readonly SemanticUsageEvent[]): SemanticUsageAggregate;
+export declare function mergeSemanticUsageAggregates(left: SemanticUsageAggregate, right: SemanticUsageAggregate): SemanticUsageAggregate;
+export declare function emptySemanticUsageAggregate(): SemanticUsageAggregate;
+//# sourceMappingURL=usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/usage.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAE5B,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,2BAA2B,sIAO9B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AACnF,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAC;AACxF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,oBAAoB,CAAC,EAAE,yBAAyB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAC/C,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,aAAa,EAAE,wBAAwB,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAC/C,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,aAAa,EAAE,wBAAwB,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC,GACxD,sBAAsB,GAAG,SAAS,CAapC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,sBAAsB,CAiBxB;AAED,wBAAgB,uBAAuB,IAAI,sBAAsB,CAMhE;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GACpC,sBAAsB,CA4CxB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,sBAAsB,EAC5B,KAAK,EAAE,sBAAsB,GAC5B,sBAAsB,CAqCxB;AAED,wBAAgB,2BAA2B,IAAI,sBAAsB,CAUpE"}

package/dist/core/semantic/usage.js

@@ -0,0 +1,193 @@
+import { countTokens } from "gpt-tokenizer/model/gpt-4o";
+import { SEMANTIC_USAGE_SCHEMA_VERSION, SEMANTIC_VISIBLE_USAGE_ESTIMATOR_ID, SEMANTIC_VISIBLE_USAGE_ESTIMATOR_VERSION, } from "./contract.js";
+export const SEMANTIC_USAGE_TOKEN_FIELDS = [
+    "input_tokens",
+    "cached_input_tokens",
+    "cache_creation_input_tokens",
+    "output_tokens",
+    "reasoning_tokens",
+    "total_tokens",
+];
+export function nativeSemanticUsage(values) {
+    const tokens = {};
+    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,
+    };
+}
+export function estimateVisibleSemanticUsage(prompt, response) {
+    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() {
+    return {
+        schema_version: SEMANTIC_USAGE_SCHEMA_VERSION,
+        source: "unreported",
+        scope: "unreported",
+    };
+}
+export function aggregateSemanticUsage(events) {
+    const aggregate = emptySemanticUsageAggregate();
+    const rows = new Map();
+    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, right) {
+    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)) {
+        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();
+    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)) {
+            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() {
+    return {
+        call_count: 0,
+        outcomes: emptyOutcomes(),
+        invalid_reasons: {},
+        native_tokens: {},
+        estimated_tokens: {},
+        unreported_calls: 0,
+        breakdowns: [],
+    };
+}
+function addInvalidReasons(target, source) {
+    if (!source)
+        return;
+    if (Array.isArray(source)) {
+        for (const code of source) {
+            target[code] = (target[code] ?? 0) + 1;
+        }
+        return;
+    }
+    for (const [code, count] of Object.entries(source)) {
+        if (typeof count === "number" && count > 0) {
+            const key = code;
+            target[key] = (target[key] ?? 0) + count;
+        }
+    }
+}
+function addReceipt(target, usage) {
+    if (!usage || usage.source === "unreported") {
+        target.unreported_calls += 1;
+        return;
+    }
+    for (const field of SEMANTIC_USAGE_TOKEN_FIELDS) {
+        const token = usage.tokens[field];
+        if (!token)
+            continue;
+        const totals = token.provenance === "native" ? target.native_tokens : target.estimated_tokens;
+        totals[field] = (totals[field] ?? 0) + token.value;
+    }
+}
+function addTotals(target, source) {
+    for (const field of SEMANTIC_USAGE_TOKEN_FIELDS) {
+        if (source[field] !== undefined)
+            target[field] = (target[field] ?? 0) + source[field];
+    }
+}
+function emptyOutcomes() {
+    return { accepted: 0, invalid: 0, unavailable: 0, deferred: 0 };
+}
+function semanticUsageOutcome(value) {
+    return value === "accepted" ||
+        value === "invalid" ||
+        value === "unavailable" ||
+        value === "deferred"
+        ? value
+        : undefined;
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}

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

@@ -0,0 +1,18 @@
+import { type SemanticAgentReadModelV2, type SemanticEvidenceV1, type SemanticInvalidReasonCode, type SemanticModelReplyV2 } from "./contract.js";
+export interface SemanticValidationSuccess<T> {
+    ok: true;
+    value: T;
+}
+export interface SemanticValidationFailure {
+    ok: false;
+    issues: string[];
+}
+export type SemanticValidationResult<T> = SemanticValidationSuccess<T> | SemanticValidationFailure;
+export declare function semanticPrivacyIssue(value: string): string | undefined;
+export declare function isSemanticPrivacySafe(value: string): boolean;
+export declare function validateSemanticEvidencePrivacy(evidence: SemanticEvidenceV1): SemanticValidationResult<SemanticEvidenceV1>;
+export declare function validateSemanticModelReply(input: unknown, evidence: SemanticEvidenceV1): SemanticValidationResult<SemanticModelReplyV2>;
+/** Reduce detailed validator messages to bounded, privacy-safe status categories. */
+export declare function classifySemanticValidationIssues(issues: readonly string[]): SemanticInvalidReasonCode[];
+export declare function validateSemanticReadModel(input: unknown, expected?: Pick<SemanticEvidenceV1, "instance_id" | "generation_id" | "evidence_digest">): SemanticValidationResult<SemanticAgentReadModelV2>;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,wBAAwB,EAG7B,KAAK,kBAAkB,EAEvB,KAAK,yBAAyB,EAE9B,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,CAAC,CAAC;CACV;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,yBAAyB,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAAC;AA+BnG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,wBAAwB,CAAC,kBAAkB,CAAC,CAe9C;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,kBAAkB,GAC3B,wBAAwB,CAAC,oBAAoB,CAAC,CAuEhD;AAED,qFAAqF;AACrF,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,yBAAyB,EAAE,CAwB7B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,eAAe,GAAG,iBAAiB,CAAC,GACvF,wBAAwB,CAAC,wBAAwB,CAAC,CAmBpD"}

package/dist/core/semantic/validate.js

@@ -0,0 +1,207 @@
+import { Value } from "@sinclair/typebox/value";
+import { SEMANTIC_INVALID_REASON_CODES, SEMANTIC_TAGS, SemanticAgentReadModelV2Schema, SemanticModelReplyV2Schema, } from "./contract.js";
+const PRIVATE_TEXT_PATTERNS = [
+    [
+        /(?:^|\s)(?:[A-Za-z]:\\|\\\\|\/(?:[A-Za-z0-9._-]+\/)+[A-Za-z0-9._-]+|\.\.\/|\.harnery\/)/i,
+        "path",
+    ],
+    [/https?:\/\//i, "url"],
+    [/(?:^|\s)--[a-z][a-z0-9-]*(?:\s|=|$)/i, "command_flag"],
+    [/(?:^|\s)[A-Z][A-Z0-9_]{2,}=/, "environment_assignment"],
+    [/`[^`]+`/, "command_or_code"],
+    [/\b(?:api[_-]?key|secret|password|token)\s*[:=]\s*\S+/i, "secret_shape"],
+];
+const FORBIDDEN_CLAIM_PATTERNS = [
+    [/\b\d{1,3}\s*%(?=\s|$|[.,])/, "percent_complete"],
+    [/\b(?:minutes?|hours?|days?)\s+(?:left|remaining)\b/i, "time_remaining"],
+    [/\b(?:frustrated|confused|happy|sad|excited|anxious|angry)\b/i, "emotion"],
+    [/\b(?:excellent|great|poor|bad)\s+(?:quality|work)\b/i, "quality"],
+];
+const RESULT_KINDS = new Set(["progress", "artifact", "action", "terminal"]);
+const ATTENTION_KINDS = new Set([
+    "wait",
+    "lifecycle",
+    "error",
+    "claim-conflict",
+]);
+const COMPLETION_LANGUAGE = /\b(?:complete|completed|done|finished|shipped|passed|succeeded|deployed|published)\b/i;
+export function semanticPrivacyIssue(value) {
+    for (const [pattern, issue] of PRIVATE_TEXT_PATTERNS) {
+        if (pattern.test(value))
+            return issue;
+    }
+    return undefined;
+}
+export function isSemanticPrivacySafe(value) {
+    return semanticPrivacyIssue(value) === undefined;
+}
+export function validateSemanticEvidencePrivacy(evidence) {
+    const text = [
+        ["task", evidence.task?.value],
+        ["operation", evidence.operation?.label],
+        ["attention", evidence.attention?.label],
+        ...evidence.recent.map((item, index) => [`recent[${index}]`, item.label]),
+    ];
+    const issues = text.flatMap(([field, value]) => {
+        if (!value)
+            return [];
+        const issue = semanticPrivacyIssue(value);
+        return issue ? [`${field}:${issue}`] : [];
+    });
+    return issues.length ? { ok: false, issues } : { ok: true, value: evidence };
+}
+export function validateSemanticModelReply(input, evidence) {
+    if (!Value.Check(SemanticModelReplyV2Schema, input)) {
+        return {
+            ok: false,
+            issues: [...Value.Errors(SemanticModelReplyV2Schema, input)]
+                .slice(0, 12)
+                .map((error) => `schema:${error.path || "/"}:${error.message}`),
+        };
+    }
+    const reply = input;
+    const issues = [];
+    if (reply.generation_id !== evidence.generation_id)
+        issues.push("generation_mismatch");
+    if (reply.evidence_digest !== evidence.evidence_digest)
+        issues.push("evidence_digest_mismatch");
+    const knownIds = new Set(evidence.evidence_event_ids);
+    const kindById = evidenceKindByEventId(evidence);
+    for (const [name, field] of meaningFields(reply.meaning)) {
+        if (name === "tags" && Array.isArray(field.value) && field.value.length === 0) {
+            if (field.evidence_event_ids.length !== 0)
+                issues.push("empty_tags_must_not_cite");
+        }
+        else if (field.evidence_event_ids.length === 0) {
+            issues.push(`${name}:missing_citation`);
+        }
+        for (const eventId of field.evidence_event_ids) {
+            if (!knownIds.has(eventId))
+                issues.push(`${name}:unknown_citation`);
+        }
+        if (name === "next_step") {
+            if (field.basis !== "prediction" || field.confidence !== "low") {
+                issues.push("next_step:must_be_low_confidence_prediction");
+            }
+        }
+        else if (field.basis !== "model-synthesis") {
+            issues.push(`${name}:must_be_model_synthesis`);
+        }
+        if (name === "expression_cue" && field.confidence === "high") {
+            issues.push("expression_cue:confidence_must_be_medium_or_low");
+        }
+        if (typeof field.value === "string") {
+            const privacyIssue = semanticPrivacyIssue(field.value);
+            if (privacyIssue)
+                issues.push(`${name}:privacy_${privacyIssue}`);
+            for (const [pattern, issue] of FORBIDDEN_CLAIM_PATTERNS) {
+                if (pattern.test(field.value))
+                    issues.push(`${name}:${issue}`);
+            }
+            if (/\bblocked\b/i.test(field.value) && name !== "attention") {
+                issues.push(`${name}:unsupported_blocker_language`);
+            }
+            if (COMPLETION_LANGUAGE.test(field.value) &&
+                !citationsSupport(field, kindById, RESULT_KINDS)) {
+                issues.push(`${name}:unsupported_completion_language`);
+            }
+        }
+    }
+    if (reply.meaning.recent_result &&
+        !citationsSupport(reply.meaning.recent_result, kindById, RESULT_KINDS)) {
+        issues.push("recent_result:unsupported_evidence_kind");
+    }
+    if (reply.meaning.attention &&
+        !citationsSupport(reply.meaning.attention, kindById, ATTENTION_KINDS)) {
+        issues.push("attention:unsupported_evidence_kind");
+    }
+    if (reply.meaning.tags) {
+        for (const tag of reply.meaning.tags.value) {
+            if (!SEMANTIC_TAGS.includes(tag))
+                issues.push("tags:unsupported_tag");
+        }
+    }
+    return issues.length ? { ok: false, issues: [...new Set(issues)] } : { ok: true, value: reply };
+}
+/** Reduce detailed validator messages to bounded, privacy-safe status categories. */
+export function classifySemanticValidationIssues(issues) {
+    const found = new Set();
+    for (const issue of issues) {
+        if (issue.startsWith("schema:"))
+            found.add("schema");
+        else if (issue === "generation_mismatch" || issue === "evidence_digest_mismatch") {
+            found.add("identity");
+        }
+        else if (issue.includes("citation") || issue === "empty_tags_must_not_cite") {
+            found.add("citation");
+        }
+        else if (issue.includes("must_be_model_synthesis") || issue.includes("prediction")) {
+            found.add("basis");
+        }
+        else if (issue.includes("confidence"))
+            found.add("confidence");
+        else if (issue.includes(":privacy_"))
+            found.add("privacy");
+        else if (issue.includes("unsupported_") ||
+            issue.endsWith(":percent_complete") ||
+            issue.endsWith(":time_remaining") ||
+            issue.endsWith(":emotion") ||
+            issue.endsWith(":quality")) {
+            found.add("unsupported_claim");
+        }
+        else
+            found.add("unknown");
+    }
+    if (found.size === 0)
+        found.add("unknown");
+    return SEMANTIC_INVALID_REASON_CODES.filter((code) => found.has(code));
+}
+export function validateSemanticReadModel(input, expected) {
+    if (!Value.Check(SemanticAgentReadModelV2Schema, input)) {
+        return {
+            ok: false,
+            issues: [...Value.Errors(SemanticAgentReadModelV2Schema, input)]
+                .slice(0, 12)
+                .map((error) => `schema:${error.path || "/"}:${error.message}`),
+        };
+    }
+    const value = input;
+    const issues = [];
+    if (expected) {
+        if (value.instance_id !== expected.instance_id)
+            issues.push("instance_mismatch");
+        if (value.generation_id !== expected.generation_id)
+            issues.push("generation_mismatch");
+        if (value.source.evidence_digest !== expected.evidence_digest) {
+            issues.push("evidence_digest_mismatch");
+        }
+    }
+    return issues.length ? { ok: false, issues } : { ok: true, value };
+}
+function meaningFields(meaning) {
+    return Object.entries(meaning).filter(([, value]) => Boolean(value && typeof value === "object" && Array.isArray(value.evidence_event_ids)));
+}
+function evidenceKindByEventId(evidence) {
+    const map = new Map();
+    if (evidence.task)
+        map.set(evidence.task.event_id, "task");
+    if (evidence.lifecycle)
+        map.set(evidence.lifecycle.event_id, "lifecycle");
+    if (evidence.intent)
+        map.set(evidence.intent.event_id, "intent");
+    if (evidence.operation)
+        map.set(evidence.operation.event_id, "operation");
+    for (const wait of evidence.waits)
+        map.set(wait.event_id, "wait");
+    for (const recent of evidence.recent)
+        map.set(recent.event_id, recent.kind);
+    if (evidence.attention)
+        map.set(evidence.attention.event_id, evidence.attention.kind);
+    return map;
+}
+function citationsSupport(field, kindById, allowed) {
+    return field.evidence_event_ids.some((eventId) => {
+        const kind = kindById.get(eventId);
+        return kind !== undefined && allowed.has(kind);
+    });
+}