import { createHash, randomUUID } from "node:crypto";
import { lstatSync, readdirSync, readFileSync } from "node:fs";
import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import { isAbsolute, join } from "node:path";
import { buildInstallationContract, renderWorkspaceDocs } from "./contracts.js";
import { parseAnnotationsYaml } from "./annotations.js";
import { syncAnnotations } from "./annotations-sync.js";
import { materializeEvidenceTree } from "./evidence/materialization.js";
import { assertCatalogMatchesDescriptor, parseWorkspaceCatalogYaml, type WorkspaceCatalog, type WorkspaceCatalogEntry } from "./catalog.js";
import {
  GitWorkspaceRepository,
  WorkspaceRegistryError,
  WorkspaceRepositoryLock,
  normalizeRepositoryIdentity,
  type GitStatus,
} from "./git-repository.js";
import {
  parseWorkspaceYaml,
  serializeWorkspaceYaml,
  validateOperationalWorkspace,
  type WorkspaceDescriptor,
} from "./schema.js";
import type { WorkspaceErrorCode, WorkspaceRegistryConfig } from "./types.js";

export type { GitStatus } from "./git-repository.js";

export interface WorkspaceRevision {
  id: string;
  commit: string;
  blob: string;
  snapshotPath: string;
}

export interface StoredWorkspaceIntegrity {
  state: "uninitialized" | "active";
  workspaces: number;
  fingerprint: string;
}

export interface SessionRevisionLease {
  workspace: WorkspaceDescriptor;
  revision: WorkspaceRevision;
  /** Mark the manifest durable; retention removes the lease only after observing that manifest. */
  markPersisted(): Promise<void>;
  /** Remove a lease for a session that failed before its manifest was durable. */
  abort(): Promise<void>;
}

interface ActiveState {
  head: string;
  revisions: WorkspaceRevision[];
  catalog?: WorkspaceCatalog;
}

interface SnapshotManifest extends ActiveState {
  files: Record<string, string>;
}

interface RevisionLeaseRecord {
  version: 1;
  token: string;
  workspaceId: string;
  commit: string;
  state: "creating" | "persisted";
}

function workspacePath(id: string): string {
  if (!/^[a-z][a-z0-9-]{2,62}$/.test(id)) {
    throw new WorkspaceRegistryError("workspace_invalid", "Workspace ID is invalid");
  }
  return `${id}/workspace.yaml`;
}

function safeCommit(commit: string): string {
  if (!/^[0-9a-f]{40}$/.test(commit)) {
    throw new WorkspaceRegistryError("workspace_invalid", "Workspace revision is invalid");
  }
  return commit;
}

function safeBlob(blob: string): string {
  if (!/^[0-9a-f]{40}$/.test(blob)) {
    throw new WorkspaceRegistryError("workspace_invalid", "Workspace snapshot blob is invalid");
  }
  return blob;
}

function digest(contents: string | Buffer): string {
  return createHash("sha256").update(contents).digest("hex");
}

function workspaceError(error: unknown): WorkspaceRegistryError {
  if (error instanceof WorkspaceRegistryError) return error;
  return new WorkspaceRegistryError("workspace_invalid", "Workspace repository content is invalid");
}

/** Immutable canonical workspace snapshots backed by the configured Git checkout. */
export class WorkspaceRegistry {
  private readonly repository: GitWorkspaceRepository;
  private readonly lock: WorkspaceRepositoryLock;

  constructor(private readonly config: WorkspaceRegistryConfig) {
    this.repository = new GitWorkspaceRepository(config);
    this.lock = new WorkspaceRepositoryLock(this.repository.locksPath);
  }

  snapshotPath(commit: string, id: string): string {
    return join(this.repository.snapshotsPath, safeCommit(commit), `${id}.yaml`);
  }

  async bootstrap(): Promise<GitStatus> {
    await this.repository.ensureLayout();
    return await this.lock.run(async () => {
      try {
        const status = await this.repository.bootstrap();
        await this.activate(status.head!);
        return status;
      } catch (error) {
        return await this.gitFallback(error);
      }
    });
  }

  async pull(): Promise<GitStatus> {
    await this.repository.ensureLayout();
    return await this.lock.run(async () => {
      try {
        const status = await this.repository.pull();
        await this.activate(status.head!);
        return status;
      } catch (error) {
        return await this.gitFallback(error);
      }
    });
  }

