@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.149

package/dist/services/migrations.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
 import { AppError } from "../shared/errors.js";
 import { requireProjectByRoot } from "./projects.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
@@ -12,11 +14,16 @@ import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityContexts, selectEngine } from "./engines.js";
 import { getCliBuildInfo } from "./build-info.js";
 import { prepareJsonFile } from "../cli/input-preparation.js";
+import { validateSchema } from "./schema-validation.js";
+import { PreparedMemoryInitRuntimeStorage } from "./memory-init-storage.js";
+import { PreparedMemoryInitResourceStorage } from "./memory-init-resource-storage.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { resourceHome } from "./managed-processes.js";
 export function assessMigrationImpact(context, input) {
     const root = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
     if (!root.root)
         throw new AppError("not_found", `Project root does not exist: ${input.projectRoot}`, 1);
-    const canon = resolveCanonRoot(context);
+    const canon = upgradeCanon(context);
     if (!canon.ok || !canon.canon)
         throw new AppError("canon_unavailable", "Cannot resolve canonical Memory Bank for upgrade impact assessment", 1, { blockers: canon.blockers, bootstrap: canon.bootstrap });
     const status = getProjectVersionStatus({ projectRoot: root.root, rootSource: root.root_source, canon: { root: canon.canon.root, metadata: canon.canon.metadata } });
@@ -24,53 +31,65 @@ export function assessMigrationImpact(context, input) {
     const to = input.targetVersion ?? canon.canon.version;
     const forced = input.mode === "full_migration";
     const impacts = readImpacts(path.join(canon.canon.memorybank_root, "release-impact"));
-    const chain = [];
+    const resolved = from && to ? adjacentMigrationChain(from, to, impacts) : null;
+    const chain = resolved?.status === "ok"
+        ? resolved.steps.map(step => impacts.find(item => item.from_version === step.from && item.to_version === step.to))
+        : [];
     const domains = new Set();
     const blockers = [];
     let mode = "patch";
     if (!from || !to)
         blockers.push("project or canonical Memory Bank version is unavailable");
-    let current = from;
-    while (current && to && current !== to) {
-        const impact = impacts.find((item) => item.from_version === current);
-        if (!impact) {
-            blockers.push(`missing adjacent release impact from ${current}`);
-            break;
-        }
-        chain.push(impact);
+    if (to !== canon.canon.version)
+        blockers.push("requested target version does not match the selected canon");
+    if (resolved?.status === "unsupported")
+        blockers.push(resolved.reason ?? "release impact chain is unsupported");
+    for (const impact of chain) {
         for (const domain of impact.domains)
             domains.add(domain);
         mode = stricterMode(mode, impact.minimum_upgrade_mode);
         if (impact.path_migration || impact.runtime_migration)
             mode = "full_migration";
-        current = impact.to_version;
     }
-    if (current && to && current !== to)
-        blockers.push(`release impact chain does not reach ${to}`);
-    if (status?.flow_pack.status !== "present" && from !== to)
+    if (status?.flow_pack.status !== "present")
         blockers.push("project flow-pack provenance is not present");
+    else {
+        try {
+            const file = path.resolve(root.root, status.flow_pack.manifest_path);
+            const prepared = prepareJsonFile(file, "Project flow-pack provenance");
+            validateSchema({ schemaName: "project-flow-pack-manifest", file, data: prepared.value,
+                schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+            if (!/^[a-f0-9]{40}$/.test(status.flow_pack.source_commit ?? "")
+                || status.flow_pack.canon_version_at_source_commit !== from)
+                blockers.push("project flow-pack provenance does not match its declared current version and commit");
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || !["schema_validation", "invalid_json", "validation"].includes(error.code)
+                && !error.code.startsWith("input_file_"))
+                throw error;
+            blockers.push("project flow-pack provenance is invalid");
+        }
+    }
     if (blockers.length > 0)
         mode = "full_migration";
     if (forced)
         mode = "full_migration";
     return { ok: true, schema_id: "dd-flow/mb-upgrade-impact-assessment@1", project_root: root.root, source_version: from, target_version: to, mode, forced_full_migration: forced, chain, domains: [...domains].sort(), blockers, required_checks: [...new Set(chain.flatMap((item) => item.required_checks))], next_action: mode === "full_migration" ? "run full mb-upgrade contour" : "run selected mb-upgrade contour" };
 }
-function readImpacts(dir) {
+export function readImpacts(dir) {
     if (!fs.existsSync(dir))
         return [];
-    return fs.readdirSync(dir).filter((file) => file.endsWith(".json")).flatMap((file) => {
+    return fs.readdirSync(dir).filter(file => file.endsWith(".json")).sort().map(file => {
+        const source = path.join(dir, file);
         try {
-            const value = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8"));
-            if (value.schema_id !== "dd-flow/release-impact@1")
-                return [];
-            if (typeof value.from_version !== "string" || typeof value.to_version !== "string" || !Array.isArray(value.domains) || !Array.isArray(value.required_checks))
-                return [];
-            if (!["patch", "targeted_minor", "full_migration"].includes(String(value.minimum_upgrade_mode)))
-                return [];
-            return [{ from_version: value.from_version, to_version: value.to_version, minimum_upgrade_mode: value.minimum_upgrade_mode, domains: value.domains.filter((item) => typeof item === "string"), path_migration: value.path_migration === true, runtime_migration: value.runtime_migration === true, required_checks: value.required_checks.filter((item) => typeof item === "string") }];
+            const prepared = prepareJsonFile(source, "Canonical release impact");
+            validateSchema({ schemaName: "release-impact", file: prepared.file, data: prepared.value,
+                schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+            return { ...prepared.value, source_reference: { path: prepared.file,
+                    sha256: crypto.createHash("sha256").update(prepared.text).digest("hex") } };
         }
-        catch {
-            return [];
+        catch (error) {
+            throw new AppError("release_impact_invalid", "Canonical release impact is invalid; it cannot authorize a lightweight upgrade", 1, { file: source, effect: "no_effect", cause: error instanceof AppError ? error.code : "unreadable_release_impact" });
         }
     });
 }
@@ -267,7 +286,7 @@ function applyPreparedMigration(context, prepared, writeDb) {
     }
     return { ok: true, schema_id: "dd-flow/mb-upgrade-migration-apply@1", status: "applied", changed: true, backup: verifiedBackup, recovery: result };
 }
-export function assertUpgradeRunStorageReady(context, projectRoot) {
+export function assertUpgradeRunStorageReady(context, projectRoot, engine) {
     const project = context.db.get("SELECT id FROM projects WHERE root = ?", [resolveProjectRoot(projectRoot)]);
     if (!project)
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires a registered project with explicit migration apply", 1);
@@ -277,12 +296,57 @@ export function assertUpgradeRunStorageReady(context, projectRoot) {
     if (!source || !target)
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires source and target Memory Bank versions", 1);
     const applied = context.db.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, source, target)]);
-    if (!applied)
+    if (!applied || engine !== undefined) {
+        const assessment = assessMigrationImpact(context, { projectRoot });
+        const blockers = assessment.blockers;
+        const chain = assessment.chain;
+        if (!blockers.length && (engine !== undefined || chain.every(step => !step.runtime_migration))) {
+            const canon = upgradeCanon(context).canon;
+            const contract = prepareJsonFile(path.join(canon.flow_root, "flow-contract.json"), "Target flow contract");
+            let selectedEngineStorage;
+            if (engine !== undefined) {
+                if (!(engine instanceof AdmittedFrozenEngine))
+                    throw new AppError("upgrade_storage_incompatible", "Upgrade requires an admitted selected engine", 1, { effect: "no_effect" });
+                const compatibility = prepareJsonFile(path.join(canon.flow_root, "compatibility.json"), "Target engine compatibility");
+                validateSchema({ schemaName: "compatibility", file: compatibility.file, data: compatibility.value,
+                    schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+                const manifest = engine.manifest();
+                if (compatibility.value.memory_bank_version !== target || compatibility.value.dd_flow_cli.flow_contract !== contract.value.id
+                    || manifest.package_name !== compatibility.value.dd_flow_cli.package_name || !semver.valid(compatibility.value.dd_flow_cli.min_version)
+                    || semver.lt(manifest.package_version, compatibility.value.dd_flow_cli.min_version)
+                    || manifest.package_name !== compatibility.value.engine.package_name
+                    || !semver.satisfies(manifest.package_version, compatibility.value.engine.version_range, { includePrerelease: true }))
+                    throw new AppError("upgrade_storage_incompatible", "Selected engine is incompatible with target canon", 1, { effect: "no_effect" });
+                selectedEngineStorage = engine.admitMemoryUpgradeStorage(context.ddFlowHome, resourceHome(context));
+            }
+            // Reuse the executing CLI's physical compatibility checks, not version text
+            // or a synthetic apply marker. This does not authorize storage migration.
+            const runOwner = fs.lstatSync(context.db.path);
+            if (!runOwner.isFile() || runOwner.nlink !== 1)
+                throw new AppError("upgrade_storage_incompatible", "Upgrade requires a regular single-linked runtime store", 1, { effect: "no_effect" });
+            const run = PreparedMemoryInitRuntimeStorage.prepareUpgrade(context);
+            const resource = PreparedMemoryInitResourceStorage.prepare(context);
+            const currentOwner = fs.lstatSync(context.db.path);
+            if (currentOwner.dev !== runOwner.dev || currentOwner.ino !== runOwner.ino)
+                throw new AppError("upgrade_storage_changed", "Runtime store changed during upgrade admission", 1, { effect: "no_effect" });
+            const manifest = prepareJsonFile(path.resolve(projectRoot, status.flow_pack.manifest_path), "Current flow-pack provenance");
+            return { schema_id: "dd-flow/mb-upgrade-storage-readiness@1", route: "verified-no-op",
+                source_version: source, target_version: target, chain,
+                current_provenance: { path: manifest.file, sha256: crypto.createHash("sha256").update(manifest.text).digest("hex") },
+                target: { root: canon.root, commit: canon.commit, contract_sha256: crypto.createHash("sha256").update(contract.text).digest("hex") },
+                ...(selectedEngineStorage ? { selected_engine_storage: selectedEngineStorage } : {}),
+                stores: [{ ...run.facts(), store_dev: runOwner.dev, store_ino: runOwner.ino }, resource.facts()].map(store => ({ store_kind: store.store_kind,
+                    store_dev: store.store_dev, store_ino: store.store_ino,
+                    store_path: store.store_path, schema_sha256: store.schema_sha256,
+                    executing_writer_version: store.executing_writer_version })) };
+        }
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires explicit migration apply before RUN creation", 1, {
             source_version: source,
             target_version: target,
+            blockers,
             next_action: "run migration plan, verify and explicit migration apply first"
         });
+    }
     const value = recordValue(parseJsonValue(applied.value_json));
     if (!value || !["applied", "verified_noop"].includes(stringValue(value.status) ?? "")) {
         throw new AppError("migration_not_applied", "mb-upgrade RUN has no successful explicit migration apply evidence", 1, {
@@ -290,6 +354,8 @@ export function assertUpgradeRunStorageReady(context, projectRoot) {
             target_version: target
         });
     }
+    return { schema_id: "dd-flow/mb-upgrade-storage-readiness@1", route: "existing-apply",
+        source_version: source, target_version: target, apply: value };
 }
 export function verifyMigrationReport(_context, input) {
     const filePath = path.resolve(input.file);
@@ -452,61 +518,45 @@ function hasActiveState(active) {
 function applyKey(projectId, source, target) {
     return `mb-upgrade.apply.${projectId}.${source}.${target}`;
 }
-function adjacentMigrationChain(source, target, impacts = []) {
-    if (source === target)
-        return { status: "ok", steps: [] };
-    const sourceParts = parseSemver(source);
-    const targetParts = parseSemver(target);
-    if (!sourceParts || !targetParts) {
+export function adjacentMigrationChain(source, target, impacts = []) {
+    if (semver.valid(source) !== source || semver.valid(target) !== target) {
         return { status: "unsupported", reason: "source or target version is not semver", steps: [] };
     }
-    if (impacts.length > 0) {
-        const steps = [];
-        const visited = new Set();
-        let current = source;
-        while (current !== target) {
-            if (visited.has(current))
-                return { status: "unsupported", reason: "release impact chain contains a cycle", steps: [] };
-            visited.add(current);
-            const impact = impacts.find((item) => item.from_version === current);
-            if (!impact)
-                return { status: "unsupported", reason: `missing adjacent release impact from ${current}`, steps: [] };
-            steps.push({
-                id: `${impact.from_version}-to-${impact.to_version}`,
-                from: impact.from_version,
-                to: impact.to_version,
-                status: "planned",
-                minimum_upgrade_mode: impact.minimum_upgrade_mode,
-                domains: impact.domains,
-                path_migration: impact.path_migration,
-                runtime_migration: impact.runtime_migration,
-                required_checks: impact.required_checks
-            });
-            current = impact.to_version;
-            const next = parseSemver(current);
-            if (!next || compareParts(next, targetParts) > 0) {
-                return { status: "unsupported", reason: `release impact chain overshoots target ${target}`, steps: [] };
-            }
-        }
-        return { status: "ok", steps };
-    }
-    if (sourceParts.major !== targetParts.major) {
-        return { status: "unsupported", reason: "major version migration requires canonical release-impact units", steps: [] };
-    }
-    if (targetParts.minor < sourceParts.minor || (targetParts.minor === sourceParts.minor && targetParts.patch < sourceParts.patch)) {
+    if (semver.gt(source, target))
         return { status: "unsupported", reason: "downgrade migrations are not supported", steps: [] };
-    }
+    if (source === target)
+        return { status: "ok", steps: [] };
     const steps = [];
-    let current = { ...sourceParts };
-    while (compareParts(current, targetParts) < 0) {
-        const next = nextAdjacent(current, targetParts);
+    const visited = new Set();
+    let current = source;
+    while (current !== target) {
+        if (visited.has(current))
+            return { status: "unsupported", reason: "release impact chain contains a cycle", steps: [] };
+        visited.add(current);
+        const matches = impacts.filter(item => item.from_version === current);
+        if (matches.length > 1)
+            return { status: "unsupported", reason: `ambiguous adjacent release impacts from ${current}`, steps: [] };
+        const impact = matches[0];
+        if (!impact)
+            return { status: "unsupported", reason: `missing adjacent release impact from ${current}`, steps: [] };
+        if (semver.valid(impact.to_version) !== impact.to_version || !semver.gt(impact.to_version, current)) {
+            return { status: "unsupported", reason: "release impact chain must advance through valid versions", steps: [] };
+        }
+        if (semver.gt(impact.to_version, target))
+            return { status: "unsupported", reason: `release impact chain overshoots target ${target}`, steps: [] };
         steps.push({
-            id: `${formatParts(current)}-to-${formatParts(next)}`,
-            from: formatParts(current),
-            to: formatParts(next),
-            status: "planned"
+            id: `${impact.from_version}-to-${impact.to_version}`,
+            from: impact.from_version,
+            to: impact.to_version,
+            status: "planned",
+            minimum_upgrade_mode: impact.minimum_upgrade_mode,
+            domains: impact.domains,
+            path_migration: impact.path_migration,
+            runtime_migration: impact.runtime_migration,
+            required_checks: impact.required_checks,
+            ...(impact.source_reference ? { source_reference: impact.source_reference } : {})
         });
-        current = next;
+        current = impact.to_version;
     }
     return { status: "ok", steps };
 }
@@ -556,24 +606,3 @@ function recordValue(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
-function parseSemver(value) {
-    const match = value.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)/);
-    if (!match?.[1] || !match[2] || !match[3])
-        return null;
-    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
-}
-function compareParts(left, right) {
-    if (left.major !== right.major)
-        return left.major - right.major;
-    if (left.minor !== right.minor)
-        return left.minor - right.minor;
-    return left.patch - right.patch;
-}
-function nextAdjacent(current, target) {
-    if (current.minor < target.minor)
-        return { major: current.major, minor: current.minor + 1, patch: 0 };
-    return { major: current.major, minor: current.minor, patch: Math.min(current.patch + 1, target.patch) };
-}
-function formatParts(parts) {
-    return `${parts.major}.${parts.minor}.${parts.patch}`;
-}

package/dist/services/native-daemon-history.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { nativeShutdownConfirmed } from "../harness-runtime/lib/native-children.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
@@ -29,7 +30,7 @@ export function historicalDaemonSettlement(context, scopeId, record) {
     if (!state.daemon_id || path.basename(file) !== `${state.daemon_id}.json` || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || owner.dd_flow_home !== metadata.dd_flow_home || !retainedResourceHomeMatches(context, owner.resource_home) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.lease_token !== record.lease_token || state.pid !== record.pid)
         throw new AppError("runtime_scope_owner_unknown", "Archived daemon does not match its registration", 1);
     const closed = state.shutdown_state === "clean" && state.active_tree === false
-        ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+        ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && nativeShutdownConfirmed(operation.result, { daemonId: state.daemon_id ?? "" })) : undefined;
     const fresh = managedProcessStatus(context).find(item => item.id === record.id);
     if (!closed || !fresh || fresh.lease_token !== record.lease_token || fresh.pid !== record.pid || fresh.pid_started_at !== record.pid_started_at || fresh.metadata_json !== record.metadata_json || fresh.state !== "stopped" || fresh.termination_reason !== "daemon_stopped" || processTreeIsAlive(fresh) || fs.readFileSync(file, "utf8") !== bytes)
         throw new AppError("runtime_scope_outcome_unknown", "Previous daemon lacks stable clean shutdown evidence", 1);

package/dist/services/physical-startup.js

@@ -0,0 +1,45 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { createRenewalState, maintenanceRetryable, renewalDelay, renewalFailure, RENEWAL_POLICY } from "../harness-runtime/lib/lease-renewal.mjs";
+import { processStartedAt } from "./managed-processes.js";
+/** Birth and confirmation share one startup horizon. Retrying observations
+ * neither launches another child nor renews an unconfirmed resource lease. */
+export function physicalStartup(databaseDeadlineAt) {
+    const deadline = performance.now() + RENEWAL_POLICY.startupMs;
+    const episode = createRenewalState();
+    const unavailable = () => new AppError("process_ownership_unknown", "Managed physical identity observation is unavailable", 1, { phase: "process_confirmation", effect: "no_effect", native_dispatch_started: false, reason: "physical_identity_unavailable" });
+    async function observe(operation, assertCurrent, leaseExpiresAt) {
+        let last;
+        const remaining = () => Math.max(0, Math.min(deadline - performance.now(), databaseDeadlineAt === undefined ? Infinity : databaseDeadlineAt - Date.now(), leaseExpiresAt === undefined ? Infinity : Date.parse(leaseExpiresAt) - Date.now() - RENEWAL_POLICY.safetyMs));
+        for (;;) {
+            assertCurrent();
+            if (!(remaining() > 0))
+                throw last ?? unavailable();
+            try {
+                const result = operation();
+                assertCurrent();
+                if (!(remaining() > 0))
+                    throw new AppError("process_startup_expired", "Physical observation completed after its original admission horizon", 1, { phase: "process_confirmation", effect: "unknown", native_dispatch_started: false });
+                return result;
+            }
+            catch (error) {
+                // A stale owner/cancellation wins over a transient observation error.
+                assertCurrent();
+                const details = error instanceof AppError ? error.details : null;
+                if (!(error instanceof AppError) || error.code !== "process_ownership_unknown" || details?.reason !== "physical_identity_unavailable" || !maintenanceRetryable(error))
+                    throw error;
+                last = error;
+                renewalFailure(episode);
+                if (!(remaining() > 0))
+                    throw error;
+                await delay(Math.min(renewalDelay(episode), remaining()));
+            }
+        }
+    }
+    return { observe, birth: (assertCurrent) => observe(() => {
+            const started = processStartedAt(process.pid);
+            if (!started)
+                throw unavailable();
+            return { pid: process.pid, pid_started_at: started };
+        }, assertCurrent) };
+}

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,58 +1,17 @@
-import fs from "node:fs";
 import path from "node:path";
 import { foreignKeyTransaction } from "../storage/foreign-key-transaction.js";
-import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.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";
-/** 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 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);
@@ -92,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) {
@@ -244,35 +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) {
-    // 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;
-}
-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,
@@ -282,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;