intentdna 1.9.0 → 1.9.3

package/dist/runtime/canonical-attempt-outcome.d.ts

@@ -0,0 +1,12 @@
+import type { AttemptExecutor, CanonicalAttemptOutcome } from "./run-contracts.js";
+export declare class CanonicalAttemptOutcomeValidationError extends TypeError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export interface ValidatedCanonicalAttemptOutcome {
+    readonly executor: AttemptExecutor;
+    readonly outcome: CanonicalAttemptOutcome;
+}
+export type CanonicalAttemptOutcomeStatus = "succeeded" | "failed" | "cancelled";
+export declare function canonicalAttemptOutcomeStatus(outcome: CanonicalAttemptOutcome): CanonicalAttemptOutcomeStatus;
+export declare function validateCanonicalAttemptOutcome(executorValue: unknown, outcomeValue: unknown): ValidatedCanonicalAttemptOutcome;

package/dist/runtime/canonical-attempt-outcome.js

@@ -0,0 +1,195 @@
+export class CanonicalAttemptOutcomeValidationError extends TypeError {
+    path;
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = "CanonicalAttemptOutcomeValidationError";
+        this.path = path;
+    }
+}
+export function canonicalAttemptOutcomeStatus(outcome) {
+    if (outcome.kind !== "worker_process")
+        return outcome.kind;
+    return outcome.status;
+}
+function record(value, path) {
+    if (typeof value !== "object"
+        || value === null
+        || Array.isArray(value)
+        || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new CanonicalAttemptOutcomeValidationError(path, "must be an object");
+    }
+    return value;
+}
+function exactKeys(value, expected, path) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length
+        || !actual.every((key, index) => key === wanted[index])) {
+        throw new CanonicalAttemptOutcomeValidationError(path, "has unexpected or missing fields");
+    }
+}
+function nonEmptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new CanonicalAttemptOutcomeValidationError(path, "must be a non-empty string");
+    }
+}
+function validateExecutor(value) {
+    const executor = record(value, "executor");
+    if (executor.kind === "worker") {
+        exactKeys(executor, ["kind", "worker_session_id"], "executor");
+        nonEmptyString(executor.worker_session_id, "executor.worker_session_id");
+        return executor;
+    }
+    if (executor.kind === "system") {
+        exactKeys(executor, ["kind", "service_instance_id", "operation"], "executor");
+        nonEmptyString(executor.service_instance_id, "executor.service_instance_id");
+        nonEmptyString(executor.operation, "executor.operation");
+        return executor;
+    }
+    if (executor.kind === "human") {
+        exactKeys(executor, ["kind", "principal_ref", "attestation_ref"], "executor");
+        nonEmptyString(executor.principal_ref, "executor.principal_ref");
+        nonEmptyString(executor.attestation_ref, "executor.attestation_ref");
+        return executor;
+    }
+    throw new CanonicalAttemptOutcomeValidationError("executor.kind", "must be worker, system, or human");
+}
+function integerOrNull(value, path, nullable) {
+    if (!(typeof value === "number" && Number.isInteger(value))
+        && !(nullable && value === null)) {
+        throw new CanonicalAttemptOutcomeValidationError(path, "is invalid");
+    }
+}
+function validateProcessOutcome(value) {
+    const outcome = record(value, "outcome.process");
+    switch (outcome.kind) {
+        case "success":
+            exactKeys(outcome, ["kind", "exit_code", "signal"], "outcome.process");
+            if (outcome.exit_code !== 0 || outcome.signal !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process", "success fields are invalid");
+            }
+            break;
+        case "non_zero_exit":
+            exactKeys(outcome, ["kind", "exit_code", "signal"], "outcome.process");
+            integerOrNull(outcome.exit_code, "outcome.process.exit_code", false);
+            if (outcome.exit_code === 0 || outcome.signal !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process", "non-zero exit fields are invalid");
+            }
+            break;
+        case "malformed_result":
+            exactKeys(outcome, ["kind", "exit_code", "signal", "error"], "outcome.process");
+            integerOrNull(outcome.exit_code, "outcome.process.exit_code", true);
+            if (outcome.signal !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.signal", "must be null");
+            }
+            nonEmptyString(outcome.error, "outcome.process.error");
+            break;
+        case "timeout":
+            exactKeys(outcome, ["kind", "exit_code", "signal", "timeout_ms"], "outcome.process");
+            integerOrNull(outcome.exit_code, "outcome.process.exit_code", true);
+            if (outcome.signal !== null && typeof outcome.signal !== "string") {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.signal", "must be a string or null");
+            }
+            if (!Number.isInteger(outcome.timeout_ms) || outcome.timeout_ms <= 0) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.timeout_ms", "must be a positive integer");
+            }
+            break;
+        case "cancelled":
+            exactKeys(outcome, ["kind", "exit_code", "signal", "reason"], "outcome.process");
+            integerOrNull(outcome.exit_code, "outcome.process.exit_code", true);
+            if (outcome.signal !== null && typeof outcome.signal !== "string") {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.signal", "must be a string or null");
+            }
+            if (outcome.reason !== null && typeof outcome.reason !== "string") {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.reason", "must be a string or null");
+            }
+            break;
+        case "signal":
+            exactKeys(outcome, ["kind", "exit_code", "signal"], "outcome.process");
+            if (outcome.exit_code !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process.exit_code", "must be null");
+            }
+            nonEmptyString(outcome.signal, "outcome.process.signal");
+            break;
+        case "launch_error":
+            exactKeys(outcome, ["kind", "exit_code", "signal", "error"], "outcome.process");
+            if (outcome.exit_code !== null || outcome.signal !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome.process", "launch fields are invalid");
+            }
+            nonEmptyString(outcome.error, "outcome.process.error");
+            break;
+        default:
+            throw new CanonicalAttemptOutcomeValidationError("outcome.process.kind", "is invalid");
+    }
+    return outcome;
+}
+export function validateCanonicalAttemptOutcome(executorValue, outcomeValue) {
+    const executor = validateExecutor(executorValue);
+    const outcome = record(outcomeValue, "outcome");
+    if (executor.kind === "worker") {
+        if (outcome.kind !== "worker_process") {
+            throw new CanonicalAttemptOutcomeValidationError("outcome.kind", "a worker outcome must be worker_process");
+        }
+        exactKeys(outcome, ["kind", "status", "reason_code", "message", "process"], "outcome");
+        const process = validateProcessOutcome(outcome.process);
+        if (!new Set(["succeeded", "failed", "cancelled"]).has(outcome.status)) {
+            throw new CanonicalAttemptOutcomeValidationError("outcome.status", "must be succeeded, failed, or cancelled");
+        }
+        if (outcome.message !== null && typeof outcome.message !== "string") {
+            throw new CanonicalAttemptOutcomeValidationError("outcome.message", "must be a string or null");
+        }
+        if (outcome.status === "succeeded") {
+            if (process.kind !== "success"
+                || outcome.reason_code !== null
+                || outcome.message !== null) {
+                throw new CanonicalAttemptOutcomeValidationError("outcome", "succeeded requires process success and null reason_code/message");
+            }
+        }
+        else {
+            nonEmptyString(outcome.reason_code, "outcome.reason_code");
+        }
+        return {
+            executor,
+            outcome: {
+                kind: "worker_process",
+                status: outcome.status,
+                reason_code: outcome.reason_code,
+                message: outcome.message,
+                process,
+            },
+        };
+    }
+    if (outcome.kind === "worker_process") {
+        throw new CanonicalAttemptOutcomeValidationError("outcome.kind", `${executor.kind} outcomes must not contain process facts`);
+    }
+    if (outcome.kind === "succeeded") {
+        exactKeys(outcome, ["kind"], "outcome");
+        return { executor, outcome: { kind: "succeeded" } };
+    }
+    if (outcome.kind === "failed") {
+        exactKeys(outcome, ["kind", "reason_code", "message"], "outcome");
+        nonEmptyString(outcome.reason_code, "outcome.reason_code");
+        if (outcome.message !== null && typeof outcome.message !== "string") {
+            throw new CanonicalAttemptOutcomeValidationError("outcome.message", "must be a string or null");
+        }
+        return {
+            executor,
+            outcome: {
+                kind: "failed",
+                reason_code: outcome.reason_code,
+                message: outcome.message,
+            },
+        };
+    }
+    if (outcome.kind === "cancelled") {
+        exactKeys(outcome, ["kind", "reason"], "outcome");
+        if (outcome.reason !== null && typeof outcome.reason !== "string") {
+            throw new CanonicalAttemptOutcomeValidationError("outcome.reason", "must be a string or null");
+        }
+        return {
+            executor,
+            outcome: { kind: "cancelled", reason: outcome.reason },
+        };
+    }
+    throw new CanonicalAttemptOutcomeValidationError("outcome.kind", `is invalid for ${executor.kind}`);
+}