  async listCatalog(): Promise<Array<WorkspaceCatalogEntry & {
    configurationState: "ready";
    revision: WorkspaceRevision;
  }>> {
    const active = await this.tryActiveState();
    if (!active) {
      await this.bootstrap();
      return await this.listCatalog();
    }
    const catalog = active.catalog ?? { schema_version: 1 as const, workspaces: [] };
    return catalog.workspaces.map((entry) => ({
      ...entry,
      configurationState: "ready" as const,
      revision: active.revisions.find((revision) => revision.id === entry.id)!,
    }));
  }

  async list(): Promise<WorkspaceRevision[]> {
    const active = await this.tryActiveState();
    if (active) return active.revisions;
    // A clean installation has no active snapshot until the first registry operation. Keep
    // this lazy so health/startup remain available when Git is temporarily unreachable, while
    // still refusing corrupted existing state (tryActiveState throws instead of returning none).
    await this.bootstrap();
    return (await this.activeState()).revisions;
  }

  /**
   * List every intact retained snapshot, current snapshots first. Session discovery and
   * retention use this rather than only the active revision so removing a workspace from
   * Git cannot strand a resumable session that still pins one of its older descriptors.
   */
  async listRetainedSnapshots(): Promise<WorkspaceRevision[]> {
    await this.repository.ensureLayout();
    return await this.lock.run(async () => {
      try {
        const active = await this.activeState();
        const revisions = [...active.revisions];
        const entries = await readdir(this.repository.snapshotsPath, { withFileTypes: true });
        for (const entry of entries) {
          if (!entry.isDirectory() || entry.isSymbolicLink() || !/^[0-9a-f]{40}$/.test(entry.name)) continue;
          if (entry.name === active.head) continue;
          const state = await this.snapshotState(entry.name);
          revisions.push(...state.revisions);
        }
        return revisions;
      } catch (error) {
        throw workspaceError(error);
      }
    });
  }

  /**
   * Validate only persisted local registry state. Restore uses this path while the installation
   * is stopped: it must neither contact Git nor turn a never-used registry into initialized state.
   * The only never-initialized shape is an existing empty root. An initialized root is exactly
   * repo/, snapshots/, state/, and locks/: locks contains repository.lock plus an empty
   * empty-hooks/, state contains active.json plus an optional empty revision-leases/, and
   * snapshots contains exact immutable commit snapshots plus an optional empty runtime/.
   * Descendants may contain only ordinary directories and regular files; links and special files
   * are rejected by the stable whole-tree fingerprint before any shape is accepted.
   */
  async verifyStoredState(): Promise<StoredWorkspaceIntegrity> {
    try {
      const before = await this.storedStateFingerprint();
      const rootEntries = await readdir(this.repository.root, { withFileTypes: true });
      if (rootEntries.length === 0) {
        const after = await this.storedStateFingerprint();
        if (after !== before) throw new Error("workspace registry changed during inspection");
        return { state: "uninitialized", workspaces: 0, fingerprint: `sha256:${before}` };
      }
      this.assertExactDirectoryEntries(rootEntries, {
        locks: "directory", repo: "directory", snapshots: "directory", state: "directory",
      });

      this.assertExactDirectoryEntries(
        await readdir(this.repository.locksPath, { withFileTypes: true }),
        { "empty-hooks": "directory", "repository.lock": "file" },
      );
      this.assertExactDirectoryEntries(
        await readdir(join(this.repository.locksPath, "empty-hooks"), { withFileTypes: true }),
        {},
      );

      const stateEntries = await readdir(this.repository.statePath, { withFileTypes: true });
      const stateShape: Record<string, "file" | "directory"> = { "active.json": "file" };
      if (stateEntries.some((entry) => entry.name === "revision-leases")) {
        stateShape["revision-leases"] = "directory";
      }
      this.assertExactDirectoryEntries(stateEntries, stateShape);
      if (stateShape["revision-leases"] !== undefined) {
        this.assertExactDirectoryEntries(
          await readdir(join(this.repository.statePath, "revision-leases"), { withFileTypes: true }),
          {},
        );
      }

      const active = this.decodeActiveState(JSON.parse(await readFile(
        join(this.repository.statePath, "active.json"), "utf8",
      )));
      const snapshotEntries = await readdir(this.repository.snapshotsPath, { withFileTypes: true });
      if (snapshotEntries.length === 0) throw new Error("workspace snapshots are unavailable");
      let activeSnapshotFound = false;
      for (const entry of snapshotEntries) {
        if (entry.name === "runtime") {
          if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error("workspace runtime path is invalid");
          this.assertExactDirectoryEntries(
            await readdir(join(this.repository.snapshotsPath, "runtime"), { withFileTypes: true }),
            {},
          );
          continue;
        }
        if (!/^[0-9a-f]{40}$/.test(entry.name) || !entry.isDirectory() || entry.isSymbolicLink()) {
          throw new Error("workspace snapshot path is invalid");
        }
        const state = entry.name === active.head ? active : await this.readStoredSnapshotState(entry.name);
        await this.assertSnapshotIntegrity(state, false, true);
        if (entry.name === active.head) activeSnapshotFound = true;
      }
      if (!activeSnapshotFound) throw new Error("active workspace snapshot is unavailable");

      const after = await this.storedStateFingerprint();
      if (after !== before) throw new Error("workspace registry changed during inspection");
      return { state: "active", workspaces: active.revisions.length, fingerprint: `sha256:${before}` };
    } catch (error) {
      throw workspaceError(error);
    }
  }

