agent-threat-rules 2.2.1 → 3.0.5

package/dist/measurement/schema.js

@@ -0,0 +1,178 @@
+/**
+ * src/measurement/schema.ts
+ *
+ * Schema for ATR benchmark measurement files.
+ *
+ * Every public ATR recall / precision / FP-rate claim must reference a
+ * measurement file conforming to this schema. The contract is documented in
+ * `data/measurements/README.md`.
+ *
+ * Design constraints:
+ *   - No external dependencies (no zod, no ajv). Schemas evolve slowly; the
+ *     dependency surface should not.
+ *   - Strict at the boundary. `parseMeasurement()` throws on any deviation;
+ *     it does not silently coerce, drop fields, or accept missing required
+ *     fields.
+ *   - Forward-compatible. `schema_version` is mandatory. Future readers can
+ *     decide how to handle older versions.
+ */
+// ─── Schema version ─────────────────────────────────────────────────────────
+/** Bump this when the schema breaks backward compatibility. */
+export const CURRENT_SCHEMA_VERSION = "1";
+// ─── Validation ─────────────────────────────────────────────────────────────
+/**
+ * Error thrown when a measurement file fails schema validation.
+ * Includes the field path and reason for fast debugging.
+ */
+export class MeasurementSchemaError extends Error {
+    path;
+    reason;
+    constructor(path, reason) {
+        super(`measurement schema: ${path}: ${reason}`);
+        this.path = path;
+        this.reason = reason;
+        this.name = "MeasurementSchemaError";
+    }
+}
+function assertString(v, path, opts) {
+    if (typeof v !== "string") {
+        throw new MeasurementSchemaError(path, `expected string, got ${typeof v}`);
+    }
+    if (opts?.nonEmpty && v.length === 0) {
+        throw new MeasurementSchemaError(path, "expected non-empty string");
+    }
+    return v;
+}
+function assertNumber(v, path, opts) {
+    if (typeof v !== "number" || Number.isNaN(v) || !Number.isFinite(v)) {
+        throw new MeasurementSchemaError(path, `expected finite number, got ${JSON.stringify(v)}`);
+    }
+    if (opts?.integer && !Number.isInteger(v)) {
+        throw new MeasurementSchemaError(path, `expected integer, got ${v}`);
+    }
+    if (opts?.min !== undefined && v < opts.min) {
+        throw new MeasurementSchemaError(path, `expected >= ${opts.min}, got ${v}`);
+    }
+    if (opts?.max !== undefined && v > opts.max) {
+        throw new MeasurementSchemaError(path, `expected <= ${opts.max}, got ${v}`);
+    }
+    return v;
+}
+function assertObject(v, path) {
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new MeasurementSchemaError(path, `expected object, got ${Array.isArray(v) ? "array" : typeof v}`);
+    }
+    return v;
+}
+function parseMetrics(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        recall: assertNumber(obj.recall, `${path}.recall`, { min: 0, max: 1 }),
+        precision: assertNumber(obj.precision, `${path}.precision`, { min: 0, max: 1 }),
+        f1: assertNumber(obj.f1, `${path}.f1`, { min: 0, max: 1 }),
+        fp_rate: assertNumber(obj.fp_rate, `${path}.fp_rate`, { min: 0, max: 1 }),
+    };
+}
+function parseConfusion(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        tp: assertNumber(obj.tp, `${path}.tp`, { min: 0, integer: true }),
+        fp: assertNumber(obj.fp, `${path}.fp`, { min: 0, integer: true }),
+        tn: assertNumber(obj.tn, `${path}.tn`, { min: 0, integer: true }),
+        fn: assertNumber(obj.fn, `${path}.fn`, { min: 0, integer: true }),
+    };
+}
+function parseLatency(raw, path) {
+    const obj = assertObject(raw, path);
+    return {
+        p50: assertNumber(obj.p50, `${path}.p50`, { min: 0 }),
+        p95: assertNumber(obj.p95, `${path}.p95`, { min: 0 }),
+        p99: assertNumber(obj.p99, `${path}.p99`, { min: 0 }),
+        mean: assertNumber(obj.mean, `${path}.mean`, { min: 0 }),
+        max: assertNumber(obj.max, `${path}.max`, { min: 0 }),
+    };
+}
+const ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const SOURCE_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Parse a `Measurement` from an arbitrary value. Throws `MeasurementSchemaError`
+ * on any deviation from the schema. Returns a strongly-typed `Measurement`.
+ *
+ * Unknown extra top-level keys are allowed but ignored (forward-compat); they
+ * are NOT preserved in the returned object.
+ */
+export function parseMeasurement(raw) {
+    const obj = assertObject(raw, "$");
+    const schema_version = assertString(obj.schema_version, "$.schema_version", { nonEmpty: true });
+    if (schema_version !== CURRENT_SCHEMA_VERSION) {
+        throw new MeasurementSchemaError("$.schema_version", `expected "${CURRENT_SCHEMA_VERSION}", got "${schema_version}" — older formats need migration`);
+    }
+    const source = assertString(obj.source, "$.source", { nonEmpty: true });
+    if (!SOURCE_RE.test(source)) {
+        throw new MeasurementSchemaError("$.source", `must match /^[a-z0-9][a-z0-9-]*$/; got "${source}"`);
+    }
+    const measured_at = assertString(obj.measured_at, "$.measured_at", { nonEmpty: true });
+    if (!ISO8601_RE.test(measured_at)) {
+        throw new MeasurementSchemaError("$.measured_at", `must be ISO 8601 UTC (e.g. "2026-05-23T03:57:58Z"); got "${measured_at}"`);
+    }
+    const m = {
+        schema_version: CURRENT_SCHEMA_VERSION,
+        source,
+        source_version: assertString(obj.source_version, "$.source_version", { nonEmpty: true }),
+        atr_version: assertString(obj.atr_version, "$.atr_version", { nonEmpty: true }),
+        atr_commit: assertString(obj.atr_commit, "$.atr_commit", { nonEmpty: true }),
+        rules_loaded: assertNumber(obj.rules_loaded, "$.rules_loaded", { min: 1, integer: true }),
+        measured_at,
+        samples: assertNumber(obj.samples, "$.samples", { min: 0, integer: true }),
+        metrics: parseMetrics(obj.metrics, "$.metrics"),
+    };
+    if (obj.source_url !== undefined)
+        m.source_url = assertString(obj.source_url, "$.source_url", { nonEmpty: true });
+    if (obj.source_commit !== undefined)
+        m.source_commit = assertString(obj.source_commit, "$.source_commit", { nonEmpty: true });
+    if (obj.confusion !== undefined)
+        m.confusion = parseConfusion(obj.confusion, "$.confusion");
+    if (obj.latency_ms !== undefined)
+        m.latency_ms = parseLatency(obj.latency_ms, "$.latency_ms");
+    if (obj.breakdown !== undefined)
+        m.breakdown = assertObject(obj.breakdown, "$.breakdown");
+    if (obj.notes !== undefined)
+        m.notes = assertString(obj.notes, "$.notes");
+    return m;
+}
+/** Parse a `LatestPointer`. Throws on schema violation. */
+export function parseLatestPointer(raw) {
+    const obj = assertObject(raw, "$");
+    return {
+        source: assertString(obj.source, "$.source", { nonEmpty: true }),
+        file: assertString(obj.file, "$.file", { nonEmpty: true }),
+        measured_at: assertString(obj.measured_at, "$.measured_at", { nonEmpty: true }),
+        metrics: parseMetrics(obj.metrics, "$.metrics"),
+        source_version: assertString(obj.source_version, "$.source_version", { nonEmpty: true }),
+        atr_version: assertString(obj.atr_version, "$.atr_version", { nonEmpty: true }),
+        samples: assertNumber(obj.samples, "$.samples", { min: 0, integer: true }),
+    };
+}
+/**
+ * Compute the canonical filename for a measurement.
+ *
+ * Format: `<YYYY-MM-DD>_<source>-<source_version>_atr-<atr_version>.json`
+ *
+ * `source_version` and `atr_version` are slugified (lowercase, non-alphanumeric
+ * → `-`, leading/trailing `-` removed, collapsed runs of `-`).
+ */
+export function measurementFilename(m) {
+    const date = m.measured_at.slice(0, 10);
+    const sourceSlug = slugify(m.source);
+    const sourceVerSlug = slugify(m.source_version);
+    const atrVerSlug = slugify(m.atr_version);
+    return `${date}_${sourceSlug}-${sourceVerSlug}_atr-${atrVerSlug}.json`;
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+}
+//# sourceMappingURL=schema.js.map

