@software-dlc/cli 0.157.2

package/dist/local/workspace-runtime.js

@@ -0,0 +1,2124 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { getLibraryOriginWarnings } from '@software-dlc/graph/validator';
+import { composeGraphProjection, diffProjectionGraphs, extendScopedProjection, graphHasProjectionEntity, hasProjectionManifest, isScopedProjection, materializeGraphProjection, projectionDiffHasChanges, projectionHasManagedContent, projectionScopeOfTaskScope, recordScopedProjectionFiles, removeEmptyGraphProjection, removeProjectionEntity, validateProjectionGraph, writeJsonAtomically } from './projection.js';
+import { heldPackages, packageUseCommitIssues } from './package-uses-check.js';
+import { introducedBrokenIssues, introducedValidationWarnings } from './workspace-merge.js';
+import { planEvidenceSign, signedMeta } from './workspace-evidence.js';
+import { evidenceWith, ReferenceLimitError, sourceIndex, sourceReference } from './workspace-sources.js';
+import { evidenceStatus } from './workspace-evidence-status.js';
+import { droppedEvidenceReferences, evidenceDropWarning } from './workspace-evidence-drop.js';
+import { assertLocalWorkspacePathsIgnored, createDetachedGitWorktree, discoverGitRemoteIdentity, gitRemoteNames, discoverGitWorktree, removeGitWorktree, namingRemote, repositoryNames, trackedRemoteName } from './git.js';
+import { LocalWorkspaceGraphStore, localGraphRootHash, resolveLocalRepositoryStateDirectory } from './workspace-graph-store.js';
+import { blastRadius } from './blast-radius.js';
+import { findGraphEntities, showGraphEntities } from './graph-read.js';
+import { readFolderMembers, repositoryTaskScope } from './folder-members.js';
+import { variantMemberFormIds, variantSyncIds, variantsReport } from './variants.js';
+import { withWorkspaceOperationLock } from './workspace-lock.js';
+import { allocationUnits, compareLocalWorkspacePlans } from './workspace-overlap.js';
+import { allocationUnitKey, combineValidationUnits, firstOwnChanges } from './workspace-overlap-allocation.js';
+import { LocalWorkspaceCommitResolver } from './workspace-commit-resolver.js';
+import { LocalWorkspaceAuthorityGuard } from './workspace-authority-guard.js';
+import { readBuiltView as readBuiltGraph } from './workspace-built-content.js';
+import { listClaims } from './workspace-claim-views.js';
+import { claimStatus, gitClaimStatusReader } from './workspace-claim-status.js';
+import { workspaceControlDirectory as controlDirectory, workspaceProjectionDirectory as projectionDirectory } from './workspace-paths.js';
+import { LocalWorkspaceStore } from './workspace-store.js';
+import { LocalWorkspaceHandoffRuntime } from './workspace-runtime-handoff.js';
+import { LocalWorkspacePruner } from './workspace-prune.js';
+import { inspectLocalWorkspaceAuthority } from './workspace-authority.js';
+import { LocalWorkspaceResolverProviderStore } from './workspace-resolver-provider.js';
+import { LocalWorkspaceRemoteProviderStore } from './workspace-remote-provider.js';
+import { LocalWorkspaceRemoteFetcher } from './workspace-remote-fetch.js';
+import { LocalWorkspaceBranchRuntime } from './workspace-branch-runtime.js';
+import { LocalWorkspaceIntegrationRuntime } from './workspace-integration-runtime.js';
+import { LocalWorkspacePickRuntime } from './workspace-pick-runtime.js';
+import { LocalWorkspaceEnvironmentRuntime } from './workspace-environment-runtime.js';
+import { LocalWorkspaceUpstreamRuntime } from './workspace-upstream-runtime.js';
+import { LocalWorkspaceRemotePusher } from './workspace-remote-push.js';
+import { LocalWorkspaceRemoteTopicPublisher } from './workspace-remote-topic.js';
+import { LocalWorkspaceRemotePullRequestCreator } from './workspace-remote-pull-request.js';
+import { LocalWorkspacePortableAuthoring } from './workspace-portable-authoring.js';
+import { assertGraphChangesWithinTaskScope, assertNodeTypeRulesOnChangedNodes, assertNoRetiredKeysOnChangedNodes, graphChangeCoordinates, ruleCovers, local_workspace_task_scope_schema } from './workspace-scope.js';
+import { assertIntroducedVocabularyAdmitted } from './workspace-admission.js';
+import { canonicalizePortableGraph, stringifyCanonicalGraph } from './canonical.js';
+import { introducedDanglingDocumentEmbeds } from './document-embeds.js';
+import { readWorkspaceTopology, removeWorkspaceTopology, topologyBindingMatch, writeWorkspaceTopology } from './workspace-topology.js';
+import { registerWorkspaceRuntimeLease, releaseWorkspaceRuntimeLease, withGraphRepositoryTopologyLock } from './workspace-runtime-lease.js';
+/**
+ * When init and attach began binding the naming remote: e33d186f reached
+ * origin/main in the production merge 866a9426cd. A binding made on origin
+ * since by a CLI from before that release is not told apart and keeps origin.
+ */
+const NAMING_REMOTE_RULE_AT = '2026-10-28T21:14:06.000Z';
+/**
+ * The node types a graph starts from, outside in (the local-graph-start
+ * skill): one is missing when no node of it exists. Complete graph validation
+ * does not ask for them, so a commit only warns.
+ */
+const STARTING_NODE_TYPES = [
+    ['system', 'the product'],
+    ['actor', 'the people and outside systems that use it']
+];
+/** An outside system, or one nested in another node, is not the product. */
+function startsTheGraph(node) {
+    if (node.type !== 'system')
+        return true;
+    const system = node.data?.data
+        ?.system;
+    return !node.parentId && system?.external !== true;
+}
+function graphShapeWarnings(graph) {
+    const types = new Set(graph.nodes.filter(startsTheGraph).map((node) => node.type));
+    return STARTING_NODE_TYPES.filter(([type]) => !types.has(type)).map(([type, what]) => `The graph has no ${type} node for ${what}.`);
+}
+function brokenValidationMessages(graph) {
+    return validateProjectionGraph(graph)
+        .issues.filter((issue) => issue.status === 'broken')
+        .map((issue) => `${issue.code}: ${issue.message}`);
+}
+export class LocalWorkspaceRuntime {
+    git;
+    state_dir;
+    store;
+    graphs;
+    topology;
+    runtime_lease;
+    closed = false;
+    resolver_store;
+    remote_store;
+    remote_fetcher;
+    remote_pusher;
+    remote_topic_publisher;
+    remote_pull_request_creator;
+    portable_authoring;
+    commits;
+    authority;
+    handoff_runtime;
+    pruner;
+    branch_runtime;
+    integration_runtime;
+    pick_runtime;
+    upstream_runtime;
+    environment_runtime;
+    materialize_projection;
+    constructor(input) {
+        this.git = input.git;
+        this.state_dir = input.state_dir;
+        this.store = input.store;
+        this.topology = input.topology;
+        this.runtime_lease = input.runtime_lease;
+        this.materialize_projection =
+            input.materialize_projection ?? materializeGraphProjection;
+        this.graphs = new LocalWorkspaceGraphStore(input.state_dir);
+        this.commits = new LocalWorkspaceCommitResolver(input.store, this.graphs);
+        this.authority = new LocalWorkspaceAuthorityGuard(input.git.repository_root, input.git.git_common_dir, input.store);
+        this.branch_runtime = new LocalWorkspaceBranchRuntime(input.git, input.store, this.authority, this.commits, this.materialize_projection);
+        this.integration_runtime = new LocalWorkspaceIntegrationRuntime(input.store, this.graphs, this.authority, this.commits, this.materialize_projection);
+        this.pick_runtime = new LocalWorkspacePickRuntime(input.store, this.graphs, this.authority, this.commits, this.materialize_projection);
+        this.upstream_runtime = new LocalWorkspaceUpstreamRuntime(input.store, this.authority, this.commits, this.materialize_projection);
+        this.resolver_store = new LocalWorkspaceResolverProviderStore(input.state_dir);
+        this.remote_store = new LocalWorkspaceRemoteProviderStore(input.state_dir);
+        this.remote_fetcher = new LocalWorkspaceRemoteFetcher(this.remote_store, input.store.remote_tracking, input.store.portable_commits, this.graphs);
+        this.remote_pusher = new LocalWorkspaceRemotePusher(this.remote_store, input.store.remote_push, input.store.portable_commits, this.graphs, input.state_dir);
+        this.remote_topic_publisher = new LocalWorkspaceRemoteTopicPublisher(this.remote_store, input.store.remote_topic, input.store.portable_commits, this.graphs, input.state_dir);
+        this.remote_pull_request_creator =
+            new LocalWorkspaceRemotePullRequestCreator(this.remote_store, input.store.remote_pull_request, input.state_dir);
+        this.portable_authoring = new LocalWorkspacePortableAuthoring(input.store.portable_commits, input.store.remote_tracking);
+        this.environment_runtime = new LocalWorkspaceEnvironmentRuntime(input.store, this.authority, this.resolver_store, this.remote_store, this.remote_fetcher, this.remote_pusher, this.remote_topic_publisher, this.remote_pull_request_creator, this.portable_authoring);
+        this.handoff_runtime = new LocalWorkspaceHandoffRuntime({
+            repository_root: input.git.repository_root,
+            git_common_dir: input.git.git_common_dir,
+            store: input.store,
+            graphs: this.graphs,
+            materialize_projection: this.materialize_projection
+        });
+        this.pruner = new LocalWorkspacePruner({
+            repository_root: input.git.repository_root,
+            current_worktree_path: input.git.repository_root,
+            store: input.store,
+            graphs: this.graphs,
+            assert_actor_authority: async (workspace_id) => {
+                await this.authority.requireCurrent(workspace_id);
+            }
+        });
+    }
+    static async open(input = {}) {
+        const git = await discoverGitWorktree(input.cwd);
+        const initial_topology = await readWorkspaceTopology(git.repository_root);
+        const open_runtime = async (topology) => {
+            if (topology &&
+                input.state_dir &&
+                resolve(input.state_dir) !== topology.state_dir) {
+                throw new Error('Explicit state directory conflicts with checkout topology.');
+            }
+            if (topology &&
+                input.graph_repository_id &&
+                input.graph_repository_id !== topology.graph_repository_id) {
+                throw new Error('Explicit graph repository identity conflicts with checkout topology.');
+            }
+            const state_dir = resolveLocalRepositoryStateDirectory({
+                git_common_dir: git.git_common_dir,
+                override: input.state_dir ?? topology?.state_dir
+            });
+            const store = await LocalWorkspaceStore.open({
+                state_dir,
+                git_common_dir: git.git_common_dir,
+                expected_repository_id: input.graph_repository_id ?? topology?.graph_repository_id
+            });
+            try {
+                if (topology) {
+                    const workspace = store.getWorkspaceByGitWorktreePath(git.repository_root);
+                    if (!workspace ||
+                        workspace.status !== 'active' ||
+                        workspace.id !== topology.workspace_id) {
+                        throw new Error('Checkout topology does not identify its active graph workspace.');
+                    }
+                    const binding = store.getSourceRepositoryBinding(git.git_common_dir);
+                    const match = topologyBindingMatch({ topology, binding });
+                    if (match === 'mismatch') {
+                        throw new Error('Checkout topology does not match its source repository binding.');
+                    }
+                    if (match === 'moved') {
+                        // The binding moved to upstream; this checkout catches up
+                        topology = {
+                            ...topology,
+                            source_remote_identity: binding.remote_identity
+                        };
+                        await writeWorkspaceTopology({
+                            repository_root: git.repository_root,
+                            topology
+                        }).catch(() => undefined);
+                    }
+                }
+                const runtime_lease = await registerWorkspaceRuntimeLease({
+                    graph_repository_id: store.repository.repository_id,
+                    state_dir,
+                    repository_root: git.repository_root
+                });
+                try {
+                    return new LocalWorkspaceRuntime({
+                        git,
+                        state_dir,
+                        store,
+                        topology,
+                        runtime_lease,
+                        materialize_projection: input.materialize_projection
+                    });
+                }
+                catch (error) {
+                    releaseWorkspaceRuntimeLease(runtime_lease);
+                    throw error;
+                }
+            }
+            catch (error) {
+                store.close();
+                throw error;
+            }
+        };
+        const expected_repository_id = input.graph_repository_id ?? initial_topology?.graph_repository_id;
+        if (expected_repository_id) {
+            return withGraphRepositoryTopologyLock({
+                graph_repository_id: expected_repository_id,
+                operation: 'open-runtime',
+                run: async () => {
+                    const topology = await readWorkspaceTopology(git.repository_root);
+                    if (initial_topology &&
+                        topology?.graph_repository_id !==
+                            initial_topology.graph_repository_id) {
+                        throw new Error('Checkout topology changed while opening runtime.');
+                    }
+                    return open_runtime(topology);
+                }
+            });
+        }
+        const runtime = await open_runtime(null);
+        return runtime;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.store.close();
+        }
+        finally {
+            releaseWorkspaceRuntimeLease(this.runtime_lease);
+        }
+    }
+    async initializeCurrentWorkspace(input = {}) {
+        await assertLocalWorkspacePathsIgnored(this.git.repository_root);
+        const existing = this.store.getWorkspaceByGitWorktreePath(this.git.repository_root);
+        if (existing) {
+            if (existing.status !== 'active') {
+                throw new Error('The current Git worktree is registered as closed.');
+            }
+            await this.persistCurrentTopology(existing, input.storage_mode);
+            return this.getWorkspaceStatus(existing.id);
+        }
+        const projection_dir = join(this.git.repository_root, 'sdlc');
+        // A repository that never had a hosted checkout has no projection yet:
+        // start its local graph empty, so local-only use needs no account. A
+        // failed init removes that empty projection again, so the worktree is
+        // left as it was found.
+        const starts_empty = !(await projectionHasManagedContent(projection_dir));
+        try {
+            if (starts_empty) {
+                await materializeGraphProjection({
+                    projection_dir,
+                    graph: {
+                        nodes: [],
+                        edges: [],
+                        tags: [],
+                        paths: [],
+                        path_relations: []
+                    }
+                });
+            }
+            return await this.registerProjectionAsWorkspace(projection_dir, input);
+        }
+        catch (error) {
+            if (starts_empty)
+                await removeEmptyGraphProjection(projection_dir);
+            throw error;
+        }
+    }
+    async registerProjectionAsWorkspace(projection_dir, input) {
+        const { graph } = await composeGraphProjection(projection_dir);
+        const issues = brokenValidationMessages(graph);
+        if (issues.length > 0) {
+            throw new Error(`Cannot initialize invalid projection: ${issues.join('; ')}`);
+        }
+        const root_hash = await this.graphs.writeGraph(graph);
+        if (input.source_repository_association_id) {
+            await this.bindCurrentSourceRepository({
+                source_repository_association_id: input.source_repository_association_id,
+                remote_name: input.source_remote_name
+            });
+        }
+        const workspace = this.store.registerForegroundWorkspace({
+            actor_kind: input.actor_kind ?? 'human',
+            git_worktree_path: this.git.repository_root,
+            git_dir: this.git.git_dir,
+            git_common_dir: this.git.git_common_dir,
+            git_head_commit_id: this.git.head,
+            sdlc_head_commit_id: root_hash,
+            attached_ref: this.git.ref
+        });
+        try {
+            await mkdir(controlDirectory(workspace), {
+                recursive: true,
+                mode: 0o700
+            });
+            const status = await this.getWorkspaceStatus(workspace.id);
+            await this.persistCurrentTopology(workspace, input.storage_mode);
+            return status;
+        }
+        catch (error) {
+            this.store.closeWorkspace({
+                actor_workspace_id: workspace.id,
+                workspace_id: workspace.id,
+                expected_head_commit_id: workspace.head_sdlc_commit_id
+            });
+            const binding = this.store.getSourceRepositoryBinding(this.git.git_common_dir);
+            if (binding) {
+                this.store.unbindSourceRepository({
+                    git_common_dir: this.git.git_common_dir,
+                    expected_source_repository_association_id: binding.source_repository_association_id
+                });
+            }
+            throw error;
+        }
+    }
+    async persistCurrentTopology(workspace, storage_mode, repository_root = this.git.repository_root, git_common_dir = this.git.git_common_dir) {
+        const binding = this.store.getSourceRepositoryBinding(git_common_dir);
+        const default_state_dir = resolveLocalRepositoryStateDirectory({
+            git_common_dir
+        });
+        const now = new Date().toISOString();
+        const written = await writeWorkspaceTopology({
+            repository_root,
+            topology: {
+                version: 1,
+                graph_repository_id: this.store.repository.repository_id,
+                workspace_id: workspace.id,
+                state_dir: this.state_dir,
+                storage_mode: storage_mode ??
+                    (this.state_dir === default_state_dir
+                        ? 'self_contained'
+                        : 'machine_shared'),
+                source_repository_association_id: binding?.source_repository_association_id ?? null,
+                source_remote_identity: binding?.remote_identity ?? null,
+                created_at: now,
+                updated_at: now
+            }
+        });
+        if (repository_root === this.git.repository_root) {
+            this.topology = written.topology;
+        }
+    }
+    async bindCurrentSourceRepository(input) {
+        const remote = await discoverGitRemoteIdentity(this.git.repository_root, input.remote_name ??
+            this.store.getSourceRepositoryBinding(this.git.git_common_dir)
+                ?.remote_name ??
+            (await this.defaultSourceRemote(input.source_repository_association_id)));
+        return this.store.bindSourceRepository({
+            git_common_dir: this.git.git_common_dir,
+            source_repository_association_id: input.source_repository_association_id,
+            remote_name: remote.remote_name,
+            remote_url: remote.remote_url,
+            remote_identity: remote.repository_identity
+        });
+    }
+    /**
+     * The remote a new binding takes when none is named: the one the
+     * association is bound to from another clone, when this repository has a
+     * remote of that identity; else the remote its references are named from
+     * (namingRemote), else origin. A binding the repository already has keeps
+     * its own remote (bindCurrentSourceRepository).
+     */
+    async defaultSourceRemote(source_repository_association_id) {
+        const root = this.git.repository_root;
+        const naming = (await namingRemote(root)) ?? 'origin';
+        const bound = this.store.getSourceAssociationBinding(source_repository_association_id);
+        if (!bound)
+            return naming;
+        for (const name of new Set([
+            naming,
+            bound.remote_name,
+            ...(await gitRemoteNames(root))
+        ])) {
+            const identity = await discoverGitRemoteIdentity(root, name).catch(() => null);
+            if (identity?.repository_identity === bound.remote_identity)
+                return name;
+        }
+        return naming;
+    }
+    /**
+     * A binding made before init and attach bound the naming remote (2026-10-28)
+     * may name a fork's origin while its references name upstream: this moves
+     * it to upstream, with the topology of every attached checkout of the
+     * repository, so a workspace commit's remote identity names the repository
+     * its references name. Only origin gives way, only to upstream, as in
+     * repositoryNames, and only for a binding made before that rule, so a
+     * remote chosen since is kept. Only the binding row moves: a checkout's
+     * topology still naming origin matches it as moved, and opening the
+     * checkout rewrites it. Returns the identities it moved between, or null.
+     */
+    async realignForkBinding(repository_root = this.git.repository_root, git_common_dir = this.git.git_common_dir) {
+        const binding = this.store.getSourceRepositoryBinding(git_common_dir);
+        if (binding?.remote_name !== 'origin')
+            return null;
+        if (binding.created_at >= NAMING_REMOTE_RULE_AT)
+            return null;
+        if (!(await gitRemoteNames(repository_root)).includes('upstream')) {
+            return null;
+        }
+        if ((await namingRemote(repository_root)) !== 'upstream')
+            return null;
+        const origin = await discoverGitRemoteIdentity(repository_root, 'origin');
+        // A changed origin is the binding mismatch, reported where it is checked
+        if (origin.repository_identity !== binding.remote_identity)
+            return null;
+        const upstream = await discoverGitRemoteIdentity(repository_root, 'upstream');
+        if (upstream.repository_identity === binding.remote_identity)
+            return null;
+        // One store transaction: every checkout's topology still naming origin is
+        // read as moved (topologyBindingMatch), and rewritten when it is opened
+        const moved = this.store.rebindSourceRepositoryRemote({
+            git_common_dir,
+            expected_remote_name: 'origin',
+            remote_name: upstream.remote_name,
+            remote_url: upstream.remote_url,
+            remote_identity: upstream.repository_identity
+        });
+        if (!moved)
+            return null;
+        if (this.topology && repository_root === this.git.repository_root) {
+            this.topology = {
+                ...this.topology,
+                source_remote_identity: moved.remote_identity
+            };
+        }
+        return { from: binding.remote_identity, to: moved.remote_identity };
+    }
+    async attachCurrentSourceWorkspace(input) {
+        await assertLocalWorkspacePathsIgnored(this.git.repository_root);
+        if (this.store.getWorkspaceByGitWorktreePath(this.git.repository_root)) {
+            throw new Error('The current Git worktree is already registered.');
+        }
+        const projection_dir = join(this.git.repository_root, 'sdlc');
+        try {
+            await stat(projection_dir);
+            throw new Error('Refusing to attach over an existing local graph projection.');
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                !('code' in error) ||
+                error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        const existing_binding = this.store.getSourceRepositoryBinding(this.git.git_common_dir);
+        await this.bindCurrentSourceRepository({
+            source_repository_association_id: input.source_repository_association_id,
+            remote_name: input.source_remote_name
+        });
+        const workspace = this.store.forkWorkspace({
+            actor_workspace_id: input.source_workspace_id,
+            expected_source_sdlc_head_commit_id: input.expected_source_sdlc_head_commit_id,
+            git_worktree_path: this.git.repository_root,
+            git_dir: this.git.git_dir,
+            git_common_dir: this.git.git_common_dir,
+            git_head_commit_id: this.git.head,
+            actor_kind: input.actor_kind ?? 'human',
+            task_scope: input.task_scope
+        });
+        try {
+            const graph = await this.readCommitGraph(workspace.head_sdlc_commit_id);
+            await this.materialize_projection({
+                projection_dir,
+                graph,
+                ...(input.full_projection
+                    ? {}
+                    : { scope: projectionScopeOfTaskScope(input.task_scope) })
+            });
+            await mkdir(controlDirectory(workspace), {
+                recursive: true,
+                mode: 0o700
+            });
+            const status = await this.getWorkspaceStatus(workspace.id);
+            await this.persistCurrentTopology(workspace, input.storage_mode);
+            return status;
+        }
+        catch (error) {
+            this.store.closeWorkspace({
+                actor_workspace_id: input.source_workspace_id,
+                workspace_id: workspace.id,
+                expected_head_commit_id: workspace.head_sdlc_commit_id
+            });
+            this.store.removeClosedWorkspaceRegistration({
+                workspace_id: workspace.id,
+                source_workspace_id: input.source_workspace_id,
+                git_worktree_path: this.git.repository_root
+            });
+            if (!existing_binding) {
+                this.store.unbindSourceRepository({
+                    git_common_dir: this.git.git_common_dir,
+                    expected_source_repository_association_id: input.source_repository_association_id
+                });
+            }
+            await rm(projection_dir, { recursive: true, force: true });
+            await rm(controlDirectory(workspace), { recursive: true, force: true });
+            throw error;
+        }
+    }
+    /**
+     * Attaches every other repository of the folder whose home this workspace's
+     * checkout belongs to (run in its plan coordinator), each from this
+     * workspace's head with its whole-repository scope (repositoryTaskScope).
+     * A member that cannot attach now (already attached, no node cites it yet,
+     * or attach refuses) is skipped with its reason, so a rerun picks it up.
+     */
+    async attachFolderMembers(input = {}) {
+        const source = this.currentActiveWorkspace();
+        if (source.source_workspace_id !== null) {
+            // Every worktree of the home reads the folder; members attach to the coordinator, never a task
+            throw new Error(`Run attach --all-members in the plan coordinator: workspace ${source.id} is a child task workspace.`);
+        }
+        const folder = await readFolderMembers(this.git.git_common_dir);
+        const graph = await this.readCommitGraph(source.head_sdlc_commit_id);
+        const result = {
+            version: 1,
+            folder: folder.folder,
+            source_workspace_id: source.id,
+            head_revision: source.head_sdlc_commit_id,
+            attached: [],
+            skipped: [...folder.skipped],
+            behind: [],
+            rebound: []
+        };
+        for (const member of folder.members) {
+            const skip = (reason) => result.skipped.push({ ...member, reason });
+            let runtime;
+            try {
+                runtime = await LocalWorkspaceRuntime.open({
+                    cwd: member.path,
+                    state_dir: this.state_dir,
+                    graph_repository_id: this.store.repository.repository_id
+                });
+            }
+            catch (error) {
+                skip(error.message);
+                continue;
+            }
+            try {
+                const attached = runtime.store.getWorkspaceByGitWorktreePath(runtime.git.repository_root);
+                if (attached?.status === 'active') {
+                    let reason = `already attached as workspace ${attached.id}`;
+                    try {
+                        const realigned = await runtime.realignForkBinding();
+                        if (realigned)
+                            result.rebound.push({ ...member, ...realigned });
+                    }
+                    catch (error) {
+                        reason += `; its binding was not moved to upstream: ${error.message}`;
+                    }
+                    skip(reason);
+                    // Attached from an older head: name the reconcile that catches it up
+                    if (attached.source_workspace_id === source.id &&
+                        attached.head_sdlc_commit_id !== source.head_sdlc_commit_id &&
+                        !runtime.store.history.isAncestor(source.head_sdlc_commit_id, attached.head_sdlc_commit_id)) {
+                        result.behind.push({
+                            ...member,
+                            workspace_id: attached.id,
+                            head_revision: attached.head_sdlc_commit_id,
+                            catch_up: `sdlc integrate reconcile --source ${source.id}`
+                        });
+                    }
+                    continue;
+                }
+                const names = await repositoryNames(runtime.git.repository_root);
+                if (names.length === 0) {
+                    skip('no remote names its repository, so no source reference can cite it');
+                    continue;
+                }
+                const task_scope = repositoryTaskScope(graph, names);
+                if (!task_scope) {
+                    skip(`no node cites ${names.join(' or ')} yet; run attach --all-members again once one does`);
+                    continue;
+                }
+                const status = await runtime.attachCurrentSourceWorkspace({
+                    source_workspace_id: source.id,
+                    expected_source_sdlc_head_commit_id: source.head_sdlc_commit_id,
+                    source_repository_association_id: member.name,
+                    actor_kind: input.actor_kind,
+                    storage_mode: input.storage_mode,
+                    task_scope,
+                    full_projection: input.full_projection
+                });
+                result.attached.push({
+                    ...member,
+                    workspace_id: status.workspace.id,
+                    projection_dir: status.projection_dir,
+                    nodes: task_scope.rules.filter((rule) => rule.entity_kind === 'node')
+                        .length,
+                    edges: task_scope.rules.filter((rule) => rule.entity_kind === 'edge')
+                        .length
+                });
+            }
+            catch (error) {
+                skip(error.message);
+            }
+            finally {
+                runtime.close();
+            }
+        }
+        return result;
+    }
+    async getMultiRepositoryContext() {
+        const workspace = this.currentActiveWorkspace();
+        if (!workspace) {
+            throw new Error('The current Git worktree is not an active local workspace.');
+        }
+        const { git } = await this.authority.requireCurrent(workspace.id);
+        return {
+            version: 1,
+            graph_repository: {
+                repository_id: this.store.repository.repository_id,
+                state_dir: this.state_dir
+            },
+            source_repository: {
+                binding: this.store.getSourceRepositoryBinding(git.git_common_dir),
+                git_ref: git.ref,
+                git_head: git.head,
+                git_worktree_path: git.repository_root
+            },
+            graph_workspace: {
+                workspace_id: workspace.id,
+                source_workspace_id: workspace.source_workspace_id,
+                sdlc_branch: workspace.attached_ref,
+                fork_revision: workspace.fork_sdlc_commit_id,
+                head_revision: workspace.head_sdlc_commit_id,
+                projection_dir: projectionDirectory(workspace)
+            },
+            topology: {
+                topology_path: join(this.git.repository_root, '.sdlc', 'topology-v1.json'),
+                storage_mode: this.topology?.storage_mode ??
+                    (this.state_dir ===
+                        resolveLocalRepositoryStateDirectory({
+                            git_common_dir: this.git.git_common_dir
+                        })
+                        ? 'self_contained'
+                        : 'machine_shared')
+            }
+        };
+    }
+    async detachCurrentSourceWorkspace() {
+        const workspace = this.currentActiveWorkspace();
+        if (!workspace || !this.topology) {
+            throw new Error('The current checkout is not attached.');
+        }
+        if (workspace.actor_kind !== 'human') {
+            throw new Error('Only a human-owned workspace may detach itself.');
+        }
+        await this.authority.requireCurrent(workspace.id);
+        const topology = this.topology;
+        // Under the operation lock: detach may rewrite the projection, so no
+        // commit or edit command may run between its clean check and the close.
+        const { closed, topology_path } = await withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'detach',
+            run: async () => {
+                const current = this.requireWorkspace(workspace.id);
+                await this.assertProjectionClean(current);
+                // The preserved projection must read without its workspace: a scoped
+                // one becomes the whole head graph, which it equals once clean.
+                if (await isScopedProjection(projectionDirectory(current))) {
+                    await this.materialize_projection({
+                        projection_dir: projectionDirectory(current),
+                        graph: await this.readCommitGraph(current.head_sdlc_commit_id),
+                        full: true
+                    });
+                }
+                const topology_path = await removeWorkspaceTopology({
+                    repository_root: this.git.repository_root,
+                    graph_repository_id: topology.graph_repository_id,
+                    workspace_id: topology.workspace_id
+                });
+                try {
+                    return {
+                        topology_path,
+                        closed: this.store.closeWorkspace({
+                            actor_workspace_id: current.id,
+                            workspace_id: current.id,
+                            expected_head_commit_id: current.head_sdlc_commit_id
+                        })
+                    };
+                }
+                catch (error) {
+                    await writeWorkspaceTopology({
+                        repository_root: this.git.repository_root,
+                        topology
+                    });
+                    throw error;
+                }
+            }
+        });
+        this.topology = null;
+        const binding = this.store.getSourceRepositoryBinding(this.git.git_common_dir);
+        const unbound = binding
+            ? this.store.unbindSourceRepository({
+                git_common_dir: this.git.git_common_dir,
+                expected_source_repository_association_id: binding.source_repository_association_id
+            })
+            : null;
+        return {
+            version: 1,
+            status: 'detached',
+            workspace: closed,
+            topology_path,
+            projection_dir: projectionDirectory(workspace),
+            projection_preserved: true,
+            source_binding_removed: unbound?.removed ?? false
+        };
+    }
+    async createChildWorkspace(input) {
+        const { workspace: source, git } = await this.authority.requireCurrent(input.actor_workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(source),
+            operation: 'create-child',
+            run: async () => {
+                const current_source = this.requireWorkspace(source.id);
+                await this.assertProjectionClean(current_source);
+                const target_path = resolve(input.target_path);
+                let created_git = null;
+                let created_workspace = null;
+                try {
+                    created_git = await createDetachedGitWorktree({
+                        source_cwd: current_source.git_worktree_path,
+                        target_path,
+                        commit_id: git.head
+                    });
+                    await assertLocalWorkspacePathsIgnored(created_git.repository_root);
+                    const child = this.store.forkWorkspace({
+                        actor_workspace_id: current_source.id,
+                        expected_source_sdlc_head_commit_id: current_source.head_sdlc_commit_id,
+                        git_worktree_path: created_git.repository_root,
+                        git_dir: created_git.git_dir,
+                        git_common_dir: created_git.git_common_dir,
+                        git_head_commit_id: created_git.head,
+                        actor_kind: input.actor_kind ?? 'ai',
+                        task_scope: input.task_scope
+                    });
+                    created_workspace = child;
+                    const graph = await this.readCommitGraph(child.head_sdlc_commit_id);
+                    await this.materialize_projection({
+                        projection_dir: projectionDirectory(child),
+                        graph
+                    });
+                    await mkdir(controlDirectory(child), {
+                        recursive: true,
+                        mode: 0o700
+                    });
+                    await this.persistCurrentTopology(child, this.topology?.storage_mode, created_git.repository_root, created_git.git_common_dir);
+                    return this.getWorkspaceStatus(child.id);
+                }
+                catch (error) {
+                    if (created_workspace) {
+                        try {
+                            this.store.closeWorkspace({
+                                actor_workspace_id: current_source.id,
+                                workspace_id: created_workspace.id,
+                                expected_head_commit_id: created_workspace.head_sdlc_commit_id
+                            });
+                        }
+                        catch {
+                            // Preserve the creation failure; the record remains inspectable.
+                        }
+                    }
+                    if (created_git) {
+                        await removeGitWorktree({
+                            repository_cwd: this.git.repository_root,
+                            target_path: created_git.repository_root,
+                            force: true
+                        }).catch(() => undefined);
+                    }
+                    throw error;
+                }
+            }
+        });
+    }
+    listWorkspaces() {
+        return this.store.listWorkspaces();
+    }
+    /**
+     * Replaces a child workspace's declared task scope, for example when a plan
+     * grows. The new scope must still cover the workspace's own changes, which
+     * are measured from its merge base with its source.
+     */
+    async replaceTaskScope(input) {
+        const { workspace: actor } = await this.authority.requireCurrent(input.actor_workspace_id);
+        const workspace = this.requireWorkspace(input.workspace_id);
+        const task_scope = local_workspace_task_scope_schema.parse(input.task_scope);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'scope',
+            run: async () => {
+                const current = this.requireWorkspace(workspace.id);
+                const source = current.source_workspace_id
+                    ? this.requireWorkspace(current.source_workspace_id)
+                    : null;
+                let base_commit_id = current.fork_sdlc_commit_id;
+                if (source) {
+                    try {
+                        base_commit_id = this.store.history.findMergeBase(current.head_sdlc_commit_id, source.head_sdlc_commit_id);
+                    }
+                    catch {
+                        // Keep the fork commit when the heads share no local ancestor.
+                    }
+                }
+                assertGraphChangesWithinTaskScope({
+                    base_graph: await this.readCommitGraph(base_commit_id),
+                    current_graph: await this.readCommitGraph(current.head_sdlc_commit_id),
+                    task_scope
+                });
+                const replaced = this.store.replaceWorkspaceTaskScope({
+                    actor_workspace_id: actor.id,
+                    workspace_id: current.id,
+                    expected_head_commit_id: current.head_sdlc_commit_id,
+                    task_scope
+                });
+                // A scoped projection gains files for the entities the scope adds.
+                const projection_dir = projectionDirectory(current);
+                if (await isScopedProjection(projection_dir)) {
+                    await extendScopedProjection({
+                        projection_dir,
+                        graph: await this.readCommitGraph(current.head_sdlc_commit_id),
+                        scope: projectionScopeOfTaskScope(task_scope)
+                    });
+                }
+                return { version: 1, workspace_id: current.id, ...replaced };
+            }
+        });
+    }
+    /**
+     * Removes one entity file from the current workspace's projection and, when
+     * the head has that entity, records the deletion for the next commit, like
+     * hosted `sdlc rm`. The commit still enforces the task scope.
+     */
+    async removeEntity(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'remove',
+            run: async () => {
+                const current = this.requireWorkspace(workspace.id);
+                const head_graph = await this.readCommitGraph(current.head_sdlc_commit_id);
+                const removed = await removeProjectionEntity({
+                    projection_dir: projectionDirectory(current),
+                    relative_path: input.relative_path,
+                    allow_missing: (entry) => graphHasProjectionEntity(head_graph, entry)
+                });
+                const deletion_recorded = graphHasProjectionEntity(head_graph, removed);
+                if (deletion_recorded) {
+                    this.store.recordWorkspaceDeletion({
+                        workspace_id: current.id,
+                        entity_kind: removed.entity_kind,
+                        entity_id: removed.entity_id
+                    });
+                }
+                return {
+                    version: 1,
+                    workspace_id: current.id,
+                    relative_path: removed.relative_path,
+                    deletion_recorded
+                };
+            }
+        });
+    }
+    /**
+     * Runs a `sdlc workspace doc` command against the current workspace's
+     * projection, under the same authority check and operation lock as `rm`
+     * and `commit`, so it never edits a projection another operation is using.
+     */
+    async withDocumentProjection(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: `doc:${input.operation}`,
+            run: async () => {
+                const projection_dir = projectionDirectory(this.requireWorkspace(workspace.id));
+                // These commands read and write entity files directly, so they need
+                // every entity on disk.
+                if (await isScopedProjection(projection_dir)) {
+                    throw new Error('This projection holds only its task scope (workspace attach); run doc, guide, journey and test commands in a workspace with the whole graph, such as a plan workspace from sdlc workspace create, or attach with --full-projection.');
+                }
+                return input.run(projection_dir);
+            }
+        });
+    }
+    /**
+     * Writes a workspace commit's graph as a canonical portable graph file, the
+     * format `sdlc save --graph-file` reads. Defaults to the workspace head.
+     */
+    async exportWorkspaceGraph(input) {
+        const workspace = this.requireWorkspace(input.workspace_id);
+        const view = input.view ?? 'planned';
+        const commit_id = input.commit_id ?? workspace.head_sdlc_commit_id;
+        if (commit_id !== workspace.head_sdlc_commit_id &&
+            !this.store.history.isAncestor(commit_id, workspace.head_sdlc_commit_id)) {
+            throw new Error('Export commit is not in the workspace history.');
+        }
+        if (view === 'built' && commit_id !== workspace.head_sdlc_commit_id) {
+            throw new Error('The built view reads the workspace head only.');
+        }
+        const built = view === 'built'
+            ? await this.integration_runtime.readBuiltView({
+                coordinator_workspace_id: workspace.id
+            })
+            : null;
+        const graph = built?.graph ?? (await this.readCommitGraph(commit_id));
+        const output_path = resolve(input.output_path);
+        const temporary_path = `${output_path}.tmp-${randomUUID()}`;
+        try {
+            await writeFile(temporary_path, `${stringifyCanonicalGraph(canonicalizePortableGraph(graph))}\n`, { encoding: 'utf8', flag: 'wx' });
+            await rename(temporary_path, output_path);
+        }
+        catch (error) {
+            await rm(temporary_path, { force: true });
+            throw error;
+        }
+        return {
+            version: 1,
+            view,
+            workspace_id: workspace.id,
+            commit_id,
+            root_hash: built
+                ? localGraphRootHash(canonicalizePortableGraph(built.graph))
+                : this.commitRoot(commit_id),
+            output_path,
+            ...(built
+                ? {
+                    marked_for_removal: built.marked_for_removal,
+                    left_out_orphans: built.left_out_orphans,
+                    validation: built.validation
+                }
+                : {})
+        };
+    }
+    /** The workspace's pending claims: merged under a gate and not landed. */
+    listPendingClaims(input) {
+        const workspace = this.requireWorkspace(input.workspace_id);
+        return listClaims({
+            workspace_id: workspace.id,
+            pending: this.store.built_content.listPendingClaims(workspace.id)
+        });
+    }
+    /**
+     * Each node's claim status in a view (`sdlc workspace status`), read from a
+     * coordinator's committed head and its pending claims. A plan workspace (one
+     * with no active plans under it) reads its coordinator, whose head is what
+     * the plans merged into. Source
+     * references are checked against `commit` in this checkout's repository.
+     * Read-only.
+     */
+    async workspaceClaimStatus(input) {
+        const asked = this.requireWorkspace(input.workspace_id);
+        const workspace = this.claimReadWorkspace(asked);
+        const result = await claimStatus({
+            graph: await this.readCommitGraph(workspace.head_sdlc_commit_id),
+            pending: this.store.built_content.listPendingClaims(workspace.id),
+            workspace_id: workspace.id,
+            graph_commit_id: workspace.head_sdlc_commit_id,
+            git: gitClaimStatusReader(this.git.repository_root),
+            // Checked against main by default, as claim_status.py is: a plan's or the
+            // coordinator's HEAD is the planning branch, not the code.
+            commit: input.commit ?? 'main',
+            environments: input.environments ?? [],
+            cites_code: input.cites_code ?? [],
+            view: input.view,
+            nodes: input.nodes,
+            status: input.status,
+            stale_only: input.stale_only,
+            behind_only: input.behind_only
+        });
+        return workspace.id === asked.id
+            ? result
+            : { ...result, asked_workspace_id: asked.id };
+    }
+    /**
+     * The workspace a claim read answers from: a coordinator has active plans
+     * under it and reads itself; a plan reads the coordinator it merges into.
+     */
+    claimReadWorkspace(asked) {
+        const coordinates = this.listWorkspaces().some((other) => other.source_workspace_id === asked.id && other.status === 'active');
+        return asked.source_workspace_id && !coordinates
+            ? this.requireWorkspace(asked.source_workspace_id)
+            : asked;
+    }
+    /**
+     * `sdlc variants`: each Variant Set in the committed graph with its gap and
+     * its sync entities' claim status (docs/specs/graph-variants.md, P3a), and
+     * with an environment, its members' forms by claim status. It reads the
+     * graph claim status reads, so a plan reads its coordinator. Read-only.
+     */
+    async workspaceVariants(input) {
+        const asked = this.requireWorkspace(input.workspace_id);
+        const workspace = this.claimReadWorkspace(asked);
+        const graph = await this.readCommitGraph(workspace.head_sdlc_commit_id);
+        const environments = input.environments ?? [];
+        const read = (view, nodes) => claimStatus({
+            graph,
+            pending: this.store.built_content.listPendingClaims(workspace.id),
+            workspace_id: workspace.id,
+            graph_commit_id: workspace.head_sdlc_commit_id,
+            git: gitClaimStatusReader(this.git.repository_root),
+            commit: input.commit ?? 'main',
+            environments,
+            view,
+            cites_code: [],
+            nodes
+        });
+        const claims = new Map();
+        let form_claims;
+        let claim_error;
+        try {
+            const sync_ids = variantSyncIds(graph);
+            if (sync_ids.length) {
+                for (const claim of (await read('planned', sync_ids)).claims ?? []) {
+                    claims.set(claim.node, {
+                        status: claim.status,
+                        environment: claim.environment
+                    });
+                }
+            }
+            // Only an environment can read a form as released, so members are read
+            // only with one, and as built: a plan's pending gate claim on a form, or
+            // on a node realizing it, must not hide a release.
+            const form_ids = environments.length ? variantMemberFormIds(graph) : [];
+            if (form_ids.length) {
+                const built = await read('built', form_ids);
+                const unresolved = built.environments.filter((environment) => !environment.resolved);
+                if (unresolved.length) {
+                    // Nothing reads released against a ref that does not resolve, which
+                    // would make every live member look contradicted.
+                    claim_error = `environment ${unresolved
+                        .map((environment) => `${environment.key}=${environment.ref}`)
+                        .join(', ')} does not resolve, so members are not checked`;
+                }
+                else {
+                    form_claims = new Map((built.claims ?? []).map((claim) => [
+                        claim.node,
+                        { status: claim.status, environment: claim.environment }
+                    ]));
+                }
+            }
+        }
+        catch (error) {
+            // The gap stands without claim status, for example where main is no ref.
+            claim_error = error instanceof Error ? error.message : String(error);
+            form_claims = undefined;
+        }
+        return {
+            ...variantsReport({ graph, claims, form_claims }),
+            ...(claim_error ? { claim_error } : {}),
+            workspace_id: workspace.id,
+            ...(workspace.id === asked.id ? {} : { asked_workspace_id: asked.id })
+        };
+    }
+    /**
+     * Claim freshness of the nodes and edges with evidence in the current
+     * workspace's projection (`sdlc workspace evidence status`): what sign
+     * writes, uncommitted edits included. Read-only.
+     */
+    async workspaceEvidenceStatus(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        const current = this.requireWorkspace(workspace.id);
+        const { graph } = await composeGraphProjection(projectionDirectory(current), undefined, { base: () => this.readCommitGraph(current.head_sdlc_commit_id) });
+        return evidenceStatus({
+            graph,
+            workspace_id: workspace.id,
+            nodes: input.nodes,
+            edges: input.edges,
+            behind_only: input.behind_only
+        });
+    }
+    /**
+     * `sdlc workspace evidence sign`: pins the selected entities' references to
+     * their current object hash in the projection, after verifying each code
+     * reference it signs at `commit` (default HEAD). Writes nothing when any
+     * does not hold. `changed` selects every node and edge the plan changed
+     * since its merge base with the coordinator. A signed entity outside a
+     * plan's task scope widens the scope to its meta. Commits nothing.
+     * `repository` is the Git repository whose code the references are
+     * verified in (default this workspace's own), so a graph that cites
+     * another repository signs that repository's references against its code.
+     */
+    async signEvidence(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'evidence-sign',
+            run: () => this.signEvidenceLocked(workspace.id, input)
+        });
+    }
+    /** signEvidence's work, for a caller already holding the workspace operation lock. */
+    async signEvidenceLocked(workspace_id, input) {
+        const current = this.requireWorkspace(workspace_id);
+        const projection_dir = projectionDirectory(current);
+        const { graph } = await composeGraphProjection(projection_dir, undefined, {
+            base: () => this.readCommitGraph(current.head_sdlc_commit_id)
+        });
+        const repository = input.repository
+            ? resolve(input.repository)
+            : this.git.repository_root;
+        const git = gitClaimStatusReader(repository);
+        const commit = await git.resolve(input.commit ?? 'HEAD');
+        if (commit === null) {
+            throw new Error(input.repository
+                ? `${input.commit ?? 'HEAD'} is not a commit in ${repository}.`
+                : `${input.commit ?? 'HEAD'} is not a commit in this repository.`);
+        }
+        const repository_names = await repositoryNames(repository, commit);
+        const nodes = [...(input.nodes ?? [])];
+        const edges = [...(input.edges ?? [])];
+        if (input.changed) {
+            if (!current.source_workspace_id) {
+                throw new Error('sign --changed reads what a plan changed, and this workspace has no coordinator.');
+            }
+            const source = this.requireWorkspace(current.source_workspace_id);
+            let base_commit_id = current.fork_sdlc_commit_id;
+            try {
+                base_commit_id = this.store.history.findMergeBase(current.head_sdlc_commit_id, source.head_sdlc_commit_id);
+            }
+            catch {
+                // Keep the fork commit when the heads share no local ancestor.
+            }
+            const present = {
+                node: new Set(graph.nodes.map((node) => node.id)),
+                edge: new Set(graph.edges.map((edge) => edge.id))
+            };
+            for (const change of graphChangeCoordinates({
+                base_graph: await this.readCommitGraph(base_commit_id),
+                current_graph: graph
+            })) {
+                if (change.entity_kind === 'node' && present.node.has(change.entity_id))
+                    nodes.push(change.entity_id);
+                if (change.entity_kind === 'edge' && present.edge.has(change.entity_id))
+                    edges.push(change.entity_id);
+            }
+        }
+        const plan = await planEvidenceSign({
+            graph,
+            git,
+            commit,
+            now: (input.now ?? new Date()).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+            nodes: [...new Set(nodes)],
+            edges: [...new Set(edges)],
+            references: input.references,
+            repository_names
+        });
+        const result = {
+            version: 1,
+            workspace_id: current.id,
+            ...plan
+        };
+        if (plan.status !== 'signed')
+            return result;
+        // A scoped projection first gains the file of each entity it signs.
+        if (await isScopedProjection(projection_dir)) {
+            await extendScopedProjection({
+                projection_dir,
+                graph,
+                scope: projectionScopeOfTaskScope({
+                    rules: plan.changes.map((change) => ({
+                        entity_kind: change.kind,
+                        entity_id: change.id
+                    }))
+                })
+            });
+        }
+        // Widen the scope next: a failure while writing then leaves signed
+        // entities the scope already covers, never ones it refuses at commit.
+        const scope = this.store.getWorkspaceTaskScope(current.id);
+        const META = '/data/meta';
+        const widened = scope
+            ? plan.changes
+                .map((change) => ({
+                entity_kind: change.kind,
+                entity_id: change.id,
+                field_path: META
+            }))
+                .filter((candidate) => !scope.rules.some((rule) => ruleCovers(rule, candidate)))
+            : [];
+        if (scope && widened.length) {
+            this.store.replaceWorkspaceTaskScope({
+                actor_workspace_id: current.id,
+                workspace_id: current.id,
+                expected_head_commit_id: current.head_sdlc_commit_id,
+                task_scope: { ...scope, rules: [...scope.rules, ...widened] }
+            });
+        }
+        for (const change of plan.changes) {
+            const path = join(projection_dir, change.kind === 'node' ? 'nodes' : 'edges', `${change.id}.json`);
+            const entity = JSON.parse(await readFile(path, 'utf8'));
+            entity.data = {
+                ...entity.data,
+                meta: signedMeta(entity.data?.meta, change.evidence)
+            };
+            await writeJsonAtomically(path, entity);
+        }
+        return {
+            ...result,
+            widened_scope: widened.map((rule) => ({
+                kind: rule.entity_kind,
+                id: rule.entity_id
+            }))
+        };
+    }
+    /**
+     * `sdlc workspace evidence record`: writes each node's source references
+     * (already verified at `commit` by the caller) into the current workspace's
+     * projection, as sources.py record does, each replacing a reference of the
+     * same identity under any name the repository goes by. With `sign`, signs
+     * exactly those references under the same lock, and restores the node
+     * files when the sign fails or is refused, so nothing is left recorded
+     * unsigned. Refuses, before writing anything, a node with no file in the
+     * projection or holding legacy source_evidence. A node whose references
+     * would pass 100 is left out and returned under over_limit with the count
+     * it would have (sources.py record). Commits nothing.
+     */
+    async recordSourceReferences(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        const repository = resolve(input.repository);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'evidence-record',
+            run: async () => {
+                const current = this.requireWorkspace(workspace.id);
+                const projection_dir = projectionDirectory(current);
+                const names = await repositoryNames(repository, input.commit);
+                if (!names.length)
+                    throw new Error(`the ${await trackedRemoteName(repository)} remote names no <owner>/<name>, so references have no repository identity`);
+                const observed_at = (input.now ?? new Date())
+                    .toISOString()
+                    .replace(/\.\d{3}Z$/, 'Z');
+                const updates = [];
+                const ids = [];
+                const over_limit = {};
+                for (const [node_id, specs] of Object.entries(input.nodes)) {
+                    const path = join(projection_dir, 'nodes', `${node_id}.json`);
+                    let node;
+                    try {
+                        node = JSON.parse(await readFile(path, 'utf8'));
+                    }
+                    catch {
+                        throw new Error(`node ${node_id} is not in the workspace's projection`);
+                    }
+                    const data = { ...(node.data ?? {}) };
+                    const meta = { ...(data.meta ?? {}) };
+                    // As sources.py tests it: an empty legacy block holds nothing to convert.
+                    const legacy = meta.source_evidence;
+                    if (legacy &&
+                        (typeof legacy !== 'object' || Object.keys(legacy).length > 0))
+                        throw new Error(`node ${node_id} holds legacy source_evidence; convert it to meta.evidence (the current form) before recording on it`);
+                    const references = specs.map((spec) => sourceReference(node_id, spec, input.commit, names[0], observed_at));
+                    try {
+                        meta.evidence = evidenceWith(meta, references, names);
+                    }
+                    catch (error) {
+                        if (!(error instanceof ReferenceLimitError))
+                            throw error;
+                        over_limit[node_id] = error.count;
+                        continue;
+                    }
+                    ids.push(...references.map((ref) => String(ref.reference_id)));
+                    updates.push({ path, node: { ...node, data: { ...data, meta } } });
+                }
+                const recorded = Object.keys(input.nodes).filter((node_id) => !(node_id in over_limit));
+                const before = new Map();
+                for (const { path } of updates)
+                    before.set(path, await readFile(path));
+                const restore = async () => {
+                    for (const [path, content] of before)
+                        await writeFile(path, content);
+                };
+                try {
+                    for (const { path, node } of updates)
+                        await writeJsonAtomically(path, node);
+                    if (!input.sign || !updates.length)
+                        return {
+                            workspace_id: current.id,
+                            repository: names[0],
+                            recorded,
+                            over_limit
+                        };
+                    const signed = await this.signEvidenceLocked(current.id, {
+                        references: ids,
+                        commit: input.commit,
+                        repository,
+                        now: input.now
+                    });
+                    if (signed.status === 'refused')
+                        throw new Error(`signing the recorded references was refused: ${signed.failures
+                            .map((f) => `${f.kind} ${f.id}: ${f.problem}`)
+                            .join('; ') || 'no failure named'}`);
+                    return {
+                        workspace_id: current.id,
+                        repository: names[0],
+                        recorded,
+                        over_limit,
+                        signed
+                    };
+                }
+                catch (error) {
+                    await restore();
+                    throw error;
+                }
+            }
+        });
+    }
+    /**
+     * The source references of a workspace's graph as built (`sdlc workspace
+     * evidence lookup|check|coverage`): its projection as it stands, so
+     * references just recorded count before a commit, with each pending claim
+     * at its built content, as sources.py index reads it with
+     * owners.built_claims. Only nodes with a pending claim come from the built
+     * view: one left out there as an orphan, under a parent never built, still
+     * names its files.
+     */
+    async workspaceSourceIndex(input) {
+        const workspace = this.requireWorkspace(input.workspace_id);
+        const { graph } = await composeGraphProjection(projectionDirectory(workspace), undefined, { base: () => this.readCommitGraph(workspace.head_sdlc_commit_id) });
+        const pending = this.store.built_content.listPendingClaimContent(workspace.id);
+        const built = await readBuiltGraph({
+            graph,
+            pending,
+            readGraph: (commit_id) => this.readCommitGraph(commit_id)
+        });
+        const claimed = new Set(pending
+            .filter((claim) => claim.entity_kind === 'node')
+            .map((claim) => claim.entity_id));
+        const nodes = [
+            ...graph.nodes.filter((node) => !claimed.has(node.id)),
+            ...built.graph.nodes.filter((node) => claimed.has(node.id))
+        ];
+        return { workspace_id: workspace.id, ...sourceIndex({ ...graph, nodes }) };
+    }
+    /**
+     * What changed repository files reach in a workspace's committed head graph
+     * (`sdlc workspace blast-radius`). Read-only: it answers from the head, so
+     * uncommitted edits never change the answer. The planned view composes the
+     * projection only to say when it differs (`projection_dirty` and a warning);
+     * the built view, read by readiness on every landing, skips that compose.
+     */
+    async workspaceBlastRadius(input) {
+        const workspace = this.requireWorkspace(input.workspace_id);
+        const commit_id = workspace.head_sdlc_commit_id;
+        const view = input.view ?? 'planned';
+        const built = view === 'built'
+            ? await this.integration_runtime.readBuiltView({
+                coordinator_workspace_id: workspace.id
+            })
+            : null;
+        const head = built ? null : await this.readCommitGraph(commit_id);
+        const dirty = head ? await this.projectionDirty(workspace, head) : null;
+        const result = await blastRadius({
+            graph: built?.graph ?? head,
+            files: input.files,
+            // An unqualified changed file belongs to the repository read here.
+            repository_names: await repositoryNames(this.git.repository_root),
+            workspace_id: workspace.id,
+            commit_id,
+            view,
+            ...(built
+                ? {
+                    marked_for_removal: built.marked_for_removal,
+                    validation: built.validation
+                }
+                : {})
+        });
+        if (!dirty)
+            return result;
+        return {
+            ...result,
+            ...(dirty.dirty === null ? {} : { projection_dirty: dirty.dirty }),
+            ...(dirty.warning ? { warnings: [dirty.warning] } : {})
+        };
+    }
+    /** `sdlc workspace find`: nodes ranked by the words they match (graph-read.ts). */
+    async workspaceFind(input) {
+        const read = await this.readGraphForView(input.workspace_id, input.view, 'find');
+        const found = findGraphEntities({
+            graph: read.graph,
+            terms: input.terms,
+            types: input.types,
+            origin: input.origin,
+            limit: input.limit,
+            view: read.view,
+            workspace_id: read.workspace_id,
+            commit_id: read.commit_id,
+            removed: read.removed
+        });
+        const warnings = [...(read.warnings ?? []), ...(found.warnings ?? [])];
+        return {
+            ...found,
+            ...read.extra,
+            ...(warnings.length > 0 ? { warnings } : {})
+        };
+    }
+    /** `sdlc workspace show`: nodes and edges read compactly with their relations (graph-read.ts). */
+    async workspaceShow(input) {
+        const read = await this.readGraphForView(input.workspace_id, input.view, 'show');
+        return {
+            ...showGraphEntities({
+                graph: read.graph,
+                ids: input.ids,
+                budget: input.budget,
+                view: read.view,
+                workspace_id: read.workspace_id,
+                commit_id: read.commit_id,
+                removed: read.removed
+            }),
+            ...read.extra,
+            ...(read.warnings ? { warnings: read.warnings } : {})
+        };
+    }
+    /**
+     * The graph a read command answers from: the committed head, or the built
+     * view, as blast radius reads it, with what blast radius reports beside it.
+     */
+    async readGraphForView(workspace_id, requested, command) {
+        const workspace = this.requireWorkspace(workspace_id);
+        const commit_id = workspace.head_sdlc_commit_id;
+        const view = requested ?? 'planned';
+        if (view === 'built') {
+            const built = await this.integration_runtime.readBuiltView({
+                coordinator_workspace_id: workspace.id
+            });
+            return {
+                graph: built.graph,
+                view,
+                workspace_id: workspace.id,
+                commit_id,
+                removed: new Set(built.marked_for_removal.map((entity) => entity.entity_id)),
+                extra: {
+                    marked_for_removal: built.marked_for_removal,
+                    validation: built.validation
+                }
+            };
+        }
+        const graph = await this.readCommitGraph(commit_id);
+        const dirty = await this.projectionDirty(workspace, graph, command);
+        return {
+            graph,
+            view,
+            workspace_id: workspace.id,
+            commit_id,
+            extra: dirty.dirty === null ? {} : { projection_dirty: dirty.dirty },
+            ...(dirty.warning ? { warnings: [dirty.warning] } : {})
+        };
+    }
+    /** Whether a workspace's projection differs from its committed head graph, with the warning blast radius gives. */
+    async projectionDirty(workspace, head, command = 'blast-radius') {
+        let projection;
+        try {
+            ({ graph: projection } = await composeGraphProjection(projectionDirectory(workspace), undefined, { base: async () => head }));
+        }
+        catch (error) {
+            return {
+                dirty: null,
+                warning: `The workspace projection could not be compared with its committed head (${error instanceof Error ? error.message : String(error)}); this answer reads the committed head.`
+            };
+        }
+        if (localGraphRootHash(projection) ===
+            this.commitRoot(workspace.head_sdlc_commit_id)) {
+            return { dirty: false, warning: null };
+        }
+        // commit takes the workspace of the directory it runs in, so name another one's worktree.
+        const where = workspace.git_worktree_path === this.git.repository_root
+            ? ''
+            : ` in ${workspace.git_worktree_path}`;
+        return {
+            dirty: true,
+            warning: `The workspace projection has uncommitted changes, such as source references sources record just wrote; this answer reads the committed head. Run sdlc workspace commit --message "<what changed>"${where}, then run ${command} again.`
+        };
+    }
+    /**
+     * Compares the committed plans of a coordinator's active child workspaces
+     * pairwise. Read-only: it never locks, commits, or moves a workspace.
+     */
+    async compareChildWorkspacePlans(input) {
+        const coordinator = this.requireWorkspace(input.coordinator_workspace_id);
+        const coordinator_commit_id = coordinator.head_sdlc_commit_id;
+        const children = this.store
+            .listChildWorkspaces(coordinator.id)
+            .filter((workspace) => workspace.status === 'active');
+        const graphs = new Map();
+        const readGraph = (commit_id) => {
+            let graph = graphs.get(commit_id);
+            if (!graph) {
+                graph = this.readCommitGraph(commit_id);
+                graphs.set(commit_id, graph);
+            }
+            return graph;
+        };
+        const coordinator_graph = await readGraph(coordinator_commit_id);
+        const plans = [];
+        const projection_dirty = new Map();
+        for (const child of children) {
+            let base_commit_id;
+            try {
+                // Integration and reconciliation record merge parents, so the merge
+                // base excludes work this plan already landed or pulled in.
+                base_commit_id = this.store.history.findMergeBase(child.head_sdlc_commit_id, coordinator_commit_id);
+            }
+            catch {
+                base_commit_id = child.fork_sdlc_commit_id;
+            }
+            // A plan with no commits of its own (it landed, or was never edited)
+            // compares as the coordinator head: neither of its graphs nor its
+            // projection is read, and whether it has uncommitted edits is left
+            // unknown. Most open plans are such plans, and composing each one's
+            // projection (thousands of files, then a root hash) cost most of a run
+            // once they numbered over a hundred (iss-130).
+            const held = base_commit_id === child.head_sdlc_commit_id;
+            const [base_graph, head_graph] = held
+                ? [coordinator_graph, coordinator_graph]
+                : await Promise.all([
+                    readGraph(base_commit_id),
+                    readGraph(child.head_sdlc_commit_id)
+                ]);
+            plans.push({
+                workspace_id: child.id,
+                base_commit_id,
+                head_commit_id: child.head_sdlc_commit_id,
+                base_graph,
+                head_graph
+            });
+            if (held) {
+                projection_dirty.set(child.id, null);
+                continue;
+            }
+            try {
+                // Root hashes alone say whether the projection moved: no graph is read.
+                const { graph } = await composeGraphProjection(projectionDirectory(child), undefined, { base: async () => head_graph });
+                projection_dirty.set(child.id, this.commitRoot(child.head_sdlc_commit_id) !==
+                    localGraphRootHash(graph));
+            }
+            catch {
+                // A missing or unreadable projection does not change the committed plan.
+                projection_dirty.set(child.id, null);
+            }
+        }
+        const comparison = compareLocalWorkspacePlans({
+            coordinator_commit_id,
+            coordinator_graph,
+            plans
+        });
+        const states = new Map(comparison.plans.map((state) => [state.workspace_id, state]));
+        let coordinator_ancestors = null;
+        for (const pair of comparison.pairs) {
+            const units = allocationUnits(pair);
+            if (units.length === 0)
+                continue;
+            coordinator_ancestors ??= this.store.history.ancestorIds(coordinator_commit_id);
+            const reachable = coordinator_ancestors;
+            const first_changed = await Promise.all(pair.workspace_ids.map((workspace_id) => firstOwnChanges({
+                head_commit_id: plans.find((plan) => plan.workspace_id === workspace_id)
+                    ?.head_commit_id ?? '',
+                units,
+                getCommit: (commit_id) => this.store.history.getCommit(commit_id),
+                reachableFromCoordinator: (commit_id) => reachable.has(commit_id),
+                readGraph
+            })));
+            const timed = units.map((unit) => ({
+                ...unit,
+                first_changed_at: Object.fromEntries(pair.workspace_ids.map((workspace_id, index) => [
+                    workspace_id,
+                    first_changed[index]?.get(allocationUnitKey(unit)) ?? null
+                ]))
+            }));
+            // A block only by validation is one unit: the combination of the
+            // entities fails, so one plan owns it, by its earliest change to any.
+            pair.allocation =
+                pair.conflicts.length > 0 ? timed : [combineValidationUnits(timed)];
+        }
+        return {
+            version: 1,
+            coordinator_workspace_id: coordinator.id,
+            coordinator_head_commit_id: coordinator_commit_id,
+            verdict: comparison.verdict,
+            stale_workspace_ids: comparison.plans
+                .filter((state) => state.status === 'stale')
+                .map((state) => state.workspace_id),
+            workspaces: plans.map((plan) => {
+                const child = children.find((workspace) => workspace.id === plan.workspace_id);
+                const state = states.get(plan.workspace_id);
+                if (!child || !state) {
+                    throw new Error('Workspace plan comparison lost a child workspace.');
+                }
+                return {
+                    ...state,
+                    git_worktree_path: child.git_worktree_path,
+                    base_commit_id: plan.base_commit_id,
+                    head_commit_id: plan.head_commit_id,
+                    projection_dirty: projection_dirty.get(child.id) ?? null
+                };
+            }),
+            compared_pairs: comparison.compared_pairs,
+            pairs: comparison.pairs
+        };
+    }
+    inspectAuthority() {
+        return inspectLocalWorkspaceAuthority({
+            workspace: this.currentActiveWorkspace(),
+            git: this.git
+        });
+    }
+    resolverStatus() {
+        return this.environment_runtime.resolverStatus();
+    }
+    async configureResolver(input) {
+        return this.environment_runtime.configureResolver(input);
+    }
+    async configureResolverFromFile(input) {
+        return this.environment_runtime.configureResolverFromFile(input);
+    }
+    async clearResolver(input) {
+        return this.environment_runtime.clearResolver(input);
+    }
+    async loadResolver(input) {
+        return this.environment_runtime.loadResolver(input);
+    }
+    listRemotes() {
+        return this.environment_runtime.listRemotes();
+    }
+    inspectRemote(name) {
+        return this.environment_runtime.inspectRemote(name);
+    }
+    async setRemote(input) {
+        return this.environment_runtime.setRemote(input);
+    }
+    async removeRemote(input) {
+        return this.environment_runtime.removeRemote(input);
+    }
+    async discoverRemote(input) {
+        return this.environment_runtime.discoverRemote(input);
+    }
+    listRemoteTrackingRefs(name) {
+        return this.environment_runtime.listRemoteTrackingRefs(name);
+    }
+    listLocalBranches() {
+        return this.branch_runtime.list();
+    }
+    async createLocalBranchFromTrackingRef(input) {
+        return this.branch_runtime.createFromTrackingRef(input);
+    }
+    async selectLocalBranch(input) {
+        return this.branch_runtime.select(input);
+    }
+    async integrateBranchUpstream(input) {
+        return this.upstream_runtime.integrate(input);
+    }
+    listBranchIntegrationAttempts(local_ref) {
+        return this.upstream_runtime.listAttempts(local_ref);
+    }
+    listBranchIntegrationResolutionAttempts(attempt_id) {
+        return this.upstream_runtime.listResolutionAttempts(attempt_id);
+    }
+    listBranchIntegrationRevertAttempts(local_ref) {
+        return this.upstream_runtime.listRevertAttempts(local_ref);
+    }
+    inspectBranchUpstream(input) {
+        return this.upstream_runtime.inspect(input);
+    }
+    revertBranchUpstream(input) {
+        return this.upstream_runtime.revert(input);
+    }
+    async fetchRemote(input) {
+        return this.environment_runtime.fetchRemote(input);
+    }
+    listRemotePushJournals(name) {
+        return this.environment_runtime.listRemotePushJournals(name);
+    }
+    listRemoteTopicJournals(name) {
+        return this.environment_runtime.listRemoteTopicJournals(name);
+    }
+    listRemotePullRequestJournals(name) {
+        return this.environment_runtime.listRemotePullRequestJournals(name);
+    }
+    async planPortableHistory(input) {
+        return this.environment_runtime.planPortableHistory(input);
+    }
+    async convertPortableHistory(input) {
+        return this.environment_runtime.convertPortableHistory(input);
+    }
+    async pushRemote(input) {
+        return this.environment_runtime.pushRemote(input);
+    }
+    async publishRemoteTopic(input) {
+        return this.environment_runtime.publishRemoteTopic(input);
+    }
+    async createRemotePullRequest(input) {
+        return this.environment_runtime.createRemotePullRequest(input);
+    }
+    async getWorkspaceStatus(workspace_id) {
+        const workspace = this.requireWorkspace(workspace_id);
+        const { graph } = await composeGraphProjection(projectionDirectory(workspace), undefined, { base: () => this.readCommitGraph(workspace.head_sdlc_commit_id) });
+        const projection_root_hash = localGraphRootHash(graph);
+        const head_root_hash = this.commitRoot(workspace.head_sdlc_commit_id);
+        await this.graphs.readGraph(head_root_hash);
+        const source = workspace.source_workspace_id
+            ? this.store.getWorkspace(workspace.source_workspace_id)
+            : null;
+        return {
+            version: 1,
+            workspace,
+            projection_dir: projectionDirectory(workspace),
+            control_dir: controlDirectory(workspace),
+            head_root_hash,
+            projection_root_hash,
+            projection_dirty: head_root_hash !== projection_root_hash,
+            task_scope: this.store.getWorkspaceTaskScope(workspace.id),
+            ...(source
+                ? {
+                    source: {
+                        workspace_id: source.id,
+                        head_revision: source.head_sdlc_commit_id,
+                        behind: source.head_sdlc_commit_id !== workspace.head_sdlc_commit_id &&
+                            !this.store.history.isAncestor(source.head_sdlc_commit_id, workspace.head_sdlc_commit_id)
+                    }
+                }
+                : {})
+        };
+    }
+    async commitCurrentProjection(input) {
+        const { workspace, git } = await this.authority.requireCurrent(input.actor_workspace_id);
+        // Before the commit reads the binding for its source context; a move that
+        // fails changes nothing, and the commit keeps the binding it has
+        await this.realignForkBinding(git.repository_root, git.git_common_dir).catch(() => null);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'commit',
+            run: async () => {
+                const current_workspace = this.requireWorkspace(workspace.id);
+                const base_graph = await this.readCommitGraph(current_workspace.head_sdlc_commit_id);
+                const { graph } = await composeGraphProjection(projectionDirectory(current_workspace), undefined, { base: async () => base_graph });
+                // A node parent the head already had is not this commit's to fix.
+                const graph_issues = validateProjectionGraph(graph, {
+                    node_parents: true
+                }).issues;
+                const issues = introducedBrokenIssues(graph, [base_graph], graph_issues).map((issue) => `${issue.code}: ${issue.message}`);
+                if (issues.length > 0) {
+                    throw new Error(`Cannot commit invalid projection: ${issues.join('; ')}`);
+                }
+                const diff = diffProjectionGraphs({
+                    base_graph,
+                    current_graph: graph,
+                    deletion_intents: this.store.listWorkspaceDeletions(current_workspace.id)
+                });
+                if (diff.missing_unrecorded.length > 0) {
+                    throw new Error(`Projection has unrecorded deletions: ${diff.missing_unrecorded
+                        .map((entry) => entry.relative_path)
+                        .join(', ')}; record them with sdlc workspace rm.`);
+                }
+                if (!projectionDiffHasChanges(diff)) {
+                    // Intents for entities that are still present no longer apply.
+                    this.store.clearWorkspaceDeletions(current_workspace.id);
+                    return {
+                        version: 1,
+                        status: 'unchanged',
+                        workspace: current_workspace,
+                        root_hash: this.commitRoot(current_workspace.head_sdlc_commit_id)
+                    };
+                }
+                assertGraphChangesWithinTaskScope({
+                    base_graph,
+                    current_graph: graph,
+                    task_scope: this.store.getWorkspaceTaskScope(current_workspace.id)
+                });
+                assertNoRetiredKeysOnChangedNodes({ base_graph, current_graph: graph });
+                assertNodeTypeRulesOnChangedNodes({ base_graph, current_graph: graph });
+                assertIntroducedVocabularyAdmitted({
+                    base_graph,
+                    graph,
+                    admission: this.store.admissions.get()
+                });
+                const use_issues = packageUseCommitIssues({
+                    base_graph,
+                    graph,
+                    source: () => heldPackages()
+                });
+                if (use_issues.length > 0) {
+                    throw new Error(`Cannot commit package uses that do not resolve: ${use_issues.join('; ')}`);
+                }
+                const embed_warnings = introducedDanglingDocumentEmbeds({
+                    base_graph,
+                    graph
+                });
+                const library_warnings = getLibraryOriginWarnings(graph, {
+                    node_ids: new Set([...diff.added, ...diff.modified]
+                        .filter((entry) => entry.entity_kind === 'node')
+                        .map((entry) => entry.entity_id))
+                });
+                const evidence_drop_warning = evidenceDropWarning(droppedEvidenceReferences({ base_graph, graph }));
+                // What a hosted save of this graph would warn of, less what the head had.
+                const validation_warnings = introducedValidationWarnings(graph, base_graph, graph_issues);
+                const root_hash = await this.graphs.writeGraph(graph);
+                const binding = this.store.getSourceRepositoryBinding(git.git_common_dir);
+                const commit = this.store.history.commitWorkspace({
+                    actor_workspace_id: current_workspace.id,
+                    expected_head_commit_id: current_workspace.head_sdlc_commit_id,
+                    root_hash,
+                    message: input.message,
+                    validation_evidence: [
+                        'complete graph validation passed',
+                        ...(embed_warnings.length > 0
+                            ? [
+                                `Document embeds reference missing entities: ${embed_warnings
+                                    .map((issue) => `${issue.node_id}#${issue.block_id} -> ${issue.entity_kind} ${issue.entity_id}`)
+                                    .join(', ')}`
+                            ]
+                            : []),
+                        ...library_warnings.map((warning) => warning.message),
+                        ...(evidence_drop_warning ? [evidence_drop_warning] : []),
+                        ...validation_warnings
+                    ],
+                    source_context: binding
+                        ? {
+                            source_repository_association_id: binding.source_repository_association_id,
+                            remote_identity: binding.remote_identity,
+                            git_ref: git.ref,
+                            git_head: git.head,
+                            evidence_scope: input.evidence_scope ?? {
+                                include_paths: [],
+                                exclude_paths: []
+                            }
+                        }
+                        : undefined
+                });
+                this.store.clearWorkspaceDeletions(current_workspace.id);
+                await recordScopedProjectionFiles(projectionDirectory(current_workspace));
+                const source_context = binding
+                    ? this.store.getWorkspaceCommitSourceContext(commit.id)
+                    : null;
+                const warnings = [
+                    ...commit.validation_evidence.slice(1),
+                    ...graphShapeWarnings(graph)
+                ];
+                return {
+                    version: 1,
+                    status: 'committed',
+                    validation: {
+                        status: warnings.length > 0 ? 'passed_with_warnings' : 'passed',
+                        warnings
+                    },
+                    workspace: this.requireWorkspace(current_workspace.id),
+                    commit,
+                    source_context,
+                    ...(embed_warnings.length > 0
+                        ? { document_embed_warnings: embed_warnings }
+                        : {}),
+                    ...(library_warnings.length > 0
+                        ? { library_origin_warnings: library_warnings }
+                        : {})
+                };
+            }
+        });
+    }
+    async enqueueChildCommit(input) {
+        return this.integration_runtime.enqueue(input);
+    }
+    async readBuiltView(input) {
+        return this.integration_runtime.readBuiltView(input);
+    }
+    async integrateNext(input) {
+        return this.integration_runtime.integrate(input);
+    }
+    async reconcileSource(input) {
+        return this.integration_runtime.reconcile(input);
+    }
+    prepareHandoff(input) {
+        return this.handoff_runtime.prepare({
+            ...input,
+            reconcile_source: (reconciliation_input) => this.reconcileSource(reconciliation_input)
+        });
+    }
+    listHandoffs(actor_workspace_id) {
+        return this.handoff_runtime.list(actor_workspace_id);
+    }
+    inspectHandoff(input) {
+        return this.handoff_runtime.inspect(input);
+    }
+    applyHandoff(input) {
+        return this.handoff_runtime.apply(input);
+    }
+    /**
+     * `sdlc workspace decision reopen`: reopens the Decision and, with
+     * `revive_workspace_id`, checks out a new plan workspace at `target_path`
+     * that starts at that closed candidate's last head and takes its place.
+     */
+    async reopenDecision(input) {
+        await this.decisionActor();
+        if (!input.revive_workspace_id) {
+            const { decision } = this.store.reopenDecision(input);
+            return { version: 1, decision, workspace: null };
+        }
+        if (!input.target_path) {
+            throw new Error('Reopening a closed candidate needs --path for its new workspace.');
+        }
+        const closed = this.requireWorkspace(input.revive_workspace_id);
+        if (closed.status !== 'closed' || !closed.source_workspace_id) {
+            throw new Error(`Workspace ${closed.id} is not a closed plan workspace.`);
+        }
+        const coordinator = this.requireWorkspace(closed.source_workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(coordinator),
+            operation: 'decision-reopen',
+            run: async () => {
+                const target_path = resolve(input.target_path);
+                const created_git = await createDetachedGitWorktree({
+                    source_cwd: coordinator.git_worktree_path,
+                    target_path,
+                    commit_id: closed.fork_git_commit_id
+                });
+                // Everything in the new checkout is written before the one store
+                // transaction, so any failure removes the checkout and leaves the
+                // Decision as it was.
+                const id = randomUUID();
+                let reopened;
+                try {
+                    await assertLocalWorkspacePathsIgnored(created_git.repository_root);
+                    await this.materialize_projection({
+                        projection_dir: join(created_git.repository_root, 'sdlc'),
+                        graph: await this.readCommitGraph(closed.head_sdlc_commit_id)
+                    });
+                    await mkdir(join(created_git.repository_root, '.sdlc', 'state'), {
+                        recursive: true,
+                        mode: 0o700
+                    });
+                    await this.persistCurrentTopology({ id }, this.topology?.storage_mode, created_git.repository_root, created_git.git_common_dir);
+                    reopened = this.store.reopenDecision({
+                        decision_id: input.decision_id,
+                        reason: input.reason,
+                        revive: {
+                            id,
+                            workspace_id: closed.id,
+                            git_worktree_path: created_git.repository_root,
+                            git_dir: created_git.git_dir,
+                            git_common_dir: created_git.git_common_dir,
+                            git_head_commit_id: created_git.head
+                        }
+                    });
+                }
+                catch (error) {
+                    await removeGitWorktree({
+                        repository_cwd: this.git.repository_root,
+                        target_path: created_git.repository_root,
+                        force: true
+                    }).catch(() => undefined);
+                    throw error;
+                }
+                return {
+                    version: 1,
+                    decision: reopened.decision,
+                    workspace: await this.getWorkspaceStatus(reopened.workspace.id)
+                };
+            }
+        });
+    }
+    /**
+     * `sdlc workspace pick`: copies chosen entities from another workspace's
+     * commit into the acting workspace as one commit with a receipt.
+     */
+    pickEntities(input) {
+        return this.pick_runtime.pick(input);
+    }
+    /** The current workspace, authorized to run `sdlc workspace decision`. */
+    async decisionActor() {
+        const { workspace } = await this.authority.requireCurrent(this.currentActiveWorkspace().id);
+        return workspace;
+    }
+    async closeWorkspace(input) {
+        const { workspace: actor } = await this.authority.requireCurrent(input.actor_workspace_id);
+        const workspace = this.requireWorkspace(input.workspace_id);
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'close',
+            run: async () => {
+                const current_workspace = this.requireWorkspace(workspace.id);
+                const status = await this.getWorkspaceStatus(current_workspace.id);
+                if (status.projection_dirty) {
+                    throw new Error('Workspace projection has uncommitted changes; commit them before closing.');
+                }
+                return this.store.closeWorkspace({
+                    actor_workspace_id: actor.id,
+                    workspace_id: current_workspace.id,
+                    expected_head_commit_id: current_workspace.head_sdlc_commit_id
+                });
+            }
+        });
+    }
+    async planPrune(input = {}) {
+        const current = this.currentActiveWorkspace();
+        await this.authority.requireCurrent(current.id);
+        return this.pruner.plan({
+            actor_workspace_id: current.id,
+            ...input
+        });
+    }
+    async applyPrune(input) {
+        const current = this.currentActiveWorkspace();
+        await this.authority.requireCurrent(current.id);
+        return this.pruner.apply({
+            actor_workspace_id: current.id,
+            ...input
+        });
+    }
+    async recoverCurrentProjection(input) {
+        const { workspace } = await this.authority.requireCurrent(input.actor_workspace_id);
+        if (!input.expected_projection_root_hash &&
+            !input.discard_unreadable_projection) {
+            throw new Error('Recovery requires --expected-projection-root unless unreadable projection discard is explicit.');
+        }
+        return withWorkspaceOperationLock({
+            control_dir: controlDirectory(workspace),
+            operation: 'recover',
+            run: async () => {
+                const current_workspace = this.requireWorkspace(workspace.id);
+                if (current_workspace.head_sdlc_commit_id !==
+                    input.expected_head_commit_id) {
+                    throw new Error('Workspace head is stale; refusing projection recovery.');
+                }
+                const head_graph = await this.readCommitGraph(current_workspace.head_sdlc_commit_id);
+                const head_root_hash = this.commitRoot(current_workspace.head_sdlc_commit_id);
+                let previous_projection_root_hash = null;
+                let discarded_unreadable_projection = false;
+                let readable_projection = null;
+                try {
+                    const { graph } = await composeGraphProjection(projectionDirectory(current_workspace), undefined, { base: async () => head_graph });
+                    readable_projection = graph;
+                }
+                catch (error) {
+                    if (!input.discard_unreadable_projection)
+                        throw error;
+                    discarded_unreadable_projection = true;
+                }
+                if (readable_projection) {
+                    if (!input.expected_projection_root_hash) {
+                        throw new Error('Readable projection recovery requires its expected root.');
+                    }
+                    previous_projection_root_hash =
+                        localGraphRootHash(readable_projection);
+                    if (previous_projection_root_hash !==
+                        input.expected_projection_root_hash) {
+                        throw new Error('Projection root is stale; refusing projection recovery.');
+                    }
+                    await this.graphs.writeGraph(readable_projection);
+                }
+                if (previous_projection_root_hash === head_root_hash) {
+                    return {
+                        version: 1,
+                        status: 'unchanged',
+                        workspace: current_workspace,
+                        head_root_hash,
+                        previous_projection_root_hash,
+                        discarded_unreadable_projection
+                    };
+                }
+                // A discarded projection.json cannot name its scope: the task scope does.
+                const rescope = discarded_unreadable_projection &&
+                    (await hasProjectionManifest(projectionDirectory(current_workspace)));
+                const task_scope = this.store.getWorkspaceTaskScope(current_workspace.id);
+                await this.materialize_projection({
+                    projection_dir: projectionDirectory(current_workspace),
+                    graph: head_graph,
+                    ...(rescope && task_scope
+                        ? { scope: projectionScopeOfTaskScope(task_scope) }
+                        : rescope
+                            ? { full: true }
+                            : {})
+                });
+                // The head projection restores every entity a deletion intent named.
+                this.store.clearWorkspaceDeletions(current_workspace.id);
+                return {
+                    version: 1,
+                    status: 'recovered',
+                    workspace: current_workspace,
+                    head_root_hash,
+                    previous_projection_root_hash,
+                    discarded_unreadable_projection
+                };
+            }
+        });
+    }
+    requireWorkspace(workspace_id) {
+        const workspace = this.store.getWorkspace(workspace_id);
+        if (!workspace)
+            throw new Error('Local workspace was not found.');
+        return workspace;
+    }
+    currentActiveWorkspace() {
+        const workspace = this.store.getWorkspaceByGitWorktreePath(this.git.repository_root);
+        if (!workspace || workspace.status !== 'active') {
+            throw new Error('The current Git worktree is not an active workspace.');
+        }
+        return workspace;
+    }
+    commitRoot(commit_id) {
+        return this.commits.root(commit_id);
+    }
+    async readCommitGraph(commit_id) {
+        return this.commits.readGraph(commit_id);
+    }
+    async assertProjectionClean(workspace) {
+        const status = await this.getWorkspaceStatus(workspace.id);
+        if (status.projection_dirty) {
+            throw new Error('Workspace projection has uncommitted changes; commit them before this operation.');
+        }
+    }
+}
+//# sourceMappingURL=workspace-runtime.js.map