@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/cli/run.mjs

@@ -51,11 +51,18 @@ export const commandMap = new Map([
   ['extension-pack:list', ['src/commands/extension-pack.mjs', 'list']],
   ['distribution', ['src/commands/distribution.mjs']],
   ['distribution:check', ['src/commands/distribution.mjs', 'check']],
+  ['disclosure', ['src/commands/disclosure.mjs']],
+  ['disclosure:check', ['src/commands/disclosure.mjs', 'check']],
   ['attestation', ['src/commands/attestation.mjs']],
   ['feedback', ['src/commands/feedback.mjs']],
   ['feedback:check', ['src/commands/feedback.mjs', 'check']],
   ['announcements', ['src/commands/announcements.mjs']],
   ['announcements:list', ['src/commands/announcements.mjs', 'list']],
+  ['sync', ['src/commands/sync.mjs']],
+  ['review', ['src/commands/review.mjs']],
+  ['coauthor', ['src/commands/coauthor.mjs']],
+  ['skills', ['src/commands/skills.mjs']],
+  ['obsidian', ['src/commands/obsidian.mjs']],
 ])
 
 function isDefaultBrand(brand) {
@@ -113,18 +120,35 @@ Core commands:
   support bundle --dry-run        Preview a no-send support bundle.
   feedback --message TEXT         Write a local, never-sent feedback report.
   announcements list              List and verify MNSTRY announcements.
+  sync enroll                     Explicitly enroll one repository for supervision.
+  sync status                     Fully observe the enrolled repository.
+  sync reconcile                  Fetch and perform only proven fast-forwards.
+  sync plan                       Prepare one bounded, reviewable commit plan.
+  sync commit                     Execute an exactly confirmed commit plan.
+  sync run --once                 Run one full-state supervisor cycle.
+  obsidian status|open|apply      Maintain and open Obsidian views of the corpus; apply edits made in them.
   egress check                    Check extracted Atelier paths for forbidden egress.
   boundary check                  Enforce private/shared repo placement rules.
   boundary audit                  Report content-rule matches tree-wide without blocking.
   boundary install-hooks          Install staged/private-domain Git guards.
   promote                         Record a git.promote disclosure event.
-  upgrade --dry-run               Plan a safe package/template upgrade.
+  upgrade plan --save             Save an exact local candidate plan.
+  upgrade explain --plan          Explain saved changes and consent without writes.
+  upgrade apply --plan --confirm   Apply the selected plan through commit hooks.
+  upgrade status|recover          Inspect receipts or preview recovery.
+  upgrade --dry-run               Plan a legacy package/template upgrade.
   upgrade --apply                 Apply a branch-based reviewable upgrade.
   lock check|write                Verify or create atelier.lock.json.
+  lock provenance                Inspect actual installed package identity.
+  review run|history|handoff       Evidence-bound local human review.
+  review export|inspect|packs      Preview inspection bundles and pack lifecycle.
+  coauthor start|read|event|recover Save and resume private authoring drafts.
+  skills audit|observe|candidates|sync Audit and manage local skill projections.
   config check                    Validate project config.
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
   distribution check              Check a distribution for MNSTRY attribution.
+  disclosure check                Scan tracked or staged content for disclosure risks.
 
 Attestation commands:
   attestation hash FILE           Print the canonical payload hash of a payload.
@@ -132,15 +156,27 @@ Attestation commands:
   attestation verify FILE         Verify an attestation against a public key file.
   attestation keygen --key-id ID  Generate a signing key pair.
 
-Every project-aware command accepts --project-config=PATH or
-MNSTRY_ATELIER_PROJECT_CONFIG=PATH. Machine-local repo paths belong in
+Commands whose usage names --project accept --project=PATH or --project PATH.
+The project resolver also accepts --project-config=PATH and
+MNSTRY_ATELIER_PROJECT_CONFIG=PATH; each command's own help is authoritative.
+Project-aware commands accept repeated --repo-path NAME=PATH or
+--repo-path=NAME=PATH. Overrides change location, never declared read authority.
+Run config check --explain for path-free resolution sources.
+Machine-local repo paths belong in
 .atelier-local/, atelier.local.json, or atelier.workspace.local.json.`
 }
 
 export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
   const c = brand.command
   const help = {
-    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution] [--target DIR] [--actor ID]
+    skills: `Usage: ${c} skills audit|observe|candidates|sync
+Audit bundled skills or --root DIR [--peer DIR].
+Sync previews by default; applying requires --apply --confirm PLAN_DIGEST.
+Observations are local metadata, never automatic telemetry.`,
+    coauthor: `Usage: ${c} coauthor start|read|event|recover
+
+Read one JSON request from stdin (maximum 1 MiB). Start takes {"config":{"id":"SESSION","fields":[{"id":"FIELD","source":{"ref":"packet.md","digest":"SHA256"}}]}}. Read/recover take {"sessionId":"SESSION"}. Event takes {"sessionId":"SESSION","event":{"id":"UNIQUE","expectedRevision":0,"type":"answer","text":"ANSWER"}}. Run from the intended Git workspace with ignored .atelier-local/. Saves are private drafts, never canonical source edits.`,
+    init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution|external-project] [--target DIR] [--actor ID]
 
 Creates tracked starter files and an Atelier lockfile. It does not install hooks unless asked separately. An unrecognized --template exits 1 and writes nothing; omit --template for the blank scaffold.`,
     adopt: `Usage: ${c} adopt [--profile single-repo|private-domain|shared-project|multi-repo|monorepo|control-workspace] [--target DIR] [--yes]
@@ -152,9 +188,9 @@ Ensures ignored local Atelier state exists, verifies ignore coverage, and record
     doctor: `Usage: ${c} doctor [--project ./atelier.project.json] [--fix] [--dry-run]
 
 Reports project config, local overlay, and repo boundary readiness. --fix only repairs ignored local state.`,
-    boundary: `Usage: ${c} boundary check|push-check|audit|install-hooks [--project ./atelier.project.json] [--staged]
+    boundary: `Usage: ${c} boundary check|push-check|audit|install-hooks [--project ./atelier.project.json] [--staged] [--source=working-tree|head]
 
-check --staged judges the staged diff. push-check reads pre-push ref updates on stdin and judges only the pushed range. audit scans the whole tree and reports without blocking, so an accepted usage never strands unrelated work.`,
+check --staged judges the staged diff. push-check reads pre-push ref updates on stdin and judges only the pushed range. audit scans the working tree by default and reports without blocking; --source=head selects the committed snapshot.`,
     graph: `Usage: ${c} graph [--check] [--project ./atelier.project.json]
 
 Builds or checks the project knowledge graph from tracked sources plus ignored local path bindings.`,
@@ -171,25 +207,55 @@ Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet dr
   ${c} extension-pack validate [--json] [--project ./atelier.project.json]
   ${c} extension-pack list [--json] [--project ./atelier.project.json]
 
-Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand.`,
+Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand. Shared --project-config and repeated --repo-path NAME=PATH options are supported in both space and equals forms.`,
     distribution: `Usage: ${c} distribution check [--target DIR] [--pack DIR]
 
 Checks a distribution package for the required MNSTRY attribution markers. Blocking: the distribution README.md byte check, and a CLI probe that EXECUTES the target's declared bin with --version (spawned with the current Node, cwd set to the target — only run this against distributions you trust) and requires the attribution in its output; a target that looks like a distribution but declares no probe-able bin, or ships a malformed package.json, is also blocking. The extension-pack manifest attribution key is advisory and reported only. The normative wording lives in TRADEMARKS.md under "Required attribution"; see also docs/attestation.md and docs/distributions.md.`,
+    disclosure: `Usage: ${c} disclosure check [--root DIR] [--staged] [--denylist FILE | --structural-only] [--fail-on-binary] [--untrusted]
+
+Scans Git-tracked files, or staged index blobs with --staged, without following symlinks. A private denylist is required by default and must be supplied through ATELIER_DENYLIST_JSON, --denylist, or ignored .atelier-local/disclosure-denylist.json. --structural-only is the explicit no-denylist lane. --untrusted suppresses finding details.`,
     attestation: `Usage:
   ${c} attestation hash <payload.json>
   ${c} attestation sign <attestation.json> [--key FILE] [--out FILE]
   ${c} attestation verify <attestation.json> --public-key FILE [--payload FILE] [--json]
   ${c} attestation keygen --key-id ID [--algorithm ed25519|es256] [--out FILE]
 
-Records and checks admission decisions. hash prints the canonical payload hash (RFC 8785 JCS, SHA-256). sign reads the local signing key file. verify reads a public key file and exits 1 when it judges the attestation invalid. keygen writes the signing key file mode 0600, refuses to overwrite, and prints only the public key document.`,
+Records and checks admission decisions. hash prints the canonical payload hash (RFC 8785 JCS, SHA-256). sign reads the local signing key file. verify reads a public key file and exits 1 when it judges the attestation invalid. keygen writes the signing key file mode 0600 on POSIX, refuses to overwrite, and prints only the public key document.`,
     feedback: `Usage:
   ${c} feedback create --message TEXT | --message-file PATH [--context FILE] [--include-gates]
   ${c} feedback check FILE
 
-Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0600), scanned with the support-bundle banned key and value patterns before writing; any match refuses the write naming pattern label and location only. Files given to --message-file and --context must be valid UTF-8 text of at most 262144 bytes. The scan is a backstop, not clearance: read the whole report before sharing it. The kit has no send path — sharing the file is always the user's own explicit act.`,
+Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0600 on POSIX), scanned with the support-bundle banned key and value patterns before writing; any match refuses the write naming pattern label and location only. Files given to --message-file and --context must be valid UTF-8 text of at most 262144 bytes. The scan is a backstop, not clearance: read the whole report before sharing it. The kit has no send path — sharing the file is always the user's own explicit act.`,
     announcements: `Usage: ${c} announcements list [--dir DIR] [--public-key FILE] | verify <file> [--public-key FILE] [--json] | show <file> [--public-key FILE]
 
 MNSTRY announcements are a pull-only channel: signed JSON documents under announcements/ in the repository. The trust anchor is always the committed MNSTRY key, or one you pass explicitly with --public-key; --dir changes only where documents are read from and never which key verifies them. Every run names the key and keyId it used. The kit never fetches anything — receiving announcements is the git pull you chose to run, and show refuses to print a body whose signature does not verify.`,