package/dist/measurement/schema.js.map

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

package/dist/measurement/write.d.ts

@@ -0,0 +1,64 @@
+/**
+ * src/measurement/write.ts
+ *
+ * Atomic writer + helpers for ATR benchmark measurement files.
+ *
+ * Used by every eval script. Guarantees:
+ *   - Schema-valid output (calls `parseMeasurement` before write).
+ *   - Atomic write (tmp file + fsync + rename — no half-written files).
+ *   - `latest.json` is updated only after the underlying file is durable on disk.
+ *   - Caller-supplied measurements receive `schema_version`, `measured_at`,
+ *     `atr_version`, `atr_commit`, and `rules_loaded` autofills if omitted.
+ */
+import { type Measurement } from "./schema.js";
+/** Read the ATR version from `package.json`. */
+export declare function readATRVersion(): string;
+/** Read the current short git SHA. Falls back to `"unknown"` outside a git repo. */
+export declare function readATRCommit(): string;
+/** Best-effort: count `ATR-*.yaml` rule files under `rules/`. */
+export declare function countRules(rulesDir?: string): number;
+/**
+ * Caller-friendly subset of `Measurement`. The fields the eval script must
+ * provide; the rest (`schema_version`, `atr_version`, `atr_commit`,
+ * `rules_loaded`, `measured_at`) are autofilled by `writeMeasurement()`.
+ *
+ * Callers MAY override any autofill by setting the field explicitly.
+ */
+export type MeasurementInput = Omit<Measurement, "schema_version" | "measured_at" | "atr_version" | "atr_commit" | "rules_loaded"> & {
+    measured_at?: string;
+    atr_version?: string;
+    atr_commit?: string;
+    rules_loaded?: number;
+};
+/**
+ * Write a measurement file and update the source's `latest.json`.
+ *
+ * Returns the absolute path of the measurement file that was written.
+ *
+ * Behavior:
+ *   1. Autofill `schema_version`, `measured_at` (now, ISO UTC), `atr_version`,
+ *      `atr_commit`, `rules_loaded` if not provided.
+ *   2. Validate via `parseMeasurement()`. Throws on any schema violation.
+ *   3. Compute the canonical filename.
+ *   4. Refuse to overwrite an existing file unless `opts.force` is true. (We
+ *      maintain the append-only invariant by default.)
+ *   5. Atomic write the measurement file.
+ *   6. Update `latest.json` only if the new measurement is strictly newer.
+ *
+ * @param input  Measurement minus the autofilled fields.
+ * @param opts   Options. `force: true` allows overwriting an existing file
+ *               with the same filename (use with caution; breaks append-only).
+ */
+export declare function writeMeasurement(input: MeasurementInput, opts?: {
+    force?: boolean;
+    rulesDir?: string;
+}): {
+    measurementPath: string;
+    latestPath: string;
+    measurement: Measurement;
+};
+/** Resolve the absolute path of a source's `latest.json`. */
+export declare function latestPath(source: string): string;
+/** Absolute path of the measurements root directory. */
+export declare function measurementsDir(): string;
+//# sourceMappingURL=write.d.ts.map

