intentdna 1.9.0 → 1.9.3

package/dist/runtime/run-binding.d.ts

@@ -0,0 +1,68 @@
+import { type CanonicalJsonValue } from "./canonical-json.js";
+import { type Sha256Digest, type StoredExecutableRunPlan } from "./executable-run-plan.js";
+export declare const RUN_BINDING_SCHEMA_VERSION = "intentdna.run_binding.v1";
+export declare const STORED_RUN_BINDING_SCHEMA_VERSION = "intentdna.stored_run_binding.v1";
+export interface SecretReference {
+    readonly input_name: string;
+    readonly source: "environment" | "file" | "keychain" | "external";
+    readonly reference: string;
+}
+export interface ProviderCredentialReference {
+    readonly name: string;
+    readonly source: "environment" | "file" | "keychain" | "external";
+    readonly reference: string;
+}
+export interface ProviderOptions {
+    readonly reasoning_effort?: "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+    readonly temperature?: number;
+    readonly max_output_tokens?: number;
+    readonly executable?: string;
+    readonly max_budget_usd?: number;
+    readonly permission_mode?: string;
+}
+export interface ProviderConfiguration {
+    readonly provider: string;
+    readonly model: string | null;
+    readonly options: ProviderOptions;
+    readonly credential_references: readonly ProviderCredentialReference[];
+}
+export interface RunBindingPayload {
+    readonly schema_version: typeof RUN_BINDING_SCHEMA_VERSION;
+    readonly plan_id: Sha256Digest;
+    readonly max_concurrency?: number;
+    readonly validated_inputs: Readonly<Record<string, CanonicalJsonValue>>;
+    readonly secret_references: readonly SecretReference[];
+    readonly provider_config: ProviderConfiguration;
+    readonly project_root: string;
+    readonly workspace_root: string;
+}
+export interface StoredRunBinding {
+    readonly schema_version: typeof STORED_RUN_BINDING_SCHEMA_VERSION;
+    readonly binding_id: Sha256Digest;
+    readonly binding_digest: Sha256Digest;
+    readonly binding: RunBindingPayload;
+}
+export type RunBinding = StoredRunBinding;
+export interface RunBindingRequest {
+    readonly plan: StoredExecutableRunPlan;
+    readonly max_concurrency?: number;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly environment: {
+        readonly project_root: string;
+        readonly workspace_root: string;
+        readonly secret_references: readonly SecretReference[];
+    };
+    readonly provider: ProviderConfiguration;
+}
+export declare class RunBindingError extends TypeError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function assertRunBindingPayload(value: unknown): asserts value is RunBindingPayload;
+export declare function parseRunBindingPayload(value: unknown): RunBindingPayload;
+export declare function runBindingDigest(binding: RunBindingPayload): Sha256Digest;
+export declare function createStoredRunBinding(binding: RunBindingPayload): StoredRunBinding;
+export declare function parseStoredRunBinding(value: unknown): StoredRunBinding;
+export declare class RunBindingFactory {
+    static bind(request: RunBindingRequest): StoredRunBinding;
+}