package/dist/runtime/canonical-json.d.ts

@@ -0,0 +1,10 @@
+export type CanonicalJsonValue = null | boolean | number | string | readonly CanonicalJsonValue[] | {
+    readonly [key: string]: CanonicalJsonValue;
+};
+export declare class CanonicalJsonError extends TypeError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function canonicalizeJson(value: unknown): string;
+export declare function canonicalJsonUtf8(value: unknown): Uint8Array;
+export declare function assertCanonicalJsonValue(value: unknown): asserts value is CanonicalJsonValue;

package/dist/runtime/canonical-json.js

@@ -0,0 +1,105 @@
+export class CanonicalJsonError extends TypeError {
+    path;
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = "CanonicalJsonError";
+        this.path = path;
+    }
+}
+function compareUtf16(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function assertUnicodeScalarString(value, path) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new CanonicalJsonError(path, "contains a lone high surrogate");
+            }
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new CanonicalJsonError(path, "contains a lone low surrogate");
+        }
+    }
+}
+function canonicalize(value, path, ancestors) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new CanonicalJsonError(path, "number must be finite");
+        }
+        if (Object.is(value, -0))
+            return "0";
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string") {
+        assertUnicodeScalarString(value, path);
+        return JSON.stringify(value);
+    }
+    if (typeof value !== "object") {
+        throw new CanonicalJsonError(path, `${typeof value} is not a JSON value`);
+    }
+    if (ancestors.has(value)) {
+        throw new CanonicalJsonError(path, "contains a cycle");
+    }
+    ancestors.add(value);
+    try {
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new CanonicalJsonError(path, "symbol-keyed properties are not JSON values");
+        }
+        if (Array.isArray(value)) {
+            const allowedProperties = new Set(["length"]);
+            const items = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new CanonicalJsonError(`${path}[${index}]`, "sparse arrays are not supported");
+                }
+                allowedProperties.add(String(index));
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!descriptor?.enumerable || !("value" in descriptor)) {
+                    throw new CanonicalJsonError(`${path}[${index}]`, "array entries must be enumerable data properties");
+                }
+                items.push(canonicalize(value[index], `${path}[${index}]`, ancestors));
+            }
+            const extraProperty = Object.getOwnPropertyNames(value).find((property) => !allowedProperties.has(property));
+            if (extraProperty !== undefined) {
+                throw new CanonicalJsonError(path, `array has non-JSON property '${extraProperty}'`);
+            }
+            return `[${items.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new CanonicalJsonError(path, "object must be a plain object");
+        }
+        const record = value;
+        const keys = Object.getOwnPropertyNames(record);
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(record, key);
+            if (!descriptor?.enumerable || !("value" in descriptor)) {
+                throw new CanonicalJsonError(`${path}.${key}`, "object members must be enumerable data properties");
+            }
+        }
+        const members = keys.sort(compareUtf16).map((key) => {
+            assertUnicodeScalarString(key, `${path} key`);
+            return `${JSON.stringify(key)}:${canonicalize(record[key], `${path}.${key}`, ancestors)}`;
+        });
+        return `{${members.join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function canonicalizeJson(value) {
+    return canonicalize(value, "$", new Set());
+}
+export function canonicalJsonUtf8(value) {
+    return new TextEncoder().encode(canonicalizeJson(value));
+}
+export function assertCanonicalJsonValue(value) {
+    canonicalizeJson(value);
+}

package/dist/runtime/canonical-run-application.d.ts

@@ -0,0 +1,93 @@
+import { type CanonicalDnaSource, type CanonicalRuntimeProjection, type CanonicalTargetCompilation, type CanonicalTarget, type CompileCanonicalTargetRequest } from "./canonical-target-compiler.js";
+import { type ExecutableRunPlanPayload } from "./executable-run-plan.js";
+import { type ProviderConfiguration, type SecretReference, type StoredRunBinding } from "./run-binding.js";
+import type { JsonValue, RunId } from "./run-contracts.js";
+export interface CanonicalTargetCompilerPort {
+    compile(request: CompileCanonicalTargetRequest): ExecutableRunPlanPayload;
+    compileCascade?(request: CompileCanonicalTargetRequest): CanonicalTargetCompilation;
+}
+export interface ResolveCanonicalDnaSourcesRequest {
+    readonly dna_sources: readonly string[];
+    readonly project_root: string;
+    readonly enterprise_policy_dirs?: readonly string[];
+}
+export interface CanonicalDnaSourceResolver {
+    resolve(request: ResolveCanonicalDnaSourcesRequest): Promise<readonly CanonicalDnaSource[]>;
+}
+export interface CanonicalRunStartRequest {
+    readonly plan_payload: ExecutableRunPlanPayload;
+    readonly run_binding: StoredRunBinding;
+    readonly metadata?: JsonValue;
+    readonly run_id?: RunId;
+}
+export interface CanonicalRunStarter<StartRunResponse> {
+    start(request: CanonicalRunStartRequest): Promise<StartRunResponse> | StartRunResponse;
+}
+export interface StartCanonicalTargetRequest {
+    readonly dna_sources: readonly string[];
+    readonly target: CanonicalTarget;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly environment: {
+        readonly project_root: string;
+        readonly workspace_root?: string;
+        readonly enterprise_policy_dirs?: readonly string[];
+        readonly secret_references?: readonly SecretReference[];
+    };
+    readonly provider: ProviderConfiguration;
+    readonly max_concurrency: number;
+    readonly input_policy?: "strict" | "declared_only";
+    readonly context?: string | null;
+    readonly attempt_policy?: CompileCanonicalTargetRequest["attempt_policy"];
+    readonly metadata?: JsonValue;
+    readonly run_id?: RunId;
+}
+export interface CanonicalRuntimeProjectionRequest<StartRunResponse> {
+    readonly phase: "before_start" | "after_start";
+    readonly projection: CanonicalRuntimeProjection;
+    readonly start_response: StartRunResponse | null;
+}
+export interface CanonicalRunMetadataFactoryRequest {
+    readonly compiled: CompiledCanonicalTarget;
+    readonly metadata: JsonValue | undefined;
+}
+export interface CanonicalRunApplicationOptions<StartRunResponse> {
+    readonly starter?: CanonicalRunStarter<StartRunResponse>;
+    readonly compiler?: CanonicalTargetCompilerPort;
+    readonly source_resolver?: CanonicalDnaSourceResolver;
+    readonly metadata_factory?: (request: CanonicalRunMetadataFactoryRequest) => Promise<JsonValue | undefined> | JsonValue | undefined;
+    readonly projection_sink?: (request: CanonicalRuntimeProjectionRequest<StartRunResponse>) => Promise<void> | void;
+}
+export interface CompiledCanonicalTarget {
+    readonly plan_payload: ExecutableRunPlanPayload;
+    readonly run_binding: StoredRunBinding;
+    readonly projection: CanonicalRuntimeProjection | null;
+}
+export interface StartCompiledCanonicalTargetRequest {
+    readonly compiled: CompiledCanonicalTarget;
+    readonly metadata?: JsonValue;
+    readonly run_id?: RunId;
+}
+export type CanonicalRunApplicationErrorCode = "invalid_request" | "invalid_service_response" | "source_resolution_failed";
+export declare class CanonicalRunApplicationError extends Error {
+    readonly code: CanonicalRunApplicationErrorCode;
+    constructor(code: CanonicalRunApplicationErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class FilesystemCanonicalDnaSourceResolver implements CanonicalDnaSourceResolver {
+    protected afterSourceSnapshotsLoaded(_files: readonly string[]): Promise<void>;
+    resolve(request: ResolveCanonicalDnaSourcesRequest): Promise<readonly CanonicalDnaSource[]>;
+}
+/**
+ * The only application boundary allowed to compose source resolution, target
+ * compilation, environment binding, and canonical service start.
+ */
+export declare class CanonicalRunApplication<StartRunResponse> {
+    private readonly starter;
+    private readonly compiler;
+    private readonly sourceResolver;
+    private readonly metadataFactory;
+    private readonly projectionSink;
+    constructor(options: CanonicalRunApplicationOptions<StartRunResponse>);
+    startTarget(request: StartCanonicalTargetRequest): Promise<StartRunResponse>;
+    compileTarget(request: StartCanonicalTargetRequest): Promise<CompiledCanonicalTarget>;
+    startCompiledTarget(request: StartCompiledCanonicalTargetRequest): Promise<StartRunResponse>;
+}

package/dist/runtime/canonical-run-application.js

@@ -0,0 +1,229 @@
+import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
+import { expandDNAInputs, } from "../compiler/index.js";
+import { validateDNA } from "../schema/validate.js";
+import { CanonicalTargetCompiler, } from "./canonical-target-compiler.js";
+import { createStoredExecutableRunPlan, parseStoredExecutableRunPlan, } from "./executable-run-plan.js";
+import { parseStoredRunBinding, RunBindingFactory, } from "./run-binding.js";
+function bindingInputs(request, planPayload) {
+    if (request.input_policy !== "declared_only")
+        return request.inputs;
+    const declaredNames = new Set(planPayload.input_contract.inputs.map((input) => input.name));
+    return Object.fromEntries(Object.entries(request.inputs).filter(([name]) => declaredNames.has(name)));
+}
+export class CanonicalRunApplicationError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "CanonicalRunApplicationError";
+        this.code = code;
+    }
+}
+function isInside(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (path !== ".."
+        && !path.startsWith(`..${sep}`)
+        && !isAbsolute(path)
+        && !win32.isAbsolute(path));
+}
+function portableRelativeRef(projectRoot, file, provenance) {
+    if (isInside(projectRoot, file)) {
+        const path = relative(projectRoot, file).split(sep).join("/");
+        if (path)
+            return path;
+    }
+    const declaredRef = provenance.source_ref;
+    if (declaredRef.length > 0
+        && !isAbsolute(declaredRef)
+        && !win32.isAbsolute(declaredRef)
+        && !declaredRef.includes("\\")
+        && !declaredRef.includes("\0")
+        && !declaredRef.split("/").includes("..")) {
+        return declaredRef;
+    }
+    const sourceId = provenance.source_id.replace(/[^A-Za-z0-9._-]/gu, "_") || "source";
+    const fingerprint = provenance.fingerprint.slice("sha256:".length, "sha256:".length + 16);
+    return `external/${sourceId}-${fingerprint}.dna`;
+}
+function sourceDigest(value, sourceId) {
+    if (!/^sha256:[a-f0-9]{64}$/u.test(value)) {
+        throw new CanonicalRunApplicationError("source_resolution_failed", `DNA source '${sourceId}' has an invalid content fingerprint`);
+    }
+    return value;
+}
+function validateCanonicalStartResponse(value, planId, bindingId) {
+    try {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error("start response must be an object");
+        }
+        const response = value;
+        if (typeof response.run_id !== "string" || response.run_id.length === 0) {
+            throw new Error("start response run_id must be a non-empty string");
+        }
+        if (response.view === null || typeof response.view !== "object") {
+            throw new Error("start response view must be an object");
+        }
+        const view = response.view;
+        const plan = parseStoredExecutableRunPlan(view.plan);
+        const binding = parseStoredRunBinding(view.run?.run_binding);
+        if (response.plan_id !== planId
+            || response.run_id !== view.run?.run_id
+            || plan.plan_id !== planId
+            || view.run?.plan_id !== planId
+            || view.run?.plan_digest !== plan.plan_digest
+            || binding.binding_id !== bindingId
+            || binding.binding.plan_id !== planId) {
+            throw new Error("start response changed the compiled plan or run binding identity");
+        }
+    }
+    catch (error) {
+        throw new CanonicalRunApplicationError("invalid_service_response", "canonical start response does not match the compiled plan and run binding", { cause: error });
+    }
+}
+export class FilesystemCanonicalDnaSourceResolver {
+    async afterSourceSnapshotsLoaded(_files) { }
+    async resolve(request) {
+        if (request.dna_sources.length === 0) {
+            throw new CanonicalRunApplicationError("invalid_request", "dna_sources must contain at least one source");
+        }
+        const projectRoot = resolve(request.project_root);
+        try {
+            const expanded = await expandDNAInputs([...request.dna_sources], {
+                cwd: projectRoot,
+                enterprisePolicyDirs: request.enterprise_policy_dirs
+                    ? [...request.enterprise_policy_dirs]
+                    : undefined,
+            });
+            await this.afterSourceSnapshotsLoaded(expanded.files);
+            return expanded.files.map((file, index) => {
+                const provenance = expanded.provenance[index];
+                const dna = expanded.dnas[index];
+                const snapshotBytes = expanded.snapshot_bytes[index];
+                if (!provenance || !dna || !snapshotBytes) {
+                    throw new CanonicalRunApplicationError("source_resolution_failed", `DNA source snapshot is incomplete for ${file}`);
+                }
+                const validation = validateDNA(dna);
+                if (!validation.valid) {
+                    throw new CanonicalRunApplicationError("source_resolution_failed", `DNA source '${provenance.source_id}' failed schema validation: ${validation.errors
+                        .map((error) => `${error.path}: ${error.message}`)
+                        .join("; ")}`);
+                }
+                return {
+                    dna,
+                    source_id: provenance.source_id,
+                    relative_ref: portableRelativeRef(projectRoot, file, provenance),
+                    content_digest: sourceDigest(provenance.fingerprint, provenance.source_id),
+                    snapshot_bytes: snapshotBytes,
+                };
+            });
+        }
+        catch (error) {
+            if (error instanceof CanonicalRunApplicationError)
+                throw error;
+            throw new CanonicalRunApplicationError("source_resolution_failed", "failed to resolve and validate DNA sources", { cause: error });
+        }
+    }
+}
+/**
+ * The only application boundary allowed to compose source resolution, target
+ * compilation, environment binding, and canonical service start.
+ */
+export class CanonicalRunApplication {
+    starter;
+    compiler;
+    sourceResolver;
+    metadataFactory;
+    projectionSink;
+    constructor(options) {
+        this.starter = options.starter;
+        this.compiler = options.compiler ?? new CanonicalTargetCompiler();
+        this.sourceResolver = options.source_resolver
+            ?? new FilesystemCanonicalDnaSourceResolver();
+        this.metadataFactory = options.metadata_factory;
+        this.projectionSink = options.projection_sink;
+    }
+    async startTarget(request) {
+        const compiled = await this.compileTarget(request);
+        const metadata = this.metadataFactory
+            ? await this.metadataFactory({ compiled, metadata: request.metadata })
+            : request.metadata;
+        return this.startCompiledTarget({
+            compiled,
+            ...(metadata !== undefined ? { metadata } : {}),
+            ...(request.run_id !== undefined ? { run_id: request.run_id } : {}),
+        });
+    }
+    async compileTarget(request) {
+        if (!request.environment.project_root.trim()) {
+            throw new CanonicalRunApplicationError("invalid_request", "environment.project_root must be non-empty");
+        }
+        const projectRoot = resolve(request.environment.project_root);
+        const workspaceRoot = request.environment.workspace_root === undefined
+            ? projectRoot
+            : resolve(projectRoot, request.environment.workspace_root);
+        const dnaSources = await this.sourceResolver.resolve({
+            dna_sources: request.dna_sources,
+            project_root: projectRoot,
+            enterprise_policy_dirs: request.environment.enterprise_policy_dirs,
+        });
+        const compileRequest = {
+            dna_sources: dnaSources,
+            target: request.target,
+            ...(request.context !== undefined ? { context: request.context } : {}),
+            ...(request.attempt_policy !== undefined
+                ? { attempt_policy: request.attempt_policy }
+                : {}),
+        };
+        const compilation = this.compiler.compileCascade?.(compileRequest);
+        const planPayload = compilation?.plan ?? this.compiler.compile(compileRequest);
+        const storedPlan = createStoredExecutableRunPlan(planPayload);
+        const runBinding = RunBindingFactory.bind({
+            plan: storedPlan,
+            max_concurrency: request.max_concurrency,
+            inputs: bindingInputs(request, planPayload),
+            environment: {
+                project_root: projectRoot,
+                workspace_root: workspaceRoot,
+                secret_references: request.environment.secret_references ?? [],
+            },
+            provider: request.provider,
+        });
+        return {
+            plan_payload: storedPlan.plan,
+            run_binding: runBinding,
+            projection: compilation?.projection ?? null,
+        };
+    }
+    async startCompiledTarget(request) {
+        if (!this.starter) {
+            throw new CanonicalRunApplicationError("invalid_request", "canonical run starter is required to start a compiled target");
+        }
+        const { compiled } = request;
+        const storedPlan = createStoredExecutableRunPlan(compiled.plan_payload);
+        const runBinding = parseStoredRunBinding(compiled.run_binding);
+        if (runBinding.binding.plan_id !== storedPlan.plan_id) {
+            throw new CanonicalRunApplicationError("invalid_request", "compiled run binding does not match the compiled plan");
+        }
+        if (compiled.projection && this.projectionSink) {
+            await this.projectionSink({
+                phase: "before_start",
+                projection: compiled.projection,
+                start_response: null,
+            });
+        }
+        const startResponse = await this.starter.start({
+            plan_payload: storedPlan.plan,
+            run_binding: runBinding,
+            ...(request.metadata !== undefined ? { metadata: request.metadata } : {}),
+            ...(request.run_id !== undefined ? { run_id: request.run_id } : {}),
+        });
+        validateCanonicalStartResponse(startResponse, storedPlan.plan_id, runBinding.binding_id);
+        if (compiled.projection && this.projectionSink) {
+            await this.projectionSink({
+                phase: "after_start",
+                projection: compiled.projection,
+                start_response: startResponse,
+            });
+        }
+        return startResponse;
+    }
+}