@agentskit/doc-bridge 1.7.45 → 1.10.0

package/src/schemas/knowledge.ts

@@ -166,7 +166,7 @@ export const ReconciliationReportV1Schema = z
         entityCount: z.number().int().nonnegative(),
         relationCount: z.number().int().nonnegative(),
         diagnosticCount: z.number().int().nonnegative(),
-        scope: z.enum(['file', 'module', 'package']).optional(),
+        scope: z.enum(['file', 'module', 'area', 'package']).optional(),
         requiredRelationKinds: z.array(boundedString(128)).max(128).optional(),
         requiredRelationTargets: z.enum(['all', 'internal']).optional(),
         diagnosticsByCode: z.record(z.string().max(128), z.number().int().nonnegative()).optional(),
@@ -228,11 +228,23 @@ export const WorkflowTransitionSchema = z
   .strict()
 export type WorkflowTransition = z.infer<typeof WorkflowTransitionSchema>
 
+/** Optional identity envelope shared with AgentsKit runtime and Chat events. */
+export const CorrelationContextV1Schema = z.object({
+  operationId: boundedString(128),
+  runId: boundedString(128).optional(),
+  sessionId: boundedString(128).optional(),
+  turnId: boundedString(128).optional(),
+  actionId: boundedString(128).optional(),
+  traceId: boundedString(128).optional(),
+}).strict()
+export type CorrelationContextV1 = z.infer<typeof CorrelationContextV1Schema>
+
 export const WorkflowRunV1Schema = z
   .object({
     type: z.literal('workflow-run'),
     ...ArtifactMetadata,
     runId: boundedString(128),
+    correlation: CorrelationContextV1Schema.optional(),
     state: WorkflowStateSchema,
     steps: z.array(WorkflowStepSchema).max(32),
     transitions: z.array(WorkflowTransitionSchema).max(1_000),
@@ -264,6 +276,7 @@ export const AgentProposalV1Schema = z
     proposalId: boundedString(128),
     baseSnapshotHash: hash,
     baseReportHash: hash,
+    baseDocumentationAuditHash: hash.optional(),
     relatedDiagnosticIds: z.array(boundedString(256)).max(64),
     rationale: boundedString(4_000),
     confidence: z.number().min(0).max(1),

package/src/schemas/retrieval-index.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod'
+
+import { ProvenanceSchema } from './knowledge.js'
+
+/**
+ * The retrieval index: what ranking reads.
+ *
+ * It is a projection of the discovery snapshot — a pure function of the snapshot, the accepted
+ * enrichment overlay and the configuration — and nothing else. It has no scanner of its own,
+ * which is the invariant that makes "the index" and "the snapshot" describe the same repository:
+ * an entity retrieval can find is an entity discovery observed, with the same id, the same
+ * content hash and the same evidence.
+ */
+
+export const RETRIEVAL_INDEX_SCHEMA_VERSION = 1 as const
+
+const hash = z.string().regex(/^[a-f0-9]{64}$/)
+
+export const RetrievalKindSchema = z.enum(['document', 'module', 'area', 'package', 'intent', 'change'])
+export type RetrievalKind = z.infer<typeof RetrievalKindSchema>
+
+/**
+ * How much to trust a result, from most to least.
+ *
+ * `observed` came from code or a manifest; `declared` from a documentation declaration or the
+ * configuration; `fuzzy` from a reference that resolved by similarity rather than by name;
+ * `proposed` from an agent whose proposal has not been accepted. A result's confidence is the
+ * weakest link between the entry and the relation that surfaced it.
+ */
+export const ConfidenceSchema = z.enum(['observed', 'declared', 'fuzzy', 'proposed'])
+export type Confidence = z.infer<typeof ConfidenceSchema>
+
+export const AudienceSchema = z.enum(['agent', 'human', 'human-and-agent'])
+export type Audience = z.infer<typeof AudienceSchema>
+
+/** Text the lexical ranker indexes, one string per field, already bounded. */
+export const RetrievalFieldsSchema = z
+  .object({
+    title: z.string().max(512),
+    headings: z.string().max(4_096),
+    path: z.string().max(1_024),
+    symbols: z.string().max(8_192),
+    summary: z.string().max(2_048),
+    body: z.string().max(16_000),
+    aliases: z.string().max(2_048),
+  })
+  .strict()
+export type RetrievalFields = z.infer<typeof RetrievalFieldsSchema>
+
+/** One edge into or out of an entry, with the confidence of the relation it came from. */
+export const RetrievalEdgeSchema = z
+  .object({
+    kind: z.string().min(1).max(64),
+    id: z.string().min(1).max(256),
+    confidence: ConfidenceSchema,
+  })
+  .strict()
+export type RetrievalEdge = z.infer<typeof RetrievalEdgeSchema>
+
+export const RetrievalGraphSchema = z
+  .object({
+    /** Canonicality: PageRank over `links-to` and `covers`. */
+    pagerank: z.number().min(0).max(1),
+    inboundLinks: z.number().int().nonnegative(),
+    coveredBy: z.array(z.string().min(1).max(256)).max(64),
+    mentionedBy: z.array(z.string().min(1).max(256)).max(64),
+    areaId: z.string().min(1).max(256).optional(),
+    packageId: z.string().min(1).max(256).optional(),
+    /** Documentation edges into this entry, with their confidence. The explain view reads these. */
+    inbound: z.array(RetrievalEdgeSchema).max(64),
+    /** Where a document's own links go, and which internal modules a module imports. */
+    outbound: z.array(RetrievalEdgeSchema).max(64),
+  })
+  .strict()
+export type RetrievalGraph = z.infer<typeof RetrievalGraphSchema>
+
+export const RetrievalEntrySchema = z
+  .object({
+    id: z.string().min(1).max(256),
+    kind: RetrievalKindSchema,
+    path: z.string().min(1).max(512),
+    title: z.string().min(1).max(256),
+    summary: z.string().max(2_048).optional(),
+    audience: AudienceSchema.optional(),
+    /** Names this entry also answers to: an ownership id, a sidecar id, a package's short name. */
+    aliases: z.array(z.string().min(1).max(256)).max(32),
+    /** A module's exported names, kept as a list so an exact-symbol match is exact. */
+    symbols: z.array(z.string().min(1).max(128)).max(256).optional(),
+    tags: z.array(z.string().min(1).max(64)).max(32),
+    fields: RetrievalFieldsSchema,
+    graph: RetrievalGraphSchema,
+    contentHash: hash,
+    provenance: ProvenanceSchema,
+    confidence: ConfidenceSchema,
+    /** The ownership record this entry stands for, when one is attached to it. */
+    ownershipId: z.string().min(1).max(256).optional(),
+    /**
+     * The accepted enrichment overlay's share of the bounded agent weight for this entry, 0..1.
+     * Absent when no live accepted entry names it; the ranker treats absent as zero.
+     */
+    agentSignal: z.number().min(0).max(1).optional(),
+  })
+  .strict()
+export type RetrievalEntry = z.infer<typeof RetrievalEntrySchema>
+
+/**
+ * What the lexical ranker needs beyond the entries themselves.
+ *
+ * The postings are not stored: `fields` already is the serialised index, because tokenisation is
+ * versioned (`lexiconVersion`) and deterministic, so the postings a reader rebuilds are the
+ * postings the writer would have stored. What is recorded is the shape of the collection —
+ * enough to check that a reader rebuilt the same index, and to score against it.
+ */
+export const RetrievalLexicalSchema = z
+  .object({
+    version: z.number().int().nonnegative().max(1_000),
+    documentCount: z.number().int().nonnegative(),
+    fieldNames: z.array(z.string().min(1).max(64)).max(32),
+    averageFieldLength: z.record(z.string().min(1).max(64), z.number().nonnegative()),
+  })
+  .strict()
+
+/**
+ * The most entries one index can carry.
+ *
+ * A bound, because an unbounded artifact is not an artifact: a reader has to be able to refuse a
+ * file before parsing it all. It is deliberately above what a large monorepo produces — the
+ * repository that first exceeded the previous bound projects about eleven thousand entries — so the
+ * limit reports a corpus nobody meant to index rather than a corpus that is merely big.
+ */
+export const RETRIEVAL_MAX_ENTRIES = 50_000
+
+export const RetrievalIndexV1Schema = z
+  .object({
+    type: z.literal('retrieval-index'),
+    schemaVersion: z.literal(RETRIEVAL_INDEX_SCHEMA_VERSION),
+    contentHash: hash,
+    contentHashAlgo: z.literal('sha256-normalized-v1'),
+    /** The three inputs the projection is a function of. Same three hashes, same projection. */
+    snapshotHash: hash,
+    overlayHash: hash,
+    configurationHash: hash,
+    lexiconVersion: z.number().int().nonnegative().max(1_000),
+    graphMetricsVersion: z.string().min(1).max(64),
+    weights: z.record(z.string().min(1).max(64), z.number().min(0).max(1_000)),
+    params: z.object({ k1: z.number().min(0).max(100), b: z.number().min(0).max(1) }).strict(),
+    lexical: RetrievalLexicalSchema,
+    entries: z.array(RetrievalEntrySchema).max(RETRIEVAL_MAX_ENTRIES),
+  })
+  .strict()
+
+export type RetrievalIndexV1 = z.infer<typeof RetrievalIndexV1Schema>

package/src/shims/graphology.d.ts

@@ -0,0 +1,91 @@
+/**
+ * graphology under `moduleResolution: NodeNext`.
+ *
+ * These packages ship CommonJS type declarations with an ESM-style `export default`. Node loads
+ * their ESM build (they declare an `import` condition) and gets the class or function, but
+ * TypeScript reads the CommonJS declarations and types the default import as the module namespace
+ * — so `new Graph()` reads as "not constructable" and `pagerank(graph)` as "not callable", both
+ * wrongly. The packages publish one `types` path for both conditions, so there is nothing to
+ * select.
+ *
+ * Rather than cast at every call site, this declares the surface the graph layer actually uses,
+ * the way it behaves at runtime. It is deliberately narrow: nothing here is a guess, every
+ * signature is exercised by `tests/graph.test.ts` against real numeric expectations, so a drift
+ * from the library fails a test rather than hiding behind a cast.
+ */
+
+declare module 'graphology' {
+  export type GraphologyAttributes = Record<string, unknown>
+
+  export type GraphologyOptions = {
+    readonly type?: 'directed' | 'undirected' | 'mixed'
+    readonly multi?: boolean
+    readonly allowSelfLoops?: boolean
+  }
+
+  export interface GraphologyGraph {
+    readonly order: number
+    readonly size: number
+    hasNode(node: string): boolean
+    addNode(node: string, attributes?: GraphologyAttributes): string
+    hasEdge(source: string, target: string): boolean
+    addEdge(source: string, target: string, attributes?: GraphologyAttributes): string
+    getEdgeAttributes(source: string, target: string): GraphologyAttributes
+    nodes(): string[]
+    edges(): string[]
+    outNeighbors(node: string): string[]
+    neighbors(node: string): string[]
+  }
+
+  const Graph: new (options?: GraphologyOptions) => GraphologyGraph
+  export default Graph
+}
+
+declare module 'graphology-metrics/centrality/pagerank.js' {
+  import type { GraphologyGraph } from 'graphology'
+
+  const pagerank: (
+    graph: GraphologyGraph,
+    options?: {
+      readonly getEdgeWeight?: string | null
+      readonly alpha?: number
+      readonly maxIterations?: number
+      readonly tolerance?: number
+    },
+  ) => Record<string, number>
+  export default pagerank
+}
+
+declare module 'graphology-metrics/centrality/betweenness.js' {
+  import type { GraphologyGraph } from 'graphology'
+
+  const betweennessCentrality: (
+    graph: GraphologyGraph,
+    options?: { readonly getEdgeWeight?: string | null; readonly normalized?: boolean },
+  ) => Record<string, number>
+  export default betweennessCentrality
+}
+
+declare module 'graphology-shortest-path/unweighted.js' {
+  import type { GraphologyGraph } from 'graphology'
+
+  export function singleSourceLength(graph: GraphologyGraph, source: string): Record<string, number>
+  export function bidirectional(graph: GraphologyGraph, source: string, target: string): string[] | null
+}
+
+declare module 'graphology-dag/has-cycle.js' {
+  import type { GraphologyGraph } from 'graphology'
+
+  const hasCycle: (graph: GraphologyGraph) => boolean
+  export default hasCycle
+}
+
+declare module 'graphology-communities-louvain' {
+  import type { GraphologyGraph } from 'graphology'
+
+  const louvain: (
+    graph: GraphologyGraph,
+    options?: { readonly rng?: () => number; readonly resolution?: number; readonly randomWalk?: boolean },
+  ) => Record<string, number>
+  export default louvain
+}

package/src/study/adjudication.ts

@@ -0,0 +1,196 @@
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { z } from 'zod'
+
+import {
+  calculateStudyCostUsd,
+  validateStudyProviderCommand,
+  type StudyAdjudicatorCli,
+} from './provider-cli.js'
+import {
+  createControlledStudyLedger,
+  createControlledStudyObservation,
+  parseControlledStudyLedger,
+  type ControlledStudyObservationLedgerV1,
+  type ControlledStudyObservationV1,
+} from './runner.js'
+import { mechanicalRubricItems, modelRubricItems, parseStudyTaskSuite, type StudyTaskV1 } from './task-suite.js'
+
+export const STUDY_ADJUDICATION_METHOD = 'independent-rubric-v1' as const
+
+const outcome = z.enum(['success', 'partial', 'incorrect', 'incomplete', 'blocked'])
+const identifier = z.string().regex(/^[a-z][a-z0-9-]{0,127}$/)
+const AdjudicatorOutputSchema = z.object({
+  outcome,
+  confidence: z.number().min(0).max(1),
+  reasonCodes: z.array(identifier).max(16),
+  inputTokens: z.number().int().nonnegative().optional(),
+  outputTokens: z.number().int().nonnegative().optional(),
+  tokenMethod: z.enum(['provider', 'estimate']).optional(),
+  measurements: z.record(z.string().min(1).max(128), z.number().finite().nonnegative()).optional(),
+}).strict().superRefine((value, context) => {
+  if ((value.inputTokens !== undefined || value.outputTokens !== undefined) && value.tokenMethod === undefined) context.addIssue({ code: z.ZodIssueCode.custom, path: ['tokenMethod'], message: 'Adjudicator token counts require a token method.' })
+})
+
+type AdjudicatorOutput = z.infer<typeof AdjudicatorOutputSchema>
+
+type ProcessResult = {
+  readonly status: 'completed' | 'timed-out' | 'unavailable' | 'invalid-output' | 'budget-exceeded'
+  readonly stdout: string
+  readonly stderrBytes: number
+  readonly durationMs: number
+}
+
+const terminate = (child: ReturnType<typeof spawn>): void => {
+  if (child.pid === undefined) return
+  try { process.kill(-child.pid, 'SIGTERM') } catch { child.kill('SIGTERM') }
+}
+
+const runAdjudicatorProcess = (config: StudyAdjudicatorCli, cwd: string, input: string, maxRuntimeMs: number): Promise<ProcessResult> => new Promise((resolveResult) => {
+  const env = Object.fromEntries([...new Set(['PATH', 'HOME', 'TMPDIR', ...config.envAllowlist])].flatMap((name) => process.env[name] === undefined ? [] : [[name, process.env[name] as string]]))
+  const started = Date.now()
+  const child = spawn(config.command, [...config.args], { cwd: resolve(cwd), shell: false, detached: true, env, stdio: ['pipe', 'pipe', 'pipe'] })
+  let stdout = ''
+  let stderrBytes = 0
+  let settled = false
+  const finish = (result: ProcessResult): void => { if (settled) return; settled = true; resolveResult(result) }
+  const timer = setTimeout(() => { terminate(child); finish({ status: 'timed-out', stdout, stderrBytes, durationMs: Date.now() - started }) }, maxRuntimeMs)
+  child.stdout.on('data', (chunk: Buffer) => {
+    stdout += chunk.toString('utf8')
+    if (Buffer.byteLength(stdout, 'utf8') > config.maxOutputBytes) { clearTimeout(timer); terminate(child); finish({ status: 'budget-exceeded', stdout: stdout.slice(0, config.maxOutputBytes), stderrBytes, durationMs: Date.now() - started }) }
+  })
+  child.stderr.on('data', (chunk: Buffer) => { stderrBytes += Buffer.byteLength(chunk) })
+  child.once('error', () => { clearTimeout(timer); finish({ status: 'unavailable', stdout, stderrBytes, durationMs: Date.now() - started }) })
+  child.once('close', (code) => {
+    clearTimeout(timer)
+    if (settled) return
+    if (code !== 0) finish({ status: 'unavailable', stdout, stderrBytes, durationMs: Date.now() - started })
+    else { try { JSON.parse(stdout) as unknown; finish({ status: 'completed', stdout, stderrBytes, durationMs: Date.now() - started }) } catch { finish({ status: 'invalid-output', stdout, stderrBytes, durationMs: Date.now() - started }) } }
+  })
+  child.stdin.end(input)
+})
+
+/**
+ * What the adjudicator is asked, and what it is not.
+ *
+ * A rubric item with a mechanical check has already been decided by the runner — acceptance
+ * commands and their exit status, evidence coverage, retrieval expectations. Showing such an item
+ * to a model invites it to disagree with a measurement, which is how a study ends up with an
+ * opinion where it had a number. So the input carries only the items no checker can settle, and
+ * the settled ones travel next to them as `mechanical`: verdicts, for context, not for review.
+ */
+export const adjudicatorRubric = (task: StudyTaskV1): {
+  readonly rubric: ReturnType<typeof modelRubricItems>
+  readonly mechanical: ReturnType<typeof mechanicalRubricItems>
+} => ({ rubric: modelRubricItems(task), mechanical: mechanicalRubricItems(task) })
+
+const adjudicatorInput = (task: StudyTaskV1, observation: ControlledStudyObservationV1): string => JSON.stringify({
+  protocol: 'doc-bridge.study-adjudicator.v1',
+  instruction: 'Evaluate only the bounded candidate record against the rubric items supplied. Items already decided by a mechanical check are listed under mechanical and are not yours to re-decide. Use evidenceCoverage and acceptanceExecution to distinguish missing evidence from unexecuted checks. Do not infer missing evidence. Return one JSON object and no prose.',
+  task: { id: task.id, category: task.category, difficulty: task.difficulty, objective: task.objective, expectedOutcome: task.expectedOutcome, evidenceRequirements: task.evidenceRequirements, acceptanceChecks: task.acceptanceChecks, ...adjudicatorRubric(task) },
+  candidate: {
+    taskOutcome: observation.taskOutcome ?? null,
+    evidenceQuality: observation.evidenceQuality ?? null,
+    safetyOutcome: observation.safetyOutcome ?? null,
+    evidenceIds: observation.evidenceIds,
+    evidenceCoverage: {
+      required: task.evidenceRequirements.map((requirement) => ({ id: requirement.id, present: observation.evidenceIds.includes(requirement.id) })),
+      referenceCount: observation.evidenceIds.length,
+    },
+    acceptanceExecution: {
+      status: observation.execution.status,
+      passed: observation.measurements?.acceptanceChecksPassed ?? null,
+      total: observation.measurements?.acceptanceChecksTotal ?? null,
+      executed: observation.measurements?.acceptanceChecksExecuted ?? null,
+      measurementPresent: observation.measurements?.acceptanceChecksPassed !== undefined
+        && observation.measurements?.acceptanceChecksTotal !== undefined
+        && observation.measurements?.acceptanceChecksExecuted !== undefined,
+    },
+    measurements: observation.measurements ?? {},
+    execution: { status: observation.execution.status, durationMs: observation.execution.durationMs, responseBytes: observation.execution.responseBytes },
+  },
+})
+
+const withUpdatedObservation = (observation: ControlledStudyObservationV1, adjudication: ControlledStudyObservationV1['adjudication'], measurements: Readonly<Record<string, number>>): ControlledStudyObservationV1 => {
+  const { contentHash: _contentHash, contentHashAlgo: _contentHashAlgo, ...payload } = observation
+  return createControlledStudyObservation({ ...payload, measurements, adjudication })
+}
+
+export const independentlyAdjudicateStudyObservation = async (task: StudyTaskV1, observation: ControlledStudyObservationV1, config: StudyAdjudicatorCli, cwd: string, maxRuntimeMs: number, configurationHash: string): Promise<ControlledStudyObservationV1> => {
+  validateStudyProviderCommand(config, cwd)
+  const input = adjudicatorInput(task, observation)
+  if (Buffer.byteLength(input, 'utf8') > config.maxInputBytes) throw new Error(`Adjudicator input limit ${config.maxInputBytes} bytes exceeded for ${task.id}.`)
+  const processResult = await runAdjudicatorProcess(config, cwd, input, maxRuntimeMs)
+  const baseMeasurements = { ...(observation.measurements ?? {}), adjudicatorLatencyMs: processResult.durationMs }
+  if (processResult.status !== 'completed') return withUpdatedObservation(observation, { status: 'pending', actor: config.id, method: STUDY_ADJUDICATION_METHOD, reason: `Independent adjudicator ${processResult.status}.` }, baseMeasurements)
+  const parsed = AdjudicatorOutputSchema.safeParse(JSON.parse(processResult.stdout))
+  if (!parsed.success) return withUpdatedObservation(observation, { status: 'pending', actor: config.id, method: STUDY_ADJUDICATION_METHOD, reason: 'Independent adjudicator returned invalid output.' }, baseMeasurements)
+  const output: AdjudicatorOutput = parsed.data
+  const costUsd = calculateStudyCostUsd(config.pricing, {
+    ...(output.inputTokens === undefined ? {} : { inputTokens: output.inputTokens }),
+    ...(output.measurements?.cachedInputTokens === undefined ? {} : { cachedInputTokens: output.measurements.cachedInputTokens }),
+    ...(output.outputTokens === undefined ? {} : { outputTokens: output.outputTokens }),
+  })
+  const tokenUnits = output.tokenMethod === 'provider' && output.inputTokens !== undefined && output.outputTokens !== undefined ? output.inputTokens + output.outputTokens : undefined
+  return withUpdatedObservation(observation, {
+    status: 'automated',
+    actor: config.id,
+    method: STUDY_ADJUDICATION_METHOD,
+    configurationHash,
+    outcome: output.outcome,
+    confidence: output.confidence,
+    reasonCodes: output.reasonCodes,
+    ...(output.tokenMethod === undefined ? {} : { tokenMethod: output.tokenMethod }),
+    reason: 'Independent adjudicator evaluated the anonymized bounded candidate record against the task rubric.',
+  }, {
+    ...baseMeasurements,
+    ...(output.measurements ?? {}),
+    ...(output.inputTokens === undefined ? {} : { adjudicatorInputTokens: output.inputTokens }),
+    ...(output.outputTokens === undefined ? {} : { adjudicatorOutputTokens: output.outputTokens }),
+    ...(tokenUnits === undefined ? {} : { adjudicatorTokenCostUnits: tokenUnits }),
+    ...(costUsd === undefined ? {} : { adjudicatorCostUsd: costUsd }),
+  })
+}
+
+export type IndependentStudyAdjudicationOptions = {
+  readonly ledger: ControlledStudyObservationLedgerV1
+  readonly taskSuite: ReturnType<typeof parseStudyTaskSuite>
+  readonly config: StudyAdjudicatorCli
+  readonly configurationHash: string
+  readonly cwd: string
+  readonly maxRuntimeMs: number
+  readonly runId?: string
+  readonly limit?: number
+  readonly offset?: number
+}
+
+export const independentlyAdjudicateStudyLedger = async (options: IndependentStudyAdjudicationOptions): Promise<ControlledStudyObservationLedgerV1> => {
+  if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) throw new Error('Adjudication limit must be a positive integer.')
+  if (options.offset !== undefined && (!Number.isInteger(options.offset) || options.offset < 0)) throw new Error('Adjudication offset must be a non-negative integer.')
+  const taskMap = new Map(options.taskSuite.tasks.map((task) => [task.id, task]))
+  const observations = [] as ControlledStudyObservationV1[]
+  let selected = 0
+  let skipped = 0
+  for (const observation of options.ledger.observations) {
+    if (options.runId !== undefined && observation.runId !== options.runId) { observations.push(observation); continue }
+    if (options.offset !== undefined && skipped < options.offset) { skipped += 1; observations.push(observation); continue }
+    if (options.limit !== undefined && selected >= options.limit) { observations.push(observation); continue }
+    const task = taskMap.get(observation.task.taskId)
+    if (!task) throw new Error(`No task definition exists for ${observation.task.taskId}.`)
+    selected += 1
+    observations.push(await independentlyAdjudicateStudyObservation(task, observation, options.config, options.cwd, options.maxRuntimeMs, options.configurationHash))
+  }
+  const { contentHash: _contentHash, contentHashAlgo: _contentHashAlgo, ...payload } = options.ledger
+  return createControlledStudyLedger({ ...payload, observations })
+}
+
+export const persistIndependentlyAdjudicatedLedger = (path: string, ledger: ControlledStudyObservationLedgerV1): string => {
+  parseControlledStudyLedger(ledger)
+  mkdirSync(dirname(resolve(path)), { recursive: true })
+  writeFileSync(resolve(path), `${JSON.stringify(ledger, null, 2)}\n`, 'utf8')
+  return resolve(path)
+}
+
+export const adjudicatedLedgerInputHash = (task: StudyTaskV1, observation: ControlledStudyObservationV1): string => createHash('sha256').update(adjudicatorInput(task, observation)).digest('hex')