harnery 0.34.1 → 0.36.0

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

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

package/dist/core/semantic/review.js

@@ -0,0 +1,544 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { SEMANTIC_EXPRESSION_CUES, SEMANTIC_HARNESSES, SEMANTIC_PHASES, SEMANTIC_TAGS, } from "./contract.js";
+import { buildSemanticEvidenceV1 } from "./evidence.js";
+import { listSemanticAgentDocuments } from "./storage.js";
+export const SEMANTIC_REVIEW_SCHEMA_VERSION = 1;
+export const SEMANTIC_REVIEW_OVERALL_VERDICTS = ["correct", "close", "wrong", "unsure"];
+export const SEMANTIC_REVIEW_FIELD_VERDICTS = ["correct", "wrong", "unsure"];
+export const SEMANTIC_REVIEW_PORTRAIT_VERDICTS = ["helpful", "neutral", "misleading"];
+export const SEMANTIC_REVIEW_TRANSITION_VERDICTS = ["real-change", "flicker", "unsure"];
+export const SEMANTIC_REVIEW_CONFIDENCE = ["low", "medium", "high"];
+export const SEMANTIC_REVIEW_NO_EXPRESSION = "none";
+const MAX_JSON_BYTES = 512 * 1024;
+const MAX_CANDIDATES = 100;
+const MAX_CANDIDATE_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+const MAX_RECEIPTS = 1_000;
+const MAX_RECEIPT_AGE_MS = 365 * 24 * 60 * 60 * 1_000;
+const DEFAULT_STUDY_SIZE = 12;
+const MAX_STUDY_SIZE = 24;
+const MAX_RESPONSE_MS = 10 * 60_000;
+const MAX_TOTAL_DURATION_MS = 2 * 60 * 60_000;
+const CANDIDATE_ID = /^candidate_[a-f0-9]{16}$/;
+const SUBJECT_ID = /^subject_[a-f0-9]{16}$/;
+const STUDY_ID = /^study_[a-f0-9]{16}$/;
+const RECEIPT_ID = /^review_[a-f0-9]{16}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const configuredModels = new Set([
+    "haiku-4.5",
+    "gpt-5.6-luna",
+    "composer-2.5",
+]);
+const phases = new Set(SEMANTIC_PHASES);
+const expressions = new Set(SEMANTIC_EXPRESSION_CUES);
+const tags = new Set(SEMANTIC_TAGS);
+export function semanticReviewPaths(coordRootRaw) {
+    const root = join(resolve(coordRootRaw), ".harnery", "semantic", "evaluations", "meaning");
+    return {
+        root,
+        candidates: join(root, "candidates"),
+        receipts: join(root, "receipts"),
+    };
+}
+export function captureSemanticReviewCandidate(coordRootRaw, evidence, document) {
+    if (document.reader_outcome !== "accepted" ||
+        document.source.evidence_digest !== evidence.evidence_digest ||
+        document.generation_id !== evidence.generation_id ||
+        document.instance_id !== evidence.instance_id) {
+        throw new Error("semantic review candidate does not match accepted evidence");
+    }
+    const subjectId = opaqueId("subject", {
+        ledger_genesis_id: evidence.source.ledger_genesis_id,
+        instance_id: evidence.instance_id,
+    });
+    const candidateId = opaqueId("candidate", {
+        subject_id: subjectId,
+        evidence_digest: evidence.evidence_digest,
+        generated_at: document.generated_at,
+        reader: document.reader,
+        proposal: proposalSnapshot(document.meaning),
+    });
+    const candidate = {
+        schema_version: SEMANTIC_REVIEW_SCHEMA_VERSION,
+        candidate_id: candidateId,
+        subject_id: subjectId,
+        captured_at: document.generated_at,
+        source: {
+            evidence_digest: evidence.evidence_digest,
+            observed_through_ts: evidence.source.observed_through_ts,
+            generated_at: document.generated_at,
+            harness: document.reader.harness,
+            configured_model: document.reader.configured_model,
+            resolved_model_id: document.reader.resolved_model_id,
+            model_attestation: document.reader.model_attestation,
+        },
+        evidence: evidenceSnapshot(evidence),
+        proposal: proposalSnapshot(document.meaning),
+    };
+    const target = join(semanticReviewPaths(coordRootRaw).candidates, `${candidateId}.json`);
+    if (!existsSync(target))
+        writePrivateJsonAtomic(target, candidate);
+    pruneSemanticReviewStorage(coordRootRaw);
+    return candidate;
+}
+export function backfillSemanticReviewCandidates(coordRootRaw, now = Date.now()) {
+    const evidenceByGeneration = new Map(buildSemanticEvidenceV1(coordRootRaw, now).map((item) => [item.generation_id, item]));
+    const captured = [];
+    for (const document of listSemanticAgentDocuments(coordRootRaw)) {
+        if (document.reader_outcome !== "accepted")
+            continue;
+        const evidence = evidenceByGeneration.get(document.generation_id);
+        if (!evidence || evidence.evidence_digest !== document.source.evidence_digest)
+            continue;
+        captured.push(captureSemanticReviewCandidate(coordRootRaw, evidence, document));
+    }
+    return captured;
+}
+export function listSemanticReviewCandidates(coordRootRaw) {
+    const dir = semanticReviewPaths(coordRootRaw).candidates;
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => /^candidate_[a-f0-9]{16}\.json$/.test(name))
+        .flatMap((name) => {
+        try {
+            const value = readBoundedJson(join(dir, name), "semantic review candidate");
+            return isSemanticReviewCandidate(value) ? [value] : [];
+        }
+        catch {
+            return [];
+        }
+    })
+        .sort(compareCandidates);
+}
+export function listSemanticReviewReceipts(coordRootRaw) {
+    const dir = semanticReviewPaths(coordRootRaw).receipts;
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => /^review_[a-f0-9]{16}\.json$/.test(name))
+        .flatMap((name) => {
+        try {
+            const value = readBoundedJson(join(dir, name), "semantic review receipt");
+            return isSemanticReviewReceipt(value) ? [value] : [];
+        }
+        catch {
+            return [];
+        }
+    })
+        .sort((left, right) => right.completed_at.localeCompare(left.completed_at));
+}
+export function prepareSemanticReviewStudy(coordRootRaw, options = {}) {
+    const now = options.now ?? new Date();
+    if (options.backfill !== false)
+        backfillSemanticReviewCandidates(coordRootRaw, now.getTime());
+    pruneSemanticReviewStorage(coordRootRaw, now.getTime());
+    const all = listSemanticReviewCandidates(coordRootRaw);
+    const reviewed = reviewedCandidateIds(listSemanticReviewReceipts(coordRootRaw));
+    const pending = all.filter((candidate) => !reviewed.has(candidate.candidate_id));
+    const limit = Math.min(MAX_STUDY_SIZE, Math.max(1, options.limit ?? DEFAULT_STUDY_SIZE));
+    const ranked = pending
+        .map((candidate) => {
+        const previous = previousCandidate(candidate, all);
+        return {
+            candidate,
+            ...(previous ? { previous } : {}),
+            transition_required: semanticTransitionChanged(candidate, previous),
+        };
+    })
+        .sort((left, right) => {
+        if (left.transition_required !== right.transition_required) {
+            return left.transition_required ? -1 : 1;
+        }
+        const leftCue = left.candidate.proposal.expression_cue ? 1 : 0;
+        const rightCue = right.candidate.proposal.expression_cue ? 1 : 0;
+        return rightCue - leftCue || compareCandidates(left.candidate, right.candidate);
+    })
+        .slice(0, limit);
+    return {
+        schema_version: SEMANTIC_REVIEW_SCHEMA_VERSION,
+        study_id: studyId(ranked.map((item) => item.candidate.candidate_id)),
+        prepared_at: now.toISOString(),
+        total_candidate_count: all.length,
+        reviewed_candidate_count: reviewed.size,
+        pending_candidate_count: pending.length,
+        candidates: ranked,
+    };
+}
+export function storeSemanticReviewSubmission(coordRootRaw, value, now = new Date()) {
+    const all = listSemanticReviewCandidates(coordRootRaw);
+    const byId = new Map(all.map((candidate) => [candidate.candidate_id, candidate]));
+    const alreadyReviewed = reviewedCandidateIds(listSemanticReviewReceipts(coordRootRaw));
+    const submission = parseSubmission(value, byId, all, alreadyReviewed);
+    const completedAt = now.toISOString();
+    const rows = submission.responses.map((response) => {
+        const candidate = byId.get(response.candidate_id);
+        return {
+            ...response,
+            subject_id: candidate.subject_id,
+            candidate_generated_at: candidate.source.generated_at,
+            source_harness: candidate.source.harness,
+            configured_model: candidate.source.configured_model,
+            resolved_model_id: candidate.source.resolved_model_id,
+            model_attestation: candidate.source.model_attestation,
+            proposed_phase: candidate.proposal.phase.value,
+            proposed_expression: candidate.proposal.expression_cue?.value ?? SEMANTIC_REVIEW_NO_EXPRESSION,
+        };
+    });
+    const receiptId = `review_${createHash("sha256")
+        .update(`${submission.study_id}:${completedAt}:${randomUUID()}`)
+        .digest("hex")
+        .slice(0, 16)}`;
+    const receipt = {
+        schema_version: SEMANTIC_REVIEW_SCHEMA_VERSION,
+        receipt_id: receiptId,
+        study_id: submission.study_id,
+        completed_at: completedAt,
+        total_duration_ms: submission.total_duration_ms,
+        responses: rows,
+        summary: summarize(rows),
+    };
+    writePrivateJsonAtomic(join(semanticReviewPaths(coordRootRaw).receipts, `${receiptId}.json`), receipt);
+    pruneSemanticReviewStorage(coordRootRaw, now.getTime());
+    return receipt;
+}
+export function pruneSemanticReviewStorage(coordRootRaw, now = Date.now()) {
+    const paths = semanticReviewPaths(coordRootRaw);
+    pruneFiles(paths.candidates, MAX_CANDIDATES, MAX_CANDIDATE_AGE_MS, now);
+    pruneFiles(paths.receipts, MAX_RECEIPTS, MAX_RECEIPT_AGE_MS, now);
+}
+function evidenceSnapshot(evidence) {
+    return {
+        observed_through_ts: evidence.source.observed_through_ts,
+        ...(evidence.task ? { task: evidence.task.value } : {}),
+        ...(evidence.lifecycle ? { lifecycle: evidence.lifecycle.state } : {}),
+        ...(evidence.intent ? { intent: evidence.intent.kind } : {}),
+        ...(evidence.operation
+            ? { operation: { category: evidence.operation.category, label: evidence.operation.label } }
+            : {}),
+        waits: evidence.waits.map((wait) => ({ kind: wait.kind, started_at: wait.started_at })),
+        recent: evidence.recent.map(observationSnapshot),
+        ...(evidence.attention ? { attention: observationSnapshot(evidence.attention) } : {}),
+    };
+}
+function observationSnapshot(observation) {
+    return {
+        kind: observation.kind,
+        observed_at: observation.observed_at,
+        ...(observation.label ? { label: observation.label } : {}),
+        ...(observation.outcome ? { outcome: observation.outcome } : {}),
+        ...(observation.error_class ? { error_class: observation.error_class } : {}),
+    };
+}
+function proposalSnapshot(meaning) {
+    return {
+        headline: reviewField(meaning.headline),
+        summary: reviewField(meaning.summary),
+        phase: reviewField(meaning.phase),
+        ...(meaning.expression_cue ? { expression_cue: reviewField(meaning.expression_cue) } : {}),
+        ...(meaning.purpose ? { purpose: reviewField(meaning.purpose) } : {}),
+        ...(meaning.recent_result ? { recent_result: reviewField(meaning.recent_result) } : {}),
+        ...(meaning.attention ? { attention: reviewField(meaning.attention) } : {}),
+        ...(meaning.next_step ? { next_step: reviewField(meaning.next_step) } : {}),
+        ...(meaning.tags ? { tags: reviewField(meaning.tags) } : {}),
+    };
+}
+function reviewField(field) {
+    return { value: field.value, confidence: field.confidence };
+}
+function previousCandidate(candidate, all) {
+    return all
+        .filter((other) => other.subject_id === candidate.subject_id &&
+        other.candidate_id !== candidate.candidate_id &&
+        other.source.generated_at < candidate.source.generated_at)
+        .sort(compareCandidates)[0];
+}
+function semanticTransitionChanged(candidate, previous) {
+    if (!previous)
+        return false;
+    return (candidate.proposal.phase.value !== previous.proposal.phase.value ||
+        (candidate.proposal.expression_cue?.value ?? SEMANTIC_REVIEW_NO_EXPRESSION) !==
+            (previous.proposal.expression_cue?.value ?? SEMANTIC_REVIEW_NO_EXPRESSION));
+}
+function parseSubmission(value, byId, all, alreadyReviewed) {
+    if (!isRecord(value) || value.schema_version !== SEMANTIC_REVIEW_SCHEMA_VERSION) {
+        throw new Error("unsupported semantic review submission");
+    }
+    if (!isString(value.study_id) || !STUDY_ID.test(value.study_id)) {
+        throw new Error("invalid semantic review study");
+    }
+    if (!isBoundedInteger(value.total_duration_ms, 0, MAX_TOTAL_DURATION_MS)) {
+        throw new Error("invalid semantic review duration");
+    }
+    if (!Array.isArray(value.responses) ||
+        value.responses.length < 1 ||
+        value.responses.length > MAX_STUDY_SIZE) {
+        throw new Error("invalid semantic review response count");
+    }
+    const seen = new Set();
+    const responses = value.responses.map((raw) => {
+        if (!isRecord(raw) || !isString(raw.candidate_id) || !CANDIDATE_ID.test(raw.candidate_id)) {
+            throw new Error("invalid semantic review response");
+        }
+        const candidate = byId.get(raw.candidate_id);
+        if (!candidate || seen.has(raw.candidate_id))
+            throw new Error("unexpected semantic review candidate");
+        if (alreadyReviewed.has(raw.candidate_id))
+            throw new Error("semantic review candidate already reviewed");
+        if (!includes(SEMANTIC_REVIEW_OVERALL_VERDICTS, raw.overall)) {
+            throw new Error("invalid semantic review overall verdict");
+        }
+        if (!includes(SEMANTIC_REVIEW_FIELD_VERDICTS, raw.phase)) {
+            throw new Error("invalid semantic review phase verdict");
+        }
+        const expectedPhase = raw.expected_phase;
+        if (raw.phase === "wrong") {
+            if (!isString(expectedPhase) || !phases.has(expectedPhase)) {
+                throw new Error("wrong phase verdict requires an expected phase");
+            }
+        }
+        else if (expectedPhase !== undefined) {
+            throw new Error("expected phase is allowed only for a wrong verdict");
+        }
+        if (!includes(SEMANTIC_REVIEW_FIELD_VERDICTS, raw.expression)) {
+            throw new Error("invalid semantic review expression verdict");
+        }
+        const expectedExpression = raw.expected_expression;
+        if (raw.expression === "wrong") {
+            if (!isString(expectedExpression) ||
+                (expectedExpression !== SEMANTIC_REVIEW_NO_EXPRESSION &&
+                    !expressions.has(expectedExpression))) {
+                throw new Error("wrong expression verdict requires an expected expression");
+            }
+        }
+        else if (expectedExpression !== undefined) {
+            throw new Error("expected expression is allowed only for a wrong verdict");
+        }
+        if (!includes(SEMANTIC_REVIEW_PORTRAIT_VERDICTS, raw.portrait_usefulness)) {
+            throw new Error("invalid semantic review portrait verdict");
+        }
+        const transitionRequired = semanticTransitionChanged(candidate, previousCandidate(candidate, all));
+        if (transitionRequired) {
+            if (!includes(SEMANTIC_REVIEW_TRANSITION_VERDICTS, raw.transition)) {
+                throw new Error("changed semantic reading requires a transition verdict");
+            }
+        }
+        else if (raw.transition !== undefined) {
+            throw new Error("transition verdict is not valid for this candidate");
+        }
+        if (!includes(SEMANTIC_REVIEW_CONFIDENCE, raw.confidence)) {
+            throw new Error("invalid semantic review confidence");
+        }
+        if (!isBoundedInteger(raw.response_ms, 0, MAX_RESPONSE_MS)) {
+            throw new Error("invalid semantic review response duration");
+        }
+        seen.add(raw.candidate_id);
+        return {
+            candidate_id: raw.candidate_id,
+            overall: raw.overall,
+            phase: raw.phase,
+            ...(raw.phase === "wrong" ? { expected_phase: expectedPhase } : {}),
+            expression: raw.expression,
+            ...(raw.expression === "wrong"
+                ? { expected_expression: expectedExpression }
+                : {}),
+            portrait_usefulness: raw.portrait_usefulness,
+            ...(transitionRequired
+                ? { transition: raw.transition }
+                : {}),
+            confidence: raw.confidence,
+            response_ms: raw.response_ms,
+        };
+    });
+    if (value.study_id !== studyId(responses.map((response) => response.candidate_id))) {
+        throw new Error("semantic review study changed");
+    }
+    return {
+        schema_version: SEMANTIC_REVIEW_SCHEMA_VERSION,
+        study_id: value.study_id,
+        total_duration_ms: value.total_duration_ms,
+        responses,
+    };
+}
+function summarize(rows) {
+    const summary = {
+        reviewed: rows.length,
+        overall: { correct: 0, close: 0, wrong: 0, unsure: 0 },
+        phase: { correct: 0, wrong: 0, unsure: 0 },
+        expression: { correct: 0, wrong: 0, unsure: 0 },
+        portrait_usefulness: { helpful: 0, neutral: 0, misleading: 0 },
+        transitions: { "real-change": 0, flicker: 0, unsure: 0 },
+    };
+    for (const row of rows) {
+        summary.overall[row.overall] += 1;
+        summary.phase[row.phase] += 1;
+        summary.expression[row.expression] += 1;
+        summary.portrait_usefulness[row.portrait_usefulness] += 1;
+        if (row.transition)
+            summary.transitions[row.transition] += 1;
+    }
+    return summary;
+}
+function studyId(candidateIds) {
+    return opaqueId("study", { candidate_ids: candidateIds });
+}
+function opaqueId(prefix, value) {
+    return `${prefix}_${createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16)}`;
+}
+function reviewedCandidateIds(receipts) {
+    return new Set(receipts.flatMap((receipt) => receipt.responses.map((row) => row.candidate_id)));
+}
+function compareCandidates(left, right) {
+    return (right.source.generated_at.localeCompare(left.source.generated_at) ||
+        right.candidate_id.localeCompare(left.candidate_id));
+}
+function pruneFiles(dir, maxFiles, maxAgeMs, now) {
+    if (!existsSync(dir))
+        return;
+    const entries = readdirSync(dir)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => ({ name, mtime: statSync(join(dir, name)).mtimeMs }))
+        .sort((left, right) => right.mtime - left.mtime);
+    for (const [index, entry] of entries.entries()) {
+        if (index >= maxFiles || now - entry.mtime > maxAgeMs)
+            rmSync(join(dir, entry.name), { force: true });
+    }
+}
+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 review file is too large");
+    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);
+}
+function isSemanticReviewCandidate(value) {
+    if (!isRecord(value) || value.schema_version !== SEMANTIC_REVIEW_SCHEMA_VERSION)
+        return false;
+    if (!isString(value.candidate_id) ||
+        !CANDIDATE_ID.test(value.candidate_id) ||
+        !isString(value.subject_id) ||
+        !SUBJECT_ID.test(value.subject_id) ||
+        !isTimestamp(value.captured_at) ||
+        !isRecord(value.source) ||
+        !isString(value.source.evidence_digest) ||
+        !DIGEST.test(value.source.evidence_digest) ||
+        !isTimestamp(value.source.observed_through_ts) ||
+        !isTimestamp(value.source.generated_at) ||
+        !includes(SEMANTIC_HARNESSES, value.source.harness) ||
+        !configuredModels.has(value.source.configured_model) ||
+        !isBoundedString(value.source.resolved_model_id, 1, 160) ||
+        (value.source.model_attestation !== "verified" &&
+            value.source.model_attestation !== "requested-only") ||
+        !isReviewEvidence(value.evidence) ||
+        !isReviewProposal(value.proposal)) {
+        return false;
+    }
+    return true;
+}
+function isReviewEvidence(value) {
+    if (!isRecord(value) || !isTimestamp(value.observed_through_ts))
+        return false;
+    if (value.task !== undefined && !isBoundedString(value.task, 1, 200))
+        return false;
+    if (value.lifecycle !== undefined && !isBoundedString(value.lifecycle, 1, 128))
+        return false;
+    if (value.intent !== undefined && !isBoundedString(value.intent, 1, 128))
+        return false;
+    if (value.operation !== undefined) {
+        if (!isRecord(value.operation) ||
+            !isBoundedString(value.operation.category, 1, 128) ||
+            !isBoundedString(value.operation.label, 1, 80))
+            return false;
+    }
+    if (!Array.isArray(value.waits) || value.waits.length > 8)
+        return false;
+    if (!value.waits.every((wait) => isRecord(wait) && isBoundedString(wait.kind, 1, 128) && isTimestamp(wait.started_at)))
+        return false;
+    if (!Array.isArray(value.recent) ||
+        value.recent.length > 8 ||
+        !value.recent.every(isReviewObservation))
+        return false;
+    return value.attention === undefined || isReviewObservation(value.attention);
+}
+function isReviewObservation(value) {
+    return Boolean(isRecord(value) &&
+        isBoundedString(value.kind, 1, 128) &&
+        isTimestamp(value.observed_at) &&
+        (value.label === undefined || isBoundedString(value.label, 1, 120)) &&
+        (value.outcome === undefined || isBoundedString(value.outcome, 1, 128)) &&
+        (value.error_class === undefined || isBoundedString(value.error_class, 1, 128)));
+}
+function isReviewProposal(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isProposalField(value.headline, (item) => isBoundedString(item, 1, 60)))
+        return false;
+    if (!isProposalField(value.summary, (item) => isBoundedString(item, 1, 240)))
+        return false;
+    if (!isProposalField(value.phase, (item) => isString(item) && phases.has(item)))
+        return false;
+    if (value.expression_cue !== undefined &&
+        !isProposalField(value.expression_cue, (item) => isString(item) && expressions.has(item)))
+        return false;
+    for (const key of ["purpose", "recent_result", "attention", "next_step"]) {
+        if (value[key] !== undefined &&
+            !isProposalField(value[key], (item) => isBoundedString(item, 1, 180)))
+            return false;
+    }
+    if (value.tags !== undefined &&
+        !isProposalField(value.tags, (item) => Array.isArray(item) &&
+            item.length <= 8 &&
+            item.every((tag) => isString(tag) && tags.has(tag))))
+        return false;
+    return true;
+}
+function isProposalField(value, valueCheck) {
+    return Boolean(isRecord(value) &&
+        valueCheck(value.value) &&
+        (value.confidence === "high" || value.confidence === "medium" || value.confidence === "low"));
+}
+function isSemanticReviewReceipt(value) {
+    if (!isRecord(value) ||
+        value.schema_version !== SEMANTIC_REVIEW_SCHEMA_VERSION ||
+        !isString(value.receipt_id) ||
+        !RECEIPT_ID.test(value.receipt_id) ||
+        !isString(value.study_id) ||
+        !STUDY_ID.test(value.study_id) ||
+        !isTimestamp(value.completed_at) ||
+        !isBoundedInteger(value.total_duration_ms, 0, MAX_TOTAL_DURATION_MS) ||
+        !Array.isArray(value.responses) ||
+        value.responses.length < 1 ||
+        value.responses.length > MAX_STUDY_SIZE ||
+        !isRecord(value.summary))
+        return false;
+    return value.responses.every((row) => isRecord(row) && isString(row.candidate_id) && CANDIDATE_ID.test(row.candidate_id));
+}
+function includes(values, value) {
+    return isString(value) && values.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isBoundedString(value, min, max) {
+    return isString(value) && value.length >= min && value.length <= max;
+}
+function isTimestamp(value) {
+    return isString(value) && Number.isFinite(Date.parse(value));
+}
+function isBoundedInteger(value, min, max) {
+    return Number.isSafeInteger(value) && value >= min && value <= max;
+}

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

@@ -0,0 +1,10 @@
+import type { SemanticConfiguredModel, SemanticHarness } from "./contract.js";
+export interface SemanticReaderRoute {
+    harness: SemanticHarness;
+    binary: string;
+    configured_model: SemanticConfiguredModel;
+    invocation_model_id: string;
+}
+/** Pure route data shared by the adapters, CLI status, and read-only Codec path. */
+export declare const SEMANTIC_READER_ROUTES: Record<SemanticHarness, SemanticReaderRoute>;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,eAAe,EAAE,mBAAmB,CAmB/E,CAAC"}

package/dist/core/semantic/routes.js

@@ -0,0 +1,21 @@
+/** Pure route data shared by the adapters, CLI status, and read-only Codec path. */
+export const SEMANTIC_READER_ROUTES = {
+    "claude-code": {
+        harness: "claude-code",
+        binary: "claude",
+        configured_model: "haiku-4.5",
+        invocation_model_id: "claude-haiku-4-5-20251001",
+    },
+    codex: {
+        harness: "codex",
+        binary: "codex",
+        configured_model: "gpt-5.6-luna",
+        invocation_model_id: "gpt-5.6-luna",
+    },
+    cursor: {
+        harness: "cursor",
+        binary: "cursor-agent",
+        configured_model: "composer-2.5",
+        invocation_model_id: "composer-2.5",
+    },
+};

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

@@ -0,0 +1,27 @@
+import type { SemanticAgentReadModelV2, SemanticEvidenceV1 } from "./contract.js";
+import type { SemanticCallReceipt, SemanticPendingItem } from "./storage.js";
+export declare const SEMANTIC_HARD_CALLS_PER_HOUR = 120;
+export declare const SEMANTIC_INVALID_RETRY_COOLDOWN_MS: number;
+export declare const SEMANTIC_MIN_PRIORITY_GENERATION_CALL_INTERVAL_MS: number;
+export declare const SEMANTIC_MIN_AMBIENT_GENERATION_CALL_INTERVAL_MS: number;
+export declare const SEMANTIC_MIN_GENERATION_CALL_INTERVAL_MS: number;
+export declare function semanticPriorityBand(evidence: SemanticEvidenceV1): 1 | 2;
+export declare function semanticPendingCallIntervalMs(pending: SemanticPendingItem): number;
+export declare function enqueueSemanticPending(pending: readonly SemanticPendingItem[], evidence: SemanticEvidenceV1, nowIso: string): SemanticPendingItem[];
+export declare function selectSemanticPending(pending: readonly SemanticPendingItem[], lastFirstBandGenerationId?: string, callHistory?: readonly SemanticCallReceipt[]): SemanticPendingItem | undefined;
+export declare function activeSemanticCallHistory(history: readonly SemanticCallReceipt[], nowMs: number): SemanticCallReceipt[];
+export declare function semanticRateCap(history: readonly SemanticCallReceipt[], nowMs: number, configuredLimit?: number): {
+    available: number;
+    eligible_after?: string;
+};
+export declare function semanticGenerationCallEligible(history: readonly SemanticCallReceipt[], generationId: string, nowMs: number, minimumIntervalMs?: number): boolean;
+export declare function semanticPendingPassDue(input: {
+    pending: readonly SemanticPendingItem[];
+    callHistory: readonly SemanticCallReceipt[];
+    nowMs: number;
+    debounceMs: number;
+    callsPerHour?: number;
+    minimumGenerationCallIntervalMs?: number;
+}): boolean;
+export declare function semanticDocumentEligible(document: SemanticAgentReadModelV2 | undefined, evidence: SemanticEvidenceV1, nowMs: number): boolean;
+//# sourceMappingURL=scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE7E,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,kCAAkC,QAAa,CAAC;AAC7D,eAAO,MAAM,iDAAiD,QAAa,CAAC;AAC5E,eAAO,MAAM,gDAAgD,QAAa,CAAC;AAC3E,eAAO,MAAM,wCAAwC,QACF,CAAC;AAEpD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,CAAC,GAAG,CAAC,CASxE;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAIlF;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,MAAM,GACb,mBAAmB,EAAE,CAUvB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,yBAAyB,CAAC,EAAE,MAAM,EAClC,WAAW,GAAE,SAAS,mBAAmB,EAAO,GAC/C,mBAAmB,GAAG,SAAS,CAkBjC;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,KAAK,EAAE,MAAM,GACZ,mBAAmB,EAAE,CAKvB;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,KAAK,EAAE,MAAM,EACb,eAAe,SAA+B,GAC7C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAUhD;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,iBAAiB,SAA2C,GAC3D,OAAO,CAOT;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B,CAAC,EAAE,MAAM,CAAC;CAC1C,GAAG,OAAO,CAsBV;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,wBAAwB,GAAG,SAAS,EAC9C,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,GACZ,OAAO,CAQT"}