  private assertExactDirectoryEntries(
    entries: Array<{ name: string; isFile(): boolean; isDirectory(): boolean; isSymbolicLink(): boolean }>,
    expected: Record<string, "file" | "directory">,
  ): void {
    if (entries.length !== Object.keys(expected).length) throw new Error("workspace registry shape is invalid");
    for (const entry of entries) {
      const kind = expected[entry.name];
      if (kind === undefined || entry.isSymbolicLink()
        || (kind === "file" && !entry.isFile())
        || (kind === "directory" && !entry.isDirectory())) {
        throw new Error("workspace registry shape is invalid");
      }
    }
  }

  private async storedStateFingerprint(): Promise<string> {
    const records: string[] = [];
    let entries = 0;
    let totalBytes = 0;
    const visit = async (path: string, relative: string): Promise<void> => {
      const before = lstatSync(path);
      if (before.isSymbolicLink()) throw new Error("workspace registry link is invalid");
      const metadata = [
        before.dev, before.ino, before.mode, before.uid, before.gid,
        before.size, before.mtimeMs, before.ctimeMs,
      ].join(":");
      entries += 1;
      if (entries > 65_536) throw new Error("workspace registry contains too many entries");
      if (before.isDirectory()) {
        records.push(`directory:${relative}:${metadata}`);
        const children = await readdir(path);
        children.sort();
        for (const name of children) {
          await visit(join(path, name), relative === "." ? name : `${relative}/${name}`);
        }
      } else if (before.isFile()) {
        if (before.size > 256 * 1024 * 1024) throw new Error("workspace registry file is too large");
        totalBytes += before.size;
        if (totalBytes > 2 * 1024 * 1024 * 1024) throw new Error("workspace registry is too large");
        const contents = await readFile(path);
        records.push(`file:${relative}:${metadata}:${contents.length}:${digest(contents)}`);
      } else {
        throw new Error("workspace registry entry is invalid");
      }
      const after = lstatSync(path);
      if (before.dev !== after.dev || before.ino !== after.ino || before.mode !== after.mode
        || before.uid !== after.uid || before.gid !== after.gid || before.size !== after.size
        || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
        throw new Error("workspace registry changed during inspection");
      }
    };
    await visit(this.repository.root, ".");
    return digest(records.join("\n"));
  }

  private async readStoredSnapshotState(head: string): Promise<ActiveState> {
    return this.decodeSnapshotManifest(await this.readSnapshotManifest(safeCommit(head)));
  }

  async read(id: string): Promise<{ workspace: WorkspaceDescriptor; revision: WorkspaceRevision }> {
    const state = await this.activeState();
    const revision = state.revisions.find((candidate) => candidate.id === id);
    if (!revision) throw new WorkspaceRegistryError("workspace_invalid", "Workspace is unavailable");
    try {
      const source = await readFile(revision.snapshotPath, "utf8");
      return { workspace: parseWorkspaceYaml(source), revision };
    } catch (error) {
      throw workspaceError(error);
    }
  }

