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

package/dist/services/hybrid-contracts.js

@@ -0,0 +1,483 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { Ajv } from "ajv/dist/ajv.js";
+/** Static E1 contracts only. No ingress, dispatch or runtime defaults are changed. */
+export const hybridContractNames = [
+    "release-manifest", "harness-catalog", "model-catalog", "discovery-result",
+    "profile-settings", "flow-descriptor", "execution-settings",
+    "memory-bootstrap-receipt", "execution-bundle"
+];
+const hybridContractRegistry = new Set(hybridContractNames);
+const record = (input) => input;
+const list = (input) => input;
+const string = (input) => input;
+/** Deterministic JSON content identity, not a signature or secret-derived hash. */
+export function hybridDigest(input) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value !== null && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b, "en"))
+                .map(([key, child]) => [key, canonical(child)]));
+        }
+        return value;
+    };
+    return createHash("sha256").update(JSON.stringify(canonical(input))).digest("hex");
+}
+/** E1 standalone validation. Runtime ingress must explicitly integrate it in E2/E3. */
+export function validateHybridContract(name, input, context = {}) {
+    if (name === "flow-descriptor") {
+        if (!context.descriptorContext)
+            return [{ gate: "context", code: "missing_descriptor_context", path: "/" }];
+        return validateFlowDescriptor(input, context.descriptorContext);
+    }
+    const shape = validateHybridShape(name, input);
+    if (shape.length)
+        return shape;
+    const data = record(input), issues = [];
+    const fail = (code, path = "/") => issues.push({ gate: "context", code, path });
+    const seen = new Set();
+    const unique = (key, path) => {
+        if (seen.has(key))
+            fail("duplicate_identity", path);
+        seen.add(key);
+    };
+    const receipt = (reference, kind, required) => {
+        if (reference === null) {
+            if (required)
+                fail("missing_receipt", `/receipts/${kind}`);
+            return;
+        }
+        const ref = record(reference), fact = context.receipts?.get(string(ref.sha256));
+        if (!fact || fact.kind !== kind) {
+            fail("unverified_receipt", `/receipts/${kind}`);
+            return;
+        }
+        const expected = context.bootstrapIdentity;
+        if (expected && (fact.requestId !== expected.requestId || fact.projectRoot !== expected.projectRoot || fact.workspace !== expected.workspace)) {
+            fail("foreign_receipt", `/receipts/${kind}`);
+        }
+    };
+    if (name === "release-manifest") {
+        const canon = record(data.canon), engine = record(data.engine);
+        if (data.version !== canon.version)
+            fail("release_canon_version_mismatch");
+        const artifacts = [record(canon.archive), record(engine.archive)];
+        if (artifacts[0].url === artifacts[1].url || artifacts[0].sha256 === artifacts[1].sha256)
+            fail("conflicting_artifact_identity");
+        for (const value of list(data.qualified_routes)) {
+            const route = record(value);
+            unique([route.platform, route.harness, route.flow, route.delegation].join("/"), "/qualified_routes");
+            receipt(route.evidence, "route-qualification", true);
+        }
+    }
+    else if (name === "harness-catalog") {
+        const families = new Set(["codex", "zcode", "agy", "opencode", "grok", "droid"]);
+        for (const value of list(data.entries)) {
+            const entry = record(value), id = string(entry.id);
+            unique(id, "/entries");
+            families.delete(id);
+            if (entry.probe_module !== `${id}-discovery`)
+                fail("foreign_probe_module", "/entries");
+        }
+        if (families.size)
+            fail("missing_harness_family", "/entries");
+    }
+    else if (name === "model-catalog") {
+        for (const value of list(data.entries)) {
+            const entry = record(value), qualification = record(entry.qualification);
+            unique([entry.harness, entry.provider, entry.model].join("/"), "/entries");
+            if (qualification.scope === "seed-only") {
+                if (qualification.evidence !== null)
+                    fail("seed_has_qualification_receipt", "/entries");
+            }
+            else
+                receipt(qualification.evidence, `model-${qualification.scope}-qualification`, true);
+        }
+    }
+    else if (name === "discovery-result") {
+        if (data.probe_scope === "live")
+            receipt(data.live_authorization_receipt, "live-probe-authorization", true);
+        else if (data.live_authorization_receipt !== null)
+            fail("unexpected_live_authorization");
+        for (const value of list(data.entries)) {
+            const entry = record(value);
+            unique(string(entry.harness), "/entries");
+            const selected = list(entry.candidates).filter(candidate => record(candidate).selected === true);
+            if (selected.length > 1)
+                fail("ambiguous_selected_executable", "/entries");
+            if (entry.installed === "yes" && selected.length !== 1)
+                fail("missing_selected_executable", "/entries");
+            if (entry.installed === "no" && (selected.length || entry.compatible === "yes" || entry.protocol === "verified" || entry.auth === "verified" || entry.qualified === "yes"))
+                fail("contradictory_discovery_facts", "/entries");
+            if (entry.auth === "verified" || entry.protocol === "verified" || entry.qualified === "yes") {
+                if (data.probe_scope === "static" || list(entry.evidence).length === 0)
+                    fail("unsupported_verified_fact", "/entries");
+                for (const evidence of list(entry.evidence))
+                    receipt(evidence, "discovery-observation", true);
+            }
+        }
+    }
+    else if (name === "profile-settings") {
+        const profiles = new Map();
+        for (const value of list(data.profiles)) {
+            const entry = record(value), profile = record(entry.profile), id = string(entry.id);
+            unique(id, "/profiles");
+            profiles.set(id, profile);
+            if (profile.id !== id || hybridDigest(profile) !== entry.revision)
+                fail("profile_revision_mismatch", "/profiles");
+        }
+        const aliases = record(data.aliases);
+        for (const [alias, target] of Object.entries(aliases)) {
+            if (!profiles.has(string(target)))
+                fail("dangling_or_chained_alias", `/aliases/${alias}`);
+            if (profiles.has(alias))
+                fail("alias_id_collision", `/aliases/${alias}`);
+        }
+        if (data.default_profile !== null && !profiles.has(string(data.default_profile)) && !Object.hasOwn(aliases, string(data.default_profile)))
+            fail("dangling_default", "/default_profile");
+        const content = Object.fromEntries(Object.entries(data).filter(([key]) => key !== "revision"));
+        if (hybridDigest(content) !== data.revision)
+            fail("settings_revision_mismatch", "/revision");
+    }
+    else if (name === "execution-settings") {
+        if (!context.descriptor || !context.descriptorSha256 || !context.profileSettings) {
+            fail("missing_execution_context");
+            return issues;
+        }
+        const descriptor = record(context.descriptor), settings = record(context.profileSettings);
+        if (validateHybridShape("flow-descriptor", descriptor).length || validateHybridContract("profile-settings", settings).length) {
+            fail("invalid_execution_context");
+            return issues;
+        }
+        if (data.flow_id !== descriptor.id || data.descriptor_sha256 !== context.descriptorSha256)
+            fail("foreign_descriptor");
+        const available = new Map(list(settings.profiles).map(value => { const entry = record(value); return [string(entry.id), entry]; }));
+        const frozen = new Set();
+        for (const value of list(data.profiles)) {
+            const profile = record(value), id = string(profile.id);
+            unique(id, "/profiles");
+            frozen.add(id);
+            if (!available.has(id) || available.get(id).revision !== profile.revision)
+                fail("foreign_profile_revision", "/profiles");
+        }
+        const stageIds = new Set(list(descriptor.stages).map(value => string(record(value).id)));
+        for (const stage of Object.keys(record(data.stage_profiles)))
+            if (!stageIds.has(stage))
+                fail("foreign_stage", `/stage_profiles/${stage}`);
+        const routes = [data.root_profile, ...Object.values(record(data.stage_profiles)), ...list(data.work_profiles)].map(string);
+        for (const id of routes)
+            if (!frozen.has(id))
+                fail("unapproved_profile", "/routing");
+        if (data.execution === "attached")
+            receipt(data.attached_session_receipt, "attached-session-binding", true);
+        else if (data.attached_session_receipt !== null)
+            fail("unexpected_attached_binding");
+        const delegation = record(data.delegation);
+        const root = available.get(string(data.root_profile));
+        const sameProfile = (id) => {
+            const entry = available.get(id);
+            if (!entry || !root)
+                return false;
+            const meaningful = (value) => Object.fromEntries(Object.entries(record(value)).filter(([key]) => key !== "id"));
+            return hybridDigest(meaningful(entry.profile)) === hybridDigest(meaningful(root.profile));
+        };
+        if (data.stage_session_mode === "same_session") {
+            for (const route of Object.values(record(data.stage_profiles)).map(string)) {
+                if (!sameProfile(route))
+                    fail("same_session_profile_override", "/stage_profiles");
+            }
+        }
+        if (delegation.mode === "native") {
+            receipt(delegation.native_capacity_receipt, "native-capacity", true);
+            for (const id of routes)
+                if (!sameProfile(id))
+                    fail("native_profile_override", "/routing");
+            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 < 1 || fact.capacity > 15
+                    || fact.capacity < Number(delegation.max_parallel))
+                    fail("native_capacity_scope_mismatch", "/delegation");
+            }
+        }
+        else if (delegation.native_capacity_receipt !== null)
+            fail("unexpected_native_capacity");
+    }
+    else if (name === "memory-bootstrap-receipt") {
+        const expected = context.bootstrapIdentity;
+        if (!expected) {
+            fail("missing_bootstrap_context");
+            return issues;
+        }
+        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);
+        const noOp = storage.route === "verified-no-op";
+        if (noOp) {
+            if (storage.outcome !== "no-op")
+                fail("invalid_no_op_outcome");
+            for (const field of ["drain_receipt", "backup_receipt", "plan_receipt", "apply_receipt", "verification_receipt"])
+                if (storage[field] !== null)
+                    fail("no_op_has_migration_effect");
+        }
+        else if (storage.outcome === "applied") {
+            for (const [field, kind] of [["drain_receipt", "writer-drain"], ["backup_receipt", "storage-backup"], ["plan_receipt", "storage-plan"], ["apply_receipt", "storage-apply"], ["verification_receipt", "storage-verification"]])
+                receipt(storage[field], kind, true);
+        }
+        if (data.readiness === "ready" && !(noOp || storage.outcome === "applied"))
+            fail("storage_not_ready");
+        if (data.flow_id === "mb-upgrade" && data.project_current === null)
+            fail("missing_upgrade_baseline");
+        for (const value of list(data.effects)) {
+            const effect = record(value);
+            receipt(effect.receipt, string(effect.kind), true);
+            if (effect.kind === "storage-apply" && (noOp || storage.outcome !== "applied"))
+                fail("undeclared_storage_effect");
+        }
+    }
+    else if (name === "execution-bundle") {
+        if (!context.blobs || !context.engineChecksum || !context.engineBindingSha256 || !context.engineManifestSha256 || !context.bundleProvenance || !context.descriptorSha256
+            || typeof context.bundleProjectRoot !== "string" || context.bundleProjectRoot.length === 0) {
+            fail("missing_bundle_context");
+            return issues;
+        }
+        if (record(data.descriptor).sha256 !== context.descriptorSha256)
+            fail("foreign_bundle_descriptor", "/descriptor");
+        if (hybridDigest(data.canon) !== hybridDigest(context.bundleProvenance.canon))
+            fail("foreign_bundle_canon", "/canon");
+        if (hybridDigest(data.project_pack) !== hybridDigest(context.bundleProvenance.project_pack))
+            fail("foreign_bundle_project_pack", "/project_pack");
+        const memoryFlow = data.flow_id === "mb-init" || data.flow_id === "mb-upgrade";
+        if (memoryFlow && context.bootstrapIdentity?.projectRoot !== context.bundleProjectRoot)
+            fail("foreign_bootstrap_identity", "/bootstrap_receipts");
+        if (memoryFlow && list(data.bootstrap_receipts).length === 0)
+            fail("missing_memory_bootstrap", "/bootstrap_receipts");
+        if (!memoryFlow && list(data.bootstrap_receipts).length > 0)
+            fail("foreign_memory_bootstrap", "/bootstrap_receipts");
+        const inventory = new Map();
+        for (const value of list(data.inventory)) {
+            const ref = record(value), path = string(ref.path);
+            unique(path, "/inventory");
+            inventory.set(path, string(ref.sha256));
+            const bytes = context.blobs.get(path);
+            if (!bytes)
+                fail("missing_bundle_blob", `/inventory/${path}`);
+            else if (createHash("sha256").update(bytes).digest("hex") !== ref.sha256)
+                fail("bundle_checksum_mismatch", `/inventory/${path}`);
+        }
+        for (const reference of [data.descriptor, data.execution_settings, data.profile_settings, data.engine_binding, data.engine_manifest, ...list(data.bootstrap_receipts)]) {
+            const ref = record(reference);
+            if (inventory.get(string(ref.path)) !== ref.sha256)
+                fail("unlisted_bundle_reference");
+        }
+        if (record(data.engine_binding).sha256 !== context.engineBindingSha256)
+            fail("foreign_engine_binding");
+        if (record(data.engine_manifest).sha256 !== context.engineManifestSha256)
+            fail("foreign_engine_manifest");
+        const loaded = (reference) => {
+            const bytes = context.blobs.get(string(record(reference).path));
+            try {
+                return bytes ? JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) : null;
+            }
+            catch {
+                fail("invalid_bundle_json");
+                return null;
+            }
+        };
+        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);
+        const bindingValid = bindingValidator(binding);
+        if (!bindingValid)
+            fail("invalid_engine_binding");
+        else if (record(binding).run_id !== data.run_id || record(binding).project_root !== context.bundleProjectRoot
+            || record(record(binding).engine).integrity_checksum !== context.engineChecksum)
+            fail("foreign_engine_binding");
+        const manifest = loaded(data.engine_manifest);
+        const manifestSchema = JSON.parse(fs.readFileSync(new URL("../schemas/engine-manifest.schema.json", import.meta.url), "utf8"));
+        const manifestValidator = new Ajv({ strict: false, validateFormats: false }).compile(manifestSchema);
+        if (!manifestValidator(manifest))
+            fail("invalid_engine_manifest");
+        else if (bindingValid) {
+            const selected = record(manifest), engine = record(record(binding).engine), integrity = record(selected.integrity);
+            if (["package_name", "package_version", "engine_version", "snapshot_root"].some(key => selected[key] !== engine[key])
+                || integrity.mode !== "full_content" || integrity.checksum !== engine.integrity_checksum)
+                fail("foreign_engine_manifest");
+        }
+        if (!descriptor || !settings || !profiles)
+            fail("missing_bundle_contract");
+        else {
+            if (record(descriptor).id !== data.flow_id || record(settings).flow_id !== data.flow_id)
+                fail("foreign_bundle_flow");
+            const retained = new Map([...context.blobs].filter(([path]) => inventory.has(path)));
+            const descriptorContext = context.descriptorContext
+                ? { ...context.descriptorContext, blobs: retained } : undefined;
+            const bundleContext = descriptorContext ? { ...context, descriptorContext } : context;
+            issues.push(...validateHybridContract("flow-descriptor", descriptor, bundleContext));
+            issues.push(...validateHybridContract("profile-settings", profiles, context));
+            issues.push(...validateHybridContract("execution-settings", settings, { ...context, descriptor,
+                descriptorSha256: string(record(data.descriptor).sha256), profileSettings: profiles }));
+            for (const reference of list(data.bootstrap_receipts)) {
+                const bootstrap = loaded(reference);
+                if (!bootstrap)
+                    fail("missing_bundle_bootstrap");
+                else {
+                    if (record(bootstrap).flow_id !== data.flow_id || record(bootstrap).readiness !== "ready")
+                        fail("bundle_bootstrap_not_admitted");
+                    issues.push(...validateHybridContract("memory-bootstrap-receipt", bootstrap, context));
+                }
+            }
+        }
+    }
+    else
+        fail("unknown_hybrid_contract");
+    return issues;
+}
+export function validateHybridShape(name, input) {
+    if (!hybridContractRegistry.has(name)) {
+        return [{ gate: "shape", code: "unknown_contract_name", path: "/" }];
+    }
+    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);
+    if (validate(input))
+        return [];
+    return (validate.errors ?? []).map(error => ({
+        gate: "shape", code: error.keyword, path: error.instancePath || "/"
+    }));
+}
+/** Context must come from the trusted materializer, never from the descriptor. */
+export function validateFlowDescriptor(input, context) {
+    const shape = validateHybridShape("flow-descriptor", input);
+    if (shape.length)
+        return shape;
+    const descriptor = input;
+    const issues = [];
+    const fail = (code, path) => issues.push({ gate: "context", code, path });
+    const ids = new Set(), directories = new Set();
+    const outgoing = new Map(), incoming = new Map();
+    for (const [index, stage] of descriptor.stages.entries()) {
+        if (ids.has(stage.id))
+            fail("duplicate_stage", `/stages/${index}/id`);
+        if (directories.has(stage.directory))
+            fail("duplicate_directory", `/stages/${index}/directory`);
+        ids.add(stage.id);
+        directories.add(stage.directory);
+        outgoing.set(stage.id, []);
+        incoming.set(stage.id, []);
+        if (!context.entryHandlers.has(stage.entry_handler))
+            fail("unknown_entry_handler", `/stages/${index}/entry_handler`);
+        if (!context.finishHandlers.has(stage.finish_handler))
+            fail("unknown_finish_handler", `/stages/${index}/finish_handler`);
+        for (const field of ["instruction", "result_schema"]) {
+            const reference = stage[field], bytes = context.blobs.get(reference.path);
+            if (!bytes) {
+                fail("missing_blob", `/stages/${index}/${field}`);
+                continue;
+            }
+            if (createHash("sha256").update(bytes).digest("hex") !== reference.sha256) {
+                fail("blob_checksum_mismatch", `/stages/${index}/${field}`);
+                continue;
+            }
+            if (field === "result_schema") {
+                try {
+                    const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+                    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}`);
+                }
+            }
+        }
+    }
+    if (!ids.has(descriptor.entry_stage))
+        fail("foreign_entry", "/entry_stage");
+    for (const terminal of descriptor.terminal_stages) {
+        if (!ids.has(terminal))
+            fail("foreign_terminal", "/terminal_stages");
+    }
+    const transitions = new Set();
+    for (const [index, edge] of descriptor.edges.entries()) {
+        const transition = `${edge.from}/${edge.on}`;
+        if (transitions.has(transition))
+            fail("ambiguous_transition", `/edges/${index}`);
+        transitions.add(transition);
+        if (!ids.has(edge.from) || !ids.has(edge.to)) {
+            fail("foreign_edge", `/edges/${index}`);
+            continue;
+        }
+        outgoing.get(edge.from).push(edge.to);
+        incoming.get(edge.to).push(edge.from);
+        if (descriptor.terminal_stages.includes(edge.from))
+            fail("terminal_outgoing", `/edges/${index}`);
+    }
+    const closure = (seeds, graph) => {
+        const seen = new Set(), pending = [...seeds];
+        while (pending.length) {
+            const id = pending.pop();
+            if (seen.has(id) || !ids.has(id))
+                continue;
+            seen.add(id);
+            pending.push(...(graph.get(id) ?? []));
+        }
+        return seen;
+    };
+    const reachable = closure([descriptor.entry_stage], outgoing);
+    const canFinish = closure(descriptor.terminal_stages, incoming);
+    for (const id of ids) {
+        if (!reachable.has(id))
+            fail("unreachable_stage", `/stages/${id}`);
+        if (!canFinish.has(id))
+            fail("no_terminal_path", `/stages/${id}`);
+    }
+    const degrees = new Map([...ids].map(id => [id, incoming.get(id).length]));
+    const ready = [...ids].filter(id => degrees.get(id) === 0);
+    let visited = 0;
+    while (ready.length) {
+        const id = ready.pop();
+        visited++;
+        for (const next of outgoing.get(id)) {
+            const count = degrees.get(next) - 1;
+            degrees.set(next, count);
+            if (count === 0)
+                ready.push(next);
+        }
+    }
+    if (visited !== ids.size)
+        fail("cyclic_graph", "/edges");
+    return issues;
+}

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

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+function refuse(reason) {
+    throw new AppError("installation_locked", "Installation owner requires reconciliation", 1, { reason, effect: "no_effect", help: "setup", next_action: "Replay the original exact request after its owner exits" });
+}
+function readOwner(file) {
+    if (!fs.lstatSync(file).isFile())
+        refuse("foreign_lock_object");
+    let owner;
+    try {
+        owner = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return refuse("unreadable_lock_owner");
+    }
+    if (!owner || owner.schema_id !== "dd-flow/installation-lock@1" || !/^[a-f0-9]{64}$/.test(owner.identity) ||
+        owner.host !== os.hostname() || !Number.isSafeInteger(owner.pid) || owner.pid < 1 || !/^[a-f0-9-]{36}$/.test(owner.token))
+        refuse("unverified_lock_owner");
+    return owner;
+}
+function isDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/** Publish a complete owner record atomically; only the same request can reclaim a kernel-confirmed dead owner. */
+export function acquireInstallationLock(file, identity) {
+    if (!/^[a-f0-9]{64}$/.test(identity))
+        refuse("invalid_lock_identity");
+    const owner = { schema_id: "dd-flow/installation-lock@1", identity, host: os.hostname(), pid: process.pid, token: randomUUID() };
+    const temporary = path.join(path.dirname(file), `.lock-owner-${owner.token}.tmp`);
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        try {
+            fs.writeFileSync(fd, JSON.stringify(owner));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                fs.linkSync(temporary, file);
+                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);
+                    } };
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const previous = readOwner(file);
+                if (previous.identity !== identity)
+                    refuse("different_request_owns_lock");
+                if (!isDead(previous.pid))
+                    refuse("owner_process_alive_or_unknown");
+                // Atomic quarantine retains crash evidence. A competing reclaimer must retry, not overwrite an owner.
+                const quarantine = `${file}.abandoned-${previous.token}`;
+                if (fs.existsSync(quarantine))
+                    refuse("ambiguous_abandoned_lock");
+                const before = fs.lstatSync(file);
+                const checked = readOwner(file);
+                if (checked.token !== previous.token || !isDead(checked.pid))
+                    refuse("lock_owner_changed");
+                try {
+                    fs.linkSync(file, quarantine);
+                }
+                catch {
+                    return refuse("concurrent_lock_reconciliation");
+                }
+                const after = fs.lstatSync(file);
+                if (before.ino !== after.ino || before.dev !== after.dev || readOwner(file).token !== previous.token)
+                    refuse("lock_owner_changed");
+                fs.unlinkSync(file);
+            }
+        }
+        return refuse("lock_contention");
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}