package/dist/measurement/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/measurement/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAGL,KAAK,WAAW,EAIjB,MAAM,aAAa,CAAC;AASrB,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED,oFAAoF;AACpF,wBAAgB,aAAa,IAAI,MAAM,CAStC;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,QAAQ,SAA8B,GAAG,MAAM,CAKzE;AAoDD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,WAAW,EACX,gBAAgB,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,GAAG,cAAc,CACjF,GAAG;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,EACvB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAgD3E;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wDAAwD;AACxD,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/measurement/write.js

@@ -0,0 +1,163 @@
+/**
+ * src/measurement/write.ts
+ *
+ * Atomic writer + helpers for ATR benchmark measurement files.
+ *
+ * Used by every eval script. Guarantees:
+ *   - Schema-valid output (calls `parseMeasurement` before write).
+ *   - Atomic write (tmp file + fsync + rename — no half-written files).
+ *   - `latest.json` is updated only after the underlying file is durable on disk.
+ *   - Caller-supplied measurements receive `schema_version`, `measured_at`,
+ *     `atr_version`, `atr_commit`, and `rules_loaded` autofills if omitted.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { CURRENT_SCHEMA_VERSION, measurementFilename, parseLatestPointer, parseMeasurement, } from "./schema.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, "..", "..");
+const MEASUREMENTS_DIR = resolve(REPO_ROOT, "data", "measurements");
+// ─── Environment auto-detection ─────────────────────────────────────────────
+/** Read the ATR version from `package.json`. */
+export function readATRVersion() {
+    const pkg = JSON.parse(readFileSync(resolve(REPO_ROOT, "package.json"), "utf-8"));
+    if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+        throw new Error("package.json: missing or non-string `version`");
+    }
+    return pkg.version;
+}
+/** Read the current short git SHA. Falls back to `"unknown"` outside a git repo. */
+export function readATRCommit() {
+    try {
+        return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+            cwd: REPO_ROOT,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).toString().trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Best-effort: count `ATR-*.yaml` rule files under `rules/`. */
+export function countRules(rulesDir = resolve(REPO_ROOT, "rules")) {
+    const out = execFileSync("find", [rulesDir, "-name", "ATR-*.yaml"], {
+        stdio: ["ignore", "pipe", "ignore"],
+    }).toString();
+    return out.split("\n").filter((l) => l.trim().length > 0).length;
+}
+// ─── Atomic write primitives ────────────────────────────────────────────────
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * Implementation: write to `<targetPath>.<pid>.<nonce>.tmp`, `fsync()` the file
+ * descriptor, then `rename()` over the target. POSIX `rename(2)` is atomic; if
+ * the process dies between write and rename, the target is untouched and the
+ * tmp file can be cleaned up safely.
+ *
+ * If `fs.renameSync` fails (cross-device EXDEV, permissions), throws.
+ */
+function writeFileAtomic(targetPath, content) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const nonce = Math.random().toString(36).slice(2, 10);
+    const tmpPath = `${targetPath}.${process.pid}.${nonce}.tmp`;
+    const fd = openSync(tmpPath, "w");
+    try {
+        writeSync(fd, content);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmpPath, targetPath);
+}
+// ─── Latest pointer ─────────────────────────────────────────────────────────
+function deriveLatestPointer(m, filename) {
+    return {
+        source: m.source,
+        file: filename,
+        measured_at: m.measured_at,
+        metrics: m.metrics,
+        source_version: m.source_version,
+        atr_version: m.atr_version,
+        samples: m.samples,
+    };
+}
+/**
+ * Decide whether `candidate` is more recent than the existing `latest.json`.
+ * Pure function (no I/O); given two pointer-shaped objects, returns boolean.
+ */
+function isStrictlyNewer(candidate, existing) {
+    return candidate.measured_at > existing.measured_at;
+}
+/**
+ * Write a measurement file and update the source's `latest.json`.
+ *
+ * Returns the absolute path of the measurement file that was written.
+ *
+ * Behavior:
+ *   1. Autofill `schema_version`, `measured_at` (now, ISO UTC), `atr_version`,
+ *      `atr_commit`, `rules_loaded` if not provided.
+ *   2. Validate via `parseMeasurement()`. Throws on any schema violation.
+ *   3. Compute the canonical filename.
+ *   4. Refuse to overwrite an existing file unless `opts.force` is true. (We
+ *      maintain the append-only invariant by default.)
+ *   5. Atomic write the measurement file.
+ *   6. Update `latest.json` only if the new measurement is strictly newer.
+ *
+ * @param input  Measurement minus the autofilled fields.
+ * @param opts   Options. `force: true` allows overwriting an existing file
+ *               with the same filename (use with caution; breaks append-only).
+ */
+export function writeMeasurement(input, opts = {}) {
+    const measured_at = input.measured_at ?? new Date().toISOString();
+    const atr_version = input.atr_version ?? readATRVersion();
+    const atr_commit = input.atr_commit ?? readATRCommit();
+    const rules_loaded = input.rules_loaded ?? countRules(opts.rulesDir);
+    const measurement = parseMeasurement({
+        schema_version: CURRENT_SCHEMA_VERSION,
+        ...input,
+        measured_at,
+        atr_version,
+        atr_commit,
+        rules_loaded,
+    });
+    const sourceDir = join(MEASUREMENTS_DIR, measurement.source);
+    const filename = measurementFilename(measurement);
+    const measurementPath = join(sourceDir, filename);
+    const latestPath = join(sourceDir, "latest.json");
+    if (existsSync(measurementPath) && !opts.force) {
+        throw new Error(`measurement already exists: ${measurementPath}\n` +
+            `Re-running the same (source, source_version, atr_version) on the same day produces the same filename.\n` +
+            `Pass { force: true } to overwrite, or change one of the inputs.`);
+    }
+    const measurementJson = JSON.stringify(measurement, null, 2) + "\n";
+    writeFileAtomic(measurementPath, measurementJson);
+    // Update latest.json only if strictly newer than the existing pointer.
+    const newPointer = deriveLatestPointer(measurement, filename);
+    let shouldWriteLatest = true;
+    if (existsSync(latestPath)) {
+        try {
+            const existing = parseLatestPointer(JSON.parse(readFileSync(latestPath, "utf-8")));
+            shouldWriteLatest = isStrictlyNewer(newPointer, existing);
+        }
+        catch {
+            // Corrupt or missing latest.json — overwrite it.
+            shouldWriteLatest = true;
+        }
+    }
+    if (shouldWriteLatest) {
+        writeFileAtomic(latestPath, JSON.stringify(newPointer, null, 2) + "\n");
+    }
+    return { measurementPath, latestPath, measurement };
+}
+/** Resolve the absolute path of a source's `latest.json`. */
+export function latestPath(source) {
+    return join(MEASUREMENTS_DIR, source, "latest.json");
+}
+/** Absolute path of the measurements root directory. */
+export function measurementsDir() {
+    return MEASUREMENTS_DIR;
+}
+//# sourceMappingURL=write.js.map

