codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14

package/src/state/store.ts

@@ -0,0 +1,567 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import type {
+  DiscoveryState,
+  DelegationGrant,
+  EntityState,
+  GraphBinding,
+  GraphKind,
+  MilestoneTransactionJournal,
+  MilestoneTransactionJournalFileSnapshot,
+  MilestoneTransactionPhase,
+  MilestoneState,
+  ProjectRecord,
+  ProjectKnowledgeMap,
+  RevisionedRecord,
+  SidecarEventRecord,
+  TaskState,
+} from '../contracts.js';
+import { STATE_SCHEMA_VERSION } from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { ensureDirectory, readJson, writeJsonAtomic, writeTextAtomic } from '../fs-utils.js';
+import type { RepositoryIdentity } from '../repository.js';
+import {
+  captureJournalTargetSnapshot,
+  createJournalSnapshotFromContent,
+  listMilestoneTransactionJournals,
+  readJournalSnapshotContent,
+  readMilestoneTransactionJournal,
+  removeMilestoneTransactionJournal,
+  resolveMilestoneTransactionDirectory,
+  resolveMilestoneTransactionJournalPath,
+  resolveMilestoneTransactionTargetPath,
+  updateMilestoneTransactionJournalPhase,
+  writeMilestoneTransactionJournal,
+  type JournalSnapshotMode,
+} from '../alpha6/journal.js';
+import {
+  assertNoSymlinkPathComponents,
+  prepareSidecarAppend,
+  readSidecarEvents as readValidatedSidecarEvents,
+  resolveSidecarPath,
+  type SidecarEventValidator,
+  type SidecarAppendInput,
+} from '../alpha6/store-sidecars.js';
+import { assertTaskTransactionBoundary as assertCorrectiveReplanTaskTransactionBoundary } from './corrective-replan-transaction.js';
+import { assertCorrectiveYieldTaskTransactionBoundary } from './corrective-yield-transaction.js';
+import { inspectCoreTaskOperationMutex } from './lock.js';
+
+export interface StateStoreOptions {
+  root?: string;
+  now?: () => Date;
+}
+
+function assertTaskTransactionBoundary(projectRoot: string, trustedRoot: string, taskId?: string): void {
+  assertCorrectiveReplanTaskTransactionBoundary(projectRoot, trustedRoot, taskId);
+  assertCorrectiveYieldTaskTransactionBoundary(projectRoot, trustedRoot, taskId);
+}
+
+export interface StagedArtifact {
+  entityRoot: string;
+  name: string;
+  hash: string;
+  stagedFile: string;
+}
+
+export interface StagedSidecarAppend<T extends SidecarEventRecord> extends StagedArtifact {
+  file: string;
+  event: T;
+}
+
+export class FileStateStore {
+  readonly root: string;
+  private readonly now: () => Date;
+
+  constructor(options: StateStoreOptions = {}) {
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    this.root = path.resolve(
+      options.root || process.env.CODEX_WORKFLOW_STATE_HOME || path.join(codexHome, 'workflow-state', 'v2'),
+    );
+    this.now = options.now ?? (() => new Date());
+  }
+
+  readProject(projectId: string): ProjectRecord {
+    const file = path.join(this.projectRoot(projectId), 'project.json');
+    if (!existsSync(file)) throw new WorkflowError('NOT_FOUND', `Project state not found: ${file}`);
+    const project = readJson<ProjectRecord>(file);
+    if (project.schemaVersion !== STATE_SCHEMA_VERSION) {
+      throw new WorkflowError('STATE_CORRUPT', `Unsupported project state schema: ${file}`, {
+        expectedSchemaVersion: STATE_SCHEMA_VERSION,
+        actualSchemaVersion: project.schemaVersion,
+      });
+    }
+    if (project.projectId !== projectId) {
+      throw new WorkflowError('STATE_CORRUPT', `Unexpected project identity: ${file}`, {
+        expectedProjectId: projectId,
+        actualProjectId: project.projectId,
+      });
+    }
+    return project;
+  }
+
+  registerProject(identity: RepositoryIdentity): ProjectRecord {
+    const projectRoot = this.projectRoot(identity.projectId);
+    ensureDirectory(projectRoot);
+    const file = path.join(projectRoot, 'project.json');
+    const timestamp = this.now().toISOString();
+    if (existsSync(file)) {
+      const existing = this.readProject(identity.projectId);
+      const repositoryRoots = [...new Set([...existing.repositoryRoots, identity.repositoryRoot])];
+      if (repositoryRoots.length === existing.repositoryRoots.length) return existing;
+      const updated: ProjectRecord = { ...existing, repositoryRoots, updatedAt: timestamp };
+      writeJsonAtomic(file, updated);
+      return updated;
+    }
+    const created: ProjectRecord = {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      projectId: identity.projectId,
+      gitCommonDir: identity.gitCommonDir,
+      repositoryRoots: [identity.repositoryRoot],
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    writeJsonAtomic(file, created);
+    return created;
+  }
+
+  projectRoot(projectId: string): string {
+    this.assertId(projectId, /^[a-f0-9]{24}$/);
+    return path.join(this.root, 'projects', projectId);
+  }
+
+  discoveryRoot(projectId: string, discoveryId: string): string {
+    this.assertId(discoveryId, /^DISC-[0-9A-HJKMNP-TV-Z]{26}$/);
+    return path.join(this.projectRoot(projectId), 'discoveries', discoveryId);
+  }
+
+  taskRoot(projectId: string, taskId: string): string {
+    this.assertId(taskId, /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/);
+    return path.join(this.projectRoot(projectId), 'tasks', taskId);
+  }
+
+  milestoneRoot(projectId: string, milestoneId: string): string {
+    this.assertId(milestoneId, /^MS-[0-9A-HJKMNP-TV-Z]{26}$/);
+    return path.join(this.projectRoot(projectId), 'milestones', milestoneId);
+  }
+
+  delegationRoot(projectId: string, grantId: string): string {
+    this.assertId(grantId, /^DGR-[0-9A-HJKMNP-TV-Z]{26}$/);
+    return path.join(this.projectRoot(projectId), 'delegations', grantId);
+  }
+
+  snapshotRoot(projectId: string): string {
+    return path.join(this.projectRoot(projectId), 'snapshots');
+  }
+
+  lockRoot(projectId: string): string {
+    return path.join(this.projectRoot(projectId), 'locks');
+  }
+
+  projectSidecarPath(projectId: string, sidecarName: string): string {
+    return resolveSidecarPath(this.projectRoot(projectId), sidecarName, this.root);
+  }
+
+  taskSidecarPath(projectId: string, taskId: string, sidecarName: string): string {
+    return resolveSidecarPath(this.taskRoot(projectId, taskId), sidecarName, this.root);
+  }
+
+  milestoneSidecarPath(projectId: string, milestoneId: string, sidecarName: string): string {
+    return resolveSidecarPath(this.milestoneRoot(projectId, milestoneId), sidecarName, this.root);
+  }
+
+  writeKnowledgeMap(map: ProjectKnowledgeMap, expectedRevision: number | null): ProjectKnowledgeMap {
+    return this.writeRevisioned(path.join(this.projectRoot(map.projectId), 'knowledge-map.json'), map, expectedRevision);
+  }
+
+  readKnowledgeMap(projectId: string): ProjectKnowledgeMap {
+    return this.readEntity(path.join(this.projectRoot(projectId), 'knowledge-map.json'), 'knowledge-map');
+  }
+
+  writeGraphBinding(binding: GraphBinding, expectedRevision: number | null): GraphBinding {
+    return this.writeRevisioned(
+      path.join(this.projectRoot(binding.projectId), 'graph-bindings', `${binding.graphKind}.json`),
+      binding,
+      expectedRevision,
+    );
+  }
+
+  readGraphBinding(projectId: string, graphKind: GraphKind): GraphBinding {
+    return this.readEntity(
+      path.join(this.projectRoot(projectId), 'graph-bindings', `${graphKind}.json`),
+      'graph-binding',
+    );
+  }
+
+  writeDiscovery(discovery: DiscoveryState, expectedRevision: number | null): DiscoveryState {
+    return this.writeRevisioned(
+      path.join(this.discoveryRoot(discovery.projectId, discovery.id), 'state.json'),
+      discovery,
+      expectedRevision,
+    );
+  }
+
+  readDiscovery(projectId: string, discoveryId: string): DiscoveryState {
+    return this.readEntity(path.join(this.discoveryRoot(projectId, discoveryId), 'state.json'), 'discovery');
+  }
+
+  writeTask(task: TaskState, expectedRevision: number | null): TaskState {
+    assertTaskTransactionBoundary(this.projectRoot(task.projectId), this.root, task.id);
+    this.assertNoCoreTaskOperation(task.projectId, task.id);
+    return this.writeRevisioned(path.join(this.taskRoot(task.projectId, task.id), 'state.json'), task, expectedRevision);
+  }
+
+  readTask(projectId: string, taskId: string): TaskState {
+    assertTaskTransactionBoundary(this.projectRoot(projectId), this.root, taskId);
+    const task = this.readEntity<TaskState>(path.join(this.taskRoot(projectId, taskId), 'state.json'), 'task');
+    assertTaskTransactionBoundary(this.projectRoot(projectId), this.root, taskId);
+    return task;
+  }
+
+  writeMilestone(milestone: MilestoneState, expectedRevision: number | null): MilestoneState {
+    return this.writeRevisioned(
+      path.join(this.milestoneRoot(milestone.projectId, milestone.id), 'state.json'),
+      milestone,
+      expectedRevision,
+    );
+  }
+
+  readMilestone(projectId: string, milestoneId: string): MilestoneState {
+    return this.readEntity(path.join(this.milestoneRoot(projectId, milestoneId), 'state.json'), 'milestone');
+  }
+
+  writeDelegation(grant: DelegationGrant, expectedRevision: number | null): DelegationGrant {
+    return this.writeRevisioned(
+      path.join(this.delegationRoot(grant.projectId, grant.id), 'state.json'),
+      grant,
+      expectedRevision,
+    );
+  }
+
+  readDelegation(projectId: string, grantId: string): DelegationGrant {
+    return this.readEntity(path.join(this.delegationRoot(projectId, grantId), 'state.json'), 'delegation-grant');
+  }
+
+  listTasks(projectId: string): TaskState[] {
+    assertTaskTransactionBoundary(this.projectRoot(projectId), this.root);
+    const tasks = this.listEntities<TaskState>(path.join(this.projectRoot(projectId), 'tasks'), 'task');
+    assertTaskTransactionBoundary(this.projectRoot(projectId), this.root);
+    return tasks;
+  }
+
+  listDiscoveries(projectId: string): DiscoveryState[] {
+    return this.listEntities<DiscoveryState>(path.join(this.projectRoot(projectId), 'discoveries'), 'discovery');
+  }
+
+  listMilestones(projectId: string): MilestoneState[] {
+    return this.listEntities<MilestoneState>(path.join(this.projectRoot(projectId), 'milestones'), 'milestone');
+  }
+
+  listDelegations(projectId: string, inertAutonomyGrantIds: ReadonlySet<string> = new Set()): DelegationGrant[] {
+    return this.listEntities<DelegationGrant>(
+      path.join(this.projectRoot(projectId), 'delegations'),
+      'delegation-grant',
+      inertAutonomyGrantIds,
+    );
+  }
+
+  writeArtifact(entityRoot: string, name: string, content: string): string {
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot, true);
+    if (!/^[a-z][a-z0-9-]*\.md$/.test(name)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Invalid artifact name: ${name}`);
+    }
+    const file = path.join(entityRoot, name);
+    writeTextAtomic(file, content);
+    return createHash('sha256').update(readFileSync(file)).digest('hex');
+  }
+
+  stageArtifact(entityRoot: string, name: string, content: string): StagedArtifact {
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot, true);
+    if (!/^[a-z][a-z0-9-]*\.(?:md|json|jsonl)$/.test(name)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Invalid artifact name: ${name}`);
+    }
+    const normalized = content.endsWith('\n') ? content : `${content}\n`;
+    const hash = createHash('sha256').update(normalized).digest('hex');
+    const stagedFile = path.join(entityRoot, '.versions', `${name}.${hash}`);
+    if (!existsSync(stagedFile)) writeTextAtomic(stagedFile, normalized);
+    return { entityRoot, name, hash, stagedFile };
+  }
+
+  publishArtifact(staged: StagedArtifact): string {
+    this.assertTaskTransactionBoundaryForEntityRoot(staged.entityRoot, true);
+    writeTextAtomic(path.join(staged.entityRoot, staged.name), readFileSync(staged.stagedFile, 'utf8'));
+    const actual = this.hashArtifact(staged.entityRoot, staged.name);
+    if (actual !== staged.hash) {
+      throw new WorkflowError('STATE_CORRUPT', `Published artifact hash mismatch: ${staged.name}`, {
+        expected: staged.hash,
+        actual,
+      });
+    }
+    return actual;
+  }
+
+  hashArtifact(entityRoot: string, name: string): string {
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot);
+    const file = path.join(entityRoot, name);
+    if (!existsSync(file)) throw new WorkflowError('NOT_FOUND', `Artifact not found: ${name}`);
+    const hash = createHash('sha256').update(readFileSync(file)).digest('hex');
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot);
+    return hash;
+  }
+
+  readSidecarEvents<T extends SidecarEventRecord>(
+    entityRoot: string,
+    sidecarName: string,
+    options: { validateEvent?: SidecarEventValidator<T> } = {},
+  ): T[] {
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot);
+    this.assertAlpha6StateRoot(entityRoot);
+    const events = readValidatedSidecarEvents<T>(resolveSidecarPath(entityRoot, sidecarName, this.root), {
+      ...options,
+      trustedRoot: this.root,
+    });
+    this.assertTaskTransactionBoundaryForEntityRoot(entityRoot);
+    return events;
+  }
+
+  stageSidecarAppend<T extends SidecarEventRecord>(
+    entityRoot: string,
+    sidecarName: string,
+    event: SidecarAppendInput<T>,
+    options: { validateEvent?: SidecarEventValidator<T> } = {},
+  ): StagedSidecarAppend<T> {
+    this.assertAlpha6StateRoot(entityRoot);
+    const current = this.readSidecarEvents<T>(entityRoot, sidecarName, options);
+    const prepared = prepareSidecarAppend(current, event, options);
+    const sidecarFile = resolveSidecarPath(entityRoot, sidecarName, this.root);
+    assertNoSymlinkPathComponents(sidecarFile, { label: 'Sidecar file', trustedRoot: this.root });
+    const staged = this.stageArtifact(entityRoot, sidecarName, prepared.content);
+    if (staged.hash !== prepared.contentHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Staged sidecar hash mismatch: ${sidecarName}`, {
+        expectedHash: prepared.contentHash,
+        actualHash: staged.hash,
+      });
+    }
+    const stagedEvents = readValidatedSidecarEvents<T>(staged.stagedFile, {
+      ...options,
+      trustedRoot: this.root,
+    });
+    if (stagedEvents.length !== current.length + 1) {
+      throw new WorkflowError('STATE_CORRUPT', `Staged sidecar append length mismatch: ${sidecarName}`, {
+        expectedLength: current.length + 1,
+        actualLength: stagedEvents.length,
+      });
+    }
+    const appended = stagedEvents[stagedEvents.length - 1];
+    if (!appended || appended.eventHash !== prepared.event.eventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Staged sidecar append validation failed: ${sidecarName}`, {
+        expectedEventHash: prepared.event.eventHash,
+        actualEventHash: appended?.eventHash ?? null,
+      });
+    }
+    return {
+      ...staged,
+      file: sidecarFile,
+      event: prepared.event,
+    };
+  }
+
+  appendSidecarEvent<T extends SidecarEventRecord>(
+    entityRoot: string,
+    sidecarName: string,
+    event: SidecarAppendInput<T>,
+    options: { validateEvent?: SidecarEventValidator<T> } = {},
+  ): T {
+    const staged = this.stageSidecarAppend(entityRoot, sidecarName, event, options);
+    this.publishArtifact(staged);
+    return staged.event;
+  }
+
+  milestoneTransactionDirectory(projectId: string, milestoneId: string): string {
+    return resolveMilestoneTransactionDirectory(this.milestoneRoot(projectId, milestoneId));
+  }
+
+  milestoneTransactionJournalPath(projectId: string, milestoneId: string, transactionId: string): string {
+    return resolveMilestoneTransactionJournalPath(this.milestoneRoot(projectId, milestoneId), transactionId);
+  }
+
+  milestoneTransactionTargetPath(projectId: string, milestoneId: string, relativePath: string): string {
+    return resolveMilestoneTransactionTargetPath(this.milestoneRoot(projectId, milestoneId), relativePath);
+  }
+
+  captureMilestoneTransactionSnapshot(
+    projectId: string,
+    milestoneId: string,
+    relativePath: string,
+    options: { mode?: JournalSnapshotMode; transactionId?: string; snapshotPath?: string } = {},
+  ): MilestoneTransactionJournalFileSnapshot {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return captureJournalTargetSnapshot(this.milestoneRoot(projectId, milestoneId), relativePath, options);
+  }
+
+  stageMilestoneTransactionSnapshot(
+    projectId: string,
+    milestoneId: string,
+    content: string | Buffer,
+    options: { mode?: JournalSnapshotMode; transactionId?: string; snapshotPath?: string } = {},
+  ): MilestoneTransactionJournalFileSnapshot {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return createJournalSnapshotFromContent(this.milestoneRoot(projectId, milestoneId), content, options);
+  }
+
+  readMilestoneTransactionSnapshot(
+    projectId: string,
+    milestoneId: string,
+    snapshot: MilestoneTransactionJournalFileSnapshot,
+  ): Buffer | null {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return readJournalSnapshotContent(this.milestoneRoot(projectId, milestoneId), snapshot);
+  }
+
+  writeMilestoneTransactionJournal(
+    projectId: string,
+    milestoneId: string,
+    journal: MilestoneTransactionJournal,
+  ): MilestoneTransactionJournal {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return writeMilestoneTransactionJournal(this.milestoneRoot(projectId, milestoneId), journal);
+  }
+
+  readMilestoneTransactionJournal(
+    projectId: string,
+    milestoneId: string,
+    transactionId: string,
+  ): MilestoneTransactionJournal {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return readMilestoneTransactionJournal(this.milestoneRoot(projectId, milestoneId), transactionId, {
+      expectedMilestoneId: milestoneId,
+    });
+  }
+
+  listMilestoneTransactionJournals(projectId: string, milestoneId: string): MilestoneTransactionJournal[] {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return listMilestoneTransactionJournals(this.milestoneRoot(projectId, milestoneId), {
+      expectedMilestoneId: milestoneId,
+    });
+  }
+
+  updateMilestoneTransactionJournalPhase(
+    projectId: string,
+    milestoneId: string,
+    transactionId: string,
+    phase: MilestoneTransactionPhase,
+  ): MilestoneTransactionJournal {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    return updateMilestoneTransactionJournalPhase(
+      this.milestoneRoot(projectId, milestoneId),
+      transactionId,
+      phase,
+      this.now().toISOString(),
+      { expectedMilestoneId: milestoneId },
+    );
+  }
+
+  removeMilestoneTransactionJournal(projectId: string, milestoneId: string, transactionId: string): void {
+    this.assertAlpha6StateRoot(this.milestoneRoot(projectId, milestoneId));
+    removeMilestoneTransactionJournal(this.milestoneRoot(projectId, milestoneId), transactionId);
+  }
+
+  private writeRevisioned<T extends RevisionedRecord>(file: string, record: T, expectedRevision: number | null): T {
+    const timestamp = this.now().toISOString();
+    if (!existsSync(file)) {
+      if (expectedRevision !== null) {
+        throw new WorkflowError('STATE_CONFLICT', `Cannot update missing state ${record.id}`, {
+          expectedRevision,
+          actualRevision: null,
+        });
+      }
+      const created = { ...record, revision: 1, updatedAt: timestamp };
+      writeJsonAtomic(file, created);
+      return created;
+    }
+
+    const existing = readJson<T>(file);
+    if (expectedRevision === null || existing.revision !== expectedRevision) {
+      throw new WorkflowError('STATE_CONFLICT', `State revision conflict for ${record.id}`, {
+        expectedRevision,
+        actualRevision: existing.revision,
+      });
+    }
+    const updated = { ...record, revision: existing.revision + 1, updatedAt: timestamp };
+    writeJsonAtomic(file, updated);
+    return updated;
+  }
+
+  private readEntity<T extends EntityState>(file: string, kind: T['kind']): T {
+    if (!existsSync(file)) throw new WorkflowError('NOT_FOUND', `${kind} state not found: ${file}`);
+    const entity = readJson<EntityState>(file);
+    if (entity.kind !== kind || entity.schemaVersion !== STATE_SCHEMA_VERSION) {
+      throw new WorkflowError('STATE_CORRUPT', `Unexpected ${kind} state schema: ${file}`);
+    }
+    return entity as T;
+  }
+
+  private listEntities<T extends EntityState>(directory: string, kind: T['kind'], knownUnpublishedIds: ReadonlySet<string> = new Set()): T[] {
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => {
+        if (!knownUnpublishedIds.has(entry.name)) return true;
+        try {
+          // A dangling symlink or a malformed published state is not an absent write.
+          lstatSync(path.join(directory, entry.name, 'state.json'));
+          return true;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+          return false;
+        }
+      })
+      .map((entry) => this.readEntity<T>(path.join(directory, entry.name, 'state.json'), kind))
+      .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  private assertId(value: string, pattern: RegExp): void {
+    if (!pattern.test(value)) throw new WorkflowError('INVALID_ARGUMENT', `Invalid state identifier: ${value}`);
+  }
+
+  private assertAlpha6StateRoot(entityRoot: string): void {
+    const resolvedRoot = path.resolve(this.root);
+    const resolvedEntityRoot = path.resolve(entityRoot);
+    if (resolvedEntityRoot !== resolvedRoot && !resolvedEntityRoot.startsWith(`${resolvedRoot}${path.sep}`)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `State path is outside of the configured store root: ${entityRoot}`);
+    }
+    const relativePath = path.relative(resolvedRoot, resolvedEntityRoot);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `State path is outside of the configured store root: ${entityRoot}`);
+    }
+    let current = resolvedRoot;
+    for (const segment of relativePath.split(path.sep).filter(Boolean)) {
+      current = path.join(current, segment);
+      if (!existsSync(current)) continue;
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `Alpha6 state root must not traverse a symlink: ${entityRoot}`, {
+          symlinkPath: current,
+        });
+      }
+    }
+  }
+
+  private assertTaskTransactionBoundaryForEntityRoot(entityRoot: string, mutation = false): void {
+    const relative = path.relative(this.root, path.resolve(entityRoot)).split(path.sep);
+    if (relative.length === 4 && relative[0] === 'projects' && relative[2] === 'tasks') {
+      assertTaskTransactionBoundary(this.projectRoot(relative[1]!), this.root, relative[3]!);
+      if (mutation) this.assertNoCoreTaskOperation(relative[1]!, relative[3]!);
+    }
+  }
+
+  private assertNoCoreTaskOperation(projectId: string, taskId: string): void {
+    const operation = inspectCoreTaskOperationMutex(this.lockRoot(projectId), taskId, this.root);
+    if (operation) {
+      throw new WorkflowError('LOCKED', `A Core Task operation owns ${taskId}.`, {
+        operationId: operation.operationId,
+        transitionId: operation.transitionId,
+      });
+    }
+  }
+}