Make workspace authoring converge through immutable Nix candidates

Coordinate registered resource edits bottom-up into retained exact remote sources.
Use one Nix-owned source graph for provisional checking, template publication,
explicit baseline upgrades and host activation; retain independent runtime pins.

Add scoped contract inspection, historical recovery, derived worklists, crash-safe
locks, named dependency adoption and plain-QX structural editing. Repair TODO
ownership and template instantiation, and document the supported agent workflow.

Validated with protocol and command suites, real jj/Nix convergence and cache
checks, TS/React installed-command acceptance, and fresh TODO first-edit acceptance.
No live deployment or public publication performed. Props projection generation
and a one-command rich feature generator remain explicitly outside this delivery.

src/capability-language/assembly.ts

@@ -361,7 +361,7 @@ export const compileWorkspaceRepository = async (options: {
       : {}),
     ...(options.workspaceRevisionId
       ? { id: capabilityId.workspaceRevision(options.workspaceRevisionId) }
-      : {}),
+      : options.sourceRootCommit ? { id: capabilityId.workspaceRevision(`workspace-revision:${options.workspaceId ?? compiled.workspace.workspaceId}:${options.sourceRootCommit}`) } : {}),
     ...(options.sourceRootCommit
       ? { sourceRootCommit: options.sourceRootCommit }
       : {}),

