@vibecompass/vibecompass 0.3.0 → 0.3.1

package/src/project-memory.js

@@ -468,8 +468,23 @@ function parseDecisionDocument(options) {
   const warnings = [];
   const errors = [];
   const entries = extractDecisionEntries(options.content);
+  const malformedHeadings = extractMalformedDecisionHeadings(options.content);
+
+  for (const heading of malformedHeadings) {
+    errors.push(
+      createError(
+        options.relativePath,
+        'decision-invalid-id',
+        `Decision heading "${heading}" must use zero-padded D-NNN or higher.`,
+      ),
+    );
+  }
 
   if (entries.length === 0) {
+    if (malformedHeadings.length > 0) {
+      return { kind: 'decision', extracted: null, warnings, errors };
+    }
+
     errors.push(
       createError(options.relativePath, 'decision-missing-entries', 'Decision files must contain at least one resolvable decision entry.'),
     );
@@ -479,7 +494,7 @@ function parseDecisionDocument(options) {
   const decisionIds = [];
   for (const entry of entries) {
     if (!entry.decisionId || entry.decisionId <= 0) {
-      errors.push(createError(options.relativePath, 'decision-invalid-id', 'Decision heading must include D-<positive integer>.'));
+      errors.push(createError(options.relativePath, 'decision-invalid-id', 'Decision heading must include zero-padded D-<NNN>.'));
       continue;
     }
 
@@ -576,7 +591,7 @@ function parseSessionDocument(options) {
 }
 
 function extractDecisionEntries(content) {
-  const matches = [...content.matchAll(/^###\s+D-(\d+)\b.*$/gm)];
+  const matches = [...content.matchAll(/^###\s+D-(\d{3,})\b.*$/gm)];
 
   return matches.map((match, index) => {
     const bodyStart = match.index ?? 0;
@@ -590,6 +605,10 @@ function extractDecisionEntries(content) {
   });
 }
 
+function extractMalformedDecisionHeadings(content) {
+  return [...content.matchAll(/^###\s+(D-\d{1,2})\b.*$/gm)].map((match) => match[1]);
+}
+
 function findDuplicateDecisionErrors(documents) {
   const seen = new Map();
   const errors = [];

package/src/read-model.js

@@ -5,7 +5,7 @@ import { generateStateManifest } from './manifest.js';
 import { scanProjectMemory } from './project-memory.js';
 
 const SECTION_PATTERN = /^##\s+(.+)$/gm;
-const DECISION_HEADING_PATTERN = /^###\s+D-(\d+)\s+—\s+(.+)$/gm;
+const DECISION_HEADING_PATTERN = /^###\s+D-(\d{3,})\s+—\s+(.+)$/gm;
 
 export async function loadProjectReadModel(rootDir) {
   const scanResult = await scanProjectMemory(rootDir);

package/src/setup.js

@@ -1,6 +1,10 @@
-import { access } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 export const PLACEMENT_PATTERNS = {
   WORKSPACE_ROOT: 'workspace-root',
@@ -73,6 +77,40 @@ export async function resolveInitCliOptions(options, environment = {}) {
   };
 }
 
+export async function resolveConnectHostedCliOptions(options, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  let resolved = {
+    ...options,
+    sync: isPlainObject(options?.sync) ? { ...options.sync } : {},
+  };
+
+  if (!resolved.sync.apiUrl || !resolved.sync.projectId || !resolved.sync.credentialEnvVar) {
+    const prompter = createPrompter(environment.io, environment.runtime);
+    try {
+      if (!resolved.sync.apiUrl) {
+        resolved.sync.apiUrl = await askInput(prompter, 'Hosted sync API URL', {
+          defaultValue: 'https://vibecompass.dev',
+        });
+      }
+      if (!resolved.sync.projectId) {
+        resolved.sync.projectId = await askInput(prompter, 'Hosted project id');
+      }
+      if (!resolved.sync.credentialEnvVar) {
+        resolved.sync.credentialEnvVar = await askInput(prompter, 'Credential env var', {
+          defaultValue: 'VIBECOMPASS_SYNC_TOKEN',
+        });
+      }
+    } finally {
+      await prompter.close();
+    }
+  }
+
+  return {
+    rootDir: resolved.rootDir ? toRelativeIfInsideCwd(resolved.rootDir, cwd) : undefined,
+    sync: resolved.sync,
+  };
+}
+
 export function applyPlacementDefaults(options, environment = {}) {
   const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
   const resolved = cloneInitOptions(options);
@@ -153,7 +191,8 @@ async function completeGuidedInitOptions(options, environment) {
   let resolved = cloneInitOptions(options);
   const cwd = environment.cwd;
   const prompter = environment.prompter;
-  const projectNameDefault = path.basename(cwd);
+  const inferredProject = await inferProjectFromCwd(cwd);
+  const projectNameDefault = inferredProject.projectName ?? path.basename(cwd);
 
   if (!resolved.name) {
     resolved.name = await askInput(prompter, 'Project name', {
@@ -162,63 +201,82 @@ async function completeGuidedInitOptions(options, environment) {
   }
 
   if (!resolved.mode) {
-    resolved.mode = await askChoice(prompter, 'Project mode', [
+    const setupGoal = await askChoice(prompter, 'What should VibeCompass set up?', [
       {
-        value: 'local-only',
-        description: 'Local files only. No hosted dependency.',
+        value: 'share-later',
+        description: 'Recommended. Local notes, with the option to share or collaborate later.',
       },
       {
-        value: 'local-primary',
-        description: 'Local files stay authoritative, with optional hosted sync/projection.',
+        value: 'local-only',
+        description: 'Local files only. No hosted sync or hosted docs-review prompts.',
       },
       {
         value: 'hosted-only',
-        description: 'Compatibility mode when hosted state remains authoritative.',
+        description: 'Hosted VibeCompass is already the source of truth for this project.',
       },
     ], {
-      defaultValue: 'local-only',
+      defaultValue: 'share-later',
     });
+    resolved.mode = setupGoal === 'share-later' ? 'local-primary' : setupGoal;
   }
 
   if (!Array.isArray(resolved.repos) || resolved.repos.length === 0) {
-    resolved.repos = await promptForRepos(prompter, cwd);
+    if (inferredProject.repo) {
+      const useDetectedRepo = await askConfirm(
+        prompter,
+        `Use detected Git repo ${inferredProject.repo.remote}?`,
+        true,
+      );
+      resolved.repos = useDetectedRepo ? [inferredProject.repo] : await promptForRepos(prompter, cwd);
+    } else {
+      resolved.repos = await promptForRepos(prompter, cwd);
+    }
   }
 
   let recommendation = null;
   if (!resolved.placementPattern) {
-    recommendation = await promptForPlacement(prompter, {
-      cwd,
-      repoCount: resolved.repos.length,
-    });
-    resolved.placementPattern = recommendation.pattern;
+    if (inferredProject.repo && resolved.repos.length === 1) {
+      recommendation = recommendPlacementPattern({ repoCount: 1 });
+      resolved.placementPattern = recommendation.pattern;
+    } else {
+      recommendation = await promptForPlacement(prompter, {
+        cwd,
+        repoCount: resolved.repos.length,
+      });
+      resolved.placementPattern = recommendation.pattern;
+    }
   }
 
   if (!resolved.toolingRootDir) {
-    const ownerLabel = describePlacementOwner(resolved.placementPattern);
-    const defaultOwnerDir = await suggestOwnerDirectory({
-      cwd,
-      placementPattern: resolved.placementPattern,
-      repos: resolved.repos,
-    });
-    resolved.toolingRootDir = await askInput(prompter, ownerLabel, {
-      defaultValue: defaultOwnerDir,
-      validate: async (value) => {
-        if (!(await directoryExists(path.resolve(cwd, value)))) {
-          return `${ownerLabel} must already exist relative to the current working directory.`;
-        }
-
-        return null;
-      },
-    });
+    if (inferredProject.repo && resolved.repos.length === 1 && resolved.placementPattern === PLACEMENT_PATTERNS.PRIMARY_REPO) {
+      resolved.toolingRootDir = '.';
+    } else {
+      const ownerLabel = describePlacementOwner(resolved.placementPattern);
+      const defaultOwnerDir = await suggestOwnerDirectory({
+        cwd,
+        placementPattern: resolved.placementPattern,
+        repos: resolved.repos,
+      });
+      resolved.toolingRootDir = await askInput(prompter, ownerLabel, {
+        defaultValue: defaultOwnerDir,
+        validate: async (value) => {
+          if (!(await directoryExists(path.resolve(cwd, value)))) {
+            return `${ownerLabel} must already exist relative to the current working directory.`;
+          }
+
+          return null;
+        },
+      });
+    }
   }
 
   resolved = applyPlacementDefaults(resolved, { cwd });
 
-  if (!resolved.sync && resolved.mode === 'local-primary') {
+  if (!resolved.sync && resolved.mode === 'hosted-only') {
     const configureSync = await askConfirm(
       prompter,
-      'Configure hosted sync binding now?',
-      false,
+      'Connect hosted VibeCompass now?',
+      resolved.mode === 'hosted-only',
     );
 
     if (configureSync) {
@@ -322,6 +380,63 @@ async function completeGuidedInitOptions(options, environment) {
   };
 }
 
+async function inferProjectFromCwd(cwd) {
+  const [packageName, gitInfo] = await Promise.all([
+    readPackageName(cwd),
+    readGitInfo(cwd),
+  ]);
+  const projectName = packageName ?? path.basename(cwd);
+
+  if (!gitInfo?.remote) {
+    return { projectName, repo: null };
+  }
+
+  const remoteSlug = extractRemoteSlug(gitInfo.remote);
+  const repoId = suggestRepoId(remoteSlug ?? packageName ?? path.basename(gitInfo.root ?? cwd));
+
+  return {
+    projectName,
+    repo: {
+      id: repoId,
+      remote: gitInfo.remote,
+      ...(gitInfo.branch ? { defaultBranch: gitInfo.branch } : {}),
+    },
+  };
+}
+
+async function readPackageName(cwd) {
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(cwd, 'package.json'), 'utf8'));
+    return typeof packageJson.name === 'string' && packageJson.name.trim()
+      ? packageJson.name.trim()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readGitInfo(cwd) {
+  try {
+    const [{ stdout: remote }, { stdout: root }, branchResult] = await Promise.all([
+      execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd }),
+      execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd }),
+      execFileAsync('git', ['branch', '--show-current'], { cwd }).catch(() => ({ stdout: '' })),
+    ]);
+    const normalizedRemote = remote.trim();
+    if (!normalizedRemote) {
+      return null;
+    }
+
+    return {
+      remote: normalizedRemote,
+      root: root.trim() || null,
+      branch: branchResult.stdout.trim() || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
 async function promptForRepos(prompter, cwd) {
   const repoCount = await askInteger(prompter, 'How many repos belong to this logical project?', {
     defaultValue: 1,

package/src/sync.js

@@ -0,0 +1,395 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256Text } from './hash.js';
+import { writeStateManifest } from './manifest.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+
+const DEFAULT_EXPORT_PATH = 'state/pull-export.json';
+
+export async function pushProjectMemory(options = {}, environment = {}) {
+  const context = await loadSyncContext(options, environment);
+  const existingManifest = await readJsonIfPresent(context.manifestPath);
+  const manifestResult = await writeStateManifest(context.rootDir, {
+    sync: existingManifest?.sync,
+  });
+  const manifest = manifestResult.manifest;
+  const documents = await readPushDocuments(context.rootDir, manifest.documents);
+  const baseRemoteRevisionId = normalizeUuid(manifest.sync?.last_successful_remote_revision);
+  const body = {
+    ...(baseRemoteRevisionId ? { base_remote_revision_id: baseRemoteRevisionId } : {}),
+    local_root_revision: manifest.canonical.local_root_revision,
+    manifest_hash: manifest.canonical.manifest_hash,
+    format_version: manifest.canonical.format_version,
+    documents,
+  };
+
+  const response = await postJson(context, 'push', body);
+  const now = new Date().toISOString();
+  const sync = {
+    ...(manifest.sync ?? {}),
+    last_successful_remote_revision: response.remote_revision_id,
+    last_successful_local_root_revision: manifest.canonical.local_root_revision,
+    last_successful_manifest_hash: manifest.canonical.manifest_hash,
+    last_sync_direction: 'push',
+    last_sync_at: now,
+    pending_previews: [],
+  };
+  const updatedManifest = await writeStateManifest(context.rootDir, { sync });
+
+  return {
+    status: response.status ?? 'completed',
+    rootDir: context.rootDir,
+    manifestPath: updatedManifest.manifestPath,
+    runId: response.run_id,
+    remoteRevisionId: response.remote_revision_id,
+    appliedProposalIds: response.applied_proposal_ids ?? [],
+    staleProposalIds: response.stale_proposal_ids ?? [],
+    message: `Pushed ${documents.length} canonical document${documents.length === 1 ? '' : 's'} to hosted project memory.`,
+  };
+}
+
+export async function pullPreviewProjectMemory(options = {}, environment = {}) {
+  const context = await loadSyncContext(options, environment);
+  const existingManifest = await readJsonIfPresent(context.manifestPath);
+  const manifestResult = await writeStateManifest(context.rootDir, {
+    sync: existingManifest?.sync,
+  });
+  const manifest = manifestResult.manifest;
+
+  const response = await postJson(context, 'pull-preview', {
+    state_version: manifest.state_version,
+    base_remote_revision_id: normalizeUuid(manifest.sync?.last_successful_remote_revision),
+    local_root_revision: manifest.canonical.local_root_revision,
+    local_manifest_hash: manifest.canonical.manifest_hash,
+    local_documents: buildLocalDocumentSummaries(manifest.documents),
+    include_pending_proposals: options.includePendingProposals !== false,
+  });
+
+  const previewRecord = {
+    preview_token: response.preview_token,
+    base_remote_revision: response.base_remote_revision_id,
+    target_remote_revision: response.target_remote_revision_id,
+    local_root_revision: manifest.canonical.local_root_revision,
+    local_manifest_hash: manifest.canonical.manifest_hash,
+    state_version: manifest.state_version,
+    authoritative_change_set_hash: response.authoritative_change_set_hash,
+    include_pending_proposals: options.includePendingProposals !== false,
+    available_proposal_ids: Array.isArray(response.proposals)
+      ? response.proposals.map((proposal) => proposal.proposal_id)
+      : [],
+    conflicts: Array.isArray(response.conflicts) ? response.conflicts : [],
+    created_at: response.created_at ?? new Date().toISOString(),
+    expires_at: response.expires_at,
+  };
+  const sync = {
+    ...(manifest.sync ?? {}),
+    pending_previews: [
+      ...(Array.isArray(manifest.sync?.pending_previews) ? manifest.sync.pending_previews : []),
+      previewRecord,
+    ].slice(-5),
+  };
+  const updatedManifest = await writeStateManifest(context.rootDir, { sync });
+
+  return {
+    status: 'preview-created',
+    rootDir: context.rootDir,
+    manifestPath: updatedManifest.manifestPath,
+    previewToken: response.preview_token,
+    proposals: response.proposals ?? [],
+    conflicts: response.conflicts ?? [],
+    warnings: response.warnings ?? [],
+    message: `Created pull preview with ${(response.proposals ?? []).length} pending proposal${(response.proposals ?? []).length === 1 ? '' : 's'}.`,
+  };
+}
+
+export async function pullExportProjectMemory(options = {}, environment = {}) {
+  const context = await loadSyncContext(options, environment);
+  const manifest = await readRequiredManifest(context.manifestPath);
+  const preview = resolvePreview(manifest, options.previewToken);
+  const proposalIds = options.proposalIds?.length
+    ? options.proposalIds
+    : preview.available_proposal_ids ?? [];
+
+  if (proposalIds.length === 0) {
+    throw new Error('pull-export requires at least one --proposal or a preview with available proposals.');
+  }
+
+  const response = await postJson(context, 'pull-export', {
+    preview_token: preview.preview_token,
+    proposal_ids: proposalIds,
+  });
+  const outputPath = path.resolve(context.rootDir, options.outputPath ?? DEFAULT_EXPORT_PATH);
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(response, null, 2)}\n`, 'utf8');
+
+  return {
+    status: 'exported',
+    rootDir: context.rootDir,
+    outputPath,
+    runId: response.run_id,
+    operationCount: Array.isArray(response.operations) ? response.operations.length : 0,
+    proposalIds: response.proposal_ids ?? proposalIds,
+    message: `Exported ${response.operations?.length ?? 0} proposal operation${(response.operations?.length ?? 0) === 1 ? '' : 's'} to ${outputPath}.`,
+  };
+}
+
+export async function applyPullExport(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const outputPath = path.resolve(rootDir, options.outputPath ?? DEFAULT_EXPORT_PATH);
+  const bundle = await readJsonRequired(outputPath, 'pull-export bundle');
+  const operations = Array.isArray(bundle.operations) ? bundle.operations : [];
+  if (operations.length === 0) {
+    throw new Error(`Pull-export bundle at ${outputPath} has no operations.`);
+  }
+
+  const applied = [];
+  for (const operation of operations) {
+    const relativePath = normalizeCanonicalPath(operation.path);
+    const targetPath = path.join(rootDir, relativePath);
+    const currentHash = await readCurrentHash(targetPath);
+    const expectedBefore = operation.before_content_hash ?? null;
+    if (currentHash !== expectedBefore) {
+      throw new Error(
+        `Cannot apply ${relativePath}: local content hash ${currentHash ?? 'missing'} does not match expected ${expectedBefore ?? 'missing'}. Run pull-preview again or resolve locally.`,
+      );
+    }
+
+    if (operation.op === 'delete') {
+      await unlink(targetPath);
+      applied.push({ path: relativePath, status: 'deleted' });
+      continue;
+    }
+
+    if (operation.op !== 'write' || typeof operation.raw_text !== 'string') {
+      throw new Error(`Unsupported operation for ${relativePath}.`);
+    }
+    const afterHash = sha256Text(operation.raw_text);
+    if (afterHash !== operation.after_content_hash) {
+      throw new Error(`Exported content hash does not match raw_text for ${relativePath}.`);
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, ensureTrailingNewline(operation.raw_text), 'utf8');
+    applied.push({ path: relativePath, status: 'written' });
+  }
+
+  bundle.applied_at = new Date().toISOString();
+  bundle.applied = applied;
+  await writeFile(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+
+  return {
+    status: 'applied',
+    rootDir,
+    outputPath,
+    applied,
+    proposalIds: bundle.proposal_ids ?? [],
+    message: `Applied ${applied.length} exported proposal operation${applied.length === 1 ? '' : 's'}. Run vibecompass push to confirm applied proposals.`,
+  };
+}
+
+async function loadSyncContext(options, environment) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const manifestPath = path.join(rootDir, 'state', 'manifest.json');
+  const project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+    sourceName: projectFilePath,
+  });
+
+  if (project.mode !== 'local-primary') {
+    throw new Error('Hosted sync commands require project.yaml mode: local-primary.');
+  }
+  if (
+    !project.sync ||
+    typeof project.sync.api_url !== 'string' ||
+    typeof project.sync.project_id !== 'string' ||
+    typeof project.sync.credential_env_var !== 'string'
+  ) {
+    throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml.');
+  }
+
+  const credential = normalizeOptionalString((environment.env ?? process.env)[project.sync.credential_env_var]);
+  if (!credential) {
+    throw new Error(`Hosted sync command requires ${project.sync.credential_env_var}.`);
+  }
+
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('Hosted sync command requires a fetch implementation.');
+  }
+
+  return {
+    rootDir,
+    project,
+    manifestPath,
+    fetch: fetchImpl,
+    credential,
+    apiUrl: project.sync.api_url,
+    projectId: project.sync.project_id,
+  };
+}
+
+async function postJson(context, routeName, body) {
+  const endpoint = new URL(
+    `api/sync/projects/${encodeURIComponent(context.projectId)}/${routeName}`,
+    ensureTrailingSlash(context.apiUrl),
+  );
+  const response = await context.fetch(endpoint.href, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${context.credential}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const responseText = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted ${routeName} failed with ${response.status}${responseText ? `: ${responseText}` : ''}`);
+  }
+
+  return typeof response.json === 'function' ? response.json() : {};
+}
+
+async function readPushDocuments(rootDir, documents) {
+  const result = [];
+  for (const [relativePath, metadata] of Object.entries(documents)) {
+    const normalizedPath = normalizeCanonicalPath(relativePath);
+    const rawText = await readFile(path.join(rootDir, normalizedPath), 'utf8');
+    result.push({
+      path: normalizedPath,
+      kind: metadata.kind,
+      content_hash: metadata.content_hash,
+      byte_length: metadata.byte_length,
+      raw_text: rawText,
+    });
+  }
+
+  result.sort((left, right) => left.path.localeCompare(right.path));
+  return result;
+}
+
+function buildLocalDocumentSummaries(documents) {
+  return Object.entries(documents ?? {}).map(([relativePath, metadata]) => ({
+    path: normalizeCanonicalPath(relativePath),
+    kind: metadata.kind,
+    content_hash: metadata.content_hash,
+    extracted: buildLocalDocumentExtractedSummary(metadata.kind, metadata.extracted),
+  }));
+}
+
+function buildLocalDocumentExtractedSummary(kind, extracted = {}) {
+  if (!extracted || typeof extracted !== 'object') return {};
+
+  if (kind === 'session') {
+    return {
+      ...(typeof extracted.title === 'string' ? { title: extracted.title } : {}),
+      ...(typeof extracted.session_date === 'string' ? { session_date: extracted.session_date } : {}),
+      ...(Number.isInteger(extracted.session_number)
+        ? { session_number: extracted.session_number }
+        : {}),
+    };
+  }
+
+  if (kind === 'decision') {
+    return {
+      ...(Array.isArray(extracted.decision_ids)
+        ? {
+          decision_ids: extracted.decision_ids.filter(
+            (value) => Number.isInteger(value) && value > 0,
+          ),
+        }
+        : {}),
+    };
+  }
+
+  return {};
+}
+
+function resolvePreview(manifest, previewToken) {
+  const previews = Array.isArray(manifest.sync?.pending_previews)
+    ? manifest.sync.pending_previews
+    : [];
+  if (previewToken) {
+    const match = previews.find((preview) => preview.preview_token === previewToken);
+    if (!match) {
+      throw new Error(`Preview token ${previewToken} was not found in state/manifest.json.`);
+    }
+    return match;
+  }
+
+  const latest = previews[previews.length - 1];
+  if (!latest) {
+    throw new Error('pull-export requires a pending preview. Run vibecompass pull-preview first.');
+  }
+  return latest;
+}
+
+async function readRequiredManifest(manifestPath) {
+  return readJsonRequired(manifestPath, 'state manifest');
+}
+
+async function readJsonRequired(filePath, label) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Could not read ${label} at ${filePath}: ${error.message}`);
+  }
+}
+
+async function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function readCurrentHash(filePath) {
+  try {
+    return sha256Text(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function normalizeCanonicalPath(value) {
+  if (
+    typeof value !== 'string' ||
+    value.startsWith('/') ||
+    value.includes('\\') ||
+    value.split('/').some((part) => part === '..' || part === '') ||
+    value.startsWith('state/') ||
+    value.startsWith('sessions/active/')
+  ) {
+    throw new Error(`Invalid canonical path: ${value}`);
+  }
+
+  return value;
+}
+
+function ensureTrailingNewline(value) {
+  return value.endsWith('\n') ? value : `${value}\n`;
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function normalizeUuid(value) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) return null;
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(normalized)
+    ? normalized
+    : null;
+}
+
+function ensureTrailingSlash(value) {
+  return value.endsWith('/') ? value : `${value}/`;
+}