package/dist/measurement/write.js.map

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

package/dist/semantic-evaluator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic-method rule evaluator (LLM-as-judge).
+ *
+ * Implements atr-method-v1.1.md §6.4 evaluation semantics. The judge
+ * itself is passed in via dependency injection — the reference engine
+ * does NOT bundle a vendor SDK. Operators wire in OpenAI, Anthropic,
+ * or a local model at deployment time.
+ *
+ * Capability: atr/method/semantic (per atr-method-v1.1.md §9).
+ *
+ * Fallback behavior per spec §6.4:
+ *   - If judge is unavailable AND rule.semantic.fallback_method === 'pattern',
+ *     the engine falls back to pattern evaluation on the same input.
+ *   - If fallback_method === 'none' or absent, the engine returns a
+ *     graceful_error (matched: false, error: <reason>).
+ */
+import type { ATRRule, ATRSemanticJudge } from "./types.js";
+export interface SemanticEvaluationResult {
+    matched: boolean;
+    /** Judge response confidence (0.0-1.0) if judge was called */
+    confidence?: number;
+    /** Judge response category if returned */
+    category?: string;
+    /** Why the rule did not evaluate via judge (cache hit / fallback / error) */
+    reason?: string;
+    /** Set when judge unavailable AND fallback_method !== 'pattern' */
+    error?: string;
+}
+interface JudgeCache {
+    get(key: string): {
+        confidence: number;
+        category: string;
+    } | undefined;
+    set(key: string, value: {
+        confidence: number;
+        category: string;
+        expires_at: number;
+    }): void;
+}
+export interface SemanticEvaluatorOptions {
+    /** Caller-supplied judge function. If absent, fallback path is taken. */
+    judge?: ATRSemanticJudge;
+    /** Caller-supplied cache. Defaults to an in-process Map cache. */
+    cache?: JudgeCache;
+}
+export declare function evaluateSemanticRule(rule: ATRRule, input: string, options?: SemanticEvaluatorOptions): Promise<SemanticEvaluationResult>;
+export {};
+//# sourceMappingURL=semantic-evaluator.d.ts.map

