@crewhaus/evaluation-service 0.0.0-stage → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The in-loop `evaluation:` gate (loop contract 0.4, G02; 0.6.0 §6.2 / §7.3),
3
+ * built ONCE, here, from the lowered `IrEvaluation`.
4
+ *
5
+ * Until 0.8.0 this closure existed four times: the three `renderEvaluation`
6
+ * copies in target-cli / target-channel-bot / target-managed rendered it as
7
+ * inline source, and `apps/cli`'s `buildRunEvaluation` built it for `crewhaus
8
+ * run`. They had to agree knob for knob and were kept in step by hand. Design
9
+ * §4.4 collapses them into this function — the `wireMemory` / `wireModels`
10
+ * rule applied to in-loop gates — and the emitters render one
11
+ * `wireEvaluation(…)` call instead. The behaviour is exactly the one the four
12
+ * copies had:
13
+ *
14
+ * - `llm_judge` grades through `@crewhaus/eval-judge`'s `gradeWithJudgePanel`
15
+ * (one `createJudgeGrader` fan-out), honouring a declared `judges` panel,
16
+ * `repeats`, `temperature`, `target` and the judge profile's pinned
17
+ * `params`; the judge model defaults to the shape's primary when the spec
18
+ * omitted `grader.model`. Every judge call publishes on the RUN bus the
19
+ * runtime hands the grader (`role: "judge"`), so it is priced and counted
20
+ * under `budget.judge_share`; the verdict's wire model and priced spend
21
+ * come back as `EvaluationResult.judge`. `judgeModel` names the
22
+ * INSTRUMENT up front (a panel is its members joined with `+`), so the
23
+ * pool's per-arm quality lineage folds the judge's identity. An
24
+ * abstaining judge scores 0 (`gradeWithJudgePanel` already says so).
25
+ * - `contains` / `regex` are pure (score 1|0, no model spend, threshold 1);
26
+ * the regex's `lastIndex` is reset per call so a global/sticky flag can
27
+ * never flip a verdict between turns.
28
+ *
29
+ * `threshold`, `onFail` and `maxRetries` are the IR's resolved values, and the
30
+ * cascade's lower-time `escalateTo` is threaded only under `on_fail: escalate`.
31
+ */
32
+ import { gradeWithJudgePanel, inLoopRunResult } from "@crewhaus/eval-judge";
33
+ import { judgeInstrumentId } from "@crewhaus/model-service";
34
+ /** The `llm_judge` rubric every in-loop judge grades against: one criterion, the spec's text. */
35
+ function inLoopRubric(criteria) {
36
+ return {
37
+ criteria: [
38
+ {
39
+ name: "criteria",
40
+ description: criteria,
41
+ anchors: {
42
+ "1": "fails the criteria entirely",
43
+ "2": "mostly fails the criteria",
44
+ "3": "partially meets the criteria",
45
+ "4": "meets the criteria with minor gaps",
46
+ "5": "fully meets the criteria",
47
+ },
48
+ },
49
+ ],
50
+ passing_score: 3,
51
+ };
52
+ }
53
+ /** The `RunEvaluation` for a lowered `evaluation:` block (see the module doc). */
54
+ export function buildRunEvaluation(ev, primaryModel, opts = {}) {
55
+ const grader = ev.grader;
56
+ // 0.6.0 §7.3 (PR 9c) — the cascade's escalation rung, resolved at lower
57
+ // time; carried only under `on_fail: escalate`.
58
+ const escalate = ev.escalateTo !== undefined ? { escalateTo: ev.escalateTo } : {};
59
+ if (grader.type === "llm_judge") {
60
+ const model = grader.model ?? primaryModel;
61
+ const rubric = inLoopRubric(grader.criteria);
62
+ const panel = { ...grader, model };
63
+ return {
64
+ graderType: "llm_judge",
65
+ judgeModel: judgeInstrumentId(panel, primaryModel),
66
+ // The lowered default is 0.7; the floor guards hand-built IR.
67
+ threshold: ev.threshold ?? 0.7,
68
+ onFail: ev.onFail,
69
+ maxRetries: ev.maxRetries,
70
+ ...escalate,
71
+ evaluate: async ({ finalText, messages, isSynthetic, bus }) => {
72
+ const verdict = await gradeWithJudgePanel({
73
+ rubric,
74
+ sample: { id: "in-loop-evaluation", input: "" },
75
+ run: inLoopRunResult({ finalText, messages, isSynthetic }),
76
+ model,
77
+ ...(grader.judges !== undefined ? { judges: grader.judges } : {}),
78
+ ...(grader.repeats !== undefined ? { repeats: grader.repeats } : {}),
79
+ ...(grader.temperature !== undefined ? { temperature: grader.temperature } : {}),
80
+ ...(grader.target !== undefined ? { target: grader.target } : {}),
81
+ ...(grader.params !== undefined ? { params: grader.params } : {}),
82
+ ...(opts.judgeAdapter !== undefined ? { adapter: opts.judgeAdapter } : {}),
83
+ // Judge spend rides the run bus (role "judge") — every panelist and
84
+ // every repeat publishes its own model_request / model_response.
85
+ bus,
86
+ });
87
+ return {
88
+ score: verdict.score,
89
+ rationale: verdict.rationale,
90
+ judge: {
91
+ model: verdict.judgeModel,
92
+ ...(verdict.costUsdMicros !== undefined
93
+ ? { costUsdMicros: verdict.costUsdMicros }
94
+ : {}),
95
+ },
96
+ };
97
+ },
98
+ };
99
+ }
100
+ const value = grader.value;
101
+ if (grader.type === "contains") {
102
+ return {
103
+ graderType: "contains",
104
+ threshold: 1,
105
+ onFail: ev.onFail,
106
+ maxRetries: ev.maxRetries,
107
+ ...escalate,
108
+ evaluate: async ({ finalText }) => finalText.includes(value)
109
+ ? { score: 1, rationale: `output contains "${value}"` }
110
+ : { score: 0, rationale: `output missing "${value}"` },
111
+ };
112
+ }
113
+ // The pattern was validated compilable at parse time.
114
+ const regex = new RegExp(value);
115
+ return {
116
+ graderType: "regex",
117
+ threshold: 1,
118
+ onFail: ev.onFail,
119
+ maxRetries: ev.maxRetries,
120
+ ...escalate,
121
+ evaluate: async ({ finalText }) => {
122
+ regex.lastIndex = 0;
123
+ return regex.test(finalText)
124
+ ? { score: 1, rationale: `output matches /${value}/` }
125
+ : { score: 0, rationale: `output does not match /${value}/` };
126
+ },
127
+ };
128
+ }
@@ -0,0 +1,97 @@
1
+ /**
2
+ * The evidence index the gate verifies against — and, through the same
3
+ * function, the one `ProvabilityPreflight` checks a draft against, so the
4
+ * model sees exactly what the gate will see (design §5.2, §7).
5
+ *
6
+ * Two sources, merged into one record per call:
7
+ *
8
+ * - the session EVENT LOG (children included, via `@crewhaus/tool-proof`'s
9
+ * `sessionEvidence`): it records every `tool_use` input and `tool_result`
10
+ * output verbatim, and compaction cannot evict from it, so `scope:
11
+ * session` keeps grounding a claim on a page fetched twenty turns and two
12
+ * compactions ago;
13
+ * - the in-memory TRANSCRIPT the runtime hands the verifier
14
+ * (`evidenceFromMessages`): it carries a block-content result in full
15
+ * where the log holds runtime-core's one-line summary of it, and it is
16
+ * the only source for a run with no session log. A preflight runs
17
+ * mid-turn with no transcript to hand and reads the log alone, which
18
+ * already holds every call the turn has finished.
19
+ *
20
+ * `scope: turn` keeps only the CURRENT turn's calls. The log records no turn
21
+ * number on a call, so the turn is read off the conversation itself, the same
22
+ * way in both sources: everything after the last REAL user message. A
23
+ * runtime-injected user message — a retry nudge, a cascade correction, a
24
+ * continue prompt (`turn.isSynthetic` on the transcript, `synthetic: true` in
25
+ * the log) — does not start a turn, so evidence the first attempt gathered
26
+ * still counts on the retry the gate itself triggered; nor does the
27
+ * tool-result carrier the runtime sends as a user message. A sub-agent
28
+ * started inside the turn counts whole (its calls ran for this turn).
29
+ */
30
+ import { type EvidenceIndex, type EvidenceMessage, type InputSchemaLookup } from "@crewhaus/provability";
31
+ export type GateEvidenceInput<M extends EvidenceMessage = EvidenceMessage> = {
32
+ readonly scope: "session" | "turn";
33
+ /** The run's session; absent ⇒ the transcript is the only source. */
34
+ readonly sessionId?: string;
35
+ /** Where session `.jsonl` logs live (resolved; undefined ⇒ event-log's default). */
36
+ readonly sessionRootDir?: string;
37
+ /** Workspace root path-shaped inputs are measured from. */
38
+ readonly workspaceRoot: string;
39
+ /**
40
+ * Where the runtime spilled results too long for the log — the active
41
+ * tenant's `toolResultRoot` inside a tenant scope; absent ⇒
42
+ * `<workspace>/.crewhaus/tool-results` — so a spilled page is graded whole,
43
+ * not on its preview.
44
+ */
45
+ readonly toolResultsRoot?: string;
46
+ /** The transcript as of turn completion (the gate); absent for a preflight. */
47
+ readonly messages?: ReadonlyArray<M>;
48
+ /** The runtime's synthetic-message test (`EvaluationTurn.isSynthetic`). */
49
+ readonly isSynthetic?: (message: M) => boolean;
50
+ /** Told when a session log could not be read to its end. */
51
+ readonly onUnreadable?: (info: {
52
+ readonly sessionId: string;
53
+ readonly message: string;
54
+ }) => void;
55
+ /**
56
+ * The input schema each tool the run has declares — the gate's own
57
+ * catalog, where the interpreter and the eval runner register their MCP
58
+ * tools (`defaultCatalog` holds them only in a compiled harness). An MCP
59
+ * call's origin is a field its schema declares, so a stray `url` beside a
60
+ * file server's `paths` grounds nothing (provability `mcpOrigins`).
61
+ * Absent ⇒ provability looks in `defaultCatalog`.
62
+ */
63
+ readonly inputSchemaOf?: InputSchemaLookup;
64
+ };
65
+ /**
66
+ * Does `message` start a turn: a user message the human sent — not one the
67
+ * runtime injected, and not the carrier of a batch of tool results? (The
68
+ * transcript twin of tool-proof's `startsTurn`, which reads the log.)
69
+ */
70
+ export declare function startsTurnMessage<M extends EvidenceMessage>(message: M, isSynthetic?: (message: M) => boolean): boolean;
71
+ /** The messages of the current turn: from the last real user message on (all of them when there is none). */
72
+ export declare function currentTurnMessages<M extends EvidenceMessage>(messages: ReadonlyArray<M>, isSynthetic?: (message: M) => boolean): ReadonlyArray<M>;
73
+ /**
74
+ * The index for one verification (or one preflight): the log's records
75
+ * first — the log wins where the two disagree, except over its own summary
76
+ * of block content — then the transcript's, each scoped as the config says.
77
+ */
78
+ export declare function gateEvidence<M extends EvidenceMessage>(input: GateEvidenceInput<M>): Promise<EvidenceIndex>;
79
+ /**
80
+ * The evidence as the verifier takes it: the index, and under `scope: turn`
81
+ * the turn it keeps (`VerifyOptions.turnNumbers`, which tool-proof's
82
+ * preflight forwards the same way). Under `scope: session` it is
83
+ * {@link gateEvidence}'s index alone.
84
+ *
85
+ * Under `scope: turn` the index holds the WHOLE session, the current turn's
86
+ * calls marked as the graded turn and every earlier one unmarked, so the
87
+ * verifier's restriction leaves grounding exactly where {@link gateEvidence}
88
+ * leaves it — a page an earlier turn fetched grounds nothing — while its
89
+ * self-written trace (`writtenBy`, `storedText`), which reads every call the
90
+ * index holds, still sees a file the session wrote in an earlier turn. A
91
+ * turn-only index hid that write, and the run's own text read back in the
92
+ * next turn was served as an outside source (design §10; I9).
93
+ */
94
+ export declare function gateEvidenceScoped<M extends EvidenceMessage>(input: GateEvidenceInput<M>): Promise<{
95
+ readonly index: EvidenceIndex;
96
+ readonly turnNumbers?: ReadonlySet<number>;
97
+ }>;
@@ -0,0 +1,147 @@
1
+ /**
2
+ * The evidence index the gate verifies against — and, through the same
3
+ * function, the one `ProvabilityPreflight` checks a draft against, so the
4
+ * model sees exactly what the gate will see (design §5.2, §7).
5
+ *
6
+ * Two sources, merged into one record per call:
7
+ *
8
+ * - the session EVENT LOG (children included, via `@crewhaus/tool-proof`'s
9
+ * `sessionEvidence`): it records every `tool_use` input and `tool_result`
10
+ * output verbatim, and compaction cannot evict from it, so `scope:
11
+ * session` keeps grounding a claim on a page fetched twenty turns and two
12
+ * compactions ago;
13
+ * - the in-memory TRANSCRIPT the runtime hands the verifier
14
+ * (`evidenceFromMessages`): it carries a block-content result in full
15
+ * where the log holds runtime-core's one-line summary of it, and it is
16
+ * the only source for a run with no session log. A preflight runs
17
+ * mid-turn with no transcript to hand and reads the log alone, which
18
+ * already holds every call the turn has finished.
19
+ *
20
+ * `scope: turn` keeps only the CURRENT turn's calls. The log records no turn
21
+ * number on a call, so the turn is read off the conversation itself, the same
22
+ * way in both sources: everything after the last REAL user message. A
23
+ * runtime-injected user message — a retry nudge, a cascade correction, a
24
+ * continue prompt (`turn.isSynthetic` on the transcript, `synthetic: true` in
25
+ * the log) — does not start a turn, so evidence the first attempt gathered
26
+ * still counts on the retry the gate itself triggered; nor does the
27
+ * tool-result carrier the runtime sends as a user message. A sub-agent
28
+ * started inside the turn counts whole (its calls ran for this turn).
29
+ */
30
+ import { buildEvidenceIndex, evidenceFromMessages, } from "@crewhaus/provability";
31
+ import { sessionEvidence } from "@crewhaus/tool-proof";
32
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
33
+ /**
34
+ * Does `message` start a turn: a user message the human sent — not one the
35
+ * runtime injected, and not the carrier of a batch of tool results? (The
36
+ * transcript twin of tool-proof's `startsTurn`, which reads the log.)
37
+ */
38
+ export function startsTurnMessage(message, isSynthetic) {
39
+ if (message.role !== "user")
40
+ return false;
41
+ try {
42
+ if (isSynthetic?.(message) === true)
43
+ return false;
44
+ }
45
+ catch {
46
+ // A membership test that throws cannot say the message is synthetic.
47
+ }
48
+ const content = message.content;
49
+ if (typeof content === "string" || content.length === 0)
50
+ return true;
51
+ return !content.every((block) => isRecord(block) && block["type"] === "tool_result");
52
+ }
53
+ /** The messages of the current turn: from the last real user message on (all of them when there is none). */
54
+ export function currentTurnMessages(messages, isSynthetic) {
55
+ for (let i = messages.length - 1; i >= 0; i -= 1) {
56
+ const message = messages[i];
57
+ if (startsTurnMessage(message, isSynthetic))
58
+ return messages.slice(i);
59
+ }
60
+ return messages;
61
+ }
62
+ /**
63
+ * The index for one verification (or one preflight): the log's records
64
+ * first — the log wins where the two disagree, except over its own summary
65
+ * of block content — then the transcript's, each scoped as the config says.
66
+ */
67
+ export async function gateEvidence(input) {
68
+ return buildEvidenceIndex(await gateRecords(input), parentOf(input));
69
+ }
70
+ /**
71
+ * What the gate's records of the turn carry as their turn under `scope:
72
+ * turn` ({@link gateEvidenceScoped}): a label for "the turn being graded",
73
+ * never a number the log recorded.
74
+ */
75
+ const GRADED_TURN = 0;
76
+ /**
77
+ * The evidence as the verifier takes it: the index, and under `scope: turn`
78
+ * the turn it keeps (`VerifyOptions.turnNumbers`, which tool-proof's
79
+ * preflight forwards the same way). Under `scope: session` it is
80
+ * {@link gateEvidence}'s index alone.
81
+ *
82
+ * Under `scope: turn` the index holds the WHOLE session, the current turn's
83
+ * calls marked as the graded turn and every earlier one unmarked, so the
84
+ * verifier's restriction leaves grounding exactly where {@link gateEvidence}
85
+ * leaves it — a page an earlier turn fetched grounds nothing — while its
86
+ * self-written trace (`writtenBy`, `storedText`), which reads every call the
87
+ * index holds, still sees a file the session wrote in an earlier turn. A
88
+ * turn-only index hid that write, and the run's own text read back in the
89
+ * next turn was served as an outside source (design §10; I9).
90
+ */
91
+ export async function gateEvidenceScoped(input) {
92
+ if (input.scope !== "turn")
93
+ return { index: await gateEvidence(input) };
94
+ const inTurn = await gateRecords(input);
95
+ const session = await gateRecords({ ...input, scope: "session" });
96
+ const ofTurn = new Set(inTurn.map(callOf));
97
+ // In the session's call order: the self-written trace reads a writer only
98
+ // where it ran before the read.
99
+ const records = session.map(({ turnNumber: _logged, ...record }) => ofTurn.has(callOf(record)) ? { ...record, turnNumber: GRADED_TURN } : record);
100
+ // A call of the turn the session walk did not reach still grounds as it would have.
101
+ const ofSession = new Set(session.map(callOf));
102
+ for (const record of inTurn) {
103
+ if (!ofSession.has(callOf(record)))
104
+ records.push({ ...record, turnNumber: GRADED_TURN });
105
+ }
106
+ return {
107
+ index: buildEvidenceIndex(records, parentOf(input)),
108
+ turnNumbers: new Set([GRADED_TURN]),
109
+ };
110
+ }
111
+ /** One call's key: its session and its id. */
112
+ const callOf = (record) => `${record.sessionId ?? ""}\u0000${record.toolUseId}`;
113
+ /** The parent session, named so a child's call never answers the parent's `tool:<id>`. */
114
+ const parentOf = (input) => input.sessionId !== undefined ? { sessionId: input.sessionId } : {};
115
+ /** {@link gateEvidence}'s records, before they are indexed. */
116
+ async function gateRecords(input) {
117
+ const records = [];
118
+ if (input.sessionId !== undefined) {
119
+ const fromLog = await sessionEvidence({
120
+ scope: input.scope,
121
+ sessionId: input.sessionId,
122
+ workspaceRoot: input.workspaceRoot,
123
+ ...(input.toolResultsRoot !== undefined ? { toolResultsRoot: input.toolResultsRoot } : {}),
124
+ ...(input.sessionRootDir !== undefined ? { rootDir: input.sessionRootDir } : {}),
125
+ ...(input.onUnreadable !== undefined ? { onUnreadable: input.onUnreadable } : {}),
126
+ ...(input.inputSchemaOf !== undefined ? { inputSchemaOf: input.inputSchemaOf } : {}),
127
+ });
128
+ records.push(...fromLog.index.all());
129
+ }
130
+ if (input.messages !== undefined && input.messages.length > 0) {
131
+ const scoped = input.scope === "turn"
132
+ ? currentTurnMessages(input.messages, input.isSynthetic)
133
+ : input.messages;
134
+ records.push(...evidenceFromMessages(scoped, {
135
+ workspaceRoot: input.workspaceRoot,
136
+ ...(input.toolResultsRoot !== undefined ? { toolResultsRoot: input.toolResultsRoot } : {}),
137
+ // The transcript is the parent's: its calls are the session's own.
138
+ ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
139
+ ...(input.inputSchemaOf !== undefined ? { inputSchemaOf: input.inputSchemaOf } : {}),
140
+ }));
141
+ }
142
+ // The parent is named (`parentOf`) when these are indexed, never inferred
143
+ // from whichever record came first: a child's call logged ahead of the
144
+ // parent's would otherwise answer the parent's `tool:<id>` (design §6.3,
145
+ // as `resolveEvidence` reads ids).
146
+ return records;
147
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The serializable input of the gate composition root (design/0.8.0-
3
+ * provability-release.md §4.4): the lowered `evaluation:` and `provability:`
4
+ * blocks plus the two facts about the spec they need — its name (where proof
5
+ * bundles and artifacts are filed) and its primary model (the judge default).
6
+ *
7
+ * The fragment is DATA: an emitter serializes it with `JSON.stringify` into
8
+ * one `wireEvaluation(<fragment>, …)` boot line, and the interpreter builds
9
+ * the same object from the same IR, so a compiled bundle and `crewhaus run`
10
+ * hand the composition root the identical input (the `memoryFragmentFromIr` /
11
+ * `modelWiringFragmentFromIr` precedent).
12
+ */
13
+ import type { IrEvaluation, IrProvability } from "@crewhaus/ir";
14
+ export type EvaluationFragment = {
15
+ /** The spec's `name:` — proof bundles and artifacts live under `.crewhaus/proofs/<specName>/`. */
16
+ readonly specName: string;
17
+ /** The shape's primary model: the `llm_judge` default when `grader.model` is absent. */
18
+ readonly primaryModel: string;
19
+ /** The lowered `evaluation:` block, when the spec declares one. */
20
+ readonly evaluation?: IrEvaluation;
21
+ /** The lowered `provability:` block, when the spec declares one at a rung above `off`. */
22
+ readonly provability?: IrProvability;
23
+ };
24
+ /** The IR slice the fragment reads — structural, so cli / channel / managed IR all satisfy it. */
25
+ export type EvaluationIrSlice = {
26
+ readonly name: string;
27
+ readonly agent: {
28
+ readonly model: string;
29
+ };
30
+ readonly evaluation?: IrEvaluation;
31
+ readonly provability?: IrProvability;
32
+ };
33
+ /**
34
+ * The fragment for `ir`, or `undefined` when the IR carries NEITHER gate —
35
+ * the signal every emitter reads to render nothing at all, so a spec without
36
+ * both blocks compiles to the bytes it compiled to before this package
37
+ * existed (design §1 principle 3). Keys are added in a fixed order and only
38
+ * when present, so the serialized fragment is deterministic.
39
+ */
40
+ export declare function evaluationFragmentFromIr(ir: EvaluationIrSlice): EvaluationFragment | undefined;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The fragment for `ir`, or `undefined` when the IR carries NEITHER gate —
3
+ * the signal every emitter reads to render nothing at all, so a spec without
4
+ * both blocks compiles to the bytes it compiled to before this package
5
+ * existed (design §1 principle 3). Keys are added in a fixed order and only
6
+ * when present, so the serialized fragment is deterministic.
7
+ */
8
+ export function evaluationFragmentFromIr(ir) {
9
+ if (ir.evaluation === undefined && ir.provability === undefined)
10
+ return undefined;
11
+ return {
12
+ specName: ir.name,
13
+ primaryModel: ir.agent.model,
14
+ ...(ir.evaluation !== undefined ? { evaluation: ir.evaluation } : {}),
15
+ ...(ir.provability !== undefined ? { provability: ir.provability } : {}),
16
+ };
17
+ }
package/dist/head.d.ts ADDED
@@ -0,0 +1,115 @@
1
+ /**
2
+ * `provability.sources.resolve: head` (design §6.1): is a cited URL there?
3
+ *
4
+ * One HEAD per distinct URL per session, through `@crewhaus/tool-fetch`'s
5
+ * `guardedHead` — the Fetch tool's own guarded path: http(s) only, the
6
+ * private-address classifier on every hop's literal and resolved address,
7
+ * the socket pinned to the vetted IP, at most five redirects, the whole
8
+ * request (DNS included) bounded. The spec's `sources.allow` / `sources.deny`
9
+ * apply to the CITED URL — that is the source (§6.1); every redirect hop is
10
+ * held to the private-host rule and `sources.deny`, so a cited page cannot
11
+ * carry the check to a host the spec refused, while a `doi.org` citation can
12
+ * still follow its redirect to the publisher an allow list does not name.
13
+ * No body is read, so nothing enters the context and nothing needs
14
+ * classifying.
15
+ *
16
+ * The answer is cached per session (bounded), the way design §6.1 asks: a
17
+ * page cited on every turn of a long session is asked about once. Only
18
+ * ANSWERS are cached — a status, or a refusal the guard will repeat (a
19
+ * private or denied host, a URL that does not parse). A timeout, a network
20
+ * failure or an unresolvable name says nothing lasting about the page: it
21
+ * reads as "no answer" for this verification and is asked again on the next
22
+ * one, so the gate's own retry can recover from a blip (and `on_fail: halt`
23
+ * does not halt on one). An abort is the turn ending, not the page: it is
24
+ * rethrown and forgotten.
25
+ *
26
+ * The request is an egress whose URL the model wrote — path and query
27
+ * included, and those may carry what an injection wanted out. So before a
28
+ * request is sent the URL goes through the sink side of the security
29
+ * fabric (AGENTS.md Pillar 3) when the caller hands a `screen` (the runtime
30
+ * does: `ProvabilityTurn.screenEgress`, `classifyEgress` over the run's data
31
+ * lineage at `external-dynamic`): content a boundary tagged from a non-user
32
+ * origin — a secret a tool read — refuses it, nothing is sent, and the
33
+ * citation reads as unanswered. A refusal is not cached: it is the run's
34
+ * lineage speaking, not the page. Each request decided (sent, refused by
35
+ * the screen, or refused by the guard) is recorded through `record` — the
36
+ * gate turns it into an `egress_decision` on the run's audit sink (sink
37
+ * `provability.resolve`, scope `external-dynamic`, the screen's verdict and
38
+ * the origins it found, §10). A cache hit sends nothing and records nothing.
39
+ * What is recorded is the host and the outcome, never the URL.
40
+ */
41
+ import type { IrProvability } from "@crewhaus/ir";
42
+ import { type HeadRefusal } from "@crewhaus/provability";
43
+ /** How many (session, URL) answers one wiring remembers. */
44
+ export declare const HEAD_CACHE_ENTRIES = 1024;
45
+ /** The sink id a HEAD's `egress_decision` names (design §6.1). */
46
+ export declare const RESOLVE_SINK_ID = "provability.resolve";
47
+ /**
48
+ * What the sink-side screen decided about one URL before it was sent (the
49
+ * runtime's `GateEgressScreen`): `block` refuses the request.
50
+ */
51
+ export type HeadScreen = {
52
+ readonly verdict: "pass" | "warn" | "block";
53
+ readonly originsFound: ReadonlyArray<string>;
54
+ readonly matchCount: number;
55
+ };
56
+ /** One HEAD the gate decided on: what it records as an `egress_decision`. */
57
+ export type HeadDecision = {
58
+ readonly sinkId: typeof RESOLVE_SINK_ID;
59
+ /** The URL is one the model wrote: a dynamic sink, as egress-classifier names it. */
60
+ readonly sinkScope: "external-dynamic";
61
+ /**
62
+ * `pass` / `warn` — the request went out (whatever came back), with the
63
+ * screen's verdict; `block` — it did not: the screen or the guard refused it.
64
+ */
65
+ readonly verdict: "pass" | "warn" | "block";
66
+ readonly method: "HEAD";
67
+ /** The cited URL's host; absent when the URL did not parse. */
68
+ readonly host?: string;
69
+ /** The final status, when one came back. */
70
+ readonly status?: number;
71
+ /**
72
+ * Why there is no status: `egress` — the screen found tagged content in
73
+ * the URL; `refused` — the source / private-host policy; `failed` — the
74
+ * request failed.
75
+ */
76
+ readonly reason?: "egress" | "refused" | "failed";
77
+ /** The origins of the tagged content the screen found in the URL, when it found any. */
78
+ readonly originsFound?: ReadonlyArray<string>;
79
+ readonly matchCount?: number;
80
+ };
81
+ export type HeadResolver = (url: string, ctx: {
82
+ readonly sessionId?: string;
83
+ readonly signal?: AbortSignal;
84
+ /** Told about every request decided (never a cache hit); see the module doc. */
85
+ readonly record?: (decision: HeadDecision) => void | Promise<void>;
86
+ /** The sink-side check a URL passes before it is sent; see the module doc. */
87
+ readonly screen?: (url: string) => Promise<HeadScreen>;
88
+ }) => Promise<number | HeadRefusal | undefined>;
89
+ /** The spec's source policy as a host test: private hosts never, deny wins, an allow list admits only its hosts. */
90
+ export declare function sourceHostPolicy(sources: IrProvability["sources"]): (host: string) => boolean;
91
+ /**
92
+ * The per-hop test for one request: the full policy on the cited URL, the
93
+ * private-host rule and `deny` on every hop a redirect names. `guardedHead`
94
+ * asks once per hop, in order, starting with the URL it was given.
95
+ */
96
+ export declare function hopPolicy(sources: IrProvability["sources"]): (host: string) => boolean;
97
+ /** Session-and-URL keyed answers; see {@link createHeadResolver}. */
98
+ export type HeadCache = Map<string, Promise<number | HeadRefusal | undefined>>;
99
+ /**
100
+ * The guarded HEAD's answers for the whole process, shared by every wiring
101
+ * that uses the default request: a channel bot wires its gates per turn, and
102
+ * a per-wiring cache would ask again on every turn of a session. Keyed by
103
+ * session, the source policy and the URL, so two specs in one process never
104
+ * read each other's answers under different policies. Bounded like any
105
+ * cache here ({@link HEAD_CACHE_ENTRIES}).
106
+ */
107
+ export declare const SHARED_HEAD_CACHE: HeadCache;
108
+ /**
109
+ * The cached resolver. `head` is the request itself — `guardedHead` in
110
+ * production; a caller's `deps.resolveHead` (tests, a proxy-aware host)
111
+ * replaces it and is cached, bounded by the turn's signal and recorded the
112
+ * same way. `cache` is where answers are kept: a fresh one per resolver
113
+ * unless the caller passes one to share.
114
+ */
115
+ export declare function createHeadResolver(sources: IrProvability["sources"], head?: (url: string, signal?: AbortSignal) => Promise<number | undefined>, cache?: HeadCache): HeadResolver;