  /**
   * Resolve the active revision and create its cross-process retention lease under the same
   * repository lock. The lease bridges the interval before `session_manifest.yaml` is durable.
   */
  async acquireSessionRevision(id: string): Promise<SessionRevisionLease> {
    await this.repository.ensureLayout();
    return await this.lock.run(async () => {
      const state = await this.activeState();
      const revision = state.revisions.find((candidate) => candidate.id === id);
      if (!revision) throw new WorkspaceRegistryError("workspace_invalid", "Workspace is unavailable");
      let workspace: WorkspaceDescriptor;
      try {
        workspace = validateOperationalWorkspace(
          parseWorkspaceYaml(await readFile(revision.snapshotPath, "utf8")),
        );
      } catch (error) {
        throw workspaceError(error);
      }

      const token = randomUUID();
      const record: RevisionLeaseRecord = {
        version: 1,
        token,
        workspaceId: id,
        commit: revision.commit,
        state: "creating",
      };
      const path = await this.writeRevisionLease(record, true);
      let localState: RevisionLeaseRecord["state"] | "aborted" = "creating";

      return {
        workspace,
        revision,
        markPersisted: async () => {
          if (localState === "persisted") return;
          if (localState === "aborted") throw new WorkspaceRegistryError(
            "workspace_invalid", "Workspace revision lease is unavailable",
          );
          await this.lock.run(async () => {
            await this.replaceRevisionLease(path, { ...record, state: "persisted" });
          });
          localState = "persisted";
        },
        abort: async () => {
          if (localState !== "creating") return;
          await this.lock.run(async () => { await rm(path, { force: true }); });
          localState = "aborted";
        },
      };
    });
  }

  /** Read a retained immutable snapshot for a session pinned to a historical commit. */
  async readPinned(id: string, commit: string): Promise<{ workspace: WorkspaceDescriptor; workspaceConfigPath: string }> {
    const snapshotPath = this.snapshotPath(safeCommit(commit), id);
    try {
      const source = await readFile(snapshotPath, "utf8");
      return {
        workspace: validateOperationalWorkspace(parseWorkspaceYaml(source)),
        workspaceConfigPath: snapshotPath,
      };
    } catch (error) {
      throw workspaceError(error);
    }
  }

  /**
   * Garbage-collect obsolete immutable snapshots without breaking cold Resume.
   * Callers must supply revisions collected from an administrator-visible complete session list;
   * a partial, per-user list could otherwise remove another user's resumable workspace pin.
   */
  async reconcileSnapshotRetention(referencedCommits: readonly string[]): Promise<void> {
    const manifestReferences = new Set(referencedCommits.map(safeCommit));
    const retained = new Set(manifestReferences);
    await this.repository.ensureLayout();
    await this.lock.run(async () => {
      const leases = await this.revisionLeases();
      for (const { record } of leases) retained.add(record.commit);
      retained.add((await this.activeState()).head);
      const entries = await readdir(this.repository.snapshotsPath, { withFileTypes: true });
      for (const entry of entries) {
        // Leave staging and unexpected entries untouched: this cleanup only owns finalized,
        // commit-addressed snapshot directories.
        if (!entry.isDirectory() || entry.isSymbolicLink() || !/^[0-9a-f]{40}$/.test(entry.name)) continue;
        if (retained.has(entry.name)) continue;
        const path = join(this.repository.snapshotsPath, entry.name);
        const current = lstatSync(path);
        if (!current.isDirectory() || current.isSymbolicLink()) continue;
        await rm(path, { recursive: true, force: true });
      }
      // A persisted lease is handed off only when this exact authoritative scan has observed a
      // manifest pin for its commit. A stale scan therefore keeps the lease and cannot prune it.
      for (const { path, record } of leases) {
        if (record.state === "persisted" && manifestReferences.has(record.commit)) {
          await rm(path, { force: true });
        }
      }
    });
  }

  private revisionLeaseDirectory(): string {
    return join(this.repository.statePath, "revision-leases");
  }

  private async writeRevisionLease(record: RevisionLeaseRecord, exclusive: boolean): Promise<string> {
    const directory = this.revisionLeaseDirectory();
    await mkdir(directory, { recursive: true, mode: 0o700 });
    const path = join(directory, `${record.token}.json`);
    await writeFile(path, JSON.stringify(record), {
      encoding: "utf8",
      mode: 0o600,
      flush: true,
      ...(exclusive ? { flag: "wx" } : {}),
    });
    return path;
  }

  private async replaceRevisionLease(path: string, record: RevisionLeaseRecord): Promise<void> {
    const staging = `${path}.staging-${randomUUID()}`;
    try {
      await writeFile(staging, JSON.stringify(record), {
        encoding: "utf8", mode: 0o600, flag: "wx", flush: true,
      });
      await rename(staging, path);
    } catch (error) {
      await rm(staging, { force: true });
      throw error;
    }
  }