package/dist/semantic-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-evaluator.d.ts","sourceRoot":"","sources":["../src/semantic-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,OAAO,EAEP,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,UAAU;IAClB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7F;AA+BD,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,kEAAkE;IAClE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,wBAAwB,CAAC,CAmEnC"}

package/dist/semantic-evaluator.js

@@ -0,0 +1,107 @@
+/**
+ * Semantic-method rule evaluator (LLM-as-judge).
+ *
+ * Implements atr-method-v1.1.md §6.4 evaluation semantics. The judge
+ * itself is passed in via dependency injection — the reference engine
+ * does NOT bundle a vendor SDK. Operators wire in OpenAI, Anthropic,
+ * or a local model at deployment time.
+ *
+ * Capability: atr/method/semantic (per atr-method-v1.1.md §9).
+ *
+ * Fallback behavior per spec §6.4:
+ *   - If judge is unavailable AND rule.semantic.fallback_method === 'pattern',
+ *     the engine falls back to pattern evaluation on the same input.
+ *   - If fallback_method === 'none' or absent, the engine returns a
+ *     graceful_error (matched: false, error: <reason>).
+ */
+class InMemoryJudgeCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expires_at < Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return { confidence: entry.confidence, category: entry.category };
+    }
+    set(key, value) {
+        this.store.set(key, value);
+    }
+}
+const DEFAULT_CACHE = new InMemoryJudgeCache();
+/** Render a prompt template by substituting `{{input}}` with the actual input. */
+function renderPrompt(template, input) {
+    return template.replace(/\{\{\s*input\s*\}\}/g, input);
+}
+/** Compute a stable cache key from (judge prompt hash, input). */
+function cacheKey(promptHash, input) {
+    // Caller should hash; we just concatenate. For reference, prefer pre-hashed input.
+    return `${promptHash ?? "no-hash"}:${input}`;
+}
+export async function evaluateSemanticRule(rule, input, options = {}) {
+    const sem = rule.detection.semantic;
+    if (!sem) {
+        return { matched: false, error: "rule has method=semantic but no detection.semantic block" };
+    }
+    // Cache check
+    const cache = options.cache ?? DEFAULT_CACHE;
+    const key = cacheKey(sem.judge_prompt_hash, input);
+    const cached = cache.get(key);
+    if (cached) {
+        return {
+            matched: cached.confidence >= sem.threshold,
+            confidence: cached.confidence,
+            category: cached.category,
+            reason: "cache_hit",
+        };
+    }
+    // Judge unavailable → fallback path
+    if (!options.judge) {
+        if (sem.fallback_method === "pattern") {
+            return {
+                matched: false,
+                reason: "judge_unavailable_fallback_pattern",
+            };
+        }
+        return {
+            matched: false,
+            error: "judge_unavailable_no_fallback",
+        };
+    }
+    // Call judge
+    const prompt = renderPrompt(sem.prompt_template, input);
+    let response;
+    try {
+        response = await options.judge({
+            prompt,
+            input,
+            judge_model_class: sem.judge_model_class,
+        });
+    }
+    catch (err) {
+        if (sem.fallback_method === "pattern") {
+            return {
+                matched: false,
+                reason: `judge_error_fallback_pattern: ${err.message}`,
+            };
+        }
+        return { matched: false, error: `judge_error: ${err.message}` };
+    }
+    // Cache the response if cache_ttl set
+    if (sem.cache_ttl && sem.cache_ttl > 0) {
+        cache.set(key, {
+            confidence: response.confidence,
+            category: response.category,
+            expires_at: Date.now() + sem.cache_ttl * 1000,
+        });
+    }
+    return {
+        matched: response.confidence >= sem.threshold,
+        confidence: response.confidence,
+        category: response.category,
+        reason: "judge_evaluated",
+    };
+}
+//# sourceMappingURL=semantic-evaluator.js.map