src/capability-language/authoring-check.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { authoringContext } from "./authoring-context.js";
+import type { convergeAuthoring } from "./authoring-converge.js";
+import { execFile as callback } from "node:child_process";
+import { promisify } from "node:util";
+import { buildImmutableCandidate, checkerIdentity } from "./checked-build.js";
+import { planEvolution, type WorkspaceRevision, type EvolutionReview } from "../capability-model/index.js";
+
+export const checkRecordName = (directory: string) => createHash("sha256").update(directory).digest("hex") + ".json";
+export async function checkAuthoring(start: string, output: string, options: { baseline?: string; reviews?: string; contractOnly?: boolean } = {}) {
+  const context = await authoringContext(start);
+  const location = await fs.realpath(start);
+  const directory = location === context.workbench ? "root" : path.relative(context.workbench, location);
+  const resource = context.resources.find(entry => entry.directory === directory);
+  if (!resource) throw new Error("Run check from a registered repository root or the workbench");
+  await fs.mkdir(output, { mode: 0o700 });
+  const report: { directory: string; checker: string; candidateOnly: true; activationEvidence: false; commit?: string; artifactPath?: string; blockers: string[]; phase: string; output: string } = {
+    directory, checker: checkerIdentity(), candidateOnly: true, activationEvidence: false, blockers: [], phase: "convergence", output,
+  };
+  try {
+    // Serialize only source capture, not the potentially slow Nix build.
+    // Repository-scoped agents can check separate immutable candidates in parallel.
+    const captured = await promisify(callback)("quixos-qx", ["converge", context.workbench, directory], {
+      maxBuffer: 4 * 1024 * 1024, env: {...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1"},
+    }).catch(error => {
+      if (typeof error.stdout === "string" && error.stdout.trim().startsWith("{")) return {stdout: error.stdout};
+      throw error;
+    });
+    const converged = JSON.parse(captured.stdout) as Awaited<ReturnType<typeof convergeAuthoring>>;
+    if (!converged.candidate) {
+      report.phase = converged.worklist.find(entry => entry.phase !== "dependency")?.phase ?? "convergence";
+      throw new Error(converged.worklist.map(entry => `${entry.directory} [${entry.phase}]: ${entry.message}`).join("\n"));
+    }
+    report.commit = converged.candidate.commit;
+    report.phase = "verification";
+    report.artifactPath = await buildImmutableCandidate(converged.candidate, resource.kind, path.join(output, "nix.log"), options.contractOnly);
+    const candidateText = await fs.readFile(path.join(report.artifactPath, "candidate.json"), "utf8");
+    await fs.writeFile(path.join(output, "candidate.json"), candidateText);
+    if (resource.kind === "workspace" && !options.contractOnly) {
+      report.phase = "evolution";
+      let baseline = options.baseline;
+      if (!baseline) {
+        try {
+          const host = JSON.parse(await fs.readFile("/etc/quixos/workspace-source.json", "utf8"));
+          if (await fs.realpath(host.workbenchRoot) === context.workbench) baseline = JSON.parse(await fs.readFile(path.join(host.runtimeClosureRoot, "manifest.json"), "utf8")).workspacePlanPath;
+        } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      }
+      const before = baseline ? JSON.parse(await fs.readFile(baseline, "utf8")) as WorkspaceRevision : null;
+      const reviews = options.reviews ? JSON.parse(await fs.readFile(options.reviews, "utf8")) as EvolutionReview[] : [];
+      const evolution = planEvolution(before, JSON.parse(candidateText), { reviews });
+      await fs.writeFile(path.join(output, "evolution.json"), JSON.stringify(evolution, null, 2));
+      report.blockers.push(...evolution.blockers);
+    }
+    if (!report.blockers.length) report.phase = options.contractOnly ? "contract-only" : "checked";
+  } catch (error) { report.blockers.push(String(error instanceof Error ? error.message : error)); }
+  await fs.writeFile(path.join(output, "report.json"), JSON.stringify(report, null, 2));
+  if (options.contractOnly) return report;
+  const records = path.join(context.workbench, ".quixos/checks");
+  await fs.mkdir(records, { recursive: true });
+  const remember = async (value: typeof report) => {
+    const filename = path.join(records, checkRecordName(value.directory)), temporary = `${filename}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, JSON.stringify(value, null, 2), { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, filename);
+  };
+  if (report.artifactPath) {
+    const graph = JSON.parse(await fs.readFile(path.join(report.artifactPath, "graph.json"), "utf8"));
+    for (const checked of graph.resources) {
+      const managed = context.resources.find(entry => entry.kind === checked.kind && entry.source?.repository === checked.source.repository);
+      if (managed && managed.directory !== directory) await remember({...report, directory: managed.directory, commit: checked.source.commit, blockers: [], phase: "checked"});
+    }
+  }
+  await remember(report);
+  return report;
+}

src/capability-language/authoring-context.ts

@@ -0,0 +1,49 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { loadQuixosLock, type GitSource } from "../resource-lock/index.js";
+
+export type AuthoringResource = {
+  kind: "workspace" | "interface" | "package";
+  directory: string;
+  resourceId?: string;
+  source?: GitSource;
+};
+
+/** Registration, not directory co-location, defines the editable selection. */
+export async function authoringContext(start: string) {
+  let workbench = await realpath(start);
+  for (;;) {
+    let text: string | undefined;
+    try { text = await readFile(path.join(workbench, ".quixos/resource-graph.json"), "utf8"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (text !== undefined) {
+      const graph = JSON.parse(text) as { resources: AuthoringResource[] };
+      if (!Array.isArray(graph.resources)) throw new Error("Managed resource inventory is malformed");
+      const resources: AuthoringResource[] = [{ kind: "workspace", directory: "root" }];
+      const identities = new Set<string>(), directories = new Set<string>(["root"]);
+      for (const entry of graph.resources) {
+        // Compiler graphs carry resolved paths; the authoring API presents
+        // stable workbench-relative names and validates containment here.
+        if (typeof entry.directory === "string" && path.isAbsolute(entry.directory)) entry.directory = path.relative(workbench, entry.directory);
+        if (!["interface", "package"].includes(entry.kind) || !entry.source ||
+            !/^resources\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(entry.directory)) {
+          throw new Error("Invalid managed resource registration");
+        }
+        const identity = `${entry.kind}\0${entry.resourceId ?? entry.source.repository}`;
+        if (identities.has(identity) || directories.has(entry.directory)) {
+          throw new Error(`Multiple editable selections for ${entry.resourceId ?? entry.source.repository}`);
+        }
+        identities.add(identity); directories.add(entry.directory);
+        resources.push({kind: entry.kind, directory: entry.directory, resourceId: entry.resourceId, source: entry.source});
+      }
+      return { workbench, resources, async baseline() {
+        const result = await loadQuixosLock(path.join(workbench, "root/quixos.lock"));
+        if (!result.ok) throw new Error(`Workspace source baseline is invalid: ${result.diagnostics.map(d => d.message).join("; ")}`);
+        return result.lock.quixos;
+      } };
+    }
+    const parent = path.dirname(workbench);
+    if (parent === workbench) throw new Error("Not in a managed workbench; select one with --workbench DIRECTORY");
+    workbench = parent;
+  }
+}

src/capability-language/authoring-converge.ts

@@ -0,0 +1,166 @@
+import { readFile, writeFile, rename, rm, realpath } from "node:fs/promises";
+import path from "node:path";
+import { execFile as callback } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { authoringContext } from "./authoring-context.js";
+import { snapshotCommit } from "./checked-build.js";
+import { loadQuixosLock, parseQuixosLockDocument, formatQuixosLockDocument, retentionTagForCommit, type GitSource } from "../resource-lock/index.js";
+
+const execFile = promisify(callback);
+const command = async (cwd: string, executable: string, args: string[]) => (await execFile(executable, args, {
+  cwd, maxBuffer: 4 * 1024 * 1024,
+  env: { ...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1", QUIXOS_SUBTREE_PUBLISH: "0", GIT_TERMINAL_PROMPT: "0" },
+})).stdout.trim();
+const identity = (kind: string, repository: string) => `${kind}\0${repository}`;
+
+export type AuthoringBlocker = { directory: string; phase: "resolution" | "dependency" | "source" | "publication" | "concurrent-edit"; message: string };
+
+/** Source retention only. Neither successful convergence nor an empty source
+ * worklist grants typechecking, semantic review or activation approval.
+ * Caller serializes coordinators; package authors may still be editing. */
+export async function convergeAuthoring(start: string, target = "root") {
+  const context = await authoringContext(start);
+  const graphFile = path.join(context.workbench, ".quixos/resource-graph.json");
+  const graphBefore = await readFile(graphFile, "utf8");
+  const blockers: AuthoringBlocker[] = [];
+  const nodes = new Map<string, { directory: string; kind: string; source: GitSource; dependencies: string[] }>();
+  const selected = new Map<string, string>();
+  for (const entry of context.resources) {
+    const root = path.join(context.workbench, entry.directory);
+    let repository = entry.source?.repository;
+    try {
+      if (await realpath(root) !== root) throw new Error(`Managed checkout crosses a symlink: ${entry.directory}`);
+      // Transport rewrites must not become committed source identities.
+      const origin = await command(root, "git", ["config", "--get", "remote.origin.url"]);
+      if (repository && origin !== repository) throw new Error(`Origin differs from registered source for ${entry.directory}`);
+      repository ??= origin;
+    } catch (error) {
+      blockers.push({directory: entry.directory, phase: "source", message: String(error).slice(0, 2000)});
+      if (!repository) throw error; // The root has no separate registered source.
+    }
+    const key = identity(entry.kind, repository);
+    if (selected.has(key)) throw new Error(`More than one editable checkout for ${repository}`);
+    selected.set(key, entry.directory);
+    nodes.set(entry.directory, { ...entry, source: { resolver: "git", repository, commit: entry.source?.commit ?? "" }, dependencies: [] });
+  }
+  for (const node of nodes.values()) {
+    try {
+      const lock = await loadQuixosLock(path.join(context.workbench, node.directory, "quixos.lock"));
+      if (!lock.ok) throw new Error(lock.diagnostics.map(d => `${d.fileName}: ${d.message}`).join("\n"));
+      node.dependencies = [...new Set(lock.lock.resources.flatMap(entry => {
+        const directory = selected.get(identity(entry.kind, entry.source.repository));
+        return directory ? [directory] : [];
+      }))];
+    } catch (error) { blockers.push({ directory: node.directory, phase: "resolution", message: String(error) }); }
+  }
+  const complete = new Map<string, GitSource>(), active = new Set<string>();
+  const visited = new Set<string>();
+  if (!nodes.has(target)) throw new Error(`Not a registered repository: ${target}`);
+  const visit = async (directory: string): Promise<boolean> => {
+    visited.add(directory);
+    if (complete.has(directory)) return true;
+    if (blockers.some(entry => entry.directory === directory)) return false;
+    if (active.has(directory)) { blockers.push({ directory, phase: "dependency", message: `Source dependency cycle: ${[...active, directory].join(" -> ")}` }); return false; }
+    active.add(directory);
+    const node = nodes.get(directory)!;
+    for (const dependency of node.dependencies) if (!await visit(dependency)) {
+      blockers.push({ directory, phase: "dependency", message: `Waiting for ${dependency}` }); active.delete(directory); return false;
+    }
+    const root = path.join(context.workbench, directory);
+    let phase: AuthoringBlocker["phase"] = "source";
+    try {
+      const lock = await loadQuixosLock(path.join(root, "quixos.lock"));
+      if (!lock.ok) throw new Error("Lock changed during convergence; retry after joining writers");
+      for (const file of lock.lock.sourceFiles ?? ["quixos.lock"]) {
+        const filename = path.join(root, file), before = await readFile(filename, "utf8");
+        const parsed = parseQuixosLockDocument(before, file);
+        if (!parsed.ok) throw new Error(`Invalid lock ${file}`);
+        let changed = false;
+        for (const dependency of parsed.document.resources) {
+          const target = selected.get(identity(dependency.kind, dependency.source.repository));
+          const source = target ? complete.get(target) : undefined;
+          if (target && !source) throw new Error(`Dependencies changed during convergence (${dependency.binding}); join writers and retry`);
+          if (source && source.commit !== dependency.source.commit) { dependency.source = source; changed = true; }
+        }
+        if (changed) {
+          const temporary = `${filename}.${randomUUID()}.tmp`;
+          try {
+            await writeFile(temporary, formatQuixosLockDocument(parsed.document), { flag: "wx" });
+            if (await readFile(filename, "utf8") !== before) throw new Error(`Concurrent edit to ${file}; retry after joining writers`);
+            await rename(temporary, filename);
+          } finally { await rm(temporary, { force: true }); }
+        }
+      }
+      const commit = await snapshotCommit(root);
+      phase = "publication";
+      const ref = retentionTagForCommit(commit);
+      const remote = await command(root, "git", ["ls-remote", "--refs", node.source.repository, ref]);
+      if (remote && remote.split(/\s+/)[0] !== commit) throw new Error(`Conflicting immutable retention ref ${ref}`);
+      if (!remote) await command(root, "git", ["push", node.source.repository, `${commit}:${ref}`]);
+      if ((await command(root, "git", ["ls-remote", "--refs", node.source.repository, ref])).split(/\s+/)[0] !== commit) throw new Error("Published source retention was not observed");
+      complete.set(directory, { ...node.source, commit });
+    } catch (error) { blockers.push({ directory, phase, message: String(error).slice(0, 4000) }); }
+    active.delete(directory);
+    return complete.has(directory);
+  };
+  // Include newly created, not-yet-imported resources, then the root.
+  if (target === "root") for (const directory of [...nodes.keys()].filter(d => d !== "root")) await visit(directory);
+  await visit(target);
+  for (let index = blockers.length - 1; index >= 0; index--) if (!visited.has(blockers[index].directory)) blockers.splice(index, 1);
+  for (const [directory, source] of complete) {
+    try { if (await snapshotCommit(path.join(context.workbench, directory)) !== source.commit) throw new Error("Source advanced while converging; join writers and retry"); }
+    catch (error) { blockers.push({ directory, phase: "concurrent-edit", message: String(error) }); }
+  }
+  // Persist successful selections even if another repository is still broken.
+  // Recovery must not depend on all parents succeeding in the same invocation.
+  const graph = JSON.parse(graphBefore);
+  for (const resource of graph.resources) resource.directory = path.relative(context.workbench, path.resolve(context.workbench, resource.directory));
+  const replacements = new Map<string, string>();
+  for (const resource of graph.resources) {
+    const source = complete.get(resource.directory);
+    if (!source) continue;
+    const key = `${resource.kind}\0${source.repository}\0${source.commit}`;
+    replacements.set(resource.key, key);
+    if (resource.source.commit !== source.commit) delete resource.revisionId;
+    resource.source = source; resource.key = key;
+  }
+  for (const resource of graph.resources) for (const dependency of resource.dependencies ?? []) {
+    dependency.resourceKey = replacements.get(dependency.resourceKey) ?? dependency.resourceKey;
+  }
+  for (const direct of graph.directResources ?? []) direct.resourceKey = replacements.get(direct.resourceKey) ?? direct.resourceKey;
+  // Inventory is a projection of actual locks, including newly added/removed
+  // imports. Never require a successful parent compilation to repair it.
+  for (const [directory] of complete) {
+    const lock = await loadQuixosLock(path.join(context.workbench, directory, "quixos.lock"));
+    if (!lock.ok) continue;
+    const dependencies = lock.lock.resources.map(dependency => ({
+      binding: `${dependency.kind}\0${dependency.binding}`,
+      resourceKey: `${dependency.kind}\0${dependency.source.repository}\0${dependency.source.commit}`,
+    }));
+    if (directory === "root") {
+      graph.quixos = lock.lock.quixos;
+      graph.directResources = lock.lock.resources.map((dependency, index) => ({
+        kind: dependency.kind, binding: dependency.binding, resourceKey: dependencies[index].resourceKey,
+        ...(selected.has(identity(dependency.kind, dependency.source.repository))
+          ? {directory: selected.get(identity(dependency.kind, dependency.source.repository))} : {}),
+      }));
+    } else {
+      const resource = graph.resources.find((entry: {directory: string}) => entry.directory === directory);
+      if (resource) resource.dependencies = dependencies;
+    }
+  }
+  const graphAfter = JSON.stringify(graph, null, 2) + "\n";
+  if (graphBefore !== graphAfter) {
+    const temporary = `${graphFile}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, graphAfter, { flag: "wx", mode: 0o600 });
+      if (await readFile(graphFile, "utf8") !== graphBefore) throw new Error("Managed inventory changed during convergence; source is retained, retry after joining writers");
+      await rename(temporary, graphFile);
+    } finally { await rm(temporary, { force: true }); }
+  }
+  return { workbench: context.workbench, converged: blockers.length === 0,
+    candidate: blockers.length ? null : complete.get(target) ?? null,
+    retained: [...complete].map(([directory, source]) => ({ directory, source })),
+    worklist: blockers, verificationEvidence: false, activated: false };
+}

