Rulvar API reference / @rulvar/core / OrchestrateCitationAudit
Interface: OrchestrateCitationAudit
Defined in: packages/core/src/orchestrator/orchestrate.ts:1169
The citation entailment audit's knobs (RV4004). The sample derives from the audited document's own hash (replay-stable, no clock, no randomness; a repaired candidate re-samples afresh), the excerpts come from a resolver the host froze before the run (PURE, exactly the citedValueValidator contract: a live-filesystem resolver would make verdicts depend on when they ran), and the judge is a paid, journaled invocation like the claim judge. A sampled citation whose FIRST cited line does not resolve is unsupported mechanically, with no judge needed for that row: a citation nothing resolves is not provenance.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
auditScope? | "sample" | "all" | What the audit judges (RV4407): 'sample' (default) keeps the deterministic stratified sample byte for byte; 'all' judges EVERY anchor row of the document, a census instead of a sample. Requires resolver 2; one judge invocation still carries all rows, so the cost scales through the prompt and judge.estCost should be sized for the whole document. | packages/core/src/orchestrator/orchestrate.ts:1204 |
judge? | { effort?: Effort; estCost?: number; limits?: UsageLimits; model?: ModelSpec; } | The judge invocation's knobs, exactly the claim judge's shape. | packages/core/src/orchestrator/orchestrate.ts:1206 |
judge.effort? | Effort | - | packages/core/src/orchestrator/orchestrate.ts:1208 |
judge.estCost? | number | Admission estimate for the judge invocation, like AgentOpts.estCost. | packages/core/src/orchestrator/orchestrate.ts:1212 |
judge.limits? | UsageLimits | UsageLimits of the judge invocation; default { maxTurns: 3 }. | packages/core/src/orchestrator/orchestrate.ts:1210 |
judge.model? | ModelSpec | - | packages/core/src/orchestrator/orchestrate.ts:1207 |
judgeOutputCapGuard? | "warn" | "fail" | What an output cap too small for the verdict bijection does (RV4706, the census reruns of the seventh and eighth comparison experiments): a census carries the whole document's rows in ONE judge dispatch, and the { row, verdict, reason } bijection over them must fit judge.limits.maxOutputTokensPerTurn or the reply truncates mid-array; both census rejudges overflowed the seventh experiment's 9000-token cap and raised it to 32000 by hand. When the cap is DECLARED and sits below the floor estimate (CITATION_VERDICT_EST_TOKENS_PER_ROW per judged row plus CITATION_VERDICT_EST_BASE_TOKENS), 'fail' (the default) refuses typed BEFORE the provider call, naming both numbers; 'warn' logs the same numbers and dispatches anyway. An undeclared cap keeps every byte: the estimator cannot judge a resolution it does not see. | packages/core/src/orchestrator/orchestrate.ts:1230 |
maxSampled? | number | The hard whole-document ceiling; default 24, the judge's own budget. | packages/core/src/orchestrator/orchestrate.ts:1177 |
onFound? | "repair" | "report" | "fail" | What a non-supported verdict does. 'report' (the default) stamps the meta and the findings on the envelope and changes nothing else. 'fail' fails the run typed (data.source 'orchestrator_citation_audit') when any sampled citation judges UNSUPPORTED (partial verdicts report either way: a half-carried claim is a finding, not a stop). 'repair' rides the RV3307 bounded round mechanics: the unsupported rows ride one more composition, the repaired document is re-audited (a fresh sample from its new hash), a configured claim pass past the draft rejudges the rewritten document, and unsupported rows that survive fail the run typed. One round exactly, shared (RV4202): arming BOTH this 'repair' and claimConsistency.onFound: 'repair' grants the same ONE bounded round, which then fires after the first audit pass carrying both defect lists (the judged claim contradictions and the unsupported citations, plus the uncovered sentences when coverageRepair is armed), and BOTH judges re-rule on the repaired document's new hash before survivors of either class fail the run typed. The budget never grows past one extra composition. | packages/core/src/orchestrator/orchestrate.ts:1252 |
pattern? | string | Overrides DEFAULT_CITATION_PATTERN; must expose path:line[-end]. | packages/core/src/orchestrator/orchestrate.ts:1173 |
resolve | (target) => string | undefined | The host's pure snapshot reader, exactly citedValueValidator's. | packages/core/src/orchestrator/orchestrate.ts:1171 |
resolver? | 1 | 2 | The resolver generation (RV4208). Default 1, the fixed downward window above, byte identical for every existing config. Declaring 2 excerpts the bounded LOGICAL UNIT the cited line belongs to (heading section, list item, table row with its header, code comment plus declaration, paragraph; citationUnitExcerptOf) and audits EVERY anchor of a compound sentence as its own row against its nearest claim clause, with the unit type and a truncation flag on the row and resolverVersion: 2 on the meta. The sixth comparison experiment's confirmed false negatives were window artifacts: a section heading whose support lives below the fixed window, and only a sentence's first anchor ever sampled. Opt-in because the sample derives from the audited document's hash and v2 changes which rows exist and what the judge reads. | packages/core/src/orchestrator/orchestrate.ts:1195 |
samplePerSection? | number | Sampled citing sentences per H2 section; default 2, the judge's own method. | packages/core/src/orchestrator/orchestrate.ts:1175 |
window? | number | Lines after the cited line an excerpt may carry; default 3. | packages/core/src/orchestrator/orchestrate.ts:1179 |