package/dist/runtime/run-binding.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, win32 } from "node:path";
+import { canonicalizeJson } from "./canonical-json.js";
+import { parseStoredExecutableRunPlan, } from "./executable-run-plan.js";
+export const RUN_BINDING_SCHEMA_VERSION = "intentdna.run_binding.v1";
+export const STORED_RUN_BINDING_SCHEMA_VERSION = "intentdna.stored_run_binding.v1";
+export class RunBindingError extends TypeError {
+    path;
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = "RunBindingError";
+        this.path = path;
+    }
+}
+function record(value, path, fields) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new RunBindingError(path, "must be an object");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new RunBindingError(path, "must be a plain object");
+    }
+    if (fields) {
+        const unknown = Object.keys(value).filter((key) => !fields.includes(key));
+        if (unknown.length > 0)
+            throw new RunBindingError(path, `unknown field '${unknown[0]}'`);
+    }
+    return value;
+}
+function required(value, key, path) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+        throw new RunBindingError(path, `missing field '${key}'`);
+    }
+    return value[key];
+}
+function string(value, path) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new RunBindingError(path, "must be a non-empty string");
+    }
+}
+function digest(value, path) {
+    if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value)) {
+        throw new RunBindingError(path, "must be a lowercase sha256 digest");
+    }
+}
+function absolutePath(value, path) {
+    string(value, path);
+    if (value.includes("\0")) {
+        throw new RunBindingError(path, "must not contain NUL");
+    }
+    if (!isAbsolute(value) && !win32.isAbsolute(value)) {
+        throw new RunBindingError(path, "must be absolute");
+    }
+}
+function assertReferenceSource(value, path) {
+    if (!["environment", "file", "keychain", "external"].includes(value)) {
+        throw new RunBindingError(path, "has an unsupported secret source");
+    }
+}
+function assertProviderOptions(value) {
+    const path = "$.provider_config.options";
+    const options = record(value, path, [
+        "reasoning_effort",
+        "temperature",
+        "max_output_tokens",
+        "executable",
+        "max_budget_usd",
+        "permission_mode",
+    ]);
+    if (Object.prototype.hasOwnProperty.call(options, "reasoning_effort")) {
+        const effort = options.reasoning_effort;
+        if (!["low", "medium", "high", "xhigh", "max", "ultra"].includes(effort)) {
+            throw new RunBindingError(`${path}.reasoning_effort`, "has an unsupported value");
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "temperature")) {
+        const temperature = options.temperature;
+        if (typeof temperature !== "number" || !Number.isFinite(temperature)) {
+            throw new RunBindingError(`${path}.temperature`, "must be a finite number");
+        }
+        if (temperature < 0 || temperature > 2) {
+            throw new RunBindingError(`${path}.temperature`, "must be between 0 and 2");
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "max_output_tokens")) {
+        const maxOutputTokens = options.max_output_tokens;
+        if (typeof maxOutputTokens !== "number" || !Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) {
+            throw new RunBindingError(`${path}.max_output_tokens`, "must be a positive safe integer");
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "executable")) {
+        absolutePath(options.executable, `${path}.executable`);
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "max_budget_usd")) {
+        const maxBudgetUsd = options.max_budget_usd;
+        if (typeof maxBudgetUsd !== "number" || !Number.isFinite(maxBudgetUsd) || maxBudgetUsd <= 0) {
+            throw new RunBindingError(`${path}.max_budget_usd`, "must be a positive finite number");
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(options, "permission_mode")) {
+        const permissionMode = options.permission_mode;
+        string(permissionMode, `${path}.permission_mode`);
+        if (permissionMode.includes("\0")) {
+            throw new RunBindingError(`${path}.permission_mode`, "must not contain NUL");
+        }
+        if (permissionMode.trim() !== permissionMode) {
+            throw new RunBindingError(`${path}.permission_mode`, "must not have leading or trailing whitespace");
+        }
+        if (permissionMode.length > 128) {
+            throw new RunBindingError(`${path}.permission_mode`, "must be at most 128 characters");
+        }
+    }
+}
+export function assertRunBindingPayload(value) {
+    canonicalizeJson(value);
+    const binding = record(value, "$", ["schema_version", "plan_id", "max_concurrency", "validated_inputs", "secret_references", "provider_config", "project_root", "workspace_root"]);
+    if (required(binding, "schema_version", "$") !== RUN_BINDING_SCHEMA_VERSION) {
+        throw new RunBindingError("$.schema_version", "unsupported schema version");
+    }
+    digest(required(binding, "plan_id", "$"), "$.plan_id");
+    if (Object.prototype.hasOwnProperty.call(binding, "max_concurrency")) {
+        const maxConcurrency = binding.max_concurrency;
+        if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) {
+            throw new RunBindingError("$.max_concurrency", "must be a positive safe integer");
+        }
+    }
+    const inputs = record(required(binding, "validated_inputs", "$"), "$.validated_inputs");
+    canonicalizeJson(inputs);
+    const references = required(binding, "secret_references", "$");
+    if (!Array.isArray(references))
+        throw new RunBindingError("$.secret_references", "must be an array");
+    const inputNames = new Set();
+    references.forEach((item, index) => {
+        const path = `$.secret_references[${index}]`;
+        const reference = record(item, path, ["input_name", "source", "reference"]);
+        string(required(reference, "input_name", path), `${path}.input_name`);
+        if (inputNames.has(reference.input_name)) {
+            throw new RunBindingError(`${path}.input_name`, "must be unique");
+        }
+        inputNames.add(reference.input_name);
+        assertReferenceSource(reference.source, `${path}.source`);
+        string(required(reference, "reference", path), `${path}.reference`);
+    });
+    const provider = record(required(binding, "provider_config", "$"), "$.provider_config", ["provider", "model", "options", "credential_references"]);
+    string(required(provider, "provider", "$.provider_config"), "$.provider_config.provider");
+    const model = required(provider, "model", "$.provider_config");
+    if (model !== null)
+        string(model, "$.provider_config.model");
+    assertProviderOptions(required(provider, "options", "$.provider_config"));
+    const providerReferences = required(provider, "credential_references", "$.provider_config");
+    if (!Array.isArray(providerReferences)) {
+        throw new RunBindingError("$.provider_config.credential_references", "must be an array");
+    }
+    const credentialNames = new Set();
+    providerReferences.forEach((item, index) => {
+        const path = `$.provider_config.credential_references[${index}]`;
+        const reference = record(item, path, ["name", "source", "reference"]);
+        string(required(reference, "name", path), `${path}.name`);
+        if (credentialNames.has(reference.name)) {
+            throw new RunBindingError(`${path}.name`, "must be unique");
+        }
+        credentialNames.add(reference.name);
+        assertReferenceSource(reference.source, `${path}.source`);
+        string(required(reference, "reference", path), `${path}.reference`);
+    });
+    absolutePath(required(binding, "project_root", "$"), "$.project_root");
+    absolutePath(required(binding, "workspace_root", "$"), "$.workspace_root");
+}
+export function parseRunBindingPayload(value) {
+    assertRunBindingPayload(value);
+    return value;
+}
+export function runBindingDigest(binding) {
+    assertRunBindingPayload(binding);
+    return `sha256:${createHash("sha256").update(canonicalizeJson(binding), "utf8").digest("hex")}`;
+}
+export function createStoredRunBinding(binding) {
+    const canonicalBinding = JSON.parse(canonicalizeJson(binding));
+    assertRunBindingPayload(canonicalBinding);
+    const bindingDigest = runBindingDigest(canonicalBinding);
+    return {
+        schema_version: STORED_RUN_BINDING_SCHEMA_VERSION,
+        binding_id: bindingDigest,
+        binding_digest: bindingDigest,
+        binding: canonicalBinding,
+    };
+}
+export function parseStoredRunBinding(value) {
+    canonicalizeJson(value);
+    const stored = record(value, "$", ["schema_version", "binding_id", "binding_digest", "binding"]);
+    if (required(stored, "schema_version", "$") !== STORED_RUN_BINDING_SCHEMA_VERSION) {
+        throw new RunBindingError("$.schema_version", "unsupported stored binding schema version");
+    }
+    digest(required(stored, "binding_id", "$"), "$.binding_id");
+    digest(required(stored, "binding_digest", "$"), "$.binding_digest");
+    const binding = parseRunBindingPayload(required(stored, "binding", "$"));
+    const recomputed = runBindingDigest(binding);
+    if (stored.binding_id !== stored.binding_digest || stored.binding_digest !== recomputed) {
+        throw new RunBindingError("$", "binding_id, binding_digest, and canonical payload digest must match");
+    }
+    return value;
+}
+function validateInputType(value, type, path) {
+    canonicalizeJson(value);
+    if (type === "string" || type === "reference" || type === "trusted_verifier_command") {
+        if (typeof value !== "string")
+            throw new RunBindingError(path, `must be ${type}`);
+    }
+    else if (type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            throw new RunBindingError(path, "must be a finite number");
+    }
+    else if (type === "boolean" && typeof value !== "boolean") {
+        throw new RunBindingError(path, "must be boolean");
+    }
+    return value;
+}
+export class RunBindingFactory {
+    static bind(request) {
+        const plan = parseStoredExecutableRunPlan(request.plan);
+        const inputDefinitions = new Map(plan.plan.input_contract.inputs.map((input) => [
+            input.name,
+            input,
+        ]));
+        for (const name of Object.keys(request.inputs)) {
+            if (!inputDefinitions.has(name)) {
+                throw new RunBindingError(`$.inputs.${name}`, "is not declared by the plan input contract");
+            }
+        }
+        const referencesByInput = new Map(request.environment.secret_references.map((reference) => [reference.input_name, reference]));
+        const validatedInputs = Object.create(null);
+        for (const definition of plan.plan.input_contract.inputs) {
+            const hasValue = Object.prototype.hasOwnProperty.call(request.inputs, definition.name);
+            const hasReference = referencesByInput.has(definition.name);
+            if (definition.sensitive) {
+                if (hasValue) {
+                    throw new RunBindingError(`$.inputs.${definition.name}`, "resolved sensitive values are forbidden; use a secret reference");
+                }
+                if (definition.required && !hasReference) {
+                    throw new RunBindingError(`$.environment.secret_references`, `missing required secret reference '${definition.name}'`);
+                }
+            }
+            else if (hasReference) {
+                throw new RunBindingError(`$.environment.secret_references`, `input '${definition.name}' is not sensitive`);
+            }
+            else if (hasValue) {
+                if (definition.type === "trusted_verifier_command") {
+                    throw new RunBindingError(`$.inputs.${definition.name}`, "trusted verifier commands cannot be overridden at runtime");
+                }
+                validatedInputs[definition.name] = validateInputType(request.inputs[definition.name], definition.type, `$.inputs.${definition.name}`);
+            }
+            else if (definition.default_value !== undefined) {
+                validatedInputs[definition.name] = validateInputType(definition.default_value, definition.type, `$.plan.input_contract.${definition.name}.default_value`);
+            }
+            else if (definition.required) {
+                throw new RunBindingError("$.inputs", `missing required input '${definition.name}'`);
+            }
+        }
+        for (const reference of request.environment.secret_references) {
+            const definition = inputDefinitions.get(reference.input_name);
+            if (!definition) {
+                throw new RunBindingError("$.environment.secret_references", `unknown input '${reference.input_name}'`);
+            }
+        }
+        return createStoredRunBinding({
+            schema_version: RUN_BINDING_SCHEMA_VERSION,
+            plan_id: plan.plan_id,
+            ...(request.max_concurrency === undefined
+                ? {}
+                : { max_concurrency: request.max_concurrency }),
+            validated_inputs: validatedInputs,
+            secret_references: request.environment.secret_references,
+            provider_config: request.provider,
+            project_root: request.environment.project_root,
+            workspace_root: request.environment.workspace_root,
+        });
+    }
+}