  private async revisionLeases(): Promise<Array<{ path: string; record: RevisionLeaseRecord }>> {
    const directory = this.revisionLeaseDirectory();
    await mkdir(directory, { recursive: true, mode: 0o700 });
    const entries = await readdir(directory, { withFileTypes: true });
    const leases: Array<{ path: string; record: RevisionLeaseRecord }> = [];
    for (const entry of entries) {
      if (!entry.isFile() || entry.isSymbolicLink() || !/^[0-9a-f-]{36}\.json$/.test(entry.name)) {
        throw new WorkspaceRegistryError("workspace_invalid", "Workspace revision lease is invalid");
      }
      const path = join(directory, entry.name);
      let record: RevisionLeaseRecord;
      try {
        record = JSON.parse(await readFile(path, "utf8")) as RevisionLeaseRecord;
      } catch {
        throw new WorkspaceRegistryError("workspace_invalid", "Workspace revision lease is invalid");
      }
      if (
        record.version !== 1
        || `${record.token}.json` !== entry.name
        || !/^[0-9a-f-]{36}$/.test(record.token)
        || !/^[a-z][a-z0-9-]{2,62}$/.test(record.workspaceId)
        || !/^[0-9a-f]{40}$/.test(record.commit)
        || (record.state !== "creating" && record.state !== "persisted")
      ) {
        throw new WorkspaceRegistryError("workspace_invalid", "Workspace revision lease is invalid");
      }
      leases.push({ path, record });
    }
    return leases;
  }

  private async assertEvidenceContext(workspace: WorkspaceDescriptor, revision: string): Promise<void> {
    if (workspace.evidence?.source.type !== "filesystem") return;
    // P6 owns recursive containment. Here we deliberately validate only the declared root object.
    await this.repository.assertTreeAtRevision(revision, workspace.evidence.source.uri);
  }

  private async assertSnapshotEvidenceContexts(state: ActiveState): Promise<void> {
    for (const revision of state.revisions) {
      const workspace = parseWorkspaceYaml(await readFile(revision.snapshotPath, "utf8"));
      await this.assertEvidenceContext(workspace, revision.commit);
    }
  }

  private async activate(commit: string): Promise<void> {
    const safeHead = safeCommit(commit);
    const catalog = parseWorkspaceCatalogYaml(await this.repository.readCatalog(safeHead));
    const catalogById = new Map(catalog.workspaces.map((entry) => [entry.id, entry]));
    for (const id of await this.repository.workspaceDirectories()) {
      if (!catalogById.has(id)) {
        throw new WorkspaceRegistryError("workspace_invalid", "Workspace directory is not listed in the catalog");
      }
    }
    const files = await this.repository.workspacePaths();
    const descriptorIds = new Set(files.map((path) => path.slice(0, -"/workspace.yaml".length)));
    for (const id of catalogById.keys()) {
      if (!descriptorIds.has(id)) {
        throw new WorkspaceRegistryError(
          "workspace_invalid",
          "Every catalog workspace must have a published descriptor",
        );
      }
    }

    const snapshots: Array<{
      id: string;
      source: string;
      workspace: WorkspaceDescriptor;
      blob: string;
    }> = [];
    const collectionOwners = new Map<string, string>();
    try {
      for (const path of files) {
        const id = path.slice(0, -"/workspace.yaml".length);
        const entry = catalogById.get(id);
        if (!entry) throw new WorkspaceRegistryError("workspace_invalid", "Workspace descriptor is not listed in the catalog");
        const source = await this.repository.readWorkspace(path, safeHead);
        const workspace = parseWorkspaceYaml(source);
        if (workspace.workspace.id !== id) {
          throw new WorkspaceRegistryError("workspace_invalid", "Workspace ID does not match its repository path");
        }
        assertCatalogMatchesDescriptor(entry, workspace);
        await this.assertEvidenceContext(workspace, safeHead);
        const annotations = await this.repository.annotationsObject(safeHead, id);
        if (annotations !== undefined) {
          parseAnnotationsYaml(annotations.contents.toString("utf8"));
          if (this.config.dataRoot !== undefined) {
            syncAnnotations({
              dataRoot: this.config.dataRoot,
              workspaceId: id,
              commit: safeHead,
              blobId: annotations.blobId,
              contents: annotations.contents,
            });
          }
        }
        const collection = workspace.semantic_index.vector_store.collection;
        const owner = collectionOwners.get(collection);
        if (owner !== undefined) {
          throw new Error(`duplicate qdrant collection ownership: ${collection} (${owner}, ${id})`);
        }
        collectionOwners.set(collection, id);
        buildInstallationContract(workspace);
        renderWorkspaceDocs(workspace);
        snapshots.push({
          id,
          source: serializeWorkspaceYaml(workspace),
          workspace,
          blob: await this.repository.blob(path, safeHead),
        });
      }
    } catch (error) {
      throw workspaceError(error);
    }

    const snapshotDirectory = join(this.repository.snapshotsPath, safeHead);
    const revisions = snapshots.map((snapshot) => ({
      id: snapshot.id,
      commit: safeHead,
      blob: snapshot.blob,
      snapshotPath: this.snapshotPath(safeHead, snapshot.id),
    }));
    if (this.pathExists(snapshotDirectory)) {
      await this.assertSnapshotIntegrity({ head: safeHead, revisions, catalog });
    } else {
      const staging = join(this.repository.snapshotsPath, `.staging-${randomUUID()}`);
      await mkdir(staging, { mode: 0o700 });
      try {
        const files: Record<string, string> = {};
        for (const snapshot of snapshots) {
          const yamlName = `${snapshot.id}.yaml`;
          const envName = `${snapshot.id}.env.example`;
          const docsName = `${snapshot.id}.md`;
          await writeFile(join(staging, yamlName), snapshot.source, { encoding: "utf8", mode: 0o400 });
          files[yamlName] = digest(snapshot.source);
          const docs = renderWorkspaceDocs(snapshot.workspace);
          await writeFile(join(staging, envName), docs.envExample, { encoding: "utf8", mode: 0o400 });
          await writeFile(join(staging, docsName), docs.markdown, { encoding: "utf8", mode: 0o400 });
          files[envName] = digest(docs.envExample);
          files[docsName] = digest(docs.markdown);
          if (snapshot.workspace.evidence?.source.type === "filesystem") {
            const materialized = await materializeEvidenceTree({
              repository: this.repository,
              revision: safeHead,
              id: snapshot.id,
              targetDirectory: join(staging, snapshot.id),
              limits: this.evidenceMaterializationLimits(),
            });
            files[`${snapshot.id}/evidence.manifest.json`] = materialized.manifestDigest;
          }
        }
        await writeFile(join(staging, "snapshot.json"), JSON.stringify({ head: safeHead, revisions, catalog, files }), {
          encoding: "utf8", mode: 0o400,
        });
        await rename(staging, snapshotDirectory);
      } catch (error) {
        await rm(staging, { recursive: true, force: true });
        throw error;
      }
    }

    await this.writeActiveState({ head: safeHead, revisions, catalog });
  }

