harnery 0.35.0 → 0.36.0

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

@@ -1,4 +1,4 @@
-import { type SemanticAgentReadModelV2, type SemanticEvidenceV1, type SemanticModelReplyV2 } from "./contract.js";
+import { type SemanticAgentReadModelV2, type SemanticEvidenceV1, type SemanticInvalidReasonCode, type SemanticModelReplyV2 } from "./contract.js";
 export interface SemanticValidationSuccess<T> {
     ok: true;
     value: T;
@@ -12,5 +12,7 @@ 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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,wBAAwB,EAG7B,KAAK,kBAAkB,EAGvB,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,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"}
+{"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

@@ -1,5 +1,5 @@
 import { Value } from "@sinclair/typebox/value";
-import { SEMANTIC_TAGS, SemanticAgentReadModelV2Schema, SemanticModelReplyV2Schema, } from "./contract.js";
+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,
@@ -123,6 +123,39 @@ export function validateSemanticModelReply(input, evidence) {
     }
     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 {

package/dist/core/storage/buffer.d.ts

@@ -0,0 +1,28 @@
+export interface BufferedLogItem<T> {
+    value: T;
+    bytes: number;
+    high_priority: boolean;
+}
+export interface BoundedLogBufferOptions<T> {
+    max_bytes: number;
+    max_records: number;
+    high_severity_reserve_bytes: number;
+    flush_interval_ms: number;
+    minimum_high_priority_drain_interval_ms?: number;
+    drain(items: readonly BufferedLogItem<T>[]): Promise<void>;
+    on_drop?(reason: "normal_capacity" | "total_capacity" | "closed", item: T): void;
+    on_drain_error?(error: unknown): void;
+}
+export declare class BoundedLogBuffer<T> {
+    #private;
+    constructor(options: BoundedLogBufferOptions<T>);
+    get size(): {
+        records: number;
+        bytes: number;
+        capacity_bytes: number;
+    };
+    enqueue(item: BufferedLogItem<T>): boolean;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=buffer.d.ts.map

package/dist/core/storage/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../../src/core/storage/buffer.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B,EAAE,MAAM,CAAC;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uCAAuC,CAAC,EAAE,MAAM,CAAC;IACjD,KAAK,CAAC,KAAK,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACjF,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACvC;AAED,qBAAa,gBAAgB,CAAC,CAAC;;gBASjB,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC;IAe/C,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAMrE;IAED,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO;IAqBpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4C7B"}

package/dist/core/storage/buffer.js

@@ -0,0 +1,101 @@
+export class BoundedLogBuffer {
+    #options;
+    #items = [];
+    #bytes = 0;
+    #closed = false;
+    #timer;
+    #draining = Promise.resolve();
+    #lastHighPriorityDrain = 0;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.max_bytes) ||
+            options.max_bytes <= 0 ||
+            !Number.isSafeInteger(options.max_records) ||
+            options.max_records <= 0 ||
+            options.high_severity_reserve_bytes < 0 ||
+            options.high_severity_reserve_bytes >= options.max_bytes ||
+            options.flush_interval_ms <= 0) {
+            throw new Error("invalid bounded log buffer policy");
+        }
+        this.#options = options;
+    }
+    get size() {
+        return {
+            records: this.#items.length,
+            bytes: this.#bytes,
+            capacity_bytes: this.#options.max_bytes,
+        };
+    }
+    enqueue(item) {
+        if (this.#closed)
+            return this.#drop("closed", item.value);
+        if (!Number.isSafeInteger(item.bytes) || item.bytes <= 0) {
+            throw new Error("buffer item bytes must be a positive safe integer");
+        }
+        const byteLimit = item.high_priority
+            ? this.#options.max_bytes
+            : this.#options.max_bytes - this.#options.high_severity_reserve_bytes;
+        if (this.#items.length >= this.#options.max_records) {
+            return this.#drop(item.high_priority ? "total_capacity" : "normal_capacity", item.value);
+        }
+        if (this.#bytes + item.bytes > byteLimit) {
+            return this.#drop(item.high_priority ? "total_capacity" : "normal_capacity", item.value);
+        }
+        this.#items.push(item);
+        this.#bytes += item.bytes;
+        this.#scheduleTimer();
+        if (item.high_priority)
+            this.#scheduleHighPriorityDrain();
+        return true;
+    }
+    async flush() {
+        this.#cancelTimer();
+        const batch = this.#take();
+        if (batch.length > 0) {
+            this.#draining = this.#draining.then(() => this.#options.drain(batch));
+        }
+        await this.#draining;
+    }
+    async close() {
+        if (this.#closed)
+            return this.#draining;
+        this.#closed = true;
+        await this.flush();
+    }
+    #take() {
+        const batch = this.#items;
+        this.#items = [];
+        this.#bytes = 0;
+        return batch;
+    }
+    #scheduleTimer() {
+        if (this.#timer)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            void this.flush().catch((error) => this.#options.on_drain_error?.(error));
+        }, this.#options.flush_interval_ms);
+        this.#timer.unref?.();
+    }
+    #scheduleHighPriorityDrain() {
+        const minimum = this.#options.minimum_high_priority_drain_interval_ms ?? 25;
+        const now = Date.now();
+        const delay = Math.max(0, minimum - (now - this.#lastHighPriorityDrain));
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#lastHighPriorityDrain = Date.now();
+            void this.flush().catch((error) => this.#options.on_drain_error?.(error));
+        }, delay);
+        this.#timer.unref?.();
+    }
+    #cancelTimer() {
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    #drop(reason, item) {
+        this.#options.on_drop?.(reason, item);
+        return false;
+    }
+}

package/dist/core/storage/builtins.d.ts

@@ -0,0 +1,3 @@
+import type { HarneryStorageFamily } from "./contract.js";
+export declare function harneryStorageFamilies(): readonly HarneryStorageFamily[];
+//# sourceMappingURL=builtins.d.ts.map

package/dist/core/storage/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../../src/core/storage/builtins.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,oBAAoB,EAKrB,MAAM,eAAe,CAAC;AAwDvB,wBAAgB,sBAAsB,IAAI,SAAS,oBAAoB,EAAE,CAUxE"}