+    obsidian: `Usage: ${c} obsidian status|scope|audience|mode|policy|service|open|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json]
+
+  ${c} obsidian status
+  ${c} obsidian scope list | scope show ID
+  ${c} obsidian audience show | set A,B | clear
+  ${c} obsidian mode show | set manual|automatic
+  ${c} obsidian policy show | install FILE | revoke
+  ${c} obsidian service start [--consent-actor ID] --adapter=obsidian-cli | status | stop | unit --print --adapter=obsidian-cli
+  ${c} obsidian open [--scope ID] [--consent-actor ID] [--allow-stale] --adapter=obsidian-cli
+  ${c} obsidian apply list | show EDIT | run EDIT [--actor ID] | recover
+  ${c} obsidian conflicts [ID]
+  ${c} obsidian apply-policy create FILE | show | revoke
+  ${c} obsidian selection resolve ID | persist ID [allow-empty] | show ID | list
+  ${c} obsidian proposals list | show OPERATION
+
+Noninteractive. With --json exactly one JSON document is printed, for a refusal too. status, scope, audience show, mode show, policy show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli. Audiences, mode and the apply policy are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
+    sync: `Usage:
+  ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
+  ${c} sync status --repo DIR
+  ${c} sync reconcile --repo DIR [--retries 3]
+  ${c} sync run --repo DIR [--once] [--interval 30]
+  ${c} sync plan --repo DIR --path FILE [--path FILE] --message TEXT [--publish]
+  ${c} sync commit --repo DIR --operation ID --confirm ID
+  ${c} sync pause|freeze|resume --repo DIR
+  ${c} sync trace --repo DIR
+
+Enrolls exactly one repository and keeps Git plus readable files authoritative. Reconciliation observes the complete repository every cycle and performs only fast-forward updates. Commit creation is a two-phase user-confirmed operation: plan shows one bounded change set, and commit refuses unless the repository is unchanged and --confirm exactly repeats the operation id. No semantic conflict resolution, force operation, browser apply endpoint, telemetry, or desktop shell is present.`,
   }
   return help[command] || `Usage: ${c} ${command} [args]\n\nRun ${c} --help for the command list.`
 }
@@ -219,6 +285,7 @@ function normalizeArgs(argv) {
   if (args[0] === 'extension-pack' && args[1] === 'validate') args.splice(0, 2, 'extension-pack:validate')
   if (args[0] === 'extension-pack' && args[1] === 'list') args.splice(0, 2, 'extension-pack:list')
   if (args[0] === 'distribution' && args[1] === 'check') args.splice(0, 2, 'distribution:check')
+  if (args[0] === 'disclosure' && args[1] === 'check') args.splice(0, 2, 'disclosure:check')
   if (args[0] === 'support' && args[1] === 'bundle') args.splice(0, 2, 'support:bundle')
   if (args[0] === 'support:bundle' && args[1] === '--dry-run') args.splice(1, 1)
   return { help: false, args }
@@ -261,12 +328,13 @@ export async function runCli({
 
   const [script, ...prefixArgs] = target
   const scriptPath = path.join(packageRoot, script)
+  const executorPath = path.join(packageRoot, 'src', 'cli', 'execute-command.mjs')
   if (!fs.existsSync(scriptPath)) {
     stderr(`${brand.displayName} command is not available in this package install: ${command}`)
     return 1
   }
 
-  const result = spawnSync(process.execPath, [scriptPath, ...prefixArgs, ...rest], {
+  const result = spawnSync(process.execPath, [executorPath, scriptPath, ...prefixArgs, ...rest], {
     cwd,
     stdio: 'inherit',
     env: {

package/src/coauthor/session.mjs

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../attestation/jcs.mjs';
+
+// Experimental adapter seam. This reducer performs no storage or authorization.
+export const COAUTHOR_SESSION_VERSION = 'atelier-coauthor-session/experimental-v1';
+export function contentDigest(text) {
+  if (typeof text !== 'string') throw new TypeError('text required');
+  if (Buffer.from(text, 'utf8').toString('utf8') !== text) throw new TypeError('text must be lossless UTF-8');
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+const digestPattern = /^[a-f0-9]{64}$/;
+function requireText(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 100000) {
+    throw new TypeError(`${label} required and bounded`);
+  }
+}
+function sourceCheck(source) {
+  if (!source || typeof source !== 'object') throw new TypeError('source required');
+  requireText(source.ref, 'source ref');
+  if (!digestPattern.test(source.digest)) throw new TypeError('source digest required');
+}
+export function createSession({ id, fields }) {
+  requireText(id, 'session id');
+  if (!Array.isArray(fields) || fields.length === 0 || fields.length > 1000) throw new TypeError('fields required');
+  const ids = new Set();
+  const targets = fields.map(({ id: fieldId, source }) => {
+    requireText(fieldId, 'field id');
+    if (ids.has(fieldId)) throw new Error('duplicate field');
+    ids.add(fieldId);
+    sourceCheck(source);
+    return { id: fieldId, source: { ref: source.ref, digest: source.digest } };
+  });
+  return { version: COAUTHOR_SESSION_VERSION, id, revision: 0, phase: 'input', index: 0,
+    fields: targets, answers: [], proposal: null, saved: [], pending: null, events: [] };
+}
+function checkEvent(event) {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) throw new TypeError('event required');
+  requireText(event.id, 'event id');
+  if (!Number.isSafeInteger(event.expectedRevision) || event.expectedRevision < 0) throw new TypeError('revision required');
+  const keys = {
+    answer: ['text', 'continueAfterSave'], propose: ['text'], confirm: [], reject: [],
+    save: [], receipt: ['receipt'], failed: [], retry: [], advance: [], pause: [], resume: [],
+  }[event.type];
+  if (!keys || Object.keys(event).some(key => !['id', 'type', 'expectedRevision', ...keys].includes(key))) {
+    throw new TypeError('unknown event or field');
+  }
+  if (['answer', 'propose'].includes(event.type)) requireText(event.text, 'answer text');
+  if (event.continueAfterSave !== undefined && typeof event.continueAfterSave !== 'boolean') throw new TypeError('continue must be boolean');
+  if (event.type === 'receipt') {
+    const r = event.receipt;
+    if (!r || Object.keys(r).sort().join(',') !== 'fieldId,requestId,sessionId,sourceDigest,sourceRef,valueDigest') throw new TypeError('invalid receipt shape');
+    for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef']) requireText(r[key], key);
+    for (const key of ['sourceDigest', 'valueDigest']) if (!digestPattern.test(r[key])) throw new TypeError('invalid receipt digest');
+  }
+}
+function need(state, phases) {
+  if (!phases.includes(state.phase)) throw new Error(`event refused in ${state.phase}`);
+}
+function writeEffect(state) {
+  const field = state.fields[state.index];
+  return { type: 'write-field', requestId: state.pending.requestId, sessionId: state.id,
+    fieldId: field.id, sourceRef: field.source.ref, sourceDigest: field.source.digest,
+    text: state.proposal.text, valueDigest: contentDigest(state.proposal.text) };
+}
+function advance(state) {
+  state.index += 1;
+  state.phase = state.index === state.fields.length ? 'complete' : 'input';
+  state.proposal = null;
+  state.pending = null;
+}
+export function transition(session, event) {
+  // State is trusted adapter-owned memory. Rehydrate by replaying validated events,
+  // not by accepting an arbitrary caller-supplied session snapshot.
+  if (session?.version !== COAUTHOR_SESSION_VERSION) throw new Error('unsupported session');
+  checkEvent(event);
+  const fingerprint = contentDigest(canonicalize(event));
+  const prior = session.events.find(item => item.id === event.id);
+  if (prior) {
+    if (prior.fingerprint !== fingerprint) throw new Error('event id conflict');
+    return { session: structuredClone(session), effects: [], duplicate: true };
+  }
+  if (event.expectedRevision !== session.revision) throw new Error('stale revision');
+  const state = structuredClone(session);
+  const effects = [];
+  switch (event.type) {
+    case 'answer':
+      need(state, ['input', 'draft']);
+      state.answers.push({ eventId: event.id, fieldId: state.fields[state.index].id, text: event.text });
+      state.proposal = { text: event.text, originalEventId: event.id, confirmed: true,
+        continueAfterSave: event.continueAfterSave ?? false };
+      state.phase = 'draft';
+      break;
+    case 'propose':
+      need(state, ['draft']);
+      // Every machine revision requires confirmation; no heuristic decides meaning.
+      state.proposal.text = event.text;
+      state.proposal.confirmed = false;
+      state.phase = 'confirmation';
+      break;
+    case 'confirm':
+      need(state, ['confirmation']);
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'reject':
+      need(state, ['confirmation']);
+      state.proposal.text = state.answers.find(answer => answer.eventId === state.proposal.originalEventId).text;
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'save':
+      need(state, ['draft']);
+      state.pending = { requestId: event.id, retries: 0 };
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'failed':
+      need(state, ['saving']);
+      state.phase = 'recovery';
+      break;
+    case 'retry':
+      need(state, ['recovery']);
+      if (state.pending.retries >= 1) throw new Error('retry budget exhausted; adapter reconciliation required');
+      state.pending.retries += 1;
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'receipt': {
+      need(state, ['saving', 'recovery']);
+      const expected = writeEffect(state);
+      for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef', 'sourceDigest', 'valueDigest']) {
+        if (event.receipt[key] !== expected[key]) throw new Error(`receipt mismatch: ${key}`);
+      }
+      state.saved.push({ fieldId: expected.fieldId, text: state.proposal.text, receipt: structuredClone(event.receipt) });
+      state.phase = 'saved';
+      state.pending = null;
+      if (state.proposal.continueAfterSave) advance(state);
+      break;
+    }
+    case 'advance':
+      need(state, ['saved']);
+      advance(state);
+      break;
+    case 'pause':
+      need(state, ['input', 'draft', 'confirmation', 'saved', 'recovery']);
+      state.resumePhase = state.phase;
+      state.phase = 'paused';
+      break;
+    case 'resume':
+      need(state, ['paused']);
+      state.phase = state.resumePhase;
+      delete state.resumePhase;
+      break;
+  }
+  state.revision += 1;
+  state.events.push({ id: event.id, fingerprint, event: structuredClone(event) });
+  return { session: state, effects, duplicate: false };
+}
+export function replaySession(config, events) {
+  return events.reduce((session, event) => transition(session, event).session, createSession(config));
+}

package/src/coauthor/store.mjs

@@ -0,0 +1,173 @@
+import { withPrivateLock, publishPrivateFile } from '../project/durable-state.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+import { createSession, transition, contentDigest } from './session.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-coauthor.v1.schema.json', import.meta.url), 'utf8'));
+function validate(value, kind) {
+  const errors = validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}` }, value);
+  if (errors.length) throw new Error(`invalid coauthor ${kind}`);
+}
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+function readText(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > MAX_SOURCE_BYTES) throw new Error('coauthor file exceeds byte limit');
+    return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd));
+  } finally { fs.closeSync(fd); }
+}
+function sourcePath(root, ref) {
+  if (typeof ref !== 'string' || !ref || ref.includes('\\') || path.isAbsolute(ref) || ref.split('/').some(s => !s || s === '.' || s === '..' || s.startsWith('.'))) {
+    throw new Error('source must be a visible workspace-relative file');
+  }
+  let current = root;
+  for (const part of ref.split('/')) {
+    current = path.join(current, part);
+    if (fs.lstatSync(current).isSymbolicLink()) throw new Error('redirected source refused');
+  }
+  return current;
+}
+
+// Local CLI boundary, not an authenticated multi-user service. Responses remain
+// private drafts; this store never modifies a canonical source file.
+export function createCoauthorStore({ workspaceRoot = process.cwd() } = {}) {
+  const root = fs.realpathSync(workspaceRoot);
+  function privatePlacement() {
+    const gitEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      const tracked = execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env: gitEnv, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      if (tracked) throw new Error('tracked private state');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env: gitEnv, stdio: 'ignore' });
+    } catch { throw new Error('coauthor requires a Git workspace with untracked, ignored .atelier-local/ state'); }
+  }
+  privatePlacement();
+  const directory = () => ensureContainedPrivateDirectory({ workspaceRoot: root,
+    directory: path.join(root, '.atelier-local', 'coauthor'), label: 'coauthor state' });
+  const ledger = () => createCollaborationEventLedger({ workspaceRoot: root,
+    ledgerPath: path.join(directory(), 'events.ndjson') });
+  const aggregate = id => `coauthor-${contentDigest(id)}`;
+  function locked(operation) {
+    privatePlacement();
+    const lockPath = path.join(directory(), 'operation.lock');
+    return withPrivateLock(lockPath, operation);
+  }
+  function load(id) {
+    const result = ledger().eventsFor(aggregate(id));
+    if (!result.ok) throw new Error(result.error);
+    if (!result.events.length) throw new Error('coauthor session not found');
+    let state;
+    let previous = null;
+    let version = 0;
+    let config;
+    for (const record of result.events) {
+      if (record.version !== ++version || record.payload.previousEventId !== previous) throw new Error('coauthor event chain is incomplete');
+      if (version === 1) {
+        if (record.type !== 'coauthor.started') throw new Error('coauthor start missing');
+        config = record.payload.config;
+        validate(config, 'config');
+        if (config.id !== id) throw new Error('coauthor identity mismatch');
+        state = createSession(config);
+      } else {
+        if (record.type !== 'coauthor.transition') throw new Error('unknown coauthor record');
+        const next = transition(state, record.payload.event);
+        if (next.duplicate) throw new Error('duplicate persisted transition');
+        state = next.session;
+      }
+      previous = record.id;
+    }
+    return { state, config, version, previous };
+  }
+  function verifySources(config) {
+    for (const field of config.fields) {
+      if (contentDigest(readText(sourcePath(root, field.source.ref))) !== field.source.digest) throw new Error('source changed; preserve history and start a newly bound session');
+    }
+  }
+  function append(id, current, event) {
+    const next = transition(current.state, event);
+    if (next.duplicate) return current;
+    const result = ledger().append({ aggregateId: aggregate(id), expectedVersion: current.version,
+      type: 'coauthor.transition', actor: 'local-harness', payload: { previousEventId: current.previous, event } });
+    if (!result.ok) throw new Error(result.error);
+    return { ...current, state: next.session, version: result.event.version, previous: result.event.id };
+  }
+  function reconcile(id, current) {
+    if (!['saving', 'recovery'].includes(current.state.phase)) return current;
+    verifySources(current.config);
+    const state = current.state;
+    const field = state.fields[state.index];
+    const requestId = state.pending.requestId;
+    const values = ensureContainedPrivateDirectory({ workspaceRoot: root,
+      directory: path.join(directory(), 'values', contentDigest(id)), label: 'coauthor values' });
+    const target = path.join(values, `${contentDigest(requestId)}.json`);
+    const receipt = { sessionId: id, requestId, fieldId: field.id, sourceRef: field.source.ref,
+      sourceDigest: field.source.digest, valueDigest: contentDigest(state.proposal.text) };
+    const saved = { schema: 'atelier-coauthor-draft@v1', status: 'draft', text: state.proposal.text, receipt };
+    validate(saved, 'draft');
+    const bytes = canonicalize(saved);
+    try {
+      // Existing values are immutable. A retry only verifies identical bytes.
+      try {
+        fs.lstatSync(target);
+        if (readText(target) !== bytes) throw new Error('saved draft differs from pending value');
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        publishPrivateFile(target, bytes);
+      }
+      if (readText(target) !== bytes) throw new Error('saved draft readback mismatch');
+      verifySources(current.config);
+    } catch (error) {
+      if (state.phase === 'saving') append(id, current, {
+        id: `failure-${contentDigest(requestId)}-${state.revision}`, expectedRevision: state.revision, type: 'failed',
+      });
+      throw error;
+    }
+    return append(id, current, { id: `receipt-${contentDigest(requestId)}`,
+      expectedRevision: state.revision, type: 'receipt', receipt });
+  }
+  return {
+    start(config) {
+      return locked(() => {
+        validate(config, 'config');
+        const clean = createSession(config);
+        const canonicalConfig = { id: clean.id, fields: clean.fields };
+        verifySources(canonicalConfig);
+        const current = ledger().eventsFor(aggregate(clean.id));
+        if (!current.ok) throw new Error(current.error);
+        if (current.events.length) {
+          const existing = load(clean.id);
+          if (canonicalize(existing.config) !== canonicalize(canonicalConfig)) throw new Error('session id already bound to another configuration');
+          return existing.state;
+        }
+        const result = ledger().append({ aggregateId: aggregate(clean.id), expectedVersion: 0,
+          type: 'coauthor.started', actor: 'local-harness', payload: { previousEventId: null, config: canonicalConfig } });
+        if (!result.ok) throw new Error(result.error);
+        return load(clean.id).state;
+      });
+    },
+    read(id) { return load(id).state; },
+    dispatch(id, event) {
+      return locked(() => {
+        if (['receipt', 'failed'].includes(event?.type)) throw new Error('receipt and failure events are store-owned');
+        const current = load(id);
+        verifySources(current.config);
+        const next = append(id, current, event);
+        // Duplicate historical events never cause repeated effects.
+        if (next === current) return next.state;
+        return ['save', 'retry'].includes(event.type) ? reconcile(id, next).state : next.state;
+      });
+    },
+    recover(id) { return locked(() => {
+      const current = load(id);
+      // Paused and exhausted sessions require an explicit resume or operator
+      // reconciliation. Never turn a read into another automatic write attempt.
+      if (current.state.phase !== 'saving') return current.state;
+      return reconcile(id, current).state;
+    }); },
+  };
+}