package/dist/semantic-evaluator.js.map

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

package/dist/trace-evaluator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Trace-method rule evaluator.
+ *
+ * Implements the formal semantics in atr-method-v1.1.md §8 for the three
+ * trace primitives: forbid, require, invariant. Operates on a Trace (DAG
+ * of spans, OpenInference / OTel GenAI format).
+ *
+ * Capability: atr/method/trace (per atr-method-v1.1.md §9).
+ *
+ * Pure function; no I/O. Engine wires this in via evaluateRule dispatch
+ * when detection.method === 'trace'.
+ */
+import type { ATRRule, ATRTrace } from "./types.js";
+export interface TraceEvaluationResult {
+    matched: boolean;
+    violations: string[];
+    matchedPrimitives: ("forbid" | "require" | "invariant")[];
+}
+/** Top-level trace rule evaluator. Returns matched=true if ANY declared
+ *  primitive evaluates to violation. */
+export declare function evaluateTraceRule(rule: ATRRule, trace: ATRTrace): TraceEvaluationResult;
+//# sourceMappingURL=trace-evaluator.d.ts.map

package/dist/trace-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-evaluator.d.ts","sourceRoot":"","sources":["../src/trace-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAMT,MAAM,YAAY,CAAC;AAqMpB,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,EAAE,CAAC,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC,EAAE,CAAC;CAC3D;AAED;wCACwC;AACxC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,qBAAqB,CAmCvF"}