  private async gitFallback(error: unknown): Promise<GitStatus> {
    const safeError = workspaceError(error);
    if (safeError.code !== "git_unavailable" && safeError.code !== "git_auth_failed") throw safeError;
    const active = await this.tryActiveState();
    if (!active) throw safeError;
    return {
      branch: this.config.branch,
      ...(this.config.remoteUrl
        ? { repository: normalizeRepositoryIdentity(this.config.remoteUrl) }
        : {}),
      head: active.head,
      ahead: 0,
      behind: 0,
      degraded: true,
      lastError: safeError.code,
    };
  }

  private async activeState(): Promise<ActiveState> {
    const active = await this.tryActiveState();
    if (!active) throw new WorkspaceRegistryError("workspace_invalid", "No active workspace snapshot is available");
    return active;
  }

  private async tryActiveState(): Promise<ActiveState | undefined> {
    const file = join(this.repository.statePath, "active.json");
    try {
      const state = this.decodeActiveState(JSON.parse(await readFile(file, "utf8")));
      await this.assertSnapshotIntegrity(state);
      return state;
    } catch (error) {
      if (this.pathIsMissing(file)) return undefined;
      if (error instanceof WorkspaceRegistryError) throw error;
      throw new WorkspaceRegistryError("workspace_invalid", "Workspace active snapshot is invalid");
    }
  }