src/capability-language/authoring-inspect.ts

@@ -0,0 +1,73 @@
+import { execFile as callback } from "node:child_process";
+import { promisify } from "node:util";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { parseQx, walkSyntax } from "./source.js";
+import { authoringContext } from "./authoring-context.js";
+import { readQxSource } from "./source-loader.js";
+
+const execFile = promisify(callback);
+const git = async (root: string, args: string[]) => (await execFile("git", ["-C", root, ...args], {
+  maxBuffer: 8 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+})).stdout;
+const message = (error: unknown) => String(error instanceof Error ? error.message : error).slice(0, 2000);
+
+/** Syntax-only contract inspection is deliberately NOT verification evidence.
+ * Each file can recover independently; current valid files always win. */
+export async function inspectAuthoringRepository(root: string, historyLimit = 100) {
+  const names = (await git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]))
+    .split("\0").filter(name => name.endsWith(".qx"));
+  if (names.length > 128) throw new Error("Repository inspection exceeds 128 QX files; split the resource into smaller repositories");
+  const files = [];
+  for (const name of [...new Set(names)].sort()) {
+    let source = "", errors: unknown[] = [], revision: string | null = null;
+    try {
+      source = await readQxSource(root, name);
+      if (source.length > 262144) throw new Error(`Inspection file exceeds 256 KiB: ${name}`);
+      errors = parseQx(source, name).diagnostics;
+    } catch (error) { errors = [{ message: message(error) }]; }
+    const currentErrors = errors;
+    if (errors.length) {
+      // Git can traverse jj's immutable commit DAG without mutating/snapshotting @.
+      const head = await execFile("jj", ["--ignore-working-copy", "log", "--no-graph", "-r", "@", "-T", "commit_id"],
+        { cwd: root, env: { ...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1" } }).then(r => r.stdout.trim(), () => "HEAD");
+      const commits = await git(root, ["rev-list", `--max-count=${historyLimit}`, head, "--", name]).catch(() => "");
+      for (const commit of commits.trim().split("\n").filter(Boolean)) {
+        const historical = await git(root, ["show", `${commit}:${name}`]).catch(() => null);
+        if (historical === null || historical.length > 262144) continue;
+        if (!parseQx(historical, name).diagnostics.length) {
+          source = historical; revision = commit; errors = []; break;
+        }
+      }
+    }
+    const syntax = errors.length ? null : parseQx(source, name);
+    files.push({ file: name, status: errors.length ? "unavailable" : revision ? "historical" : "current",
+      revision, currentErrors: currentErrors.slice(0, 20), omittedErrors: Math.max(0, currentErrors.length - 20),
+      declarations: syntax ? [...walkSyntax(syntax.root)]
+        .filter(node => /^(?:interface|package|atom|state|edge|method|function|event|conformance)\w*Decl$/.test(node.kind))
+        .map(node => ({ kind: node.kind, source: source.slice(node.start, node.end) })) : [],
+    });
+  }
+  return { verificationEvidence: false as const, resolutionChecked: false as const, files };
+}
+
+export async function inspectWorkbench(start: string, selector?: string) {
+  const context = await authoringContext(start);
+  if (!selector) {
+    const relative = path.relative(context.workbench, await realpath(start));
+    selector = context.resources.find(entry => relative === entry.directory || relative.startsWith(entry.directory + path.sep))?.directory ?? "root";
+  }
+  const selected = context.resources.filter(entry => !selector || selector === entry.directory ||
+    selector === entry.resourceId || selector === path.basename(entry.directory));
+  if (!selected.length) throw new Error(`No registered resource matches ${selector}`);
+  if (selector && selected.length > 1) throw new Error(`Ambiguous resource ${selector}; use its resource ID or directory`);
+  const resources = [];
+  for (const entry of selected) {
+    try {
+      const root = path.join(context.workbench, entry.directory);
+      if (await realpath(root) !== root) throw new Error("Managed checkout crosses a symlink");
+      resources.push({ ...entry, ...await inspectAuthoringRepository(root) });
+    } catch (error) { resources.push({ ...entry, error: message(error) }); }
+  }
+  return { workbench: context.workbench, verificationEvidence: false, resources };
+}

src/capability-language/authoring-worklist.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile as callback } from "node:child_process";
+import { promisify } from "node:util";
+import { authoringContext } from "./authoring-context.js";
+import { inspectAuthoringRepository } from "./authoring-inspect.js";
+import { checkRecordName } from "./authoring-check.js";
+import { loadQuixosLock } from "../resource-lock/index.js";
+import { checkerIdentity } from "./checked-build.js";
+
+const execFile = promisify(callback);
+export async function authoringWorklist(start: string) {
+  const context = await authoringContext(start);
+  const entries: {directory: string; resourceId?: string; phase: string; message: string; next: string}[] = [];
+  const dependencies = new Map<string, string[]>();
+  for (const resource of context.resources) {
+    const root = path.join(context.workbench, resource.directory);
+    const add = (phase: string, message: string) => entries.push({directory: resource.directory, resourceId: resource.resourceId, phase, message,
+      next: phase === "syntax" ? `qx-workspace inspect ${resource.directory}` : `cd ${resource.directory} && qx-workspace check`});
+    try {
+      if (await fs.realpath(root) !== root) throw new Error("Registered checkout crosses a symlink");
+      const inspected = await inspectAuthoringRepository(root);
+      for (const file of inspected.files) if (file.currentErrors.length) add("syntax", `${file.file}: ${JSON.stringify(file.currentErrors)}${file.status === "historical" ? `; historical contract available at ${file.revision}` : ""}`);
+      const lock = await loadQuixosLock(path.join(root, "quixos.lock"));
+      if (!lock.ok) add("resolution", lock.diagnostics.map(entry => `${entry.fileName}: ${entry.message}`).join("\n"));
+      else dependencies.set(resource.directory, lock.lock.resources.flatMap(dependency => {
+        const selected = context.resources.find(entry => entry.kind === dependency.kind && entry.source?.repository === dependency.source.repository);
+        if (selected?.source && selected.source.commit !== dependency.source.commit) add("propagation", `Dependency ${dependency.binding} has advanced; check will repin it automatically`);
+        return selected ? [selected.directory] : [];
+      }));
+      let record;
+      try { record = JSON.parse(await fs.readFile(path.join(context.workbench, ".quixos/checks", checkRecordName(resource.directory)), "utf8")); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      if (!record?.commit) {
+        if (record?.blockers?.length) add(record.phase, record.blockers.join("\n"));
+        else add("unchecked", "No immutable candidate check recorded yet");
+        continue;
+      }
+      if (record.checker !== checkerIdentity()) add("unchecked", "The installed checker changed since the last check");
+      const env = {...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1"};
+      const commit = (await execFile("jj", ["--ignore-working-copy", "log", "--no-graph", "-r", "@", "-T", "commit_id"], {cwd: root, env})).stdout.trim();
+      const dirty = await execFile("git", ["diff", "--quiet", "--no-ext-diff", record.commit, "--"], {cwd: root}).then(() => false, () => true);
+      const untracked = (await execFile("git", ["ls-files", "--others", "--exclude-standard"], {cwd: root})).stdout;
+      if (commit !== record.commit || dirty || untracked) add("unchecked", `Edits are newer than the last check (${record.commit.slice(0, 12)})`);
+      else if (record.blockers?.length) add(record.phase, record.blockers.join("\n"));
+    } catch (error) { add("inspection", String(error).slice(0, 3000)); }
+  }
+  // Fixed-point propagation, independent of registration order.
+  const blocked = new Set(entries.map(entry => entry.directory));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [directory, required] of dependencies) if (!blocked.has(directory)) {
+      const waiting = required.filter(dependency => blocked.has(dependency));
+      if (waiting.length) { blocked.add(directory); changed = true; entries.push({directory, phase: "dependency", message: `Waiting for ${waiting.join(", ")}`, next: "Resolve the named repositories, then rerun check"}); }
+    }
+  }
+  return { workbench: context.workbench, verificationEvidence: false, worklist: entries,
+    note: "Derived authoring guidance, not activation approval. Independent repositories can be delegated separately; join writers before a root check." };
+}

src/capability-language/checked-build.ts

@@ -1,10 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import {execFile as callback, spawn} from "node:child_process";
+import { createWriteStream } from "node:fs";
 import {promisify} from "node:util";
 import {fileURLToPath} from "node:url";
 const execFile = promisify(callback);
 const environment = () => ({...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1", GIT_TERMINAL_PROMPT: "0"});
+export const checkerIdentity = () => process.env.QUIXOS_CHECK_GENERATOR ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
 /** Checking snapshots jj, but never publishes or activates the working copy. */
 export async function snapshotCommit(root: string): Promise<string> {
@@ -60,3 +62,34 @@ export async function buildCheckedPackage(source: string, schema: string, packag
     });
   });
 }
