@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/generic-execution.js

@@ -0,0 +1,164 @@
+import { AppError } from "../shared/errors.js";
+import { sameSessionProfile } from "./execution-policy.js";
+import { hybridDigest, validateHybridContract } from "./hybrid-contracts.js";
+import { prepareOperatorProfile, resolveOperatorProfile } from "./operator-profiles.js";
+function fail(message, issues) {
+    throw new AppError("generic_execution_invalid", message, 2, { phase: "prepare", effect: "no_effect", ...(issues ? { issues } : {}) });
+}
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+}
+function scopedReceipts(settings, scope, receipts) {
+    for (const [reference, kind] of [
+        [settings.attached_session_receipt, "attached-session-binding"],
+        [settings.delegation.native_capacity_receipt, "native-capacity"]
+    ]) {
+        if (reference === null)
+            continue;
+        const fact = receipts.get(reference.sha256);
+        if (!fact || fact.kind !== kind || fact.requestId !== scope.requestId
+            || fact.projectRoot !== scope.projectRoot || fact.workspace !== scope.workspace) {
+            fail("Execution receipt does not belong to the selected request and workspace");
+        }
+    }
+}
+function validateSnapshot(snapshot, flow, scope, receipts) {
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)
+        || Object.keys(snapshot).some(key => !["schema_id", "scope", "settings", "profiles"].includes(key))
+        || ["schema_id", "scope", "settings", "profiles"].some(key => !Object.hasOwn(snapshot, key))
+        || snapshot.schema_id !== "dd-flow/frozen-execution@1"
+        || !snapshot.scope || typeof snapshot.scope !== "object" || Array.isArray(snapshot.scope)
+        || !scope || [scope.requestId, scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !value.trim())
+        || hybridDigest(snapshot.scope) !== hybridDigest(scope))
+        fail("Invalid frozen execution identity");
+    const content = { schema_id: "dd-flow/profile-settings@1", profiles: snapshot.profiles, aliases: {}, default_profile: null };
+    const profiles = { ...content, revision: hybridDigest(content) };
+    const issues = validateHybridContract("execution-settings", snapshot.settings, {
+        descriptor: flow.descriptor, descriptorSha256: flow.sha256, profileSettings: profiles, receipts
+    });
+    if (issues.length)
+        fail("Frozen execution violates the admitted descriptor or profile policy", issues);
+    const settings = snapshot.settings;
+    if (snapshot.profiles.length !== settings.profiles.length
+        || snapshot.profiles.some(profile => !settings.profiles.some(reference => reference.id === profile.id && reference.revision === profile.revision))) {
+        fail("Frozen profile bytes and revision inventory differ");
+    }
+    for (const stage of flow.descriptor.stages) {
+        if (!Object.hasOwn(settings.stage_profiles, stage.id))
+            fail("Every declared stage must have an explicit frozen route");
+    }
+    scopedReceipts(settings, scope, receipts);
+}
+/** Separate from SDLC settings: no plan review, merge, bootstrap command or stop target. */
+export class FrozenGenericExecution {
+    sha256;
+    settings;
+    #snapshot;
+    #flow;
+    constructor(snapshot, flow) {
+        freeze(snapshot);
+        this.#snapshot = snapshot;
+        this.#flow = flow;
+        this.settings = snapshot.settings;
+        this.sha256 = hybridDigest(snapshot);
+        Object.freeze(this);
+    }
+    /** Pure selection from one admitted operator snapshot; never reread it during a RUN. */
+    static prepare(flow, operatorSettings, selection, scope, receipts = new Map()) {
+        const issues = validateHybridContract("profile-settings", operatorSettings);
+        if (issues.length)
+            fail("Operator profiles cannot be frozen", issues);
+        if (!selection || typeof selection !== "object" || Array.isArray(selection)
+            || Object.keys(selection).some(key => !["rootProfile", "stageProfiles", "workProfiles", "execution", "stageSessionMode", "attachedSessionReceipt", "delegation"].includes(key))) {
+            fail("Unsupported execution selection");
+        }
+        if (!["mb-init", "mb-upgrade"].includes(flow.descriptor.id)
+            && (selection.execution === undefined || selection.stageSessionMode === undefined || selection.delegation === undefined)) {
+            fail("Non-memory flows must supply their own execution defaults explicitly");
+        }
+        let rootSelection = selection.rootProfile;
+        if (rootSelection !== undefined && typeof rootSelection !== "string") {
+            const profile = prepareOperatorProfile(rootSelection);
+            const existing = operatorSettings.profiles.find(entry => entry.id === profile.id);
+            if (Object.hasOwn(operatorSettings.aliases, profile.id) || existing && existing.revision !== hybridDigest(profile))
+                fail("Operation-only profile conflicts with an existing ID or alias");
+            const { revision: _revision, ...content } = structuredClone(operatorSettings);
+            void _revision;
+            if (!existing)
+                content.profiles.push({ id: profile.id, revision: hybridDigest(profile), profile });
+            operatorSettings = { ...content, revision: hybridDigest(content) };
+            rootSelection = profile.id;
+        }
+        const profiles = new Map();
+        const resolve = (id) => {
+            const profile = prepareOperatorProfile(resolveOperatorProfile(operatorSettings, id));
+            profiles.set(profile.id, { id: profile.id, revision: hybridDigest(profile), profile });
+            return profile.id;
+        };
+        const root = resolve(rootSelection);
+        const stages = Object.create(null);
+        if (selection.stageProfiles !== undefined && (!selection.stageProfiles || typeof selection.stageProfiles !== "object" || Array.isArray(selection.stageProfiles))) {
+            fail("Stage profile selection must be an object");
+        }
+        for (const id of Object.keys(selection.stageProfiles ?? {}))
+            flow.stage(id);
+        for (const stage of flow.descriptor.stages) {
+            const selected = selection.stageProfiles && Object.hasOwn(selection.stageProfiles, stage.id) ? selection.stageProfiles[stage.id] : undefined;
+            if (selected !== undefined && typeof selected !== "string")
+                fail("Stage profile selection must name a profile");
+            stages[stage.id] = selected === undefined ? root : resolve(selected);
+        }
+        if (selection.workProfiles !== undefined && (!Array.isArray(selection.workProfiles) || selection.workProfiles.some(id => typeof id !== "string"))) {
+            fail("Approved Work profiles must be a list of profile IDs");
+        }
+        const works = [...new Set((selection.workProfiles ?? []).map(id => resolve(id)))];
+        const delegation = selection.delegation;
+        if (delegation !== undefined && (!delegation || typeof delegation !== "object" || Array.isArray(delegation)
+            || Object.keys(delegation).some(key => !["mode", "max_parallel", "nativeCapacityReceipt"].includes(key))))
+            fail("Unsupported delegation selection");
+        const settings = {
+            schema_id: "dd-flow/execution-settings@1", flow_id: flow.descriptor.id, descriptor_sha256: flow.sha256,
+            execution: selection.execution ?? "managed", attached_session_receipt: selection.attachedSessionReceipt ?? null,
+            stage_session_mode: selection.stageSessionMode ?? "new_session",
+            delegation: { mode: delegation?.mode ?? "external", max_parallel: delegation?.max_parallel ?? 1, native_capacity_receipt: delegation?.nativeCapacityReceipt ?? null },
+            profiles: [...profiles.values()].map(({ id, revision }) => ({ id, revision })), root_profile: root,
+            stage_profiles: stages, work_profiles: works
+        };
+        const snapshot = structuredClone({ schema_id: "dd-flow/frozen-execution@1", scope, settings, profiles: [...profiles.values()] });
+        validateSnapshot(snapshot, flow, scope, receipts);
+        return new FrozenGenericExecution(snapshot, flow);
+    }
+    /** Admission uses retained bytes and trusted scope/receipts, never the current operator settings. */
+    static restore(snapshot, expectedSha256, flow, scope, receipts = new Map()) {
+        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || hybridDigest(snapshot) !== expectedSha256)
+            fail("Frozen execution identity changed");
+        const retained = structuredClone(snapshot);
+        validateSnapshot(retained, flow, scope, receipts);
+        return new FrozenGenericExecution(retained, flow);
+    }
+    snapshot() { return structuredClone(this.#snapshot); }
+    stage(id) {
+        this.#flow.stage(id);
+        return { profile: this.profile(this.settings.stage_profiles[id]), session_mode: this.settings.stage_session_mode };
+    }
+    work(stage, profileId) {
+        const coordinator = this.stage(stage).profile;
+        const id = profileId ?? coordinator.id;
+        if (id !== coordinator.id && !this.settings.work_profiles.includes(id))
+            fail("Work profile is not approved for this RUN");
+        const worker = this.profile(id);
+        if (this.settings.delegation.mode === "native" && !sameSessionProfile(coordinator, worker))
+            fail("Native Work cannot change execution profile");
+        return { coordinator, worker, delegation: structuredClone(this.settings.delegation) };
+    }
+    profile(id) {
+        const value = this.#snapshot.profiles.find(entry => entry.id === id);
+        if (!value)
+            fail("Profile is absent from the frozen execution inventory");
+        return structuredClone(value.profile);
+    }
+}

package/dist/services/harness-adapter.js

@@ -10,9 +10,35 @@ import { canonicalNativeOperation, nativeOperationWait } from "../harness-runtim
 import { readOperationProgress, readOperationRecord, readOperationWaiting, suspendOperationClock } from "../harness-runtime/lib/operation-progress.mjs";
 import { recoverDaemonReply } from "../harness-runtime/lib/daemon-observation.mjs";
 import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+import { readBoundedReleaseFile } from "./release-source.js";
 const maxAdapterOutputBytes = 1_000_000;
 /** Native hooks need a real executable, not a PATH-dependent shell expression. */
-export function prepareHarnessFlowExecutable(context, stateDir) {
+export function prepareHarnessFlowExecutable(context, stateDir, engine) {
+    // Native login shells rewrite search paths. The owned SDK must execute with
+    // the same original paths as its controller, not merely hash them as equal.
+    const searchPaths = ["PATH", "FPATH", "INFOPATH"].map(name => context.env[name] === undefined
+        ? `delete process.env.${name};\n` : `process.env.${name} = ${JSON.stringify(context.env[name])};\n`).join("");
+    if (engine) {
+        const executable = path.join(stateDir, "dd-flow");
+        const contents = `#!${engine.nodeExecutable}\n${searchPaths}process.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\nprocess.env.DD_FLOW_ENGINE_MODE = "1";\nprocess.env.DD_FLOW_ENGINE_HOME = ${JSON.stringify(engine.manifest().snapshot_root)};\nconst { spawnSync } = await import("node:child_process");\nconst child = spawnSync(${JSON.stringify(engine.nodeExecutable)}, [${JSON.stringify(engine.entrypoint)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (child.error) throw child.error;\nif (child.signal) process.kill(process.pid, child.signal);\nprocess.exit(child.status ?? 1);\n`;
+        try {
+            fs.writeFileSync(executable, contents, { flag: "wx", mode: 0o700 });
+        }
+        catch (error) {
+            const conflict = () => new AppError("harness_runtime_binding_conflict", "Launch runtime executable already has different or linked content", 1, { path: executable });
+            if (error.code !== "EEXIST")
+                throw conflict();
+            try {
+                const stat = fs.lstatSync(executable);
+                if (!stat.isFile() || stat.nlink !== 1 || readBoundedReleaseFile(executable, 64 * 1024).toString("utf8") !== contents)
+                    throw conflict();
+            }
+            catch {
+                throw conflict();
+            }
+        }
+        return executable;
+    }
     const configured = context.env.DD_FLOW_BIN;
     if (configured !== undefined) {
         if (!path.isAbsolute(configured) || !fs.existsSync(configured))
@@ -32,7 +58,7 @@ export function prepareHarnessFlowExecutable(context, stateDir) {
     const dispatch = configured
         ? `const { spawnSync } = await import("node:child_process");\nconst child = spawnSync(${JSON.stringify(configured)}, process.argv.slice(2), { stdio: "inherit", env: process.env });\nif (child.error) throw child.error;\nif (child.signal) process.kill(process.pid, child.signal);\nprocess.exit(child.status ?? 1);\n`
         : `await import(${JSON.stringify(pathToFileURL(entry).href)});\n`;
-    const contents = `#!${process.execPath}\nprocess.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\n${dispatch}`;
+    const contents = `#!${process.execPath}\n${searchPaths}process.env.DD_FLOW_HOME = ${JSON.stringify(context.ddFlowHome)};\n${dispatch}`;
     try {
         fs.writeFileSync(executable, contents, { flag: "wx", mode: 0o700 });
     }

package/dist/services/hooks.js

@@ -9,6 +9,8 @@ import { parseJsonObject } from "../shared/json.js";
 import { canonicalPath, ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { resolveWorkReference } from "../storage/work-references.js";
 import { appendAudit } from "./audit.js";
+import { memoryRepairAssignedHookCwd } from "./memory-repair-physical-binding.js";
+import { memoryNativeReviewAssignedHookCwd } from "./memory-native-review-copy.js";
 import { prepareTextFile, prepareJsonText, prepareError } from "../cli/input-preparation.js";
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { assertRecoveryHookCurrent } from "./run-recovery.js";
@@ -714,6 +716,11 @@ export function handleDroidEvent(context, input) {
     return handleControlledToolEvent(context, input, event, "droid-cli");
 }
 /** Stable project identity is not the native Session's execution workspace. */
+function requiresAssignedLifecycleCwd(facts) {
+    // Settlement and user interaction address the retained RUN explicitly;
+    // their tools/checks receive owned paths, not the shell's working directory.
+    return !facts || !["stage_finish", "stage_pause", "stage_resume", "work_finish", "work_fail"].includes(facts.invocation.operation);
+}
 function assignedLifecycleCwd(context, projectRoot, facts, providerSessionId, command, observedCwd, identity, harness) {
     const auxiliary = continuationCommand(command);
     if ((!facts && !auxiliary) || facts?.analysis.supported === false)
@@ -723,7 +730,9 @@ function assignedLifecycleCwd(context, projectRoot, facts, providerSessionId, co
     const issuedRunId = facts && !facts.runId && !facts.workId && !facts.bootstrapStageStart && constraint ? observedLifecycleInvocation(context, command, constraint, identity ? { identity } : undefined)?.scope.runId : null;
     if (facts?.invocation.operation.startsWith("stage_") && !facts.bootstrapStageStart && !facts.runId && !issuedRunId)
         throw new AppError("invocation_assignment_missing", "Short lifecycle call has no unique issued RUN assignment; its workspace cannot be inferred", 1, { phase: "prepare", effect: "no_effect", recoverable: false });
-    const expected = controlledLifecycleCwd(context, projectRoot, facts, providerSessionId, auxiliary, issuedRunId);
+    if (!requiresAssignedLifecycleCwd(facts))
+        return undefined;
+    const expected = controlledLifecycleCwd(context, projectRoot, facts, providerSessionId, auxiliary, issuedRunId, observedCwd);
     // Unknown CLI targets have no assigned workspace. Recording their native
     // observation must not turn the stable identity root into cwd authority.
     if (!expected)
@@ -737,7 +746,7 @@ function assignedLifecycleCwd(context, projectRoot, facts, providerSessionId, co
     // physical process directory, rather than inventing native observation.
     return expected;
 }
-function controlledLifecycleCwd(context, projectRoot, facts, providerSessionId, auxiliary, issuedRunId) {
+function controlledLifecycleCwd(context, projectRoot, facts, providerSessionId, auxiliary, issuedRunId, observedCwd) {
     if (facts?.bootstrapStageStart)
         return projectRoot;
     const project = context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]);
@@ -768,6 +777,14 @@ function controlledLifecycleCwd(context, projectRoot, facts, providerSessionId,
     if (!run)
         return undefined; // Hook ingress does not validate a mistyped CLI target.
     if (work) {
+        const repair = memoryRepairAssignedHookCwd(context, { projectRoot, projectId: project.id, runId: run.id,
+            workId: work.work_id, providerSessionId, ...(observedCwd ? { observedCwd: resolveProjectRoot(observedCwd) } : {}),
+            ...(facts?.invocation.expectedCwd ? { literalExecutionCwd: resolveProjectRoot(facts.invocation.expectedCwd) } : {}) });
+        if (repair)
+            return resolveProjectRoot(repair.root);
+        const nativeReview = memoryNativeReviewAssignedHookCwd(context, { projectId: project.id, runId: run.id, workId: work.work_id, providerSessionId });
+        if (nativeReview)
+            return resolveProjectRoot(nativeReview);
         // PROTOCOLIZE provisions the feature checkout after its coordinator
         // Session has launched in the stable project root. Its transition Work
         // must keep that physical route until the Stage is complete. Child Works
@@ -862,12 +879,13 @@ function handleControlledToolEvent(context, input, event, harness) {
     }
     // These controlled platforms additionally qualify their native launch
     // route against the stable project root when no CLI target is assigned.
-    const expectedCwd = shellRefusal ? observedCwd : controlledLifecycleCwd(context, expectedRoot, lifecycle, providerSessionId, auxiliary, issuedRunId) ?? expectedRoot;
-    const executionRoute = shellRefusal ? undefined : lifecycle?.invocation.expectedCwd ?? auxiliary?.expectedCwd;
+    const workspaceBound = requiresAssignedLifecycleCwd(lifecycle);
+    const expectedCwd = shellRefusal || !workspaceBound ? observedCwd : controlledLifecycleCwd(context, expectedRoot, lifecycle, providerSessionId, auxiliary, issuedRunId, observedCwd) ?? expectedRoot;
+    const executionRoute = shellRefusal || !workspaceBound ? undefined : lifecycle?.invocation.expectedCwd ?? auxiliary?.expectedCwd;
     if (executionRoute && resolveProjectRoot(executionRoute) !== expectedCwd) {
         throw new AppError(`${errorPrefix}_directory_mismatch`, "Literal shell cd route does not match the assigned lifecycle workspace", 1, { expected: expectedCwd, actual: executionRoute, actual_provenance: "shell_literal_route", effect: "no_effect", recoverable: false });
     }
-    if (!executionRoute && observedCwd !== expectedCwd) {
+    if (workspaceBound && !executionRoute && observedCwd !== expectedCwd) {
         throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} ${agy ? "launch route" : "Session directory"} does not match the assigned execution workspace`, 1, { expected: expectedCwd, actual: observedCwd, effect: "no_effect", recoverable: false, ...(agy ? { actual_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}) });
     }
     const bootstrapStageStart = !shellRefusal && lifecycle?.bootstrapStageStart;
@@ -906,7 +924,7 @@ function handleControlledToolEvent(context, input, event, harness) {
         let inserted = false;
         const receipt = observeLifecycleInvocation(context, {
             currentEventKey: baseKey,
-            command, harness, projectId: project.id, ...(!shellRefusal ? { executionCwd: expectedCwd } : {}), identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
+            command, harness, projectId: project.id, ...(!shellRefusal && workspaceBound ? { executionCwd: expectedCwd } : {}), identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
             recordReceipt: scope => { inserted = persist(scope); return baseKey; }
         });
         const admitted = { ...result(inserted), ...lifecycleObservationResult(receipt), ...(receipt.invocationId ? { invocation_id: receipt.invocationId } : {}) };

package/dist/services/hybrid-contracts.js

@@ -197,7 +197,8 @@ export function validateHybridContract(name, input, context = {}) {
             if (delegation.native_capacity_receipt !== null) {
                 const fact = context.receipts?.get(string(record(delegation.native_capacity_receipt).sha256));
                 if (!fact || !root || fact.harness !== record(root.profile).harness || fact.profileRevision !== root.revision
-                    || !Number.isInteger(fact.capacity) || fact.capacity < Number(delegation.max_parallel))
+                    || !Number.isInteger(fact.capacity) || fact.capacity < 1 || fact.capacity > 15
+                    || fact.capacity < Number(delegation.max_parallel))
                     fail("native_capacity_scope_mismatch", "/delegation");
             }
         }
@@ -213,6 +214,14 @@ export function validateHybridContract(name, input, context = {}) {
         const workspace = record(data.workspace), execution = record(data.effective_execution), storage = record(data.storage);
         if (data.request_id !== expected.requestId || data.project_root !== expected.projectRoot || workspace.path !== expected.workspace || data.baseline_sha256 !== expected.baselineSha256)
             fail("foreign_bootstrap_identity");
+        if (data.schema_id === "dd-flow/memory-bootstrap-receipt@2") {
+            const git = expected.workspaceGit;
+            if (!git)
+                fail("missing_bootstrap_git_observation");
+            else if (workspace.repository !== git.repository || workspace.branch !== git.branch || workspace.commit !== git.commit
+                || workspace.git_state !== (git.commit === null ? "unborn" : "committed"))
+                fail("foreign_bootstrap_git_state");
+        }
         if (execution.engine_sha256 !== expected.engineSha256 || execution.canon_sha256 !== expected.canonSha256)
             fail("foreign_execution_identity");
         receipt(storage.compatibility_receipt, "storage-compatibility", true);
@@ -289,6 +298,16 @@ export function validateHybridContract(name, input, context = {}) {
             }
         };
         const descriptor = loaded(data.descriptor), settings = loaded(data.execution_settings), profiles = loaded(data.profile_settings);
+        // Execution receipts are evidence references, not just trusted facts. They
+        // must survive reopening the RUN inside the same frozen blob inventory.
+        for (const reference of [record(settings).attached_session_receipt,
+            record(record(settings).delegation).native_capacity_receipt]) {
+            if (reference === null || reference === undefined)
+                continue;
+            const ref = record(reference);
+            if (inventory.get(string(ref.path)) !== ref.sha256)
+                fail("unlisted_bundle_reference");
+        }
         const binding = loaded(data.engine_binding);
         const bindingSchema = JSON.parse(fs.readFileSync(new URL("../schemas/run-engine-binding.schema.json", import.meta.url), "utf8"));
         const bindingValidator = new Ajv({ strict: false, validateFormats: false }).compile(bindingSchema);
@@ -342,7 +361,9 @@ export function validateHybridShape(name, input) {
     if (!hybridContractRegistry.has(name)) {
         return [{ gate: "shape", code: "unknown_contract_name", path: "/" }];
     }
-    const schemaUrl = new URL(`../schemas/${name}.schema.json`, import.meta.url);
+    const versionedName = name === "memory-bootstrap-receipt" && input !== null && typeof input === "object"
+        && input.schema_id === "dd-flow/memory-bootstrap-receipt@2" ? "memory-bootstrap-receipt-v2" : name;
+    const schemaUrl = new URL(`../schemas/${versionedName}.schema.json`, import.meta.url);
     const schema = JSON.parse(fs.readFileSync(schemaUrl, "utf8"));
     const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false });
     const validate = ajv.compile(schema);
@@ -388,7 +409,14 @@ export function validateFlowDescriptor(input, context) {
             if (field === "result_schema") {
                 try {
                     const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-                    new Ajv2020({ strict: true, validateFormats: false }).compile(schema);
+                    const draft = schema.$schema;
+                    // Existing SDLC schemas require parent properties inside conditional
+                    // subschemas. Keep all other strict checks without rejecting those
+                    // valid JSON Schema contracts through Ajv's strictRequired heuristic.
+                    const ajv = draft === "http://json-schema.org/draft-07/schema#"
+                        ? new Ajv({ strict: true, strictRequired: false, validateFormats: false })
+                        : new Ajv2020({ strict: true, strictRequired: false, validateFormats: false });
+                    ajv.compile(schema);
                 }
                 catch {
                     fail("invalid_result_schema", `/stages/${index}/${field}`);

package/dist/services/ids.js

@@ -77,9 +77,37 @@ function parseEntityKind(value) {
 function databaseIds(context, table, idField, type, projectId) {
     if (!projectId)
         return [];
-    return context.db
+    const ids = context.db
         .all(`SELECT ${idField} AS id FROM ${table} WHERE project_id = ? AND ${idField} LIKE ?`, [projectId, `${type}-%`])
         .map((row) => row.id);
+    if (type === "RUN") {
+        for (const row of context.db.all("SELECT json_extract(payload_json,'$.run_id') AS id FROM audit_events WHERE project_id=? AND event_type IN ('memory.init_run_allocation_intent','memory.init_run_allocation')", [projectId])) {
+            try {
+                if (typeof row.id !== "string")
+                    throw new Error("Invalid reserved RUN id");
+                const parsed = parseFullEntityId(row.id), sequence = Number(parsed.shortId.slice(4));
+                if (parsed.type !== "RUN" || !Number.isSafeInteger(sequence) || sequence < 1)
+                    throw new Error("Invalid reserved RUN id");
+            }
+            catch {
+                throw new AppError("memory_init_run_allocation_invalid", "Retained RUN reservation identity is invalid", 1, { effect: "no_effect" });
+            }
+            ids.push(row.id);
+        }
+    }
+    return ids;
+}
+/** Includes retained request reservations, even before their RUN row exists. */
+export function nextRunId(context, projectId, slug) {
+    const used = new Set();
+    for (const id of databaseIds(context, "runs", "id", "RUN", projectId))
+        addSequence(used, id, "RUN");
+    let max = 0;
+    for (const sequence of used)
+        max = Math.max(max, sequence);
+    if (!Number.isSafeInteger(max + 1))
+        throw new AppError("validation", "RUN sequence cannot be represented safely", 1, { effect: "no_effect" });
+    return formatFullId("RUN", max + 1, normalizeSlug(slug));
 }
 function filesystemIds(projectRoot, relativeRoot, type) {
     const root = path.join(projectRoot, relativeRoot);

package/dist/services/installation-lock.js

@@ -48,10 +48,13 @@ export function acquireInstallationLock(file, identity) {
         for (let attempt = 0; attempt < 3; attempt++) {
             try {
                 fs.linkSync(temporary, file);
-                return { token: owner.token, release: () => {
-                        const retained = readOwner(file);
-                        if (retained.token !== owner.token || retained.pid !== process.pid || retained.identity !== identity)
-                            refuse("lock_owner_changed");
+                const assertOwnership = () => {
+                    const retained = readOwner(file);
+                    if (retained.token !== owner.token || retained.pid !== process.pid || retained.identity !== identity)
+                        refuse("lock_owner_changed");
+                };
+                return { token: owner.token, assertOwnership, release: () => {
+                        assertOwnership();
                         fs.unlinkSync(file);
                     } };
             }

package/dist/services/installed-flow-source.js

@@ -0,0 +1,183 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { readSetupStatus } from "./setup.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { admitBundledFlow } from "./stage-handlers.js";
+const limit = 1024 * 1024;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("installed_flow_source_invalid", "Installed flow source is not the selected verified canon", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function directory(target) {
+    if (!fs.lstatSync(target).isDirectory())
+        refuse("unsafe_source_directory");
+}
+function containedFile(root, logical) {
+    if (!/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(logical)
+        || logical.split("/").some(part => part === "." || part === ".."))
+        refuse("unsafe_source_path");
+    let current = root;
+    for (const part of logical.split("/").slice(0, -1)) {
+        current = path.join(current, part);
+        directory(current);
+    }
+    return path.join(root, logical);
+}
+/** Initial RUN materialization input, not handler/engine/storage admission.
+ * Built-in memory flows live in the global canon, not the curated project pack.
+ * Existing RUNs must restore their retained bundle rather than call this reader.
+ */
+export class PreparedInstalledFlowSource {
+    sha256;
+    #home;
+    #installationSha256;
+    #flowId;
+    #descriptor;
+    #canon;
+    #blobs;
+    constructor(home, installationSha256, flowId, descriptor, canon, blobs) {
+        this.#home = home;
+        this.#installationSha256 = installationSha256;
+        this.#flowId = flowId;
+        this.#descriptor = descriptor;
+        this.#canon = canon;
+        this.#blobs = blobs;
+        this.sha256 = hybridDigest({ installation_sha256: installationSha256, canon, inventory: this.inventory() });
+        Object.freeze(this);
+    }
+    static fromInstalledRelease(home, expectedInstallationSha256, flowId) {
+        try {
+            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256) || flowId !== "mb-init")
+                refuse("invalid_selection");
+            const selected = readSetupStatus(home);
+            if (!selected.installation || selected.installation_readiness !== "installed")
+                refuse("installed_release_unavailable");
+            const installation = selected.installation;
+            if (installation.manifest_sha256 !== expectedInstallationSha256)
+                refuse("installation_selection_changed");
+            directory(installation.canon_root);
+            const roots = fs.readdirSync(installation.canon_root);
+            if (roots.length !== 1)
+                refuse("ambiguous_archive_root");
+            const canonRoot = path.join(installation.canon_root, roots[0]);
+            directory(canonRoot);
+            const dotRoot = path.join(canonRoot, ".memory-bank"), memoryRoot = fs.existsSync(dotRoot) ? dotRoot : canonRoot;
+            directory(memoryRoot);
+            const flowRoot = path.join(memoryRoot, "dd-flow");
+            directory(flowRoot);
+            const descriptorPath = `${flowId}/flow-descriptor.json`;
+            const bytes = readBoundedReleaseFile(containedFile(flowRoot, descriptorPath), limit);
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (validateHybridShape("flow-descriptor", value).length || value.id !== flowId || value.origin !== "canon"
+                || value.stages.length > 64)
+                refuse("invalid_descriptor");
+            const blobs = new Map([[descriptorPath, Buffer.from(bytes)]]), folded = new Map([[descriptorPath.toLowerCase(), descriptorPath]]);
+            let total = bytes.length;
+            for (const stage of value.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], existing = blobs.get(reference.path);
+                    if (existing) {
+                        if (hash(existing) !== reference.sha256)
+                            refuse("conflicting_source_reference");
+                        continue;
+                    }
+                    if (folded.has(reference.path.toLowerCase()))
+                        refuse("conflicting_source_path");
+                    const content = readBoundedReleaseFile(containedFile(flowRoot, reference.path), limit);
+                    if (!content.length || (total += content.length) > 32 * limit || hash(content) !== reference.sha256)
+                        refuse("source_bytes_changed");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    if (kind === "result_schema")
+                        JSON.parse(content.toString("utf8"));
+                    folded.set(reference.path.toLowerCase(), reference.path);
+                    blobs.set(reference.path, Buffer.from(content));
+                }
+            // Verify compressed/expanded archive identity again after collecting bytes.
+            // A coherent descriptor+prompt edit cannot become a new trusted selection.
+            const final = readSetupStatus(home);
+            if (final.installation_readiness !== "installed" || hybridDigest(final.installation) !== hybridDigest(installation))
+                refuse("source_changed_during_preparation");
+            return new PreparedInstalledFlowSource(home, expectedInstallationSha256, flowId, { path: descriptorPath, sha256: hash(bytes) }, { version: installation.manifest.canon.version, commit: installation.manifest.canon.commit, archive_sha256: installation.manifest.canon.archive.sha256 }, blobs);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("source_unavailable_or_changed");
+        }
+    }
+    descriptorReference() { return { ...this.#descriptor }; }
+    installationSha256() { return this.#installationSha256; }
+    snapshot() {
+        return { schema_id: "dd-flow/installed-flow-source@1", installation_sha256: this.#installationSha256,
+            descriptor: this.descriptorReference(), canon: this.canonProvenance(),
+            blobs: [...this.#blobs].map(([logical, bytes]) => ({ path: logical, base64: bytes.toString("base64") })) };
+    }
+    /** Copied source restoration only. expectedSha256 must come from independent
+     * request custody, not from the same input. This does not verify a new release
+     * or admit its engine/storage; those remain the bootstrap owner's duties.
+     */
+    static restoreRetained(input, expectedSha256) {
+        try {
+            if (!input || typeof input !== "object" || Array.isArray(input) || typeof expectedSha256 !== "string"
+                || !/^[a-f0-9]{64}$/.test(expectedSha256))
+                refuse("invalid_retained_source");
+            const value = input;
+            if (Object.keys(value).sort().join() !== "blobs,canon,descriptor,installation_sha256,schema_id"
+                || value.schema_id !== "dd-flow/installed-flow-source@1" || typeof value.installation_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.installation_sha256)
+                || !value.canon || Object.keys(value.canon).sort().join() !== "archive_sha256,commit,version"
+                || typeof value.canon.commit !== "string" || !/^[a-f0-9]{40}$/.test(value.canon.commit)
+                || typeof value.canon.archive_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.canon.archive_sha256)
+                || typeof value.canon.version !== "string" || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.canon.version)
+                || !value.descriptor || Object.keys(value.descriptor).sort().join() !== "path,sha256"
+                || value.descriptor.path !== "mb-init/flow-descriptor.json" || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
+                || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 129)
+                refuse("invalid_retained_source");
+            const blobs = new Map(), folded = new Set();
+            let total = 0;
+            for (const entry of value.blobs) {
+                if (!entry || Object.keys(entry).sort().join() !== "base64,path" || typeof entry.path !== "string"
+                    || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(entry.path)
+                    || entry.path.split("/").some(part => part === "." || part === "..")
+                    || folded.has(entry.path.toLowerCase()) || typeof entry.base64 !== "string" || entry.base64.length > 2 * limit)
+                    refuse("invalid_retained_source");
+                const content = Buffer.from(entry.base64, "base64");
+                if (!content.length || content.length > limit || content.toString("base64") !== entry.base64
+                    || (total += content.length) > 32 * limit)
+                    refuse("invalid_retained_source");
+                new TextDecoder("utf-8", { fatal: true }).decode(content);
+                folded.add(entry.path.toLowerCase());
+                blobs.set(entry.path, content);
+            }
+            const descriptor = blobs.get(value.descriptor.path);
+            if (!descriptor || hash(descriptor) !== value.descriptor.sha256)
+                refuse("retained_source_changed");
+            const result = new PreparedInstalledFlowSource(null, value.installation_sha256, "mb-init", { ...value.descriptor }, { ...value.canon }, blobs);
+            if (result.sha256 !== expectedSha256)
+                refuse("retained_source_changed");
+            result.resolveRegisteredFlow();
+            return result;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("invalid_retained_source");
+        }
+    }
+    canonProvenance() { return { ...this.#canon }; }
+    blobs() { return new Map([...this.#blobs].map(([logical, bytes]) => [logical, Buffer.from(bytes)])); }
+    inventory() { return [...this.#blobs].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) })).sort((a, b) => a.path.localeCompare(b.path, "en")); }
+    /** Production handler registry only: source declarations cannot register code. */
+    resolveRegisteredFlow() { return admitBundledFlow(this.#blobs.get(this.#descriptor.path), this.#descriptor.sha256, this.#blobs); }
+    /** Initial materialization only, outside SQL writers. */
+    revalidate() {
+        if (this.#home === null) {
+            PreparedInstalledFlowSource.restoreRetained(this.snapshot(), this.sha256);
+            return;
+        }
+        if (PreparedInstalledFlowSource.fromInstalledRelease(this.#home, this.#installationSha256, this.#flowId).sha256 !== this.sha256)
+            refuse("source_changed_after_preparation");
+    }
+}