  private async writeActiveState(state: ActiveState): Promise<void> {
    const target = join(this.repository.statePath, "active.json");
    const staging = join(this.repository.statePath, `.active-${randomUUID()}.json`);
    await writeFile(staging, JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
    await rename(staging, target);
  }

  private decodeActiveState(value: unknown): ActiveState {
    const record = this.optionalKeyObject(value, ["head", "revisions"], ["catalog"]);
    const state = this.decodeStateRevisions(record.head, record.revisions);
    return record.catalog === undefined ? state : { ...state, catalog: this.decodeCatalog(record.catalog) };
  }

  private decodeSnapshotManifest(value: unknown): SnapshotManifest {
    const manifest = this.optionalKeyObject(value, ["head", "revisions", "files"], ["catalog"]);
    const state = this.decodeStateRevisions(manifest.head, manifest.revisions);
    const catalog = manifest.catalog === undefined ? undefined : this.decodeCatalog(manifest.catalog);
    if (!manifest.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
      throw new Error("bad manifest files");
    }
    const entries = Object.entries(manifest.files as Record<string, unknown>);
    if (entries.some(([, contentsDigest]) => typeof contentsDigest !== "string")) {
      throw new Error("bad manifest files");
    }
    return { ...state, ...(catalog ? { catalog } : {}), files: Object.fromEntries(entries) as Record<string, string> };
  }

  private decodeStateRevisions(headValue: unknown, revisionsValue: unknown): ActiveState {
    if (typeof headValue !== "string" || !Array.isArray(revisionsValue)) throw new Error("bad state");
    const head = safeCommit(headValue);
    const ids = new Set<string>();
    const revisions = revisionsValue.map((value) => {
      const revision = this.decodeRevision(value, head);
      if (ids.has(revision.id)) throw new Error("duplicate revision");
      ids.add(revision.id);
      return revision;
    });
    return { head, revisions };
  }

  private decodeRevision(value: unknown, head: string): WorkspaceRevision {
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("bad revision");
    const revision = value as Record<string, unknown>;
    const keys = Object.keys(revision);
    const required = ["id", "commit", "blob", "snapshotPath"];
    const hasHistoricalState = Object.prototype.hasOwnProperty.call(revision, "state");
    if (
      keys.length !== required.length + (hasHistoricalState ? 1 : 0)
      || !required.every((key) => Object.prototype.hasOwnProperty.call(revision, key))
      || (hasHistoricalState && revision.state !== "operational")
    ) {
      throw new Error("bad revision");
    }
    if (
      typeof revision.id !== "string"
      || typeof revision.commit !== "string"
      || typeof revision.blob !== "string"
      || typeof revision.snapshotPath !== "string"
    ) {
      throw new Error("bad revision");
    }
    const id = revision.id;
    const commit = safeCommit(revision.commit);
    const blob = safeBlob(revision.blob);
    const snapshotPath = revision.snapshotPath;
    workspacePath(id);
    if (
      commit !== head
      || !isAbsolute(snapshotPath)
      || snapshotPath !== this.snapshotPath(commit, id)
    ) {
      throw new Error("bad revision");
    }
    // Always reconstruct a fresh public revision. The sole accepted historical state field is
    // compatibility input and must never cross the registry boundary.
    return { id, commit, blob, snapshotPath };
  }

  private decodeCatalog(value: unknown): WorkspaceCatalog {
    if (typeof value !== "object" || value === null) throw new Error("bad catalog");
    return parseWorkspaceCatalogYaml(JSON.stringify(value));
  }

  private optionalKeyObject(
    value: unknown,
    requiredKeys: readonly string[],
    optionalKeys: readonly string[],
  ): Record<string, unknown> {
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("bad state");
    const record = value as Record<string, unknown>;
    const allowed = new Set([...requiredKeys, ...optionalKeys]);
    const keys = Object.keys(record);
    if (
      keys.length !== requiredKeys.length + optionalKeys.length
      || !requiredKeys.every((key) => Object.prototype.hasOwnProperty.call(record, key))
      || !keys.every((key) => allowed.has(key))
    ) {
      throw new Error("bad state");
    }
    return record;
  }

  private strictObject(value: unknown, expectedKeys: readonly string[]): Record<string, unknown> {
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("bad state");
    const record = value as Record<string, unknown>;
    const keys = Object.keys(record);
    if (
      keys.length !== expectedKeys.length
      || !expectedKeys.every((key) => Object.prototype.hasOwnProperty.call(record, key))
    ) {
      throw new Error("bad state");
    }
    return record;
  }

  private async readSnapshotManifest(head: string): Promise<unknown> {
    const path = join(this.repository.snapshotsPath, head, "snapshot.json");
    return JSON.parse(await readFile(path, "utf8"));
  }

  private async snapshotState(head: string): Promise<ActiveState> {
    const state = this.decodeSnapshotManifest(await this.readSnapshotManifest(safeCommit(head)));
    await this.assertSnapshotIntegrity(state);
    return state;
  }

  private async assertSnapshotIntegrity(
    state: ActiveState,
    verifyGitEvidence = true,
    exactStoredShape = false,
  ): Promise<void> {
    const directory = join(this.repository.snapshotsPath, state.head);
    try {
      const manifest = this.decodeSnapshotManifest(await this.readSnapshotManifest(state.head));
      if (manifest.head !== state.head || !this.sameRevisions(manifest.revisions, state.revisions)
        || JSON.stringify(manifest.catalog ?? null) !== JSON.stringify(state.catalog ?? null)) {
        throw new Error("manifest state does not match active state");
      }
      await this.assertManifestFiles(directory, manifest.files, this.expectedSnapshotFiles(state, directory));
      if (exactStoredShape) this.assertStoredSnapshotShape(directory, state);
      if (verifyGitEvidence) await this.assertSnapshotEvidenceContexts(state);
    } catch (error) {
      if (error instanceof WorkspaceRegistryError) throw error;
      throw new WorkspaceRegistryError("workspace_invalid", "Workspace snapshot integrity check failed");
    }
  }

  private assertStoredSnapshotShape(directory: string, state: ActiveState): void {
    const expected: Record<string, "file" | "directory"> = { "snapshot.json": "file" };
    for (const revision of state.revisions) {
      expected[`${revision.id}.yaml`] = "file";
      expected[`${revision.id}.env.example`] = "file";
      expected[`${revision.id}.md`] = "file";
      const workspace = parseWorkspaceYaml(readFileSync(join(directory, `${revision.id}.yaml`), "utf8"));
      if (workspace.evidence?.source.type === "filesystem") expected[revision.id] = "directory";
    }
    this.assertExactDirectoryEntries(readdirSync(directory, { withFileTypes: true }), expected);
    for (const revision of state.revisions) {
      if (expected[revision.id] !== "directory") continue;
      this.assertExactDirectoryEntries(
        readdirSync(join(directory, revision.id), { withFileTypes: true }),
        { evidence: "directory", "evidence.manifest.json": "file" },
      );
    }
  }

  private expectedSnapshotFiles(state: ActiveState, directory: string): string[] {
    return state.revisions.flatMap((revision) => {
      const names = [`${revision.id}.yaml`, `${revision.id}.env.example`, `${revision.id}.md`];
      const workspace = parseWorkspaceYaml(readFileSync(join(directory, `${revision.id}.yaml`), "utf8"));
      if (workspace.evidence?.source.type === "filesystem") {
        names.push(`${revision.id}/evidence.manifest.json`);
      }
      return names;
    });
  }

  private evidenceMaterializationLimits(): Partial<{
    maxEntries: number;
    maxTotalBytes: number;
    maxFileBytes: number;
    maxPathBytes: number;
    maxManifestBytes: number;
  }> {
    return {
      ...(this.config.maxEvidenceEntries === undefined ? {} : { maxEntries: this.config.maxEvidenceEntries }),
      ...(this.config.maxEvidenceBytes === undefined ? {} : { maxTotalBytes: this.config.maxEvidenceBytes }),
      ...(this.config.maxEvidenceFileBytes === undefined ? {} : { maxFileBytes: this.config.maxEvidenceFileBytes }),
      ...(this.config.maxEvidencePathBytes === undefined ? {} : { maxPathBytes: this.config.maxEvidencePathBytes }),
      ...(this.config.maxEvidenceManifestBytes === undefined ? {} : { maxManifestBytes: this.config.maxEvidenceManifestBytes }),
    };
  }

  private async assertManifestFiles(
    directory: string,
    files: Record<string, string>,
    expected: string[],
  ): Promise<void> {
    if (!files || typeof files !== "object" || Object.keys(files).length !== expected.length || !expected.every((name) => (
      /^[0-9a-f]{64}$/.test(files[name] ?? "")
    ))) throw new Error("manifest files are invalid");
    for (const name of expected) {
      const path = join(directory, name);
      const entry = lstatSync(path);
      if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("snapshot file is invalid");
      const contents = await readFile(path);
      if (digest(contents) !== files[name]) throw new Error("snapshot file does not match manifest");
      if (name.endsWith(".yaml")) {
        const workspace = parseWorkspaceYaml(contents.toString("utf8"));
        if (workspace.workspace.id !== name.slice(0, -".yaml".length)) {
          throw new Error("snapshot workspace is invalid");
        }
      }
    }
  }

  private sameRevisions(left: WorkspaceRevision[], right: WorkspaceRevision[]): boolean {
    return left.length === right.length && left.every((revision, index) => {
      const candidate = right[index];
      return candidate !== undefined
        && candidate.id === revision.id && candidate.commit === revision.commit
        && candidate.blob === revision.blob && candidate.snapshotPath === revision.snapshotPath;
    });
  }

  private pathExists(path: string): boolean {
    try {
      const entry = lstatSync(path);
      if (!entry.isDirectory() || entry.isSymbolicLink()) {
        throw new WorkspaceRegistryError("workspace_invalid", "Workspace snapshot path is invalid");
      }
      return true;
    } catch (error) {
      if (error instanceof WorkspaceRegistryError) throw error;
      return false;
    }
  }

  private pathIsMissing(path: string): boolean {
    try {
      lstatSync(path);
      return false;
    } catch {
      return true;
    }
  }
}