@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

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

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { Ajv } from "ajv/dist/ajv.js";
+import semver from "semver";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { isCanonicalOnlyMemoryPath } from "./memory-layer.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+import { admitBundledFlow } from "./stage-handlers.js";
+import { normalizeFlowContract } from "../domain/flow-contract.js";
+const limit = 1024 * 1024, manifestPath = "project-pack/manifest.json";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("project_flow_source_invalid", "Project-local flow requires its own valid curated pack; use the supported pack upgrade/repair route", 2, { reason, phase: "prepare", effect: "no_effect", next_action: "inspect_project_pack_and_upgrade_or_repair" });
+}
+function safe(name) {
+    return typeof name === "string" && /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(name)
+        && name.split("/").every(part => ![".", "..", ".git", "node_modules", ".dd-flow"].includes(part.toLowerCase()) && localEnvironmentAllowed(part));
+}
+function schema(name) { return JSON.parse(fs.readFileSync(new URL(`../schemas/${name}.schema.json`, import.meta.url), "utf8")); }
+function decoded(bytes) { try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+}
+catch {
+    return refuse("invalid_pack_json");
+} }
+function validate(scope, blobs) {
+    if (!scope || Object.keys(scope).sort().join() !== "flowId,projectRoot,workspace" || scope.flowId !== "interactive"
+        || [scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !path.isAbsolute(value)))
+        refuse("invalid_project_scope");
+    const manifest = decoded(blobs.get(manifestPath) ?? Buffer.alloc(0));
+    if (!new Ajv({ strict: false, validateFormats: false }).compile(schema("project-flow-pack-manifest"))(manifest)
+        || manifest.schema_id !== "dd-flow/project-flow-pack-manifest@2" || !/^[a-f0-9]{40}$/.test(manifest.source_commit)
+        || !semver.valid(manifest.canon_version_at_source_commit))
+        refuse("invalid_or_legacy_project_manifest");
+    if (manifest.included_files.length > 20_000 || manifest.included_files.some(name => !safe(name) || name === manifestPath
+        || name.startsWith("project-pack/") || isCanonicalOnlyMemoryPath(`dd-flow/${name}`)))
+        refuse("invalid_curated_inventory");
+    const names = [manifestPath, ...manifest.included_files], folded = new Set();
+    let total = 0;
+    if (blobs.size !== names.length)
+        refuse("pack_inventory_changed");
+    for (const name of names) {
+        if (folded.has(name.toLowerCase()))
+            refuse("aliased_pack_path");
+        folded.add(name.toLowerCase());
+        const bytes = blobs.get(name);
+        if (!bytes?.length || bytes.length > limit || (total += bytes.length) > 32 * limit)
+            refuse("missing_or_unbounded_pack_file");
+        if (name !== manifestPath && manifest.file_hashes?.[name] !== undefined && manifest.file_hashes[name] !== hash(bytes))
+            refuse("project_pack_file_changed");
+    }
+    const descriptorPath = `${scope.flowId}/flow-descriptor.json`, descriptor = decoded(blobs.get(descriptorPath) ?? Buffer.alloc(0));
+    if (validateHybridShape("flow-descriptor", descriptor).length || descriptor.id !== scope.flowId || descriptor.origin !== "project")
+        refuse("project_descriptor_required");
+    for (const stage of descriptor.stages)
+        for (const kind of ["instruction", "result_schema"]) {
+            const ref = stage[kind], bytes = blobs.get(ref.path);
+            if (!bytes || ref.path === manifestPath || !manifest.included_files.includes(ref.path) || hash(bytes) !== ref.sha256)
+                refuse("stage_source_not_in_project_pack");
+            try {
+                new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            }
+            catch {
+                refuse("invalid_stage_source_encoding");
+            }
+            if (kind === "result_schema")
+                decoded(bytes);
+        }
+    const compatibility = decoded(blobs.get("compatibility.json") ?? Buffer.alloc(0));
+    if (!new Ajv({ strict: false, validateFormats: false }).compile(schema("compatibility"))(compatibility))
+        refuse("invalid_project_compatibility");
+    const contract = normalizeFlowContract(decoded(blobs.get("flow-contract.json") ?? Buffer.alloc(0)));
+    if (contract.id !== manifest.flow_contract || compatibility.dd_flow_cli.flow_contract !== contract.id
+        || compatibility.memory_bank_version !== manifest.canon_version_at_source_commit)
+        refuse("project_contract_mismatch");
+    return { manifest, descriptorPath, compatibility };
+}
+/** Project pack data, not engine/handler admission. Manifest canon paths are
+ * provenance hints only: never follow them or fall back to global instructions. */
+export class PreparedProjectFlowSource {
+    sha256;
+    #scope;
+    #blobs;
+    #facts;
+    #fresh;
+    constructor(scope, blobs, fresh) {
+        this.#facts = validate(scope, blobs);
+        this.#scope = structuredClone(scope);
+        this.#blobs = new Map([...blobs].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, bytes]) => [name, Buffer.from(bytes)]));
+        this.sha256 = hybridDigest({ scope, inventory: [...this.#blobs].map(([name, bytes]) => ({ path: name, sha256: hash(bytes) })) });
+        this.#fresh = fresh;
+        Object.freeze(this);
+    }
+    static fromProject(scope) {
+        try {
+            for (const root of [scope.projectRoot, scope.workspace])
+                if (fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+                    refuse("noncanonical_project_root");
+            let root = scope.workspace;
+            for (const name of [".memory-bank", "dd-flow"]) {
+                root = path.join(root, name);
+                if (!fs.lstatSync(root).isDirectory())
+                    refuse("linked_project_pack");
+            }
+            const read = (logical) => {
+                if (!safe(logical))
+                    refuse("unsafe_pack_path");
+                let parent = root;
+                for (const part of logical.split("/").slice(0, -1)) {
+                    parent = path.join(parent, part);
+                    if (!fs.lstatSync(parent).isDirectory())
+                        refuse("linked_project_pack");
+                }
+                return readBoundedReleaseFile(path.join(root, logical), limit);
+            };
+            const raw = read("manifest.json"), manifest = decoded(raw);
+            if (!new Ajv({ strict: false, validateFormats: false }).compile(schema("project-flow-pack-manifest"))(manifest)
+                || manifest.schema_id !== "dd-flow/project-flow-pack-manifest@2")
+                refuse("invalid_or_legacy_project_manifest");
+            const blobs = new Map([[manifestPath, raw]]);
+            if (manifest.included_files.length > 20_000)
+                refuse("unbounded_project_pack");
+            let total = raw.length;
+            for (const name of manifest.included_files) {
+                if (!safe(name) || isCanonicalOnlyMemoryPath(`dd-flow/${name}`) || name.startsWith("project-pack/"))
+                    refuse("invalid_curated_inventory");
+                const bytes = read(name);
+                total += bytes.length;
+                if (total > 32 * limit)
+                    refuse("unbounded_project_pack");
+                blobs.set(name, bytes);
+            }
+            if (!read("manifest.json").equals(raw))
+                refuse("manifest_changed_during_capture");
+            return new PreparedProjectFlowSource(scope, blobs, true);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "project_flow_source_invalid")
+                throw error;
+            return refuse("project_pack_unavailable_or_changed");
+        }
+    }
+    snapshot() { return { schema_id: "dd-flow/project-flow-source@1", scope: structuredClone(this.#scope), blobs: [...this.#blobs].map(([name, bytes]) => ({ path: name, base64: bytes.toString("base64") })) }; }
+    /** Data restoration only. expectedSha256 must come from independent request/
+     * RUN custody. Engine/handler admission is separate and never inferred here. */
+    static restoreRetained(value, expectedSha256) {
+        if (!value || Object.keys(value).sort().join() !== "blobs,schema_id,scope" || value.schema_id !== "dd-flow/project-flow-source@1"
+            || !Array.isArray(value.blobs) || value.blobs.length > 20_001)
+            refuse("invalid_retained_project_source");
+        const blobs = new Map();
+        let total = 0;
+        for (const item of value.blobs) {
+            if (!item || Object.keys(item).sort().join() !== "base64,path" || !safe(item.path) || typeof item.base64 !== "string" || item.base64.length > 2 * limit || blobs.has(item.path))
+                refuse("invalid_retained_project_source");
+            const bytes = Buffer.from(item.base64, "base64");
+            total += bytes.length;
+            if (!bytes.length || bytes.length > limit || total > 32 * limit || bytes.toString("base64") !== item.base64)
+                refuse("invalid_retained_project_source");
+            blobs.set(item.path, bytes);
+        }
+        const result = new PreparedProjectFlowSource(value.scope, blobs, false);
+        if (result.sha256 !== expectedSha256)
+            refuse("retained_project_source_changed");
+        return result;
+    }
+    blobs() { return new Map([...this.#blobs].map(([name, bytes]) => [name, Buffer.from(bytes)])); }
+    scope() { return structuredClone(this.#scope); }
+    descriptorReference() { const name = this.#facts.descriptorPath; return { path: name, sha256: hash(this.#blobs.get(name)) }; }
+    projectPackProvenance() { return { sha256: hybridDigest([...this.#blobs].map(([name, bytes]) => ({ path: name === manifestPath ? "dd-flow/manifest.json" : `dd-flow/${name}`, sha256: hash(bytes) })).sort((a, b) => a.path.localeCompare(b.path, "en"))), source_commit: this.#facts.manifest.source_commit }; }
+    canonSource() { return { version: this.#facts.manifest.canon_version_at_source_commit, commit: this.#facts.manifest.source_commit }; }
+    /** Declared project base, not a claim that customized instructions are bytes
+     * from an installed canonical archive. Actual data identity is the pack hash. */
+    canonProvenance() { return { ...this.canonSource(), archive_sha256: null }; }
+    resolveRegisteredFlow() { const ref = this.descriptorReference(); return admitBundledFlow(this.#blobs.get(ref.path), ref.sha256, this.#blobs); }
+    assertEngineCompatibility(engine) {
+        const value = this.#facts.compatibility;
+        if (engine.package_name !== value.engine.package_name || engine.package_name !== value.dd_flow_cli.package_name
+            || !semver.valid(engine.package_version) || !semver.valid(engine.engine_version)
+            || !semver.validRange(value.engine.version_range) || !semver.valid(value.dd_flow_cli.min_version)
+            || !semver.satisfies(engine.engine_version, value.engine.version_range, { includePrerelease: true })
+            || !semver.gte(engine.package_version, value.dd_flow_cli.min_version))
+            refuse("project_pack_engine_incompatible");
+    }
+    revalidate() {
+        if (!this.#fresh) {
+            validate(this.#scope, this.#blobs);
+            return;
+        }
+        if (PreparedProjectFlowSource.fromProject(this.#scope).sha256 !== this.sha256)
+            refuse("project_source_changed_before_retention");
+    }
+}

package/dist/services/project-git-integration.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { interactiveWorkPathAllowed } from "./interactive-work-batch.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { assertMemoryGitRemovalSources } from "./memory-git-integration.js";
+function refuse(reason) {
+    throw new AppError("project_git_integration_invalid", "Reviewed project files lack exact local Git integration", 2, { reason, effect: "no_effect" });
+}
+export function assertReviewedProjectGitInventory(references, removals) {
+    const valid = (ref) => ref?.root === "workspace" && interactiveWorkPathAllowed(ref.path)
+        && /^[a-f0-9]{64}$/.test(ref.sha256) && (Object.keys(ref).sort().join() === "path,root,sha256"
+        || Object.keys(ref).sort().join() === "git_mode,path,root,sha256" && ["100644", "100755"].includes(ref.git_mode));
+    if (!Array.isArray(references) || !Array.isArray(removals) || !references.length && !removals.length
+        || references.length + removals.length > 4096 || [...references, ...removals].some(ref => !valid(ref))
+        || new Set([...references, ...removals].map(ref => ref.path)).size !== references.length + removals.length)
+        refuse("invalid_reviewed_project_inventory");
+}
+/** Physical selected-file readback only, not review, policy or commit authority.
+ * Unrelated dirty files/index entries are deliberately neither committed nor
+ * treated as failures. The terminal owner must admit the original dirty input. */
+export function observeReviewedProjectGitIntegration(input, environment, references, removals = []) {
+    assertReviewedProjectGitInventory(references, removals);
+    for (const root of [input.projectRoot, input.workspaceRoot]) {
+        if (!path.isAbsolute(root) || fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+            refuse("canonical_repository_root_required");
+    }
+    if (!path.isAbsolute(input.gitExecutable) || typeof input.integrationBranch !== "string" || !input.integrationBranch)
+        refuse("explicit_git_selection_required");
+    const env = { ...Object.fromEntries(Object.entries(environment).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" };
+    const git = (root, args) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-C", root, ...args], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            refuse("git_readback_failed");
+        return result.stdout;
+    };
+    const text = (root, args) => git(root, args).toString("utf8").trim();
+    const source = input.workspaceRoot, target = input.projectRoot, integrationRef = `refs/heads/${input.integrationBranch}`;
+    git(target, ["check-ref-format", integrationRef]);
+    const common = (root) => fs.realpathSync(path.resolve(root, text(root, ["rev-parse", "--git-common-dir"])));
+    const repository = common(source);
+    if (common(target) !== repository || [source, target].some(root => text(root, ["rev-parse", "--show-toplevel"]) !== root))
+        refuse("foreign_repository");
+    const workspaceBranch = text(source, ["symbolic-ref", "--short", "HEAD"]);
+    if (text(target, ["symbolic-ref", "--short", "HEAD"]) !== input.integrationBranch)
+        refuse("integration_branch_changed");
+    const head = text(source, ["rev-parse", "--verify", "HEAD^{commit}"]), integrated = text(target, ["rev-parse", "--verify", `${integrationRef}^{commit}`]);
+    git(target, ["merge-base", "--is-ancestor", head, integrated]);
+    const paths = [...references, ...removals].map(ref => ref.path);
+    const observations = [...new Set([source, target])].map(root => {
+        const visibility = git(root, ["ls-files", "-v", "-z", "--", ...paths]).toString("utf8");
+        if (visibility.split("\0").filter(Boolean).some(entry => !entry.startsWith("H ")))
+            refuse("selected_index_visibility_override");
+        git(root, ["diff", "--cached", "--exit-code", "--", ...paths]);
+        assertMemoryGitRemovalSources(root, removals);
+        const observed = ObservedMemorySources.capture({ workspace: root }, references.map(({ root, path }) => ({ root, path })));
+        const hashes = observed.hashes();
+        for (const ref of references) {
+            if (hashes.get(memorySourceKey("workspace", ref.path)) !== ref.sha256)
+                refuse("reviewed_workspace_bytes_changed");
+            if (process.platform !== "win32" && ((fs.lstatSync(path.join(root, ref.path)).mode & 0o111) !== 0) !== (ref.git_mode === "100755"))
+                refuse("reviewed_workspace_mode_changed");
+        }
+        return observed;
+    });
+    // ponytail: at most 4096 selected paths; batch Git reads if real interactive
+    // inventories make per-file subprocess latency material.
+    for (const [root, revision] of [[source, head], [target, integrated]]) {
+        for (const ref of references) {
+            const entry = git(root, ["ls-tree", "-z", revision, "--", ref.path]).toString("utf8");
+            if (!entry.startsWith(`${ref.git_mode ?? "100644"} blob `) || !entry.endsWith(`\t${ref.path}\0`))
+                refuse("reviewed_regular_git_blob_required");
+            if (createHash("sha256").update(git(root, ["cat-file", "blob", `${revision}:${ref.path}`])).digest("hex") !== ref.sha256)
+                refuse("reviewed_git_bytes_changed");
+        }
+        for (const ref of removals)
+            if (git(root, ["ls-tree", "-z", revision, "--", ref.path]).length)
+                refuse("removed_file_still_committed");
+    }
+    for (const observation of observations)
+        observation.revalidate();
+    if (text(source, ["rev-parse", "HEAD"]) !== head || text(target, ["rev-parse", integrationRef]) !== integrated)
+        refuse("integration_changed_during_observation");
+    return { schema_id: "dd-flow/project-git-integration-observation@1", project_root: target, workspace_root: source,
+        repository, workspace_branch: workspaceBranch, integration_ref: integrationRef, workspace_head: head, integration_head: integrated,
+        reviewed_files_sha256: hybridDigest([...references].sort((a, b) => a.path.localeCompare(b.path, "en"))),
+        removed_files_sha256: hybridDigest([...removals].sort((a, b) => a.path.localeCompare(b.path, "en"))) };
+}

package/dist/services/project-registry.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
+import { formatFullId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.js";
+import { appendAudit } from "./audit.js";
+/** Resolve filesystem identity before entering a composite SQL writer. */
+export class PreparedProjectRegistration {
+    #root;
+    constructor(root) { this.#root = root; Object.freeze(this); }
+    static prepare(input) {
+        return new PreparedProjectRegistration(resolveProjectRoot(input.root));
+    }
+    root() { return this.#root; }
+}
+export function registerProject(context, input) {
+    return registerPreparedProject(context, PreparedProjectRegistration.prepare(input));
+}
+/** Metadata-only registration; the composite caller owns its SQL transaction. */
+export function registerPreparedProject(context, prepared) {
+    if (!(prepared instanceof PreparedProjectRegistration))
+        throw new AppError("validation", "Project registration must be prepared", 2);
+    const root = prepared.root();
+    const existing = context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
+    const now = context.now();
+    const project = existing ?? newProjectRecord(context, root, now);
+    if (existing) {
+        context.db.run("UPDATE projects SET status = 'active', updated_at = ? WHERE id = ?", [now, existing.id]);
+    }
+    else {
+        context.db.run("INSERT INTO projects (id, short_id, slug, root, status, state_root, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+            project.id,
+            project.short_id,
+            project.slug,
+            project.root,
+            project.status,
+            project.state_root,
+            project.created_at,
+            project.updated_at
+        ]);
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "project.registered",
+            payload: { project_id: project.id, root }
+        });
+    }
+    return { ok: true, project: { ...project, status: "active", updated_at: now }, db_path: context.db.path };
+}
+export function normalizeStoredRoot(root) {
+    const absolute = path.resolve(root);
+    if (fs.existsSync(absolute)) {
+        return fs.realpathSync(absolute);
+    }
+    const parent = path.dirname(absolute);
+    if (fs.existsSync(parent)) {
+        return path.join(fs.realpathSync(parent), path.basename(absolute));
+    }
+    return absolute;
+}
+export function findProjectByRoot(context, root) {
+    return context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
+}
+export function requireProjectByRoot(context, root) {
+    // Callers may receive a path through a native adapter or shell.  Resolve
+    // aliases such as macOS `/var` -> `/private/var` before comparing with the
+    // canonical root persisted in the project registry.
+    const canonical = normalizeStoredRoot(root);
+    const project = findProjectByRoot(context, canonical);
+    if (!project) {
+        throw new AppError("not_found", `Project is not registered: ${canonical}`, 1);
+    }
+    return project;
+}
+export function newProjectRecord(context, root, now) {
+    const slug = slugFromRoot(root);
+    const id = nextFullProjectId(context, slug);
+    const { shortId } = parseFullEntityId(id);
+    return {
+        id,
+        short_id: shortId,
+        slug,
+        root,
+        status: "active",
+        state_root: projectRuntimeRoot(context.ddFlowHome, id),
+        created_at: now,
+        updated_at: now
+    };
+}
+export function nextFullProjectId(context, slug) {
+    const rows = context.db.all("SELECT id FROM projects WHERE id LIKE 'PRJ-%'");
+    const used = rows
+        .map((row) => /^PRJ-(\d{3})-/.exec(row.id)?.[1])
+        .filter((value) => Boolean(value))
+        .map((value) => Number(value));
+    const next = Math.max(0, ...used) + 1;
+    return formatFullId("PRJ", next, slug);
+}

package/dist/services/project-summary.js

@@ -5,7 +5,7 @@ import { ensureDir } from "../storage/paths.js";
 import { getCliVersionReport } from "./build-info.js";
 import { projectDashboardHtmlPath, projectSummaryJsonPath } from "./config.js";
 import { queueForProject } from "./merge-queue.js";
-import { activeFlowSessionsForProject } from "./sessions.js";
+import { activeFlowSessionsForProject } from "./hook-session-observation.js";
 import { getProjectVersionStatus } from "./version-status.js";
 export function projectSummaryPath(context, projectId) {
     return projectSummaryJsonPath(context, projectId);

package/dist/services/projects.js

@@ -1,44 +1,24 @@
-import fs from "node:fs";
 import path from "node:path";
-import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.js";
+import { foreignKeyTransaction } from "../storage/foreign-key-transaction.js";
+import { isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { AppError } from "../shared/errors.js";
 import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { registerProject, registerPreparedProject, PreparedProjectRegistration, normalizeStoredRoot, findProjectByRoot, requireProjectByRoot, newProjectRecord } from "./project-registry.js";
+export { registerProject, registerPreparedProject, PreparedProjectRegistration, findProjectByRoot, requireProjectByRoot };
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { dashboardMarkdownPath, globalDashboardMarkdownPath, readProjectConfig } from "./config.js";
 import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
 import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { buildProjectSummary, projectRegistrySummary, readPublishedProjectSummary } from "./project-summary.js";
-export function registerProject(context, input) {
-    const root = resolveProjectRoot(input.root);
-    const existing = findProjectByRoot(context, root);
-    const now = context.now();
-    const project = existing ?? newProjectRecord(context, root, now);
-    if (existing) {
-        context.db.run("UPDATE projects SET status = 'active', updated_at = ? WHERE id = ?", [now, existing.id]);
-    }
-    else {
-        context.db.run("INSERT INTO projects (id, short_id, slug, root, status, state_root, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
-            project.id,
-            project.short_id,
-            project.slug,
-            project.root,
-            project.status,
-            project.state_root,
-            project.created_at,
-            project.updated_at
-        ]);
-        appendAudit(context, {
-            projectId: project.id,
-            eventType: "project.registered",
-            payload: { project_id: project.id, root }
-        });
-    }
-    return { ok: true, project: { ...project, status: "active", updated_at: now }, db_path: context.db.path };
-}
-export function archiveProject(context, input) {
-    const reason = input.reason.trim();
+export function prepareProjectArchive(context, input) {
+    if (Boolean(input.idOrAlias) === Boolean(input.root))
+        throw new AppError("usage", "Project archive requires exactly one project ID/alias or --root", 2);
+    for (const value of [input.idOrAlias, input.root])
+        if (value !== undefined && (typeof value !== "string" || !value.trim()))
+            throw new AppError("validation", "Project archive target must be a non-empty string", 2);
+    const reason = typeof input.reason === "string" ? input.reason.trim() : "";
     if (!reason) {
         throw new AppError("validation", "project archive requires --reason", 2);
     }
@@ -50,6 +30,10 @@ export function archiveProject(context, input) {
     if (!project) {
         throw new AppError("not_found", "Project is not registered.", 1, { root: input.root, input: input.idOrAlias });
     }
+    return { project, reason };
+}
+export function archiveProject(context, input) {
+    const { project, reason } = prepareProjectArchive(context, input);
     const now = context.now();
     const result = context.db.run("UPDATE projects SET status = 'archived', updated_at = ? WHERE id = ? AND status <> 'archived'", [now, project.id]);
     if (result.changes === 1) {
@@ -67,17 +51,6 @@ export function archiveProject(context, input) {
         ...(result.changes === 1 ? {} : { skipped: true, reason: "already_archived" })
     };
 }
-function normalizeStoredRoot(root) {
-    const absolute = path.resolve(root);
-    if (fs.existsSync(absolute)) {
-        return fs.realpathSync(absolute);
-    }
-    const parent = path.dirname(absolute);
-    if (fs.existsSync(parent)) {
-        return path.join(fs.realpathSync(parent), path.basename(absolute));
-    }
-    return absolute;
-}
 export function resolveProject(context, input) {
     const candidates = resolveProjectCandidates(context, input.idOrAlias);
     if (candidates.length === 1) {
@@ -139,9 +112,7 @@ export function migrateProjectIds(context, input) {
     if (conflictingProject) {
         throw new AppError("conflict", `Target project id already exists: ${target.id}`, 1, plan);
     }
-    context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    foreignKeyTransaction(context.db, () => {
         context.db.run("UPDATE projects SET id = ?, short_id = ?, slug = ?, state_root = ?, updated_at = ? WHERE id = ?", [target.id, target.short_id, target.slug, target.state_root, now, oldId]);
         for (const table of projectReferenceTables()) {
             context.db.run(`UPDATE ${table} SET project_id = ? WHERE project_id = ?`, [target.id, oldId]);
@@ -153,14 +124,7 @@ export function migrateProjectIds(context, input) {
                 foreign_key_errors: foreignKeyErrors
             });
         }
-        context.db.exec("COMMIT");
-        context.db.exec("PRAGMA foreign_keys = ON");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        context.db.exec("PRAGMA foreign_keys = ON");
-        throw error;
-    }
+    });
     appendAudit(context, {
         projectId: target.id,
         eventType: "project.id_migrated",
@@ -228,31 +192,6 @@ export function getProjectStatus(context, input) {
         }
     };
 }
-export function findProjectByRoot(context, root) {
-    return context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
-}
-export function requireProjectByRoot(context, root) {
-    const project = findProjectByRoot(context, root);
-    if (!project) {
-        throw new AppError("not_found", `Project is not registered: ${root}`, 1);
-    }
-    return project;
-}
-function newProjectRecord(context, root, now) {
-    const slug = slugFromRoot(root);
-    const id = nextFullProjectId(context, slug);
-    const { shortId } = parseFullEntityId(id);
-    return {
-        id,
-        short_id: shortId,
-        slug,
-        root,
-        status: "active",
-        state_root: projectRuntimeRoot(context.ddFlowHome, id),
-        created_at: now,
-        updated_at: now
-    };
-}
 function backfilledTypedProjectRecord(context, project, typed, now) {
     return {
         ...project,
@@ -262,15 +201,6 @@ function backfilledTypedProjectRecord(context, project, typed, now) {
         updated_at: now
     };
 }
-function nextFullProjectId(context, slug) {
-    const rows = context.db.all("SELECT id FROM projects WHERE id LIKE 'PRJ-%'");
-    const used = rows
-        .map((row) => /^PRJ-(\d{3})-/.exec(row.id)?.[1])
-        .filter((value) => Boolean(value))
-        .map((value) => Number(value));
-    const next = Math.max(0, ...used) + 1;
-    return formatFullId("PRJ", next, slug);
-}
 function typedProjectMetadata(project) {
     if (!isFullEntityId(project.id)) {
         return null;

package/dist/services/prompt-delivery.js

@@ -0,0 +1,71 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+const digest = (text) => crypto.createHash("sha256").update(text).digest("hex");
+/** Describe the exact delivery before the existing operation receipt is settled.
+ * This does not issue commands or replace the original semantic prompt. */
+export function preparePromptDelivery(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const packet = value, text = packet.worker_prompt_markdown;
+    if (typeof text !== "string" || typeof packet.prompt_path !== "string")
+        return value;
+    if (!path.isAbsolute(packet.prompt_path))
+        throw new AppError("prompt_delivery_invalid", "Prompt delivery requires an absolute original prompt path", 1, { effect: "committed" });
+    const sha256 = digest(text);
+    let file = path.join(path.dirname(packet.prompt_path), "prompt-deliveries", `${sha256}.md`);
+    try {
+        if (fs.lstatSync(packet.prompt_path).isFile() && !fs.lstatSync(packet.prompt_path).isSymbolicLink()
+            && fs.readFileSync(packet.prompt_path, "utf8") === text)
+            file = packet.prompt_path;
+    }
+    catch { /* A retained delivery can republish an absent original without replay. */ }
+    const retained = packet.prompt_delivery;
+    if (retained && (retained.sha256 !== sha256 || retained.path !== file)) {
+        // An original file may disappear after commit. Keep the exact retained locator.
+        if (retained.sha256 !== sha256 || !path.isAbsolute(retained.path)
+            || retained.path !== packet.prompt_path && retained.path !== path.join(path.dirname(packet.prompt_path), "prompt-deliveries", `${sha256}.md`)) {
+            throw new AppError("prompt_delivery_invalid", "Retained delivery differs from its committed bytes", 1, { effect: "committed" });
+        }
+        file = retained.path;
+    }
+    const delivery = { path: file, sha256 };
+    // Keep the locator visible even when native tools clip verbose JSON metadata.
+    return Object.assign({ prompt_delivery: delivery }, packet, { prompt_delivery: delivery });
+}
+/** Publish only retained bytes, after commit and before advertising the locator. */
+export function publishPromptDelivery(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const packet = value, delivery = packet.prompt_delivery;
+    if (!delivery)
+        return;
+    const text = packet.worker_prompt_markdown;
+    try {
+        if (typeof text !== "string" || digest(text) !== delivery.sha256 || !path.isAbsolute(delivery.path))
+            throw new Error("Delivery checksum mismatch");
+        if (typeof packet.prompt_path !== "string" || !path.isAbsolute(packet.prompt_path))
+            throw new Error("Delivery has no original prompt directory");
+        // Revalidate retained routing before touching the filesystem. System path
+        // aliases (/var on macOS) are allowed; a delivery-directory symlink is not.
+        preparePromptDelivery(packet);
+        const directory = path.dirname(delivery.path);
+        if (delivery.path !== packet.prompt_path) {
+            const stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+            if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+                throw new Error("Delivery directory is not an owned regular directory");
+        }
+        fs.mkdirSync(path.dirname(delivery.path), { recursive: true, mode: 0o700 });
+        if (delivery.path !== packet.prompt_path
+            && fs.realpathSync(directory) !== path.join(fs.realpathSync(path.dirname(packet.prompt_path)), "prompt-deliveries"))
+            throw new Error("Delivery directory escaped its original prompt directory");
+        publishImmutableInput(delivery.path, Buffer.from(text), "prompt_delivery_conflict");
+        fs.accessSync(delivery.path, fs.constants.R_OK);
+    }
+    catch (cause) {
+        throw new AppError("prompt_delivery_pending", "Operation committed; reconcile its retained delivery before continuing. Do not repeat the lifecycle operation or execute the old prompt", 1, { effect: "committed", publication_pending: true, path: delivery.path, sha256: delivery.sha256, cause: cause instanceof Error ? cause.message : String(cause) });
+    }
+}
+export const promptDeliveryInstruction = "Read the complete plain Markdown file at prompt_delivery.path; it is the exact current instruction packet (SHA-256 in prompt_delivery.sha256). Read all chunks if needed. The JSON response is routing metadata, not the primary prompt. If prompt_delivery is absent on a legacy response, read the complete worker_prompt_markdown from response_file. If publication is pending, stop and reconcile the existing operation; never replay Stage/Work start or use an old prompt.";