+
+/** Exact remote source DAG; the Nix checker owns schema construction and all
+ * nested fetches. Keep build noise in a named log, with a bounded failure tail. */
+export async function buildImmutableCandidate(source: { repository: string; commit: string }, kind: "workspace" | "interface" | "package", logFile: string, contractOnly = false): Promise<string> {
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(source.commit)) throw new Error("An immutable candidate requires an exact commit");
+  const url = new URL(source.repository);
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("Candidate origin must be credential-free HTTPS");
+  const generator = process.env.QUIXOS_CHECK_GENERATOR ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  if (!/^\/nix\/store\/[^/]+$/.test(generator)) throw new Error("Use the installed Quixos checker");
+  const builder = path.join(generator, "share/checked-candidate.nix");
+  await fs.access(builder);
+  const log = createWriteStream(logFile, { flags: "wx", mode: 0o600 });
+  await new Promise<void>((resolve, reject) => { log.once("open", () => resolve()); log.once("error", reject); });
+  return await new Promise((resolve, reject) => {
+    let output = "", tail = "", failure: Error | undefined;
+    const child = spawn("nix", ["build", "--impure", "--file", builder,
+      "--argstr", "repository", source.repository, "--argstr", "commit", source.commit,
+      "--argstr", "kind", kind, "--argstr", "generator", generator,
+      "--arg", "contractOnly", contractOnly ? "true" : "false",
+      "--no-link", "--print-out-paths", "-L"], { env: environment(), stdio: ["ignore", "pipe", "pipe"] });
+    log.on("error", error => { failure = error; child.kill(); });
+    child.stdout.on("data", chunk => { output += chunk; });
+    child.stderr.on("data", chunk => { log.write(chunk); tail = (tail + String(chunk)).slice(-6000); });
+    child.on("error", error => { failure = error; });
+    child.on("close", code => log.end(() => {
+      if (failure) reject(failure);
+      else if (code !== 0 || !/^\/nix\/store\/[a-z0-9]{32}-[^\s/]+$/.test(output.trim())) reject(new Error(`Candidate Nix check failed (${code}). Full log: ${logFile}\n${tail}`));
+      else resolve(output.trim());
+    }));
+  });
+}

src/capability-language/file-lock.ts

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+
+/** Kernel-owned lock: a crashed coordinator cannot leave a stale ownership file.
+ * The persistent file is just an inode; EOF releases the helper's lock. */
+export async function withFileLock<T>(filename: string, work: () => Promise<T>): Promise<T> {
+  const child = spawn("flock", ["--exclusive", "--nonblock", "--conflict-exit-code", "75", filename,
+    process.execPath, "-e", 'process.stdout.write("locked\\n"); process.stdin.resume();'], {stdio: ["pipe", "pipe", "pipe"]});
+  let diagnostics = "";
+  child.stdin.on("error", () => { /* acquisition/exit handling reports helper failure */ });
+  child.stderr.on("data", chunk => { diagnostics = (diagnostics + String(chunk)).slice(-2000); });
+  const closed = new Promise<void>((resolve) => { child.once("close", () => resolve()); });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      let output = "";
+      child.once("error", reject);
+      child.once("exit", code => reject(new Error(code === 75 ? "Another authoring command owns this repository; retry when it finishes" : `Cannot acquire authoring lock: ${diagnostics}`)));
+      child.stdout.on("data", chunk => { output += chunk; if (output.includes("locked\n")) resolve(); });
+    });
+    return await work();
+  } finally { child.stdin.end(); await closed; }
+}

src/capability-language/git-resolver.ts

@@ -1,6 +1,6 @@
 import childProcess from "node:child_process";
 import crypto from "node:crypto";
