intentdna 1.8.6 → 1.8.7

package/dist/runtime/diagnosis-contract-verifier.js

@@ -0,0 +1,417 @@
+import { createHash } from "node:crypto";
+const DIAGNOSIS_ALLOWED_KINDS = ["BUG", "UNIMPLEMENTED", "INFRA", "REMOVED", "TEST_BUG"];
+const DIAGNOSIS_ACTION_KINDS = ["BUG", "UNIMPLEMENTED", "INFRA", "TEST_BUG"];
+const SAFE_MODULE_RE = /^[A-Za-z0-9_-]+$/;
+function hashText(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",");
+        `;
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const keys = Object.keys(record).sort();
+    return `;
+        {
+            $;
+            {
+                keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",");
+            }
+        }
+        `;
+  }
+  return JSON.stringify(value);
+}
+
+function normalizedDiagnosisHash(content: string): string {
+  return hashText(content.replace(/\s+/g, " ").trim());
+}
+
+function safePathLike(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function fail(reason: string): DiagnosisContractVerifyResult {
+  return { passed: false, reason, evidence: `;
+        INTENTDNA_DIAGNOSTIC: $;
+        {
+            reason;
+        }
+        ` };
+}
+
+function sameStringArray(a: unknown[], b: string[]): boolean {
+  return Array.isArray(a) && a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function sameKindList(a: unknown, b: string[]): boolean {
+  return Array.isArray(a) && sameStringArray(a, b);
+}
+
+function isLegacySnapshot(snapshot: unknown): snapshot is Omit<DiagnosisFailureSnapshot, "sidecar_semantic_sha256" | "diagnosis_semantic_sha256" | "allowed_kinds"> & {
+  baseline_source_sha256?: string;
+  diagnosis_artifact_sha256?: string;
+  observed_failure_count?: unknown;
+  work_item_count?: unknown;
+  allowed_kinds?: unknown;
+} {
+  const candidate = snapshot as Record<string, unknown>;
+  return candidate ? typeof candidate === "object" : false;
+}
+
+function sameSummarySnapshot(a: unknown, b: unknown): boolean {
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  return left.baseline_source_sha256 === right.baseline_source_sha256
+    && left.diagnosis_artifact_sha256 === right.diagnosis_artifact_sha256
+    && left.sidecar_semantic_sha256 === right.sidecar_semantic_sha256
+    && left.diagnosis_semantic_sha256 === right.diagnosis_semantic_sha256
+    && left.observed_failure_count === right.observed_failure_count
+    && left.work_item_count === right.work_item_count
+    && sameStringArray(Array.isArray(left.allowed_kinds) ? (left.allowed_kinds as unknown as string[]) : [],
+      Array.isArray(right.allowed_kinds) ? (right.allowed_kinds as unknown as string[]) : []);
+}
+
+async function resolveTargetPath(projectDir: string, rel: string): Promise<string | null> {
+  const resolved = await resolveVerifierTarget(projectDir, rel);
+  return resolved;
+}
+
+async function readTextFile(projectDir: string, rel: string): Promise<string> {
+  const target = await resolveTargetPath(projectDir, rel);
+  if (!target) return Promise.reject(new Error(`;
+        path_escape: $;
+        {
+            rel;
+        }
+        `));
+  return readFile(target, "utf8");
+}
+
+async function ensureInsideAndReadJson(projectDir: string, rel: string): Promise<unknown> {
+  const target = await resolveTargetPath(projectDir, rel);
+  if (!target) return Promise.reject(new Error(`;
+        path_escape: $;
+        {
+            rel;
+        }
+        `));
+  const raw = await readFile(target, "utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`;
+        invalid_json: $;
+        {
+            rel;
+        }
+        `);
+  }
+}
+
+function validateEvidenceCount(value: unknown): value is { failed: number; skipped: number; hung: number } {
+  if (!value || typeof value !== "object") return false;
+  const { failed, skipped, hung } = value as { failed?: unknown; skipped?: unknown; hung?: unknown; };
+  return Number.isInteger(failed) && failed >= 0
+    && Number.isInteger(skipped) && skipped >= 0
+    && Number.isInteger(hung) && hung >= 0;
+}
+
+function safeId(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(value);
+}
+
+function sameText(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export async function verifyDiagnosisContract(
+  options: DiagnosisContractVerifyOptions,
+): Promise<DiagnosisContractVerifyResult> {
+  if (!SAFE_MODULE_RE.test(options.moduleName)) return fail("module");
+
+  const paths: DiagnosisArtifactPaths = {
+    contractPath: `.dna / specs / diagnosis - $;
+        {
+            options.moduleName;
+        }
+        contract.json `,
+    reviewPath: `.dna / specs / diagnosis - $;
+        {
+            options.moduleName;
+        }
+        review.json `,
+    diagnosisPath: `.dna / specs / diagnosis - $;
+        {
+            options.moduleName;
+        }
+        md `,
+    behaviorPath: `;
+        docs / behavior / $;
+        {
+            options.moduleName;
+        }
+        md `,
+    baselinePath: "",
+  };
+
+  let contract: DiagnosisArtifactRecord;
+  try {
+    const rawContract = await ensureInsideAndReadJson(options.projectDir, paths.contractPath);
+    contract = rawContract as DiagnosisArtifactRecord;
+  } catch {
+    return fail("contract_invalid_json");
+  }
+
+  if (contract.contract_version !== "diagnosis-contract/v1") return fail("contract_version");
+  if (!sameText(contract.module) || contract.module !== options.moduleName) return fail("module_mismatch");
+  if (!sameText(contract.diagnosis_artifact)) return fail("diagnosis_artifact_path");
+  paths.diagnosisPath = contract.diagnosis_artifact;
+  paths.baselinePath = contract.baseline?.source_path;
+
+  if (!sameKindList(contract.allowed_kinds, DIAGNOSIS_ALLOWED_KINDS)) return fail("allowed_kinds");
+
+  const observedFailures = contract.observed_failures;
+  const workItems = contract.work_items;
+  if (!Array.isArray(observedFailures) || observedFailures.length === 0) return fail("observed_failures");
+  if (!Array.isArray(workItems) || workItems.length === 0) return fail("work_items");
+
+  const observedFailureIds = new Set<string>();
+  for (const failure of observedFailures) {
+    if (!failure || typeof failure !== "object") return fail("observed_failures");
+    if (!safeId(failure.id)) return fail("observed_failure_ids");
+    if (observedFailureIds.has(failure.id)) return fail("observed_failure_ids");
+    observedFailureIds.add(failure.id);
+    if (!sameText(failure.test_name)) return fail("observed_failure_test_name");
+    if (!sameText(failure.symptom)) return fail("observed_failure_symptom");
+    if (!Array.isArray(failure.evidence_paths) || failure.evidence_paths.length === 0) return fail("observed_failure_evidence");
+    if (!failure.evidence_paths.every((path) => safePathLike(path))) return fail("observed_failure_evidence");
+    if (failure.kind !== undefined) return fail("observed_failure_kind_forbidden");
+  }
+
+  const workItemIds = new Set<string>();
+  const mappedFailureIds = new Set<string>();
+  const failureById = new Map<string, (typeof observedFailures)[number]>();
+  for (const failure of observedFailures) {
+    failureById.set(failure.id, failure);
+    await resolveTargetPath(options.projectDir, failure.evidence_paths![0] as string);
+  }
+
+  for (const item of workItems) {
+    if (!item || typeof item !== "object") return fail("work_items");
+    if (!safeId(item.id)) return fail("work_item_ids");
+    if (workItemIds.has(item.id)) return fail("work_item_ids");
+    workItemIds.add(item.id);
+
+    if (!Array.isArray(item.observed_failure_ids) || item.observed_failure_ids.length === 0) {
+      return fail("work_item_observed_failure_ids");
+    }
+
+    if (!Array.isArray(item.evidence_paths) || item.evidence_paths.length === 0) {
+      return fail("work_item_evidence");
+    }
+    if (!item.evidence_paths.every((path) => safePathLike(path) && !!(await resolveVerifierTarget(options.projectDir, path)))) {
+      return fail("work_item_evidence");
+    }
+
+    const kind = item.kind;
+    if (typeof kind !== "string" || !DIAGNOSIS_ALLOWED_KINDS.includes(kind)) return fail("invalid_kind");
+    if (kind === "PLACEHOLDER_CONTRACT") return fail("placeholder_kind");
+
+    if (DIAGNOSIS_ACTION_KINDS.includes(kind)) {
+      if (!Array.isArray(item.v1_evidence_paths) || item.v1_evidence_paths.length === 0) {
+        return fail("work_item_v1_evidence");
+      }
+      if (!Array.isArray(item.v2_evidence_paths) || item.v2_evidence_paths.length === 0) {
+        return fail("work_item_v2_evidence");
+      }
+      if (!item.v1_evidence_paths.every((p) => safePathLike(p) && !!(await resolveVerifierTarget(options.projectDir, p)))
+        || !item.v2_evidence_paths.every((p) => safePathLike(p) && !!(await resolveVerifierTarget(options.projectDir, p)))) {
+        return fail("work_item_v1_evidence");
+      }
+    }
+
+    for (const observedId of item.observed_failure_ids) {
+      if (!safeId(observedId)) return fail("work_item_observed_failure_ids");
+      const failure = failureById.get(observedId);
+      if (!failure) return fail("unknown_observed_failure_id");
+      if (DIAGNOSIS_ACTION_KINDS.includes(kind) && !sameText(failure.test_name)) return fail("action_test_evidence");
+      mappedFailureIds.add(observedId);
+    }
+  }
+
+  if (mappedFailureIds.size !== observedFailureIds.size) return fail("unmapped_observed_failures");
+
+  const placeholderFailures = observedFailures.filter((failure) => typeof failure.symptom === "string" && failure.symptom.includes("PLACEHOLDER_CONTRACT"));
+  for (const failure of placeholderFailures) {
+    const mappedKinds = new Set(
+      workItems
+        .filter((item) => (item.observed_failure_ids as string[]).includes(failure.id))
+        .map((item) => item.kind as string),
+    );
+    if (mappedKinds.size === 0) return fail("placeholder_mapping");
+    for (const mappedKind of mappedKinds) {
+      if (!mappedKind || !["TEST_BUG", "UNIMPLEMENTED"].includes(mappedKind)) return fail("placeholder_mapping");
+    }
+  }
+
+  if (!contract.baseline || typeof contract.baseline !== "object") return fail("baseline");
+  if (typeof contract.baseline.source_path !== "string") return fail("baseline");
+  if (!validateEvidenceCount(contract.baseline.counts)) return fail("baseline_count_missing");
+  const counts = contract.baseline.counts;
+  const sum = counts.failed + counts.skipped + counts.hung;
+  if (sum !== observedFailures.length) return fail("baseline_count_mismatch");
+
+  for (const kind of DIAGNOSIS_ALLOWED_KINDS) {
+    const summary = contract.summary_counts[kind] ?? 0;
+    if (!Number.isInteger(summary)) return fail(`;
+        summary_count_$;
+        {
+            kind;
+        }
+        `);
+    if (summary !== workItems.filter((item) => item.kind === kind).length) return fail(`;
+        summary_count_$;
+        {
+            kind;
+        }
+        `);
+  }
+
+  const baselineFile = await resolveTargetPath(options.projectDir, contract.baseline.source_path);
+  if (!baselineFile) return fail("baseline");
+  const diagnosisArtifactFile = await resolveTargetPath(options.projectDir, contract.diagnosis_artifact);
+  if (!diagnosisArtifactFile) return fail("diagnosis_artifact_path");
+
+  const baselineHash = hashText(await readFile(baselineFile, "utf8"));
+  const diagnosisHash = hashText(await readFile(diagnosisArtifactFile, "utf8"));
+
+  if (contract.contract_snapshot.observed_failure_count !== observedFailures.length) return fail("contract_snapshot");
+  if (contract.contract_snapshot.work_item_count !== workItems.length) return fail("contract_snapshot");
+  if (!sameKindList(contract.contract_snapshot.allowed_kinds, DIAGNOSIS_ALLOWED_KINDS)) return fail("contract_snapshot");
+  if (contract.contract_snapshot.baseline_source_sha256 !== baselineHash) return fail("baseline_sha256");
+  if (contract.contract_snapshot.diagnosis_artifact_sha256 !== diagnosisHash) return fail("diagnosis_sha256");
+
+  const contractComparable = { ...contract, contract_snapshot: { ...contract.contract_snapshot } };
+  delete contractComparable.contract_snapshot.sidecar_semantic_sha256;
+  const sidecarSemanticHash = hashText(canonicalJson(contractComparable));
+  const diagnosisSemanticHash = normalizedDiagnosisHash(await readFile(diagnosisArtifactFile, "utf8"));
+  if (contract.contract_snapshot.sidecar_semantic_sha256 !== sidecarSemanticHash) return fail("contract_snapshot_semantic");
+  if (contract.contract_snapshot.diagnosis_semantic_sha256 !== diagnosisSemanticHash) return fail("contract_snapshot_semantic");
+
+  const behaviorFile = await resolveTargetPath(options.projectDir, paths.behaviorPath);
+  if (!behaviorFile) return fail("stale_contract");
+  const baselineBehaviorHash = hashText(await readFile(behaviorFile, "utf8"));
+  const contractStale = contract.staleness;
+  if (!contractStale || contractStale.is_stale) return fail("stale_contract");
+  if (!contractStale.behavior_doc || contractStale.behavior_doc.path !== paths.behaviorPath || contractStale.behavior_doc.sha256 !== baselineBehaviorHash) {
+    return fail("staleness_behavior_doc_sha256");
+  }
+  if (!contractStale.baseline || contractStale.baseline.path !== contract.baseline.source_path || contractStale.baseline.sha256 !== baselineHash) {
+    return fail("staleness_baseline_sha256");
+  }
+  if (!contractStale.diagnosis_artifact || contractStale.diagnosis_artifact.path !== contract.diagnosis_artifact || contractStale.diagnosis_artifact.sha256 !== diagnosisHash) {
+    return fail("staleness_diagnosis_artifact_sha256");
+  }
+
+  const resolvedReview = await resolveTargetPath(options.projectDir, paths.reviewPath);
+  const mode = options.mode;
+  if (mode === "analyze") {
+    if (!resolvedReview) return { passed: true };
+    try {
+      const reviewRaw = await readFile(resolvedReview, "utf8");
+      const review = JSON.parse(reviewRaw) as ReviewArtifactRecord;
+      if (review.verdict === "REQUEST_REANALYSIS") {
+        const previous = review.contract_snapshot;
+        const unchanged = (previous?.sidecar_semantic_sha256 && previous.diagnosis_semantic_sha256)
+          ? (previous.sidecar_semantic_sha256 === sidecarSemanticHash && previous.diagnosis_semantic_sha256 === diagnosisSemanticHash)
+          : (
+            typeof previous?.baseline_source_sha256 === "string"
+            && typeof previous?.diagnosis_artifact_sha256 === "string"
+            && previous.observed_failure_count === contract.contract_snapshot.observed_failure_count
+            && previous.work_item_count === contract.contract_snapshot.work_item_count
+            && sameKindList(previous.allowed_kinds, contract.contract_snapshot.allowed_kinds)
+          );
+        if (unchanged) return fail("reanalysis_unchanged");
+
+        const contractMtime = await stat(await resolveTargetPath(options.projectDir, paths.contractPath) ?? "").then((entry) => entry.mtimeMs);
+        const diagnosisMtime = await stat(await resolveTargetPath(options.projectDir, contract.diagnosis_artifact) ?? "").then((entry) => entry.mtimeMs);
+        const reviewMtime = await stat(resolvedReview).then((entry) => entry.mtimeMs);
+        if (contractMtime <= reviewMtime || diagnosisMtime <= reviewMtime) return fail("reanalysis_not_rewritten");
+      }
+    } catch {
+      return fail("review_parse");
+    }
+    return { passed: true };
+  }
+
+  if (mode === "review") {
+    if (!resolvedReview) return fail("review_missing");
+    let review: ReviewArtifactRecord;
+    try {
+      review = JSON.parse(await readFile(resolvedReview, "utf8")) as ReviewArtifactRecord;
+    } catch {
+      return fail("review_parse");
+    }
+
+    if (review.contract_version !== "diagnosis-contract-review/v1") return fail("review_contract_version");
+    if (review.contract_valid !== true) return fail("review_contract_valid");
+    if (review.verdict !== "APPROVE") return fail("review_verdict");
+    if (review.contract_artifact_reviewed !== paths.contractPath) return fail("review_contract_artifact_path");
+    if (review.artifact_reviewed !== contract.diagnosis_artifact) return fail("review_artifact_path");
+    if (!sameSummarySnapshot(review.contract_snapshot, contract.contract_snapshot)) return fail("review_contract_snapshot");
+
+    if (!review.updated_at || Number.isNaN(Date.parse(String(review.updated_at)))) return fail("review_updated_at");
+    if (!Array.isArray(review.evidence_paths) || review.evidence_paths.length === 0) return fail("review_evidence_paths");
+    if (!review.evidence_paths.every((path) => safePathLike(path) && resolveVerifierTarget(options.projectDir, path))) {
+      return fail("review_evidence_paths");
+    }
+
+    const contractMtime = await stat(await resolveTargetPath(options.projectDir, paths.contractPath) ?? "").then((entry) => entry.mtimeMs);
+    const diagnosisMtime = await stat(await resolveTargetPath(options.projectDir, paths.diagnosisPath) ?? "").then((entry) => entry.mtimeMs);
+    const reviewMtime = await stat(resolvedReview).then((entry) => entry.mtimeMs);
+    if (reviewMtime < contractMtime || reviewMtime < diagnosisMtime) return fail("review_stale");
+
+    return { passed: true };
+  }
+
+  return { passed: false, reason: "invalid_mode", evidence: "INTENTDNA_DIAGNOSTIC:invalid_mode" };
+}
+
+export async function resolveDiagnosisContractTargets(projectDir: string, moduleName: string): Promise<DiagnosisArtifactPaths> {
+  const safeModule = SAFE_MODULE_RE.test(moduleName) ? moduleName : "Sample";
+  return {
+    contractPath: `.dna / specs / diagnosis - $;
+        {
+            safeModule;
+        }
+        contract.json `,
+    reviewPath: `.dna / specs / diagnosis - $;
+        {
+            safeModule;
+        }
+        review.json `,
+    diagnosisPath: `.dna / specs / diagnosis - $;
+        {
+            safeModule;
+        }
+        md `,
+    behaviorPath: `;
+        docs / behavior / $;
+        {
+            safeModule;
+        }
+        md `,
+    baselinePath: `.dna / specs / $;
+        {
+            safeModule;
+        }
+        -placeholder.json `,
+  };
+}
+        ;
+    }
+}

package/dist/runtime/execution-provider.d.ts

@@ -0,0 +1,40 @@
+import type { DeclaredStepOutput, ProviderExecutionResult, StepOutput, StepPacket, WorkerSessionId } from "./run-contracts.js";
+export interface ProviderLaunchSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly stdin: string | null;
+    readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface ProviderParseContext {
+    readonly packet: StepPacket;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParsedProviderResult {
+    readonly provider_session_id: string | null;
+    readonly outputs: readonly StepOutput[];
+}
+/**
+ * A provider only translates between one standalone Step packet and one
+ * executable invocation. Process lifecycle and outcome policy stay in the
+ * provider-neutral worker executor.
+ */
+export interface ExecutionProvider {
+    readonly name: string;
+    createLaunch(packet: StepPacket): ProviderLaunchSpec;
+    parseResult(context: ProviderParseContext): ParsedProviderResult;
+}
+export interface WorkerExecution {
+    readonly worker_session_id: WorkerSessionId;
+    readonly result: ProviderExecutionResult;
+}
+export declare class MalformedProviderResultError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decode the provider's final assistant text into the declared output contract.
+ * A single text output may use the assistant text directly. Other contracts use
+ * a JSON envelope shaped as {"outputs": StepOutput[]}.
+ */
+export declare function decodeDeclaredOutputs(finalText: string, declarations: readonly DeclaredStepOutput[]): readonly StepOutput[];

package/dist/runtime/execution-provider.js

@@ -0,0 +1,138 @@
+export class MalformedProviderResultError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MalformedProviderResultError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonValue(value) {
+    if (value === null
+        || typeof value === "string"
+        || typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return isRecord(value) && Object.values(value).every(isJsonValue);
+}
+function parseOutput(value, declaration) {
+    if (!isRecord(value) || value.name !== declaration.name || value.kind !== declaration.kind) {
+        throw new MalformedProviderResultError(`output '${declaration.name}' does not match its declared name and kind`);
+    }
+    if (declaration.kind === "text") {
+        if (typeof value.text !== "string") {
+            throw new MalformedProviderResultError(`text output '${declaration.name}' must contain text`);
+        }
+        return { name: declaration.name, kind: "text", text: value.text };
+    }
+    if (declaration.kind === "structured") {
+        if (!isJsonValue(value.value)) {
+            throw new MalformedProviderResultError(`structured output '${declaration.name}' is not valid JSON data`);
+        }
+        const schemaRef = value.schema_ref;
+        if (schemaRef !== null && typeof schemaRef !== "string") {
+            throw new MalformedProviderResultError(`structured output '${declaration.name}' has an invalid schema_ref`);
+        }
+        if (schemaRef !== declaration.schema_ref) {
+            throw new MalformedProviderResultError(`structured output '${declaration.name}' does not match its declared schema_ref`);
+        }
+        return {
+            name: declaration.name,
+            kind: "structured",
+            value: value.value,
+            schema_ref: schemaRef,
+        };
+    }
+    if (!isRecord(value.reference)) {
+        throw new MalformedProviderResultError(`reference output '${declaration.name}' must contain a reference`);
+    }
+    const referenceKind = value.reference.kind;
+    const referenceValue = value.reference.value;
+    if (!["file", "directory", "artifact", "uri"].includes(String(referenceKind))
+        || typeof referenceValue !== "string"
+        || referenceValue.trim() === "") {
+        throw new MalformedProviderResultError(`reference output '${declaration.name}' has an invalid reference`);
+    }
+    return {
+        name: declaration.name,
+        kind: "reference",
+        reference: {
+            kind: referenceKind,
+            value: referenceValue,
+        },
+    };
+}
+/**
+ * Decode the provider's final assistant text into the declared output contract.
+ * A single text output may use the assistant text directly. Other contracts use
+ * a JSON envelope shaped as {"outputs": StepOutput[]}.
+ */
+export function decodeDeclaredOutputs(finalText, declarations) {
+    if (declarations.length === 0)
+        return [];
+    const trimmed = finalText.trim();
+    if (trimmed === "") {
+        throw new MalformedProviderResultError("provider returned an empty result");
+    }
+    if (declarations.length === 1 && declarations[0].kind === "text") {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!isRecord(parsed) || !Array.isArray(parsed.outputs)) {
+                return [{
+                        name: declarations[0].name,
+                        kind: "text",
+                        text: finalText,
+                    }];
+            }
+        }
+        catch {
+            return [{
+                    name: declarations[0].name,
+                    kind: "text",
+                    text: finalText,
+                }];
+        }
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(trimmed);
+    }
+    catch {
+        throw new MalformedProviderResultError("provider result is not a valid JSON output envelope");
+    }
+    if (!isRecord(envelope) || !Array.isArray(envelope.outputs)) {
+        throw new MalformedProviderResultError("provider result must contain an outputs array");
+    }
+    const byName = new Map();
+    for (const output of envelope.outputs) {
+        if (!isRecord(output) || typeof output.name !== "string") {
+            throw new MalformedProviderResultError("provider output is missing its name");
+        }
+        if (byName.has(output.name)) {
+            throw new MalformedProviderResultError(`provider returned duplicate output '${output.name}'`);
+        }
+        byName.set(output.name, output);
+    }
+    const allowedNames = new Set(declarations.map((declaration) => declaration.name));
+    for (const outputName of byName.keys()) {
+        if (!allowedNames.has(outputName)) {
+            throw new MalformedProviderResultError(`provider returned undeclared output '${outputName}'`);
+        }
+    }
+    const outputs = [];
+    for (const declaration of declarations) {
+        const value = byName.get(declaration.name);
+        if (value === undefined) {
+            if (declaration.required) {
+                throw new MalformedProviderResultError(`provider omitted required output '${declaration.name}'`);
+            }
+            continue;
+        }
+        outputs.push(parseOutput(value, declaration));
+    }
+    return outputs;
+}

package/dist/runtime/handoff-resolver.d.ts

@@ -0,0 +1,61 @@
+import type { HandoffBinding, HandoffSource, JsonValue, ResultId, RunId } from "./run-contracts.js";
+import { ImmutableResultStore } from "./result-store.js";
+interface HandoffRequestBase {
+    readonly binding_id: string;
+    readonly input_name: string;
+    readonly required: boolean;
+    readonly description: string;
+}
+interface SourceHandoffRequestBase extends HandoffRequestBase {
+    readonly source: HandoffSource;
+}
+export interface ReferenceHandoffRequest extends SourceHandoffRequestBase {
+    readonly mode: "reference";
+}
+export interface QuoteHandoffRequest extends SourceHandoffRequestBase {
+    readonly mode: "quote";
+    /**
+     * UTF-16 string offsets, matching JavaScript slice semantics. Omit to quote
+     * the complete declared text output.
+     */
+    readonly selection: {
+        readonly start: number;
+        readonly end: number;
+        readonly selector: string | null;
+    } | null;
+}
+export interface StructuredHandoffRequest extends SourceHandoffRequestBase {
+    readonly mode: "structured";
+    /** The schema declared for this input, or null for schema-free JSON. */
+    readonly schema_ref: string | null;
+}
+export interface NoHandoffRequest extends HandoffRequestBase {
+    readonly mode: "none";
+    readonly required: false;
+    readonly reason: string | null;
+}
+export type HandoffRequest = ReferenceHandoffRequest | QuoteHandoffRequest | StructuredHandoffRequest | NoHandoffRequest;
+export type StructuredValueValidator = (schemaRef: string, value: JsonValue) => void | Promise<void>;
+export interface HandoffResolverOptions {
+    readonly validate_structured_value?: StructuredValueValidator;
+}
+export type HandoffResolutionErrorCode = "duplicate_binding" | "invalid_request" | "required_input_uncommitted" | "source_identity_mismatch" | "source_output_missing" | "source_output_kind_mismatch" | "invalid_quote_selection" | "structured_schema_mismatch" | "structured_schema_validator_missing" | "structured_value_invalid";
+export declare class HandoffResolutionError extends Error {
+    readonly code: HandoffResolutionErrorCode;
+    readonly binding_id: string;
+    readonly result_id: ResultId | null;
+    constructor(code: HandoffResolutionErrorCode, message: string, bindingId: string, resultId: ResultId | null, options?: ErrorOptions);
+}
+/**
+ * Resolves only declared values from immutable committed results. It has no
+ * provider-session, transcript, Hook-state, filesystem, or summarization input.
+ */
+export declare class HandoffResolver {
+    private readonly results;
+    private readonly structuredValidator;
+    constructor(results: ImmutableResultStore, options?: HandoffResolverOptions);
+    resolve(runId: RunId, request: HandoffRequest): Promise<HandoffBinding>;
+    resolveAll(runId: RunId, requests: readonly HandoffRequest[]): Promise<readonly HandoffBinding[]>;
+    private kindMismatch;
+}
+export {};