@velum-labs/routekit-eval-setup 1.3.2 → 1.5.0

package/dist/agentic-capabilities-protocol.js

@@ -0,0 +1,786 @@
+import { Schema } from "effect";
+import { pipelineDigestV2 } from "./case-pipeline-protocol-v2.js";
+/** Additive foundry-tool boundary. A schema-valid handle is not proof of acceptance. */
+export const AGENTIC_CAPABILITIES_PROTOCOL_VERSION_V1 = 1;
+/**
+ * Request-scoped negotiation for the additive trusted-invocation ceilings.
+ * Cloud must not emit those members unless the invoking Sandbox Agent
+ * advertises this exact extension: N-1 readers decode the v1 invocation
+ * strictly and reject unknown members.
+ */
+export const AGENTIC_SCIENTIFIC_INVOCATION_CEILINGS_V1 = "scientific-invocation-ceilings-v1";
+export const AGENTIC_CAPABILITY_NAMES_V1 = [
+    "inspect_repository",
+    "list_candidates",
+    "read_source",
+    "search_source",
+    "draft_specification",
+    "plan_environment",
+    "probe_fixture",
+    "qualify_reference",
+    "author_oracle",
+    "generate_controls",
+    "evaluate_oracle",
+    "repair_oracle",
+    "freeze_candidate",
+    "run_held_out_challenge",
+    "request_admission",
+    "get_progress",
+    "read_diagnostics",
+    "reject_candidate",
+    "finish_campaign"
+];
+const AGENTIC_CAPABILITY_SOURCE_HANDLE_DESCRIPTIONS_V1 = {
+    read_source: {
+        source: "Use the exact opaque source handle returned by inspect_repository or list_candidates. A Git commit SHA, tree SHA, repository name, path, candidate handle, or guessed digest is not a source handle."
+    },
+    search_source: {
+        source: "Use the exact opaque source handle returned by inspect_repository or list_candidates. A Git commit SHA, tree SHA, repository name, path, candidate handle, or guessed digest is not a source handle."
+    }
+};
+export const AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1 = {
+    draft_specification: {
+        previousDraft: "Previously accepted specification-draft handle to revise.",
+        feedback: "Specification-review findings handle to address."
+    },
+    probe_fixture: {
+        environment: "Accepted environment-plan handle.",
+        fixtureDraft: "Accepted fixture-draft handle."
+    },
+    qualify_reference: {
+        environment: "Accepted environment-plan handle."
+    },
+    author_oracle: {
+        specification: "Accepted specification handle.",
+        previousOracle: "Previously accepted oracle handle to revise.",
+        findings: "Oracle-review findings handle to address."
+    },
+    generate_controls: {
+        specification: "Accepted specification handle.",
+        environment: "Accepted environment-plan handle."
+    },
+    evaluate_oracle: {
+        oracle: "Accepted oracle handle.",
+        controls: "Pass a one-element list containing the latest cumulative controls checkpoint handle returned by generate_controls. Each generation returns a new snapshot containing all accepted valid and wrong controls and supersedes earlier snapshots; do not combine old and new handles."
+    },
+    repair_oracle: {
+        oracle: "Accepted oracle handle to repair.",
+        findings: "Accepted oracle-evaluation findings handle to address."
+    }
+};
+const AGENTIC_CAPABILITY_ARTIFACT_HANDLE_INSTRUCTION_V1 = "Supply the exact opaque artifact handle returned by a prior foundry tool result; never paste artifact contents, prose, commands, or an invented identifier.";
+/**
+ * Effect's JSON Schema renderer does not consistently retain annotations on
+ * refined schemas. Apply the canonical agent-facing handle descriptions after
+ * rendering so every generated transport contract is derived from one durable
+ * protocol-owned mechanism.
+ */
+export const agenticCapabilityRequestJsonSchemaV1 = (schema) => {
+    const decorated = structuredClone(schema);
+    const root = decorated;
+    const descriptionsByTool = AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1;
+    const sourceDescriptionsByTool = AGENTIC_CAPABILITY_SOURCE_HANDLE_DESCRIPTIONS_V1;
+    for (const branch of root.anyOf ?? []) {
+        const tool = branch.properties?.tool?.enum?.[0];
+        const descriptions = typeof tool === "string" ? descriptionsByTool[tool] : undefined;
+        const sourceDescriptions = typeof tool === "string" ? sourceDescriptionsByTool[tool] : undefined;
+        const args = branch.properties?.args;
+        const properties = args?.properties ??
+            args?.anyOf?.find((candidate) => candidate.properties !== undefined)
+                ?.properties;
+        if (properties === undefined)
+            continue;
+        for (const [field, description] of Object.entries(descriptions ?? {})) {
+            const property = properties[field];
+            if (property === undefined)
+                continue;
+            property.description =
+                `${description} ${AGENTIC_CAPABILITY_ARTIFACT_HANDLE_INSTRUCTION_V1}`;
+        }
+        for (const [field, description] of Object.entries(sourceDescriptions ?? {})) {
+            const property = properties[field];
+            if (property !== undefined)
+                property.description = description;
+        }
+    }
+    return decorated;
+};
+const boundedText = (bytes, nonempty = false) => {
+    const base = Schema.String.check(Schema.isMaxLength(bytes), Schema.makeFilter((value) => Buffer.byteLength(value, "utf8") <= bytes && (!nonempty || value.trim().length > 0)
+        ? undefined
+        : `must contain ${nonempty ? "1 to " : "at most "}${bytes} UTF-8 bytes`));
+    return nonempty
+        ? base.check(Schema.isPattern(/\S/u, {
+            expected: `a nonempty string with at most ${bytes} UTF-8 bytes`
+        }))
+        : base;
+};
+const handle = boundedText(256, true).pipe(Schema.check(Schema.isTrimmed()), Schema.check(Schema.isPattern(/^[^\u0000-\u001f\u007f]+$/u, {
+    expected: "a normalized opaque handle without control characters"
+})), Schema.check(Schema.makeFilter((value) => value.trim() === value && !/[\u0000-\u001f\u007f]/u.test(value)
+    ? undefined
+    : "invalid opaque handle")));
+const artifactHandle = (description) => handle.annotate({
+    description: `${description} ${AGENTIC_CAPABILITY_ARTIFACT_HANDLE_INSTRUCTION_V1}`
+});
+const digest = Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-f0-9]{64}$/u)), Schema.check(Schema.makeFilter((value) => /^[a-f0-9]{64}$/u.test(value) ? undefined : "must be a lowercase SHA-256 digest")));
+const integer = (maximum = Number.MAX_SAFE_INTEGER, minimum = 0) => Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isBetween({ minimum, maximum })), Schema.check(Schema.makeFilter((value) => Number.isSafeInteger(value) && value >= minimum && value <= maximum
+    ? undefined
+    : `must be an integer between ${minimum} and ${maximum}`)));
+const timestamp = boundedText(64, true).pipe(Schema.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}(Z|[+-]\d{2}:\d{2})$/u)), Schema.check(Schema.makeFilter((value) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}(Z|[+-]\d{2}:\d{2})$/u.test(value) &&
+    Number.isFinite(Date.parse(value))
+    ? undefined
+    : "must be an ISO timestamp with milliseconds and timezone")));
+const decimal = Schema.String.pipe(Schema.check(Schema.isPattern(/^(0|[1-9]\d{0,14})(\.\d{1,12})?$/u)), Schema.check(Schema.makeFilter((value) => /^(0|[1-9]\d{0,14})(\.\d{1,12})?$/u.test(value)
+    ? undefined
+    : "must be a nonnegative decimal amount")));
+const path = boundedText(4096, true).pipe(Schema.check(Schema.isPattern(/^(?!\/)(?![a-z]:)(?!.*[\\\u0000-\u001f\u007f])(?!(?:.*\/)?(?:\.|\.\.)(?:\/|$))[^/]+(?:\/[^/]+)*$/iu, { expected: "a normalized repository-relative path without traversal" })), Schema.check(Schema.makeFilter((value) => !value.startsWith("/") &&
+    !/^[a-z]:/iu.test(value) &&
+    !/[\\\u0000-\u001f\u007f]/u.test(value) &&
+    value.split("/").every((part) => part !== "" && part !== "." && part !== "..")
+    ? undefined
+    : "must be a normalized repository-relative path without traversal")));
+// Package roots may name the repository itself. File and artifact paths remain
+// strict relative paths, so accepting a root never admits "." as a file.
+const packageRoot = Schema.Union([Schema.Literal("."), path]);
+const struct = (fields) => Schema.Struct(fields).annotate({ parseOptions: { onExcessProperty: "error" } });
+const list = (schema, maximum = 32, minimum = 0) => Schema.Array(schema).pipe(Schema.check(Schema.isLengthBetween(minimum, maximum)), Schema.check(Schema.makeFilter((value) => value.length >= minimum && value.length <= maximum
+    ? undefined
+    : `must contain ${minimum} to ${maximum} entries`)));
+const capability = (tool, fields) => struct({ tool: Schema.Literal(tool), args: struct(fields) });
+export const AgenticCapabilityRequestV1 = Schema.Union([
+    capability("inspect_repository", {}),
+    capability("list_candidates", {
+        coverageCell: handle,
+        cursor: Schema.optionalKey(handle),
+        limit: integer(50, 1)
+    }),
+    capability("read_source", {
+        source: handle,
+        path,
+        offset: integer(),
+        length: integer(120_000, 1)
+    }),
+    capability("search_source", {
+        source: handle,
+        query: boundedText(512, true),
+        cursor: Schema.optionalKey(handle)
+    }),
+    capability("draft_specification", {
+        candidate: handle,
+        previousDraft: Schema.optionalKey(artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.draft_specification
+            .previousDraft)),
+        feedback: Schema.optionalKey(artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.draft_specification
+            .feedback))
+    }),
+    capability("plan_environment", {
+        candidate: handle,
+        recipeIds: list(handle, 32, 1).annotate({
+            description: "Select one to 32 existing repository-owned grade recipe IDs for this candidate; never submit an empty list or invent commands."
+        }),
+        executionMode: Schema.Literals(["source", "emitted", "repository-default"]),
+        targetRoots: list(packageRoot, 32, 1).annotate({
+            description: "Select one to 32 normalized repository package roots required by the chosen recipes."
+        }),
+        requiredArtifacts: list(path),
+        justification: boundedText(4096, true)
+    }),
+    capability("probe_fixture", {
+        candidate: handle,
+        environment: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.probe_fixture.environment),
+        fixtureDraft: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.probe_fixture.fixtureDraft)
+    }),
+    capability("qualify_reference", {
+        candidate: handle,
+        environment: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.qualify_reference
+            .environment)
+    }),
+    capability("author_oracle", {
+        candidate: handle,
+        specification: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.author_oracle
+            .specification),
+        previousOracle: Schema.optionalKey(artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.author_oracle
+            .previousOracle)),
+        findings: Schema.optionalKey(artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.author_oracle.findings))
+    }),
+    capability("generate_controls", {
+        candidate: handle,
+        specification: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.generate_controls
+            .specification),
+        environment: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.generate_controls
+            .environment),
+        kind: Schema.Literals(["valid", "wrong"])
+    }),
+    capability("evaluate_oracle", {
+        candidate: handle,
+        oracle: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.evaluate_oracle.oracle),
+        controls: list(handle, 32, 1).annotate({
+            description: AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.evaluate_oracle.controls
+        })
+    }),
+    capability("repair_oracle", {
+        candidate: handle,
+        oracle: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.repair_oracle.oracle),
+        findings: artifactHandle(AGENTIC_CAPABILITY_ARTIFACT_HANDLE_DESCRIPTIONS_V1.repair_oracle.findings)
+    }),
+    capability("freeze_candidate", { candidate: handle, revision: handle }),
+    capability("run_held_out_challenge", { frozenCandidate: handle }),
+    capability("request_admission", { frozenCandidate: handle, qualification: handle }),
+    capability("get_progress", { candidate: Schema.optionalKey(handle) }),
+    capability("read_diagnostics", {
+        operation: handle,
+        cursor: Schema.optionalKey(handle),
+        maximumBytes: integer(65_536, 1)
+    }),
+    capability("reject_candidate", {
+        candidate: handle,
+        reason: boundedText(4096, true),
+        evidence: list(handle)
+    }),
+    capability("finish_campaign", { reason: boundedText(4096, true) })
+]);
+export const decodeAgenticCapabilityRequestV1 = Schema.decodeUnknownSync(AgenticCapabilityRequestV1);
+export const AgenticTrustedInvocationV1 = struct({
+    orgId: handle,
+    campaignId: handle,
+    executionId: handle,
+    epoch: integer(Number.MAX_SAFE_INTEGER, 1),
+    operationId: handle,
+    inputDigest: digest,
+    candidateRevision: Schema.optionalKey(handle),
+    actorRole: handle,
+    modelBinding: handle,
+    reservation: handle,
+    deadlineAt: timestamp,
+    maximumModelCalls: Schema.optionalKey(integer(Number.MAX_SAFE_INTEGER, 1)),
+    maximumWallTimeMs: Schema.optionalKey(integer(Number.MAX_SAFE_INTEGER, 1)),
+    toolBundleDigest: digest,
+    traceparent: Schema.optionalKey(Schema.String.pipe(Schema.check(Schema.makeFilter((value) => /^00-(?!0{32})[a-f0-9]{32}-(?!0{16})[a-f0-9]{16}-[a-f0-9]{2}$/u.test(value)
+        ? undefined
+        : "invalid W3C traceparent")))),
+    request: AgenticCapabilityRequestV1
+});
+export const decodeAgenticTrustedInvocationV1 = Schema.decodeUnknownSync(AgenticTrustedInvocationV1);
+export const AgenticProgressFingerprintV1 = struct({
+    version: Schema.Literal(1),
+    acceptedEvidenceDigest: digest,
+    completedGateDigest: digest,
+    environmentDigest: Schema.NullOr(digest),
+    continuationProgressDigest: Schema.optionalKey(Schema.NullOr(digest))
+});
+export const decodeAgenticProgressFingerprintV1 = Schema.decodeUnknownSync(AgenticProgressFingerprintV1);
+const scientificBudgetRemaining = struct({
+    phaseCalls: integer(),
+    phaseSpendUsd: Schema.NullOr(decimal),
+    phaseWallTimeMs: integer(),
+    phaseAttempts: integer(),
+    downstreamCalls: integer(),
+    downstreamSpendUsd: Schema.NullOr(decimal),
+    downstreamWallTimeMs: integer(),
+    downstreamAttempts: integer()
+});
+/** Host-computed scientific progress; model prose and activity are never inputs. */
+export const AgenticScientificProgressReceiptV1 = struct({
+    version: Schema.Literal(1),
+    receiptId: handle,
+    operationId: handle,
+    capability: Schema.Literals(AGENTIC_CAPABILITY_NAMES_V1),
+    scientificRole: handle,
+    phase: handle,
+    inputRevision: Schema.NullOr(handle),
+    outputRevision: Schema.NullOr(handle),
+    acceptedEvidenceDigest: digest,
+    previousFingerprint: Schema.NullOr(AgenticProgressFingerprintV1),
+    resultingFingerprint: AgenticProgressFingerprintV1,
+    acceptedEvidenceAdded: list(handle, 128),
+    acceptedEvidenceRemoved: list(handle, 128),
+    gatesCompleted: list(handle, 64),
+    gatesInvalidated: list(handle, 64),
+    sameFingerprintCount: integer(),
+    consumption: struct({
+        wallTimeMs: integer(),
+        receivedCalls: integer(),
+        spendKnownUsd: decimal,
+        spendUnknown: Schema.Boolean
+    }),
+    remaining: scientificBudgetRemaining,
+    recordedAt: timestamp
+}).pipe(Schema.check(Schema.makeFilter((value) => value.acceptedEvidenceDigest === value.resultingFingerprint.acceptedEvidenceDigest
+    ? undefined
+    : "receipt evidence digest must equal resulting fingerprint")));
+export const decodeAgenticScientificProgressReceiptV1 = Schema.decodeUnknownSync(AgenticScientificProgressReceiptV1);
+/** Privacy-safe sequence evidence returned at the control error boundary. */
+export const AgenticScientificProgressSequenceDiagnosticV1 = struct({
+    accepted: Schema.Boolean,
+    previousFingerprintPresent: Schema.Boolean,
+    previousFingerprintComponentsMatch: struct({
+        acceptedEvidence: Schema.Boolean,
+        completedGates: Schema.Boolean,
+        environment: Schema.Boolean
+    }),
+    resultingFingerprintUnchanged: Schema.Boolean,
+    previousCapability: Schema.Literals(AGENTIC_CAPABILITY_NAMES_V1),
+    receivedCapability: Schema.Literals(AGENTIC_CAPABILITY_NAMES_V1),
+    capabilityContinued: Schema.Boolean,
+    expectedSameFingerprintCount: integer(),
+    receivedSameFingerprintCount: integer()
+});
+export const decodeAgenticScientificProgressSequenceDiagnosticV1 = Schema.decodeUnknownSync(AgenticScientificProgressSequenceDiagnosticV1);
+export const AgenticCapabilityReconciliationV1 = struct({
+    kind: Schema.Literals([
+        "applied",
+        "already_applied",
+        "scientific_progress_stale",
+        "scientific_progress_conflict"
+    ]),
+    latestProgressReceipt: Schema.NullOr(handle),
+    recoveryAction: Schema.Literals(["continue", "get_progress", "stop"])
+});
+export const decodeAgenticCapabilityReconciliationV1 = Schema.decodeUnknownSync(AgenticCapabilityReconciliationV1);
+/**
+ * Bounded Sandbox-to-Cloud settlement for an admitted capability that failed
+ * before it could produce a normal scientific receipt. This closes known
+ * local failures immediately while preserving genuinely ambiguous external
+ * effects as uncertain.
+ */
+export const AgenticCapabilityExecutionFailureV1 = struct({
+    classification: Schema.Literals([
+        "deterministic_local",
+        "external_outcome_unknown",
+        "cancelled"
+    ]),
+    code: handle
+});
+export const decodeAgenticCapabilityExecutionFailureV1 = Schema.decodeUnknownSync(AgenticCapabilityExecutionFailureV1);
+export const AgenticCapabilityResultV1 = struct({
+    outcome: Schema.Literals([
+        "completed",
+        "progress",
+        "environment_blocked",
+        "scientific_rejection",
+        "budget_exhausted",
+        "cancelled",
+        "infrastructure_uncertain"
+    ]),
+    operation: handle,
+    inputDigest: digest,
+    candidateRevision: Schema.optionalKey(handle),
+    accepted: list(handle),
+    evidenceSummary: boundedText(8192),
+    gradeExecuted: Schema.optionalKey(Schema.Boolean),
+    diagnostics: Schema.optionalKey(handle),
+    logCursor: Schema.optionalKey(handle),
+    pendingJob: Schema.optionalKey(handle),
+    exhaustionScope: Schema.optionalKey(Schema.Literals([
+        "campaign",
+        "execution_epoch_orchestration",
+        "scientific_role"
+    ])),
+    progressReceipt: Schema.optionalKey(AgenticScientificProgressReceiptV1),
+    reconciliation: Schema.optionalKey(AgenticCapabilityReconciliationV1),
+    usage: struct({ receivedCalls: integer(), spendKnownUsd: decimal, spendUnknown: Schema.Boolean }),
+    allowedNext: list(Schema.Literals(AGENTIC_CAPABILITY_NAMES_V1), AGENTIC_CAPABILITY_NAMES_V1.length)
+})
+    .pipe(Schema.check(Schema.makeFilter((value) => {
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
+        return "model-facing result exceeds 64 KiB";
+    if (value.outcome === "environment_blocked" && value.gradeExecuted !== false)
+        return "environment blockage must explicitly report gradeExecuted=false";
+    return undefined;
+})))
+    .annotate({ parseOptions: { onExcessProperty: "error" } });
+export const decodeAgenticCapabilityResultV1 = Schema.decodeUnknownSync(AgenticCapabilityResultV1);
+export const AgenticEnvironmentPlanV1 = struct({
+    version: Schema.Literal(1),
+    planId: handle,
+    candidate: handle,
+    revision: handle,
+    sourceDigest: digest,
+    commitSha: Schema.String.pipe(Schema.check(Schema.makeFilter((value) => /^[a-f0-9]{40}$/u.test(value) ? undefined : "invalid commit SHA"))),
+    recipeIds: list(handle, 32, 1),
+    executionMode: Schema.Literals(["source", "emitted", "repository-default"]),
+    targetRoots: list(packageRoot, 32, 1),
+    // A root-scoped test command can legitimately require the repository's
+    // project-reference graph; keep it bounded without rejecting a 36-package
+    // TypeScript workspace before any scientific command can run.
+    dependencyClosure: list(packageRoot, 64),
+    requiredArtifacts: list(path),
+    lockfileDigest: Schema.NullOr(digest),
+    packageManager: Schema.NullOr(struct({ name: handle, version: handle })),
+    runtime: struct({ name: handle, version: handle, platform: handle, architecture: handle }),
+    commands: list(struct({
+        id: handle,
+        purpose: Schema.Literals(["install", "build", "generate", "probe", "grade"]),
+        executable: boundedText(4096, true),
+        args: list(boundedText(4096), 128),
+        cwd: Schema.NullOr(path),
+        timeoutMs: integer(600_000, 1)
+    }), 64),
+    expectedCost: struct({ wallTimeMs: integer(), spendUsd: Schema.NullOr(decimal) }),
+    justification: boundedText(4096, true),
+    justificationEvidence: list(handle)
+});
+export const decodeAgenticEnvironmentPlanV1 = Schema.decodeUnknownSync(AgenticEnvironmentPlanV1);
+export const AgenticScientificInputsV1 = struct({
+    sourceDigest: digest,
+    environmentDigest: digest,
+    specificationDigest: digest,
+    oracleDigest: digest,
+    controlsDigest: digest,
+    policyDigest: digest,
+    modelPlanDigest: digest
+});
+const NON_SCIENTIFIC_EVIDENCE_KINDS = new Set([
+    "budget_exhaustion", "diagnostics", "message", "model_call", "progress_receipt",
+    "qualification_progress", "continuation_progress", "read", "scorecard", "scientific_checkpoint"
+]);
+export const makeAgenticProgressFingerprintV1 = (input) => {
+    // Continuations are accepted state, but not completed scientific evidence.
+    // Derive both components from the artifact set carried by receipt deltas.
+    const continuations = input.acceptedEvidence
+        .filter((entry) => entry.kind === "qualification_progress" || entry.kind === "continuation_progress")
+        .map(({ kind, contentDigest }) => ({ kind, contentDigest }))
+        .sort((left, right) => left.contentDigest.localeCompare(right.contentDigest));
+    const continuationProgressDigest = input.continuationProgressDigest === undefined
+        ? continuations.length === 0 ? null : agenticDigestV1(continuations)
+        : input.continuationProgressDigest;
+    return decodeAgenticProgressFingerprintV1({
+        version: 1,
+        acceptedEvidenceDigest: agenticDigestV1([
+            ...new Map(input.acceptedEvidence
+                .filter((entry) => !NON_SCIENTIFIC_EVIDENCE_KINDS.has(entry.kind))
+                .map(({ contentDigest, kind }) => {
+                const accepted = {
+                    contentDigest: Schema.decodeUnknownSync(digest)(contentDigest),
+                    kind: Schema.decodeUnknownSync(handle)(kind)
+                };
+                return [`${accepted.kind}:${accepted.contentDigest}`, accepted];
+            })).values()
+        ].sort((left, right) => `${left.kind}:${left.contentDigest}`.localeCompare(`${right.kind}:${right.contentDigest}`))),
+        completedGateDigest: agenticDigestV1([...input.completedGates]
+            .map((gate) => Schema.decodeUnknownSync(handle)(gate))
+            .sort((left, right) => left.localeCompare(right))),
+        environmentDigest: input.environmentDigest === null
+            ? null
+            : Schema.decodeUnknownSync(digest)(input.environmentDigest),
+        continuationProgressDigest: continuationProgressDigest === null
+            ? null
+            : Schema.decodeUnknownSync(digest)(continuationProgressDigest)
+    });
+};
+const candidateFields = {
+    version: Schema.Literal(1),
+    candidate: handle,
+    revision: handle,
+    coverageCell: handle,
+    sourceDigest: digest,
+    proposal: handle,
+    createdAt: timestamp
+};
+const qualifiedFields = { ...candidateFields, environment: handle, referenceQualification: handle };
+const frozenFields = {
+    ...qualifiedFields,
+    specification: handle,
+    oracle: handle,
+    controls: list(handle, 32, 1),
+    tournament: handle,
+    inputs: AgenticScientificInputsV1,
+    frozenAt: timestamp
+};
+export const AgenticCandidateV1 = Schema.Union([
+    struct({ ...candidateFields, state: Schema.Literal("draft") }),
+    struct({
+        ...candidateFields,
+        state: Schema.Literal("probed"),
+        environment: handle,
+        observation: handle,
+        gradeExecuted: Schema.Boolean
+    }),
+    struct({ ...qualifiedFields, state: Schema.Literal("reference_qualified") }),
+    struct({ ...frozenFields, state: Schema.Literal("frozen") }),
+    struct({
+        ...frozenFields,
+        state: Schema.Literal("admitted"),
+        challenge: handle,
+        admission: handle
+    }),
+    struct({
+        ...candidateFields,
+        state: Schema.Literal("superseded"),
+        reason: boundedText(4096, true),
+        replacementRevision: handle,
+        evidence: list(handle)
+    }),
+    struct({
+        ...candidateFields,
+        state: Schema.Literal("rejected"),
+        reason: boundedText(4096, true),
+        evidence: list(handle)
+    })
+]);
+export const decodeAgenticCandidateV1 = Schema.decodeUnknownSync(AgenticCandidateV1);
+export const AgenticAcceptedArtifactV1 = struct({
+    handle,
+    candidate: handle,
+    revision: handle,
+    contentDigest: digest,
+    kind: Schema.Literals([
+        "proposal",
+        "specification",
+        "environment",
+        "fixture",
+        "observation",
+        "reference_qualification",
+        "oracle",
+        "valid_controls",
+        "wrong_controls",
+        "tournament",
+        "frozen_candidate",
+        "held_out_challenge",
+        "admission",
+        "diagnostics"
+    ]),
+    state: Schema.Literals([
+        "draft",
+        "probed",
+        "reference_qualified",
+        "frozen",
+        "admitted",
+        "superseded",
+        "rejected"
+    ]),
+    dependencies: struct({
+        sourceDigest: Schema.optionalKey(digest),
+        environmentDigest: Schema.optionalKey(digest),
+        specificationDigest: Schema.optionalKey(digest),
+        oracleDigest: Schema.optionalKey(digest),
+        controlsDigest: Schema.optionalKey(digest),
+        policyDigest: Schema.optionalKey(digest),
+        modelPlanDigest: Schema.optionalKey(digest)
+    }),
+    gradeExecuted: Schema.optionalKey(Schema.Boolean),
+    fresh: Schema.optionalKey(Schema.Boolean)
+});
+export const decodeAgenticAcceptedArtifactV1 = Schema.decodeUnknownSync(AgenticAcceptedArtifactV1);
+const measurement = struct({
+    passed: integer(),
+    failed: integer(),
+    missing: integer(),
+    evidence: list(handle)
+});
+export const AgenticQualityScorecardV1 = struct({
+    version: Schema.Literal(1),
+    candidate: handle,
+    revision: handle,
+    reference: measurement,
+    validControls: measurement,
+    wrongControls: measurement,
+    heldOut: measurement,
+    coverage: list(struct({ cell: handle, observed: Schema.Boolean, evidence: list(handle) }), 128),
+    disposition: Schema.Literals([
+        "draft",
+        "environment_blocked",
+        "qualified",
+        "rejected",
+        "admitted",
+        "exhausted"
+    ]),
+    reasons: list(boundedText(4096, true)),
+    missingEvidence: list(handle),
+    usage: struct({
+        elapsedMs: integer(),
+        receivedCalls: integer(),
+        spendKnownUsd: decimal,
+        spendUnknown: Schema.Boolean
+    }),
+    admission: Schema.NullOr(handle)
+})
+    .pipe(Schema.check(Schema.makeFilter((value) => {
+    if (value.disposition !== "admitted")
+        return value.admission === null
+            ? undefined
+            : "only admitted scorecards have an admission receipt";
+    if (value.admission === null || value.missingEvidence.length > 0)
+        return "admission requires a receipt and complete evidence";
+    for (const measurement of [
+        value.reference,
+        value.validControls,
+        value.wrongControls,
+        value.heldOut
+    ]) {
+        if (measurement.passed === 0 ||
+            measurement.missing > 0 ||
+            measurement.evidence.length === 0)
+            return "admission requires measured reference, controls and held-out evidence";
+    }
+    return undefined;
+})))
+    .annotate({ parseOptions: { onExcessProperty: "error" } });
+export const decodeAgenticQualityScorecardV1 = Schema.decodeUnknownSync(AgenticQualityScorecardV1);
+/** Existing V2 canonical digest: path-independent and stable across object key ordering. */
+export const agenticDigestV1 = pipelineDigestV2;
+/** Deliberately excludes transport tool-call IDs, attempt epoch, deadlines and reservations. */
+export const agenticSemanticOperationDigestV1 = (input) => agenticDigestV1({
+    orgId: Schema.decodeUnknownSync(handle)(input.orgId),
+    campaignId: Schema.decodeUnknownSync(handle)(input.campaignId),
+    candidateRevision: input.candidateRevision === undefined
+        ? undefined
+        : Schema.decodeUnknownSync(handle)(input.candidateRevision),
+    toolBundleDigest: Schema.decodeUnknownSync(digest)(input.toolBundleDigest),
+    request: decodeAgenticCapabilityRequestV1(input.request)
+});
+/** Conservative invalidation: every recorded dependency must still match. */
+export const assertAgenticEvidenceInputsV1 = (artifactValue, current) => {
+    const artifact = decodeAgenticAcceptedArtifactV1(artifactValue);
+    const sourceOnly = ["sourceDigest"];
+    const executable = ["sourceDigest", "environmentDigest"];
+    const authored = ["sourceDigest", "policyDigest", "modelPlanDigest"];
+    const qualified = [
+        "sourceDigest",
+        "environmentDigest",
+        "policyDigest",
+        "modelPlanDigest"
+    ];
+    const oracle = [...qualified, "specificationDigest"];
+    const full = [...oracle, "oracleDigest", "controlsDigest"];
+    const required = {
+        proposal: sourceOnly,
+        specification: authored,
+        environment: sourceOnly,
+        fixture: sourceOnly,
+        observation: executable,
+        reference_qualification: qualified,
+        oracle,
+        valid_controls: oracle,
+        wrong_controls: oracle,
+        tournament: full,
+        frozen_candidate: full,
+        held_out_challenge: full,
+        admission: full,
+        diagnostics: sourceOnly
+    };
+    for (const key of required[artifact.kind]) {
+        if (artifact.dependencies[key] === undefined)
+            throw new Error(`scientific evidence is missing dependency: ${key}`);
+    }
+    for (const [key, value] of Object.entries(artifact.dependencies)) {
+        if (current[key] !== value)
+            throw new Error(`stale scientific evidence: ${key}`);
+    }
+};
+/** The caller passes host-resolved records, never model-provided checkpoint objects. */
+export const assertAgenticArtifactPrerequisitesV1 = (input) => {
+    if (input.handles.length === 0)
+        throw new Error("scientific prerequisites require accepted evidence");
+    const records = input.accepted.map((value) => decodeAgenticAcceptedArtifactV1(value));
+    if (new Set(records.map((entry) => entry.handle)).size !== records.length)
+        throw new Error("conflicting accepted handle records");
+    if (new Set(input.handles).size !== input.handles.length)
+        throw new Error("duplicate prerequisite handles");
+    for (const requested of input.handles) {
+        const artifact = records.find((entry) => entry.handle === requested);
+        if (!artifact || artifact.candidate !== input.candidate || artifact.revision !== input.revision)
+            throw new Error("unaccepted or mismatched candidate revision handle");
+        if (artifact.state === "superseded" || artifact.state === "rejected")
+            throw new Error("retired evidence cannot satisfy prerequisites");
+        if (input.kinds && !input.kinds.includes(artifact.kind))
+            throw new Error("incorrect prerequisite artifact kind");
+        if (input.states && !input.states.includes(artifact.state))
+            throw new Error("incorrect prerequisite artifact state");
+        if (input.requireGrade && artifact.gradeExecuted !== true)
+            throw new Error("preparation is not an executed grade");
+        if (input.requireFresh && artifact.fresh !== true)
+            throw new Error("development evidence is not a fresh challenge");
+        assertAgenticEvidenceInputsV1(artifact, input.inputs);
+    }
+};
+/** State transitions validate evidence references; scientific services still decide the verdict. */
+export const assertAgenticCandidateTransitionV1 = (previousValue, nextValue, accepted, currentInputs = {}) => {
+    const previous = decodeAgenticCandidateV1(previousValue);
+    const next = decodeAgenticCandidateV1(nextValue);
+    for (const field of [
+        "candidate",
+        "revision",
+        "coverageCell",
+        "sourceDigest",
+        "proposal",
+        "createdAt"
+    ]) {
+        if (previous[field] !== next[field])
+            throw new Error(`immutable candidate field changed: ${field}`);
+    }
+    if (previous.state === next.state && agenticDigestV1(previous) === agenticDigestV1(next))
+        return;
+    const transitions = {
+        draft: ["probed", "reference_qualified", "rejected", "superseded"],
+        probed: ["reference_qualified", "rejected", "superseded"],
+        reference_qualified: ["frozen", "rejected", "superseded"],
+        frozen: ["admitted", "rejected", "superseded"],
+        admitted: [],
+        rejected: [],
+        superseded: []
+    };
+    if (!transitions[previous.state].includes(next.state))
+        throw new Error("invalid candidate state transition");
+    const inputs = "inputs" in next ? next.inputs : { ...currentInputs, sourceDigest: next.sourceDigest };
+    const requireArtifact = (requested, kinds, requireGrade = false, requireFresh = false) => assertAgenticArtifactPrerequisitesV1({
+        candidate: next.candidate,
+        revision: next.revision,
+        handles: typeof requested === "string" ? [requested] : requested,
+        accepted,
+        kinds,
+        inputs,
+        states: ["probed", "reference_qualified", "frozen", "admitted"],
+        requireGrade,
+        requireFresh
+    });
+    if (next.state === "probed") {
+        requireArtifact(next.observation, ["observation"]);
+        const observation = accepted.find((entry) => entry.handle === next.observation);
+        if (observation?.gradeExecuted !== next.gradeExecuted)
+            throw new Error("probe grade flag does not match observation");
+    }
+    if ("referenceQualification" in next) {
+        requireArtifact(next.environment, ["environment"]);
+        requireArtifact(next.referenceQualification, ["reference_qualification"], true);
+    }
+    if ("inputs" in next) {
+        if (next.sourceDigest !== next.inputs.sourceDigest)
+            throw new Error("frozen source identity differs from candidate");
+        requireArtifact(next.specification, ["specification"]);
+        requireArtifact(next.environment, ["environment"]);
+        requireArtifact(next.oracle, ["oracle"]);
+        for (const [requested, expected] of [
+            [next.specification, next.inputs.specificationDigest],
+            [next.environment, next.inputs.environmentDigest],
+            [next.oracle, next.inputs.oracleDigest]
+        ]) {
+            if (accepted.find((entry) => entry.handle === requested)?.contentDigest !== expected)
+                throw new Error("frozen artifact digest does not match scientific inputs");
+        }
+        requireArtifact(next.controls, ["valid_controls", "wrong_controls"], true);
+        const kinds = new Set(accepted.filter((entry) => next.controls.includes(entry.handle)).map((entry) => entry.kind));
+        if (!kinds.has("valid_controls") || !kinds.has("wrong_controls"))
+            throw new Error("freeze requires valid and wrong controls");
+        requireArtifact(next.tournament, ["tournament"], true);
+    }
+    if (next.state === "admitted") {
+        if (previous.state !== "frozen" ||
+            agenticDigestV1(previous.inputs) !== agenticDigestV1(next.inputs))
+            throw new Error("admission must preserve frozen scientific inputs");
+        for (const field of [
+            "environment",
+            "referenceQualification",
+            "specification",
+            "oracle",
+            "controls",
+            "tournament",
+            "frozenAt"
+        ]) {
+            if (agenticDigestV1(previous[field]) !== agenticDigestV1(next[field]))
+                throw new Error(`frozen artifact binding changed: ${field}`);
+        }
+        requireArtifact(next.challenge, ["held_out_challenge"], true, true);
+        requireArtifact(next.admission, ["admission"], true);
+    }
+};