-import { mkdir, readFile, realpath } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, realpath, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import type { CapabilityRepositoryResolver } from "./assembly.js";
@@ -61,7 +61,27 @@ export const createGitCapabilityResolver = async (options: {
         checkoutRoot,
         checkoutName(kind, source.repository, source.commit),
       );
-      await execFile("git", [
+      const verify = async (checkout: string) => {
+        const { stdout } = await execFile("git", ["-C", checkout, "rev-parse", "HEAD"]);
+        if (stdout.trim().toLowerCase() !== source.commit.toLowerCase()) {
+          throw new Error(`Locked commit mismatch for ${source.repository}: wanted ${source.commit}, fetched ${stdout.trim()}`);
+        }
+        const { stdout: changes } = await execFile("git", ["-C", checkout, "status", "--porcelain", "--untracked-files=all"]);
+        if (changes.trim()) throw new Error(`Dependency checkout was modified: ${checkout}`);
+      };
+      // Only complete, checked clones become visible under the deterministic name.
+      // Concurrent resolvers may fetch independently, but cannot observe a partial clone.
+      if (await stat(directory).then(() => true, (error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      })) {
+        await verify(directory);
+        return { directory };
+      }
+      const staging = await mkdtemp(path.join(checkoutRoot, ".fetch-"));
+      const checkout = path.join(staging, "checkout");
+      try {
+        await execFile("git", [
         "-c",
         "advice.detachedHead=false",
         "clone",
@@ -71,18 +91,21 @@ export const createGitCapabilityResolver = async (options: {
         "--branch",
         `quixos-reachability/${source.commit.toLowerCase()}`,
         source.repository,
-        directory,
+        checkout,
       ]);
-      const { stdout } = await execFile("git", ["-C", directory, "rev-parse", "HEAD"]);
-      if (stdout.trim().toLowerCase() !== source.commit.toLowerCase()) {
-        throw new Error(
-          `Locked commit mismatch for ${source.repository}: ` +
-          `wanted ${source.commit}, fetched ${stdout.trim()}`,
-        );
+        await verify(checkout);
+        try { await rename(checkout, directory); }
+        catch (error) {
+          if (!["EEXIST", "ENOTEMPTY"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+          await verify(directory);
+        }
+      } finally {
+        await rm(staging, { recursive: true, force: true });
       }
       return { directory };
     })();
     checkouts.set(key, pending);
-    return await pending;
+    try { return await pending; }
+    catch (error) { checkouts.delete(key); throw error; }
   };
 };

src/capability-language/inspect-cli.ts

@@ -2,12 +2,19 @@
 // Data only: never load files, resolve repositories, or evaluate code.
 import { parseQx } from "./source.js";
 import { parseQuixosLockDocument } from "../resource-lock/parser.js";
+import { instantiateWorkspaceIdentity } from "./structural-edits.js";
 let input = "";
 for await (const chunk of process.stdin) {
   input += chunk;
   if (Buffer.byteLength(input) > 6 * 1024 * 1024) throw new Error("Inspection input exceeds limit");
 }
-const files: { path: string; source: string }[] = JSON.parse(input);
+const document = JSON.parse(input);
+if (!Array.isArray(document) && document?.operation === "instantiate-workspace") {
+  if (typeof document.source !== "string" || document.source.length > 262144 || typeof document.workspaceId !== "string") throw new Error("Invalid template identity request");
+  process.stdout.write(JSON.stringify({ source: instantiateWorkspaceIdentity(document.source, document.workspaceId) }));
+  process.exit(0);
+}
+const files: { path: string; source: string }[] = document;
 if (!Array.isArray(files) || files.length > 128) throw new Error("Too many source files");
 const result = files.map(({ path, source }) => {
   if (typeof path !== "string" || typeof source !== "string" || source.length > 262144)

src/capability-language/pin-upgrades.ts

@@ -7,10 +7,12 @@ import {promisify} from "node:util";
 import {loadQuixosLock, parseQuixosLockDocument} from "../resource-lock/index.js";
 import {contentDigest} from "../capability-model/evolution.js";
 import {planStructure, applyStructure, type StructuralRequest} from "./structural-plan.js";
-import {snapshotRepository, checkResourceCandidate, checkWorkspaceCandidate} from "./candidate-check.js";
+import {snapshotRepository} from "./candidate-check.js";
 import {compileWorkspaceRepository, compileCapabilityResourceRepository, type ResolvedCapabilityResource} from "./assembly.js";
 import {createGitCapabilityResolver} from "./git-resolver.js";
-import {snapshotCommit} from "./checked-build.js";
+import {snapshotCommit, buildImmutableCandidate} from "./checked-build.js";
+import {planEvolution, type WorkspaceRevision, type EvolutionReview} from "../capability-model/index.js";
+import {withFileLock} from "./file-lock.js";
 const execFile = promisify(callback);
 type Source = {repository: string; commit: string};
 export type UpgradeNode = {kind: "workspace" | "package" | "interface"; directory: string; source: Source};
@@ -103,15 +105,21 @@ export type UpgradeEffects = {
 const effects: UpgradeEffects = {
   async check(node, root, output, spec) {
     if (node.kind === "workspace" && !spec.baseline && !spec.bootstrap) throw new Error("Upgrading a workspace requires its checked active baseline for major-review checks (or explicit bootstrap:true for a new workspace)");
-    // Publication checks consume already-published dependency revisions, never
-    // workbench dirty overlays masquerading as those immutable identities.
-    const snapshotMap = `${output}-published-dependencies.json`;
-    await fs.writeFile(snapshotMap, JSON.stringify({resources: []}), {flag: "wx"});
-    const result = node.kind === "workspace" ? await checkWorkspaceCandidate({root, output, snapshotMap, baseline: spec.baseline, reviews: spec.reviews})
-      : await checkResourceCandidate({root, output, kind: node.kind, source: node.source, snapshotMap});
-    if (result.blockers.length) throw new Error(`Refactor required in ${node.directory}: ${result.blockers.join("; ")}`);
-    const evolution = (result as {evolution?: {reviews: {accepted: boolean}[]}}).evolution;
-    if (evolution?.reviews.some((review) => !review.accepted)) throw new Error("Explicit semantic-major review required before publishing the workspace");
+    // Explicit baseline upgrades use the same immutable Nix checker. Retaining
+    // an unverified source is safe and must precede a remote flake fetch.
+    await fs.mkdir(output);
+    const commit = await snapshotCommit(root);
+    await effects.publish(root, commit);
+    const artifact = await buildImmutableCandidate({...node.source, commit}, node.kind, path.join(output, "nix.log"));
+    const candidate = await fs.readFile(path.join(artifact, "candidate.json"), "utf8");
+    await fs.writeFile(path.join(output, "candidate.json"), candidate);
+    if (node.kind === "workspace") {
+      const baseline = spec.baseline ? JSON.parse(await fs.readFile(spec.baseline, "utf8")) as WorkspaceRevision : null;
+      const reviews = spec.reviews ? JSON.parse(await fs.readFile(spec.reviews, "utf8")) as EvolutionReview[] : [];
+      const evolution = planEvolution(baseline, JSON.parse(candidate), {reviews});
+      await fs.writeFile(path.join(output, "evolution.json"), JSON.stringify(evolution, null, 2));
+      if (evolution.blockers.length) throw new Error(`Refactor required in ${node.directory}: ${evolution.blockers.join("; ")}`);
+    }
   },
   async snapshot(root) {
     const commit = await snapshotCommit(root);
@@ -139,10 +147,10 @@ export const applyPinUpgrades = async (plan: UpgradePlan, journalId?: string, im
   const directory = path.join(plan.workbench, ".quixos", "upgrades");
   await fs.mkdir(directory, {recursive: true, mode: 0o700});
   if (await fs.realpath(directory) !== directory) throw new Error("Upgrade journals must not cross symlinks");
-  const lock = await fs.open(path.join(directory, "writer.lock"), "wx", 0o600);
   const id = journalId ?? randomUUID();
-  if (!/^[a-f0-9-]{36}$/.test(id)) {await lock.close(); await fs.unlink(path.join(directory, "writer.lock")); throw new Error("Invalid upgrade journal ID");}
+  if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error("Invalid upgrade journal ID");
   const filename = path.join(directory, `${id}.json`);
+  return withFileLock(path.join(directory, "writer.lock"), async () => {
   try {
     const journal: Journal = journalId ? JSON.parse(await fs.readFile(filename, "utf8")) : {schemaVersion: 1, plan, steps: []};
     if (journal.plan.digest !== plan.digest) throw new Error("Upgrade journal belongs to another plan");
@@ -242,5 +250,5 @@ export const applyPinUpgrades = async (plan: UpgradePlan, journalId?: string, im
     }
     return {id, journal: filename, revisions: journal.steps.map((step) => ({directory: step.directory, commit: step.commit})), activated: false};
   } catch (error) {throw new Error(`${error instanceof Error ? error.message : String(error)}; upgrade journal ${filename}`, {cause: error});}
-  finally {await lock.close(); await fs.unlink(path.join(directory, "writer.lock"));}
+  });
 };

src/capability-language/scaffold-recipes.ts

@@ -88,7 +88,6 @@ export const scaffoldRecipe = async (root: string, command: "package" | "functio
       installServer = { libexecName = ${JSON.stringify(name.toLowerCase())}; descriptorPath = "descriptor.quixos-package.txtpb"; ${react ? 'extraFiles = [ { source = "dist/component.mjs"; target = "component.mjs"; } ];' : ""} };
     };
 }\n`);
-    generated("quixos.resources.json", json({generatedBy: "qx-scaffold-v1", resources: []}));
   } else {
     registry = await ownedJson<Registry>(root, prefix + "quixos.scaffold.json");
     catalog = await ownedJson<typeof catalog>(root, prefix + "quixos.migrations.json");

src/capability-language/structural-edits.ts

@@ -21,6 +21,21 @@ const selectable = new Set(["workspaceDecl", "fragmentDecl", "interfaceResourceD
   "valueMember", "relationshipMember", "operationMember", "packageOperationExport", "packageFunctionExport", "packageConstructorExport",
   "conformanceDecl", "stateDecl", "edgeDecl", "constructorBindingDecl", "resourceImportDecl", "sourceImportDecl", "operationBindingDecl"]);
 
+/** Bind only the template root identity; schema/atom identities are reusable.
+ * The revision's real identity is derived from its containing commit at compile time. */
+export const instantiateWorkspaceIdentity = (source: string, workspaceId: string): string => {
+  if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(workspaceId)) throw new Error("Workspace identity must be a UUID");
+  const syntax = parseQx(source);
+  if (syntax.diagnostics.length) throw new Error("Cannot instantiate a malformed template workspace");
+  const declaration = syntax.root.children.find(node => node.kind === "workspaceDecl");
+  const literals = declaration?.children.filter(node => node.kind === "stringLiteral");
+  if (!literals || literals.length !== 3) throw new Error("Template must contain a workspace declaration");
+  return applySourceEdits(source, [
+    { ...literals[0], text: JSON.stringify(workspaceId) },
+    { ...literals[1], text: JSON.stringify(`workspace-revision:${workspaceId}:source`) },
+  ]);
+};
+
 const select = (source: string, selector: StructuralSelector): {node: SyntaxNode; syntax: ReturnType<typeof parseQx>} => {
   if (!selectable.has(selector.kind)) throw new Error(`Unsupported structural selector ${selector.kind}`);
   const syntax = parseQx(source);
@@ -117,10 +132,16 @@ export const editStructure = (source: string, edit: StructuralEdit): string => {
     if (!closing) throw new Error("Append requires a declaration with a body");
     result = applySourceEdits(source, [{start: closing.start, end: closing.start, text: `\n${edit.source}\n`}]);
   } else {
+    // A resource parser node includes imports/external declarations preceding
+    // its header. Replacing the declaration must not delete that preamble.
+    const identifier = node.children.find(child => child.kind === "identifier");
+    const header = ["packageResourceDecl", "interfaceResourceDecl"].includes(node.kind) && identifier
+      ? syntax.tokens.filter(token => token.start >= node.start && token.end <= identifier.start &&
+        token.kind === (node.kind === "packageResourceDecl" ? "PACKAGE" : "INTERFACE")).at(-1)?.start : undefined;
     const wrapper = edit.operation === "remove" && ["stateDecl", "edgeDecl"].includes(node.kind)
       ? [...walkSyntax(syntax.root)].filter((entry) => ["conformanceItem", "sharedAttachmentDecl"].includes(entry.kind) && entry.start <= node.start && entry.end >= node.end).sort((a, b) => (a.end - a.start) - (b.end - b.start))[0]
       : undefined;
-    result = applySourceEdits(source, [{start: wrapper?.start ?? node.start, end: wrapper?.end ?? node.end, text: edit.operation === "replace" ? edit.source : ""}]);
+    result = applySourceEdits(source, [{start: wrapper?.start ?? header ?? node.start, end: wrapper?.end ?? node.end, text: edit.operation === "replace" ? edit.source : ""}]);
   }
   const checked = parseQx(result);
   if (checked.diagnostics.length) throw new Error(`Invalid structural change: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);

src/capability-language/structural-plan.ts

@@ -8,11 +8,15 @@ import { snapshotRepository, localResourceSnapshots } from "./candidate-check.js
 import { compileWorkspaceRepository, compileCapabilityResourceRepository } from "./assembly.js";
 import { createGitCapabilityResolver } from "./git-resolver.js";
 import {bindingSchema, generateTypeScriptBindings} from "../bindings/index.js";
+import { parseQx } from "./source.js";
+import { parseQuixosLockDocument } from "../resource-lock/index.js";
+import { withFileLock } from "./file-lock.js";
 
 export type StructuralRequest = {
   kind: "workspace" | "interface" | "package";
   source?: {repository: string; commit: string};
   resourceRoot?: string;
+  validation?: "syntax" | "resource-graph";
   files: ({file: string; edits: StructuralEdit[]} | {file: string; create: string} | {file: string; generated: string})[];
 };
 type Change = {file: string; before: string | null; after: string; mode: number};
@@ -50,6 +54,7 @@ const durableJson = async (file: string, value: unknown) => {
 
 /** Validate the entire edited resource graph in a private snapshot before writes. */
 export const planStructure = async (rootPath: string, request: StructuralRequest, snapshotMap?: string) => {
+  if (request.validation && !["syntax", "resource-graph"].includes(request.validation)) throw new Error("Unknown structural validation mode");
   const root = await fs.realpath(rootPath);
   const temporary = await fs.mkdtemp(path.join(os.tmpdir(), "qx-structure-"));
   try {
@@ -74,11 +79,28 @@ export const planStructure = async (rootPath: string, request: StructuralRequest
         after = input.edits.reduce(editStructure, before);
       }
       if (Buffer.byteLength(after) > 1024 * 1024) throw new Error("Scaffold file exceeds 1 MiB");
+      if (input.file.endsWith("package.qx")) {
+        let registry;
+        try { registry = JSON.parse(await fs.readFile(path.join(root, path.dirname(input.file), "quixos.scaffold.json"), "utf8")); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+        if (registry?.generatedBy === "qx-scaffold-v1") {
+          const declaration = parseQx(after).root.children.find(node => node.kind === "packageResourceDecl");
+          const literal = declaration?.children.find(node => node.kind === "stringLiteral");
+          if (literal && JSON.parse(after.slice(literal.start, literal.end)) !== registry.id)
+            throw new Error("Cannot change a scaffold-owned package identity independently of its registry; create a new managed package instead");
+        }
+      }
       const mode = before === null ? 0o644 : (await fs.stat(path.join(root, input.file))).mode & 0o777;
       changes.push({file: input.file, before, after, mode});
       await containedParent(snapshot.directory, input.file);
       await fs.writeFile(path.join(snapshot.directory, input.file), after);
     }
+    if (request.validation === "syntax") {
+      for (const change of changes) {
+        if (change.file.endsWith(".qx") && parseQx(change.after, change.file).diagnostics.length) throw new Error(`Invalid QX syntax in ${change.file}`);
+        if (change.file.endsWith(".lock") && !parseQuixosLockDocument(change.after, change.file).ok) throw new Error(`Invalid lock syntax in ${change.file}`);
+      }
+    } else {
     const localMap = path.join(temporary, "local-resources.json");
     await fs.writeFile(localMap, JSON.stringify(await localResourceSnapshots(root, snapshotMap)));
     const resolveResource = await createGitCapabilityResolver({checkoutRoot: path.join(temporary, "resources"), snapshotMap: localMap});
@@ -93,7 +115,6 @@ export const planStructure = async (rootPath: string, request: StructuralRequest
         const configuration = JSON.parse(await fs.readFile(path.join(resourceRoot, "quixos.check.json"), "utf8"));
         const artifacts = [
           {file: configuration.bindingOutput as string, after: generateTypeScriptBindings(bindingSchema(compiled), compiled.resource.revision.revisionId, configuration.options)},
-          {file: "quixos.resources.json", after: JSON.stringify({generatedBy: "qx-scaffold-v1", resources: compiled.resources.filter((entry) => entry.directory !== resourceRoot).map((entry) => ({kind: entry.kind, repository: entry.source.repository, commit: entry.source.commit}))}, null, 2) + "\n"},
         ];
         for (const artifact of artifacts) {
           const file = request.resourceRoot ? `${request.resourceRoot}/${artifact.file}` : artifact.file;
@@ -108,11 +129,12 @@ export const planStructure = async (rootPath: string, request: StructuralRequest
       }
     }
     else throw new Error("Resource plans require kind and exact authored source identity");
+    }
     if (changes.length > 100) throw new Error("Structural plan including generated artifacts exceeds 100 files");
     // Validation may fetch dependencies; reject edits made while it was running.
     for (const entry of changes) if (await read(root, entry.file) !== entry.before) throw new Error(`Source changed while planning: ${entry.file}`);
     for (const entry of observed) if (contentDigest(await fs.readFile(path.join(root, entry.file), "utf8")) !== entry.digest) throw new Error(`Validation input changed while planning: ${entry.file}`);
-    return {root, changes, observed, digest: contentDigest(changes), validation: "resource-graph" as const};
+    return {root, changes, observed, digest: contentDigest(changes), validation: request.validation ?? "resource-graph" as const};
   } finally { await fs.rm(temporary, {recursive: true, force: true}); }
 };
 
@@ -154,15 +176,7 @@ const replayStructure = async (rootPath: string, id: string) => {
 const withStructureLock = async <T>(root: string, work: () => Promise<T>) => {
   await containedParent(root, ".quixos/scaffolds/placeholder.json");
   const lock = path.join(root, ".quixos", "scaffolds", "writer.lock");
-  // Never steal a possibly live writer's lock. A process crash requires the
-  // operator to verify that writer is gone, remove this lock, then resume its
-  // journal. This is deliberately fail-closed instead of guessing from a PID.
-  const handle = await fs.open(lock, "wx", 0o600).catch((error) => {
-    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Another scaffold writer or interrupted writer owns ${lock}; verify it has exited before removing its lock and resuming`);
-    throw error;
-  });
-  try { await handle.writeFile(JSON.stringify({pid: process.pid})); await handle.sync(); return await work(); }
-  finally { await handle.close(); await fs.unlink(lock); }
+  return withFileLock(lock, work);
 };
 export const resumeStructure = async (rootPath: string, id: string) => {
   const root = await fs.realpath(rootPath);

src/capability-language/tool-cli.ts

@@ -1,29 +1,120 @@
 #!/usr/bin/env node
-import { readFile, writeFile, mkdtemp, rm } from "node:fs/promises";
+import { readFile, writeFile, mkdtemp, rm, realpath } from "node:fs/promises";
 import { parseQx, formatQx, lintQx } from "./source.js";
 import { scaffoldAtom } from "./scaffold.js";
 import { createGitCapabilityResolver } from "./git-resolver.js";
 import { planEvolution } from "../capability-model/index.js";
-import { checkWorkspaceCandidate, checkResourceCandidate, snapshotRepository } from "./candidate-check.js";
+import { snapshotRepository } from "./candidate-check.js";
 import {planPinUpgrades, applyPinUpgrades, discoverUpgradeSpec, type UpgradeSpec} from "./pin-upgrades.js";
 import path from "node:path";
 import os from "node:os";
 import {spawnSync} from "node:child_process";
 import { planStructure, applyStructure, resumeStructure, type StructuralRequest } from "./structural-plan.js";
 import {scaffoldRecipe, type ScaffoldRecipe} from "./scaffold-recipes.js";
-import {buildCheckedPackage, snapshotCommit} from "./checked-build.js";
+import {buildCheckedPackage, buildImmutableCandidate, snapshotCommit} from "./checked-build.js";
 import {formatQuixosLock, loadQuixosLock, parseQuixosLockDocument} from "../resource-lock/index.js";
+import { walkSyntax } from "./source.js";
+import { inspectWorkbench } from "./authoring-inspect.js";
+import { authoringContext } from "./authoring-context.js";
+import { convergeAuthoring } from "./authoring-converge.js";
+import { checkAuthoring } from "./authoring-check.js";
+import { authoringWorklist } from "./authoring-worklist.js";
 
 const authorSource = async (root: string) => {
-  const result = spawnSync("git", ["remote", "get-url", "origin"], {cwd: root, encoding: "utf8"});
+  const result = spawnSync("git", ["config", "--get", "remote.origin.url"], {cwd: root, encoding: "utf8"});
   if (result.error || result.status !== 0) throw new Error("Managed resource has no origin");
   return {repository: result.stdout.trim(), commit: await snapshotCommit(root)};
 };
 
+const readSpec = async (value: string) => {
+  if (value === "-") { let input = ""; for await (const chunk of process.stdin) { input += chunk; if (input.length > 1024 * 1024) throw new Error("Scaffold specification exceeds 1 MiB"); } return JSON.parse(input); }
+  return JSON.parse(value.trimStart().startsWith("{") ? value : await readFile(value, "utf8"));
+};
+const planSummary = (plan: Awaited<ReturnType<typeof planStructure>>) => ({
+  root: plan.root, validation: plan.validation,
+  changes: plan.changes.map(change => ({file: change.file, beforeBytes: change.before?.length ?? 0, afterBytes: change.after?.length ?? 0})),
+  note: "Structural plan only, not implementation verification. Run qx-workspace check while iterating.",
+});
+
 const main = async () => {
   const [command, ...args] = process.argv.slice(2);
+  if (command === "worklist" && !args.includes("--help")) {
+    if (args.length !== 1) throw new Error("usage: quixos-qx worklist WORKBENCH");
+    process.stdout.write(`${JSON.stringify(await authoringWorklist(args[0]), null, 2)}\n`);
+    return;
+  }
+  if (["author-check", "author-contract"].includes(command) && !args.includes("--help")) {
+    const [root, output, ...flags] = args;
+    if (!root || !output) throw new Error("usage: quixos-qx author-check ROOT OUTPUT [--baseline FILE] [--reviews FILE]");
+    const options: {baseline?: string; reviews?: string} = {};
+    for (let index = 0; index < flags.length; index += 2) {
+      if (!flags[index + 1]) throw new Error("Missing check option value");
+      if (flags[index] === "--baseline") options.baseline = flags[index + 1];
+      else if (flags[index] === "--reviews") options.reviews = flags[index + 1];
+      else throw new Error(`Unknown check option ${flags[index]}`);
+    }
+    const result = await checkAuthoring(root, output, {...options, contractOnly: command === "author-contract"});
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result.blockers.length) process.exitCode = 1;
+    return;
+  }
+  if (["converge", "_converge"].includes(command) && !args.includes("--help")) {
+    if (!args.length || args.length > 2) throw new Error("usage: quixos-qx converge WORKBENCH [REGISTERED_DIRECTORY] (join package writers first)");
+    const context = await authoringContext(args[0]);
+    if (command === "converge") {
+      const result = spawnSync("flock", ["--exclusive", "--nonblock", "--conflict-exit-code", "75", path.join(context.workbench, ".quixos/converge.lock"),
+        process.execPath, process.argv[1], "_converge", context.workbench, ...(args[1] ? [args[1]] : [])], {stdio: "inherit"});
+      if (result.error) throw result.error;
+      if (result.status === 75) process.stderr.write("Another source coordinator is running; retry when it finishes.\n");
+      process.exitCode = result.status ?? 1; return;
+    }
+    const result = await convergeAuthoring(context.workbench, args[1]);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.converged) process.exitCode = 1;
+    return;
+  }
+  if (command === "check-committed" && !args.includes("--help")) {
+    const [kind, repository, commit, log, ...extra] = args;
+    if (!["workspace", "interface", "package"].includes(kind) || !log || extra.length) throw new Error("usage: quixos-qx check-committed workspace|interface|package REPOSITORY COMMIT LOG_FILE");
+    process.stdout.write(`${await buildImmutableCandidate({repository, commit}, kind as "workspace" | "interface" | "package", log)}\n`);
+    return;
+  }
+  if (!command || command === "--help" || args.includes("--help")) {
+    process.stdout.write("quixos-qx: author-check, author-contract, converge, worklist, inspect, resources, check-committed, source-baseline, scaffold-package, scaffold-interface, scaffold-function, scaffold-dependency, scaffold-structure, scaffold-resume, pin-upgrade, parse, lint, format\n" +
+      "inspect WORKBENCH [RESOURCE] shows provisional contracts, with explicit historical fallback; never verification evidence.\n" +
+      "resources WORKBENCH lists registered editable repositories. Use qx-workspace for the workspace authoring workflow.\n");
+    return;
+  }
+  if (command === "inspect" || command === "resources") {
+    if (!args[0] || args.length > (command === "inspect" ? 2 : 1)) throw new Error(`usage: quixos-qx ${command} WORKBENCH${command === "inspect" ? " [RESOURCE]" : ""}`);
+    const result = command === "inspect" ? await inspectWorkbench(args[0], args[1]) : await authoringContext(args[0]);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (command === "source-baseline") {
+    if (args.length !== 1) throw new Error("usage: quixos-qx source-baseline WORKBENCH");
+    process.stdout.write(`${JSON.stringify(await (await authoringContext(args[0])).baseline())}\n`);
+    return;
+  }
   if (command === "scaffold-dependency") {
-    const [root, kind, name, repository, commit, ...flags] = args;
+    const [root, kind, name, ...remaining] = args;
+    let repository: string | undefined, commit: string | undefined;
+    const flags = [...remaining];
+    if (flags.length && !flags[0].startsWith("--")) { repository = flags.shift(); commit = flags.shift(); }
+    else if (root && ["interface", "package"].includes(kind) && name) {
+      const context = await authoringContext(root);
+      const alias = await realpath(path.join(context.workbench, `${kind}s`, name)).catch(() => null);
+      const matches = context.resources.filter(entry => entry.kind === kind && (entry.resourceId === name || path.basename(entry.directory) === name || path.join(context.workbench, entry.directory) === alias));
+      if (matches.length !== 1 || !matches[0].source) throw new Error(`Select exactly one registered ${kind} with qx-workspace resources; no match for ${name}`);
+      const selected = matches[0];
+      let source = selected.source!;
+      if (flags.includes("--write")) {
+        const retained = spawnSync("quixos-qx", ["converge", context.workbench, selected.directory], {encoding: "utf8", env: {...process.env, QUIXOS_JJ_NO_CHECKPOINT: "1"}});
+        if (retained.error || retained.status !== 0) throw new Error(`Dependency source needs attention: ${retained.error?.message ?? retained.stdout ?? retained.stderr}`);
+        source = JSON.parse(retained.stdout).candidate;
+      }
+      repository = source.repository; commit = source.commit;
+    }
     if (!root || !["interface", "package"].includes(kind) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name ?? "") || !repository || !commit || flags.some(flag => flag !== "--write")) throw new Error("usage: quixos-qx scaffold-dependency ROOT interface|package NAME REPOSITORY COMMIT [--write]");
     const resourceKind = kind as "package" | "interface";
     let entrypoint: "workspace" | "package" | "interface" | undefined;
@@ -44,13 +135,13 @@ const main = async () => {
       {file: target, edits: [{operation: "dependency", kind: resourceKind, name, source: {repository, commit}}]},
     ]};
     const plan = await planStructure(root, request, process.env.QUIXOS_SNAPSHOT_MAP);
-    process.stdout.write(`${JSON.stringify({...plan, applied: flags.includes("--write") ? await applyStructure(plan) : undefined}, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({...planSummary(plan), applied: flags.includes("--write") ? await applyStructure(plan) : undefined}, null, 2)}\n`);
     return;
   }
   if (command === "scaffold-interface") {
     const [root, specFile, ...flags] = args;
     if (!root || !specFile || flags.some(flag => flag !== "--write")) throw new Error("usage: quixos-qx scaffold-interface ROOT SPEC_JSON [--write]");
-    const spec = JSON.parse(await readFile(specFile, "utf8")) as ScaffoldRecipe;
+    const spec = await readSpec(specFile) as ScaffoldRecipe;
     if (!spec.name || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(spec.name) || !spec.id || !spec.revision || !spec.tools?.quixos) throw new Error("Interface scaffold requires name, id, revision and Quixos toolchain source");
     const request: StructuralRequest = {kind: "interface", source: spec.source, files: [
       {file: "interface.qx", create: `interface ${spec.name} id ${JSON.stringify(spec.id)} revision ${JSON.stringify(spec.revision)} {\n}\n`},
@@ -58,7 +149,7 @@ const main = async () => {
       {file: ".gitignore", create: ".quixos/\n"},
     ]};
     const plan = await planStructure(root, request, process.env.QUIXOS_SNAPSHOT_MAP);
-    process.stdout.write(`${JSON.stringify({...plan, applied: flags.includes("--write") ? await applyStructure(plan) : undefined}, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({...planSummary(plan), applied: flags.includes("--write") ? await applyStructure(plan) : undefined}, null, 2)}\n`);
     return;
   }
   if (command === "build-package") {
@@ -89,14 +180,6 @@ const main = async () => {
     process.stdout.write(`${JSON.stringify(publish ? await applyPinUpgrades(plan, resume, undefined, {acceptEdits}) : plan, null, 2)}\n`);
     return;
   }
-  if (command === "check-resource") {
-    const [root, kind, repository, commit, output, ...extra] = args;
-    if (!root || !output || !["package", "interface"].includes(kind) || extra.length) throw new Error("usage: quixos-qx check-resource ROOT package|interface REPOSITORY COMMIT OUTPUT");
-    const result = await checkResourceCandidate({root, kind: kind as "package" | "interface", source: {repository, commit}, output, publishedOnly: true});
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    if (result.blockers.length) process.exitCode = 1;
-    return;
-  }
   if (["scaffold-package", "scaffold-function", "scaffold-migration", "scaffold-refresh"].includes(command)) {
     const [root, specFile, ...flags] = args;
     let spec: ScaffoldRecipe;
@@ -107,9 +190,16 @@ const main = async () => {
       if (declaration >= 0) {
         if (!flags[declaration + 1]) throw new Error("--declaration requires a QX declaration file");
         spec.declaration = await readFile(flags[declaration + 1], "utf8");
+        const parsed = parseQx(`package Draft id "package:draft" revision "package:draft@1" { ${spec.declaration} }`);
+        if (parsed.diagnostics.length) throw new Error(parsed.diagnostics.map(d => d.message).join("\n"));
+        const exported = [...walkSyntax(parsed.root)].filter(node => ["packageOperationExport", "packageFunctionExport", "packageConstructorExport"].includes(node.kind));
+        if (exported.length !== 1) throw new Error("--declaration must contain exactly one function, operation or constructor export");
+        const literal = exported[0].children.find(node => node.kind === "stringLiteral");
+        if (!literal) throw new Error("Declaration requires an authored export ID");
+        spec.id = JSON.parse(parsed.source.slice(literal.start, literal.end));
         flags.splice(declaration, 2);
       }
-    } else spec = JSON.parse(await readFile(specFile, "utf8")) as ScaffoldRecipe;
+    } else spec = await readSpec(specFile) as ScaffoldRecipe;
     if (!root || !specFile || flags.some((flag) => !["--write", "--install"].includes(flag)) || (flags.includes("--install") && !flags.includes("--write"))) throw new Error("usage: quixos-qx scaffold-package|function|migration|refresh ROOT SPEC_JSON [--write [--install]]");
     const request = await scaffoldRecipe(root, command.slice(9) as "package" | "function" | "migration" | "refresh", spec);
     const plan = await planStructure(root, request, process.env.QUIXOS_SNAPSHOT_MAP);
@@ -128,16 +218,17 @@ const main = async () => {
       const locked = spawnSync("nix", ["flake", "lock"], {cwd, stdio: ["inherit", 2, 2]});
       if (locked.error || locked.status !== 0) throw new Error("Scaffold files retained; nix flake lock failed");
     }
-    process.stdout.write(`${JSON.stringify({...plan, applied}, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({...planSummary(plan), applied}, null, 2)}\n`);
     return;
   }
   if (command === "scaffold-structure") {
     const [root, spec, ...flags] = args;
     if (!root || !spec || flags.some((flag) => flag !== "--write")) throw new Error("usage: quixos-qx scaffold-structure ROOT SPEC_JSON [--write]");
-    const request = JSON.parse(await readFile(spec, "utf8")) as StructuralRequest;
+    const request = await readSpec(spec) as StructuralRequest;
+    if (request.kind !== "workspace" && !request.source) request.source = await authorSource(root);
     const plan = await planStructure(root, request, process.env.QUIXOS_SNAPSHOT_MAP);
     const applied = flags.includes("--write") ? await applyStructure(plan) : undefined;
-    process.stdout.write(`${JSON.stringify({...plan, applied}, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({...planSummary(plan), applied}, null, 2)}\n`);
     return;
   }
   if (command === "scaffold-resume") {
@@ -146,19 +237,7 @@ const main = async () => {
     process.stdout.write(`${JSON.stringify(await resumeStructure(root, id), null, 2)}\n`);
     return;
   }
-  if (command === "check") {
-    const [root, output, ...flags] = args;
-    if (!root || !output || flags.length % 2) throw new Error("usage: quixos-qx check ROOT OUTPUT [--snapshot-map FILE] [--baseline FILE] [--reviews FILE]");
-    const values = new Map<string, string>();
-    for (let index = 0; index < flags.length; index += 2) {
-      if (!["--snapshot-map", "--baseline", "--reviews"].includes(flags[index])) throw new Error(`Unknown check option ${flags[index]}`);
-      values.set(flags[index], flags[index + 1]);
-    }
-    const result = await checkWorkspaceCandidate({ root, output, snapshotMap: values.get("--snapshot-map"), baseline: values.get("--baseline"), reviews: values.get("--reviews") });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    if (result.blockers.length) process.exitCode = 1;
-    return;
-  }
+  if (["check", "check-resource"].includes(command)) throw new Error("Use qx-workspace check in the registered repository; handwritten source/snapshot-map candidates are no longer an authoring check path");
   if (command === "evolution") {
     const [baseline, candidate, reviews, ...extra] = args;
     if (!baseline || !candidate || extra.length) throw new Error("usage: quixos-qx evolution BASELINE_JSON CANDIDATE_JSON [REVIEWS_JSON]");

src/capability-model/validation.ts

@@ -1467,8 +1467,12 @@ const validateConformances = (
           );
           continue;
         }
-        validateAttachmentAccess(issues, attachment, conformance, `${bindingPath}.binding.edgeTypeId`);
         const projection = edgeProjection(attachment.attachment, binding.projectionId);
+        // An owned endpoint may explicitly export read-only traversal, including
+        // a native inverse relationship view. This never exports mutation rights.
+        if (!(binding.primitive === "resolve" && projection?.endpoint.publicTraversal)) {
+          validateAttachmentAccess(issues, attachment, conformance, `${bindingPath}.binding.edgeTypeId`);
+        }
         const relationshipMember = operationEntry.member.kind === "relationship"
           ? operationEntry.member
           : undefined;