@logicseek/hello-cc 1.1.0-rc.8 → 1.1.0

package/lib/runtime/private-state.mjs

@@ -12,7 +12,11 @@ const FILE_READ_FLAGS = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW;
 const FILE_CREATE_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT |
   fs.constants.O_EXCL | fs.constants.O_NOFOLLOW;
 const MANIFEST_NAME = '.project-root.json';
-const MANIFEST_VERSION = 1;
+const LEGACY_MANIFEST_VERSION = 1;
+const MANIFEST_VERSION = 2;
+const GENERATION_VERSION = 2;
+const GENERATION_NAME = /^[a-f0-9]{32}$/;
+const DECIMAL_IDENTITY = /^(0|[1-9][0-9]*)$/;
 const AUTHORITY_KINDS = new Set(['pending', 'fresh', 'migrated', 'purging', 'reset']);
 const AUTHORITY_TRANSITIONS = {
   missing: new Set(['pending', 'migrated', 'purging']),
@@ -213,14 +217,117 @@ function optionalDirectory(target, description, {
 }
 
 function expectedManifest(root) {
+  const birthtimeNs = projectBirthtime(root);
+  if (!birthtimeNs) throw forbidden(`Project directory has no stable birth time: ${root.canonical}`);
   return {
     version: MANIFEST_VERSION,
     canonicalRoot: root.canonical,
     dev: root.stat.dev.toString(),
-    ino: root.stat.ino.toString()
+    ino: root.stat.ino.toString(),
+    birthtimeNs
   };
 }
 
+function projectBirthtime(project) {
+  const birthtimeNs = project.stat?.birthtimeNs;
+  return typeof birthtimeNs === 'bigint' && birthtimeNs > 0n ? birthtimeNs.toString() : null;
+}
+
+function validBirthtime(value) {
+  return typeof value === 'string' && /^[1-9][0-9]*$/.test(value);
+}
+
+function generationParent(base) {
+  return `${base}.generations`;
+}
+
+function validGenerationMarker(value, canonical, id) {
+  return value?.version === GENERATION_VERSION && value.generation === id &&
+    value.canonicalRoot === canonical && DECIMAL_IDENTITY.test(value.dev) &&
+    DECIMAL_IDENTITY.test(value.ino) && validBirthtime(value.birthtimeNs) &&
+    AUTHORITY_KINDS.has(value.kind);
+}
+
+function generationBinding(project, home) {
+  if (!project.stat) return null;
+  const base = statePath(project.canonical, home);
+  const parent = generationParent(base);
+  let entries;
+  try {
+    fs.lstatSync(parent);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw inspectError(error, 'private project generations', parent);
+  }
+  inspectDirectory(parent, 'private project generations', { mode: 0o700 });
+  try { entries = fs.readdirSync(parent); }
+  catch (error) { throw inspectError(error, 'private project generations', parent); }
+  if (entries.length > 256) throw forbidden(`Too many private project generations: ${parent}`);
+  const names = new Set(entries);
+  const markers = new Set();
+  let matched = null;
+  for (const name of entries) {
+    if (!name.endsWith('.authority.json')) continue;
+    const id = name.slice(0, -'.authority.json'.length);
+    if (!GENERATION_NAME.test(id)) throw forbidden(`Invalid private project generation: ${parent}`);
+    markers.add(id);
+    const actual = readManifest(path.join(parent, name));
+    if (!validGenerationMarker(actual, project.canonical, id)) {
+      throw forbidden(`Invalid private project generation marker: ${path.join(parent, name)}`);
+    }
+    if (actual.dev === project.stat.dev.toString() && actual.ino === project.stat.ino.toString() &&
+        actual.birthtimeNs === projectBirthtime(project)) {
+      if (matched) throw forbidden(`Ambiguous private project generation: ${project.canonical}`);
+      matched = { directory: path.join(parent, id), marker: path.join(parent, name),
+        generation: id, authority: actual, parent };
+    }
+  }
+  for (const name of entries) {
+    if (GENERATION_NAME.test(name)) {
+      if (!markers.has(name)) throw forbidden(`Unbound private project generation: ${path.join(parent, name)}`);
+      const entry = fs.lstatSync(path.join(parent, name));
+      if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw forbidden(`Invalid private project generation directory: ${path.join(parent, name)}`);
+      }
+    } else if (!name.endsWith('.authority.json')) {
+      throw forbidden(`Unexpected private project generation entry: ${path.join(parent, name)}`);
+    }
+  }
+  const fence = readManifest(`${base}.authority.json`);
+  if (fence?.version !== GENERATION_VERSION ||
+      !['legacy-v1', 'legacy-v2'].includes(fence.fence) ||
+      fence.canonicalRoot !== project.canonical || !DECIMAL_IDENTITY.test(fence.dev) ||
+      !DECIMAL_IDENTITY.test(fence.ino) || !AUTHORITY_KINDS.has(fence.kind) ||
+      (fence.fence === 'legacy-v1' ? fence.birthtimeNs !== null
+        : !validBirthtime(fence.birthtimeNs))) {
+    throw forbidden(`Private project generation fence is missing or invalid: ${base}`);
+  }
+  return matched;
+}
+
+function projectStateBinding(project, home) {
+  return generationBinding(project, home) || {
+    directory: statePath(project.canonical, home),
+    marker: `${statePath(project.canonical, home)}.authority.json`,
+    generation: null,
+    parent: path.join(home, '.hello-cc', 'projects')
+  };
+}
+
+function expectedGenerationManifest(project, generation) {
+  const birthtimeNs = projectBirthtime(project);
+  if (!birthtimeNs) throw forbidden(`Project directory has no stable birth time: ${project.canonical}`);
+  return { version: GENERATION_VERSION, canonicalRoot: project.canonical,
+    dev: project.stat.dev.toString(), ino: project.stat.ino.toString(),
+    birthtimeNs, generation };
+}
+
+function expectedBindingManifest(project, binding) {
+  return binding.generation
+    ? expectedGenerationManifest(project, binding.generation)
+    : expectedManifest(project);
+}
+
 function readManifest(manifestPath) {
   let before;
   try { before = fs.lstatSync(manifestPath, { bigint: true }); }
@@ -253,7 +360,7 @@ function readManifest(manifestPath) {
   }
 }
 
-function ensureManifest(directory, root, create) {
+function ensureManifest(directory, root, create, binding) {
   const manifestPath = path.join(directory, MANIFEST_NAME);
   let exists;
   try { fs.lstatSync(manifestPath); exists = true; }
@@ -265,12 +372,12 @@ function ensureManifest(directory, root, create) {
     if (!create || fs.readdirSync(directory).length !== 0) {
       throw forbidden(`Project state directory has no binding manifest: ${directory}`);
     }
-    const temporary = path.join(path.dirname(directory),
+    const temporary = path.join(path.dirname(binding.parent),
       `.${path.basename(directory)}.manifest-tmp-${randomBytes(16).toString('hex')}`);
     let fd;
     try {
       fd = fs.openSync(temporary, FILE_CREATE_FLAGS, 0o600);
-      fs.writeFileSync(fd, `${JSON.stringify(expectedManifest(root))}\n`);
+      fs.writeFileSync(fd, `${JSON.stringify(expectedBindingManifest(root, binding))}\n`);
       fs.fchmodSync(fd, 0o600);
       fs.fsyncSync(fd);
       fs.closeSync(fd);
@@ -285,9 +392,16 @@ function ensureManifest(directory, root, create) {
     }
   }
   const actual = readManifest(manifestPath);
-  const expected = expectedManifest(root);
+  const expected = expectedBindingManifest(root, binding);
+  if (!binding.generation && actual?.version === LEGACY_MANIFEST_VERSION) {
+    throw new CliError('STATE_BINDING_UPGRADE_REQUIRED',
+      `Historical private project state requires explicit offline identity upgrade: ${directory}`);
+  }
   if (actual?.version !== expected.version || actual.canonicalRoot !== expected.canonicalRoot ||
-      actual.dev !== expected.dev || actual.ino !== expected.ino) {
+      actual.dev !== expected.dev || actual.ino !== expected.ino ||
+      (!binding.generation && actual.birthtimeNs !== expected.birthtimeNs) ||
+      (binding.generation && (actual.birthtimeNs !== expected.birthtimeNs ||
+        actual.generation !== expected.generation))) {
     throw forbidden(`Project root identity differs from private state binding: ${root.canonical}. ` +
       'Back up the old private store and authority marker, stop all writers, and review both root identities ' +
       'before manual recovery; automatic rebinding is refused.');
@@ -298,7 +412,8 @@ function assertProjectUnchanged(root) {
   let current;
   try { current = canonicalProjectRoot(root.requested); }
   catch { throw forbidden(`Project root changed during private state validation: ${root.requested}`); }
-  if (current.canonical !== root.canonical || !sameIdentity(current.stat, root.stat)) {
+  if (current.canonical !== root.canonical || !sameIdentity(current.stat, root.stat) ||
+      projectBirthtime(current) !== projectBirthtime(root)) {
     throw forbidden(`Project root changed during private state validation: ${root.requested}`);
   }
 }
@@ -307,24 +422,188 @@ function assertProjectUnchanged(root) {
 // path solely for hashing; state access always requires an existing directory.
 export function privateProjectStateDir(root) {
   const project = canonicalProjectRoot(root, { allowMissing: true });
-  return statePath(project.canonical, canonicalHome({ allowMissing: true }));
+  return projectStateBinding(project, canonicalHome({ allowMissing: true })).directory;
 }
 
 export function privateProjectAuthorityPath(root) {
-  return `${privateProjectStateDir(root)}.authority.json`;
+  const project = canonicalProjectRoot(root, { allowMissing: true });
+  return projectStateBinding(project, canonicalHome({ allowMissing: true })).marker;
+}
+
+export function privateProjectStateManifest(root) {
+  const project = canonicalProjectRoot(root);
+  return expectedBindingManifest(project, projectStateBinding(project, canonicalHome()));
+}
+
+export function privateProjectGenerationFromPath(value) {
+  if (typeof value !== 'string' || !value) return null;
+  return value.match(/(?:^|[/\\])[a-f0-9]{64}\.generations[/\\]([a-f0-9]{32})(?:[/\\]|$)/)?.[1] || null;
+}
+
+function upgradeReceipt(project, kind) {
+  return createHash('sha256').update(JSON.stringify({
+    operation: 'private-binding-v1-to-v2',
+    canonicalRoot: project.canonical,
+    dev: project.stat.dev.toString(),
+    ino: project.stat.ino.toString(),
+    birthtimeNs: projectBirthtime(project),
+    kind
+  })).digest('hex');
+}
+
+function inspectBindingUpgrade(project, home) {
+  inspectHomeAncestry(home);
+  const global = path.join(home, '.hello-cc');
+  const projects = path.join(global, 'projects');
+  if (!optionalDirectory(global, 'global state directory', {
+    create: false, mode: 0o700, allowReadOnlyPublic: true
+  }) || !optionalDirectory(projects, 'private projects directory', {
+    create: false, mode: 0o700
+  })) return { status: 'not-required', receipt: null };
+  const base = statePath(project.canonical, home);
+  const marker = `${base}.authority.json`;
+  let markerExists = false;
+  try { fs.lstatSync(marker); markerExists = true; }
+  catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  if (!markerExists) {
+    try { fs.lstatSync(base); }
+    catch (storeError) {
+      if (storeError?.code === 'ENOENT') return { status: 'not-required', receipt: null };
+      throw inspectError(storeError, 'private project state', base);
+    }
+    throw forbidden(`Historical private project state has no authority marker: ${base}`);
+  }
+  const authority = readManifest(marker);
+  inspectDirectory(base, 'historical private project state', { mode: 0o700 });
+  if (authority.version === LEGACY_MANIFEST_VERSION && authority.kind === 'pending') {
+    let manifestPresent = false;
+    try { fs.lstatSync(path.join(base, MANIFEST_NAME)); manifestPresent = true; }
+    catch (error) {
+      if (error?.code !== 'ENOENT') throw inspectError(error, 'project state manifest', base);
+    }
+    if (!manifestPresent) {
+      throw new CliError('STATE_BINDING_MANUAL_RECOVERY_REQUIRED',
+        `Historical v1 initialization has no committed root manifest: ${base}. ` +
+        'Cold-drain writers, back up the root, private directory and authority marker, ' +
+        'and inspect any project-local legacy state before manual recovery. ' +
+        'Do not purge or fabricate a v2 marker.');
+    }
+  }
+  const manifest = readManifest(path.join(base, MANIFEST_NAME));
+  const identity = expectedManifest(project);
+  const kind = authority.kind ?? 'migrated';
+  if (!['fresh', 'migrated'].includes(kind) ||
+      authority.canonicalRoot !== project.canonical ||
+      authority.dev !== identity.dev || authority.ino !== identity.ino ||
+      manifest.canonicalRoot !== project.canonical ||
+      manifest.dev !== identity.dev || manifest.ino !== identity.ino) {
+    throw forbidden(`Cannot assert that current root owns historical private state: ${base}`);
+  }
+  if (authority.version === MANIFEST_VERSION && authority.fence === undefined &&
+      manifest.version === MANIFEST_VERSION && authority.birthtimeNs === identity.birthtimeNs &&
+      manifest.birthtimeNs === identity.birthtimeNs) {
+    return { status: 'already-current', receipt: null, stateDir: base };
+  }
+  const receipt = upgradeReceipt(project, kind);
+  const historical = authority.version === LEGACY_MANIFEST_VERSION &&
+    manifest.version === LEGACY_MANIFEST_VERSION;
+  const pending = authority.version === MANIFEST_VERSION &&
+    authority.fence === 'upgrade-pending' && authority.upgradeReceipt === receipt &&
+    authority.birthtimeNs === identity.birthtimeNs &&
+    (manifest.version === LEGACY_MANIFEST_VERSION ||
+      (manifest.version === MANIFEST_VERSION && manifest.birthtimeNs === identity.birthtimeNs));
+  if (!historical && !pending) {
+    throw forbidden(`Private binding upgrade state needs manual recovery: ${base}`);
+  }
+  return {
+    status: pending ? 'pending' : 'required', receipt, stateDir: base,
+    canonicalRoot: project.canonical,
+    rootIdentity: { dev: identity.dev, ino: identity.ino,
+      birthtimeNs: identity.birthtimeNs },
+    warning: 'Receipt records current filesystem metadata, not proof that this root is historical A. '
+      + 'Proceed only after verifying A independently and cold-draining every old writer.'
+  };
+}
+
+export function inspectPrivateProjectBindingUpgrade(root) {
+  const project = canonicalProjectRoot(root);
+  return inspectBindingUpgrade(project, canonicalHome());
+}
+
+export function upgradePrivateProjectBinding(root, {
+  confirmedOffline = false, confirmedHistoricalRoot = false,
+  expectedReceipt = null, assertOffline = null
+} = {}) {
+  if (!confirmedOffline || !confirmedHistoricalRoot ||
+      typeof expectedReceipt !== 'string' || !/^[a-f0-9]{64}$/.test(expectedReceipt) ||
+      typeof assertOffline !== 'function') {
+    throw new CliError('STATE_BINDING_UPGRADE_CONFIRMATION_REQUIRED',
+      'Private binding upgrade requires --offline, --yes, --assert-historical-root and an exact inspection receipt');
+  }
+  const project = canonicalProjectRoot(root);
+  const original = expectedManifest(project);
+  return withPrivateProjectStateTransition(root, ({ projects, home }) => {
+    assertFullProjectIdentity(project);
+    const inspected = inspectBindingUpgrade(project, home);
+    if (inspected.status === 'already-current' || inspected.status === 'not-required') return inspected;
+    if (inspected.receipt !== expectedReceipt ||
+        original.birthtimeNs !== inspected.rootIdentity.birthtimeNs) {
+      throw new CliError('STATE_BINDING_UPGRADE_RECEIPT_MISMATCH',
+        'Private binding inspection receipt or root identity changed; inspect again before upgrading');
+    }
+    if (assertOffline({ phase: 'before', stateDir: inspected.stateDir }) !== true) {
+      throw new CliError('STATE_BINDING_UPGRADE_OFFLINE_REQUIRED',
+        'Cannot establish cold-drained private state');
+    }
+    const marker = `${inspected.stateDir}.authority.json`;
+    const manifestPath = path.join(inspected.stateDir, MANIFEST_NAME);
+    let authority = readManifest(marker);
+    if (inspected.status === 'required') {
+      publishPrivateManifest(marker, { ...original, kind: authority.kind ?? 'migrated',
+        fence: 'upgrade-pending', upgradeReceipt: expectedReceipt }, projects, authority);
+      authority = readManifest(marker);
+    }
+    // Once the fence is durable, v1 readers reject the store. A crash in this
+    // gap leaves a retryable pending state; v2 readers also reject it.
+    const manifest = readManifest(manifestPath);
+    if (manifest.version === LEGACY_MANIFEST_VERSION) {
+      publishPrivateManifest(manifestPath, original, inspected.stateDir, manifest);
+    }
+    assertFullProjectIdentity(project);
+    if (assertOffline({ phase: 'after', stateDir: inspected.stateDir }) !== true) {
+      throw new CliError('STATE_BINDING_UPGRADE_OFFLINE_REQUIRED',
+        'Private binding remains fenced because offline evidence changed');
+    }
+    publishPrivateManifest(marker, { ...original, kind: authority.kind }, projects, authority);
+    assertFullProjectIdentity(project);
+    return { status: 'upgraded', stateDir: inspected.stateDir,
+      canonicalRoot: project.canonical, rootIdentity: inspected.rootIdentity };
+  });
 }
 
 export function inspectPrivateProjectAuthority(root) {
   const project = canonicalProjectRoot(root);
-  const marker = privateProjectAuthorityPath(project.canonical);
+  const binding = projectStateBinding(project, canonicalHome());
+  const marker = binding.marker;
   try { fs.lstatSync(marker); }
   catch (error) {
     if (error?.code === 'ENOENT') return null;
     throw inspectError(error, 'project authority marker', marker);
   }
   const actual = readManifest(marker);
-  const expected = expectedManifest(project);
-  if (actual?.version !== expected.version || actual.canonicalRoot !== expected.canonicalRoot ||
+  const expected = expectedBindingManifest(project, binding);
+  if (!binding.generation && actual?.version === LEGACY_MANIFEST_VERSION) {
+    throw new CliError('STATE_BINDING_UPGRADE_REQUIRED',
+      `Historical private project state requires explicit offline identity upgrade: ${marker}`);
+  }
+  const valid = binding.generation
+    ? actual?.version === expected.version && actual?.generation === expected.generation &&
+      actual?.birthtimeNs === expected.birthtimeNs
+    : actual?.version === expected.version && actual?.birthtimeNs === expected.birthtimeNs &&
+      (actual.fence === undefined || actual.fence === 'legacy-v2');
+  if (!valid || actual.canonicalRoot !== expected.canonicalRoot ||
       actual.dev !== expected.dev || actual.ino !== expected.ino) {
     throw forbidden(`Project authority marker differs from project root: ${marker}. ` +
       'Back up the old private store and authority marker, stop all writers, and review both root identities ' +
@@ -344,16 +623,141 @@ function fsyncDirectory(directory) {
   finally { fs.closeSync(fd); }
 }
 
+function publishPrivateManifest(marker, contents, parent, expected = null) {
+  const temporary = path.join(path.dirname(parent),
+    `.${path.basename(marker)}.tmp-${randomBytes(16).toString('hex')}`);
+  let fd;
+  try {
+    fd = fs.openSync(temporary, FILE_CREATE_FLAGS, 0o600);
+    fs.writeFileSync(fd, `${JSON.stringify(contents)}\n`);
+    fs.fchmodSync(fd, 0o600);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    if (expected && JSON.stringify(readManifest(marker)) !== JSON.stringify(expected)) {
+      throw forbidden(`Private project marker changed during publication: ${marker}`);
+    }
+    fs.renameSync(temporary, marker);
+    fsyncDirectory(parent);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try { fs.unlinkSync(temporary); } catch { /* An inert private temp is safe to leave. */ }
+  }
+}
+
+function assertFullProjectIdentity(project, selected = null) {
+  const current = canonicalProjectRoot(project.requested);
+  if (current.canonical !== project.canonical || !sameIdentity(current.stat, project.stat) ||
+      projectBirthtime(current) !== projectBirthtime(project) ||
+      (selected && (selected.canonical !== project.canonical ||
+        selected.identity?.dev !== project.stat.dev.toString() ||
+        selected.identity?.ino !== project.stat.ino.toString() ||
+        selected.identity?.birthtimeNs !== projectBirthtime(project)))) {
+    throw forbidden(`Project root changed during private generation selection: ${project.requested}`);
+  }
+}
+
+// A replacement root gets a separate store only after an explicit selection.
+// The v2 fence at the v1 pathname makes older binaries reject *both* roots,
+// while retaining A's original directory and manifest byte-for-byte.
+export function provisionPrivateProjectGeneration(root, { expectedIdentity = null } = {}) {
+  const project = canonicalProjectRoot(root);
+  // Refuse unknown creation times before fencing an old binding or creating
+  // generation records. Zero is an unavailable value, not a stable identity.
+  expectedManifest(project);
+  assertFullProjectIdentity(project, expectedIdentity);
+  const home = canonicalHome();
+  const base = statePath(project.canonical, home);
+  return withPrivateProjectStateTransition(project.requested, ({ projects }) => {
+    assertFullProjectIdentity(project, expectedIdentity);
+    const existing = generationBinding(project, home);
+    if (existing) return existing.directory;
+    const marker = `${base}.authority.json`;
+    let markerExists = false;
+    try { fs.lstatSync(marker); markerExists = true; }
+    catch (error) { if (error?.code !== 'ENOENT') throw inspectError(error, 'project authority marker', marker); }
+    if (!markerExists) {
+      try { fs.lstatSync(base); }
+      catch (error) { if (error?.code === 'ENOENT') return null; throw inspectError(error, 'private project state', base); }
+      throw forbidden(`Historical private project state has no authority marker: ${base}`);
+    }
+    let old;
+    old = readManifest(marker);
+    if (![LEGACY_MANIFEST_VERSION, GENERATION_VERSION].includes(old.version) ||
+        (old.version === GENERATION_VERSION &&
+          ((old.fence && !['legacy-v1', 'legacy-v2'].includes(old.fence)) ||
+            (old.fence !== 'legacy-v1' && !validBirthtime(old.birthtimeNs)))) ||
+        old.canonicalRoot !== project.canonical ||
+        !DECIMAL_IDENTITY.test(old.dev) || !DECIMAL_IDENTITY.test(old.ino) ||
+        !['fresh', 'migrated'].includes(old.version === LEGACY_MANIFEST_VERSION
+          ? old.kind ?? 'migrated' : old.kind)) {
+      throw forbidden(`Existing private project authority requires recovery: ${marker}`);
+    }
+    if (old.version === LEGACY_MANIFEST_VERSION) {
+      throw new CliError('STATE_BINDING_UPGRADE_REQUIRED',
+        `Historical v1 private state must be upgraded before selecting a replacement root: ${marker}. ` +
+        'Restore and independently confirm historical A at this canonical path, cold-drain every writer, ' +
+        'run migrate-state --inspect-private-binding, then migrate-state --upgrade-private-binding ' +
+        '--offline --yes --assert-historical-root --expect-receipt=SHA256, and only then select B. ' +
+        'Matching dev/ino alone does not prove the current root is A.');
+    }
+    if (old.fence === 'legacy-v1') {
+      throw new CliError('STATE_BINDING_MANUAL_RECOVERY_REQUIRED',
+        `A historical v1 store was already fenced without a saved root birth time: ${marker}. ` +
+        'Preserve both stores, cold-drain writers, and review the original A root and generation records ' +
+        'before manual recovery; further automatic provisioning is refused.');
+    }
+    if (old.dev === project.stat.dev.toString() && old.ino === project.stat.ino.toString()) {
+      if (old.birthtimeNs === projectBirthtime(project) && old.fence !== 'legacy-v1') {
+        return null; // The fully identified original v2 root is still selected.
+      }
+      if (old.birthtimeNs === null) {
+        throw forbidden(`Historical project identity is ambiguous after fencing: ${project.canonical}`);
+      }
+    }
+    inspectDirectory(base, 'historical private project state', { mode: 0o700 });
+    const oldManifest = readManifest(path.join(base, MANIFEST_NAME));
+    if (oldManifest.version !== MANIFEST_VERSION || oldManifest.canonicalRoot !== old.canonicalRoot ||
+        oldManifest.dev !== old.dev || oldManifest.ino !== old.ino ||
+        oldManifest.birthtimeNs !== old.birthtimeNs) {
+      throw forbidden(`Historical private project state does not match its authority: ${base}`);
+    }
+    if (!old.fence) {
+      publishPrivateManifest(marker, { ...old, fence: 'legacy-v2' }, projects, old);
+    }
+    const parent = generationParent(base);
+    optionalDirectory(parent, 'private project generations', {
+      create: true, mode: 0o700, tighten: true
+    });
+    fsyncDirectory(projects);
+    const id = randomBytes(16).toString('hex');
+    const generationMarker = path.join(parent, `${id}.authority.json`);
+    if (fs.existsSync(generationMarker) || fs.existsSync(path.join(parent, id))) {
+      throw forbidden(`Private project generation identifier already exists: ${id}`);
+    }
+    publishPrivateManifest(generationMarker,
+      { ...expectedGenerationManifest(project, id), kind: 'pending' }, parent);
+    assertFullProjectIdentity(project, expectedIdentity);
+    return path.join(parent, id);
+  });
+}
+
 function writePrivateProjectAuthorityKind(project, home, projects, kind) {
   if (!AUTHORITY_KINDS.has(kind)) throw forbidden(`Invalid project authority kind: ${kind}`);
-  const marker = `${statePath(project.canonical, home)}.authority.json`;
+  const binding = projectStateBinding(project, home);
+  const marker = binding.marker;
   const current = inspectPrivateProjectAuthority(project.canonical);
   if (current === kind) return marker;
   if (!AUTHORITY_TRANSITIONS[current ?? 'missing']?.has(kind)) {
     throw forbidden(`Invalid project authority transition ${current ?? 'missing'} -> ${kind}: ${marker}`);
   }
-  const contents = `${JSON.stringify({ ...expectedManifest(project), kind })}\n`;
-  const temporary = `${marker}.tmp-${randomBytes(16).toString('hex')}`;
+  const previous = current === null ? null : readManifest(marker);
+  const manifest = binding.generation
+    ? expectedGenerationManifest(project, binding.generation)
+    : { ...expectedManifest(project), ...(previous?.fence ? { fence: previous.fence } : {}) };
+  const contents = `${JSON.stringify({ ...manifest, kind })}\n`;
+  const temporary = path.join(path.dirname(binding.parent),
+    `.${path.basename(marker)}.tmp-${randomBytes(16).toString('hex')}`);
   let fd;
   try {
     fd = fs.openSync(temporary, FILE_CREATE_FLAGS, 0o600);
@@ -374,7 +778,7 @@ function writePrivateProjectAuthorityKind(project, home, projects, kind) {
     if (fd !== undefined) fs.closeSync(fd);
     try { fs.unlinkSync(temporary); } catch { /* A private temp is inert. */ }
   }
-  fsyncDirectory(projects);
+  fsyncDirectory(binding.parent);
   assertProjectUnchanged(project);
   return marker;
 }
@@ -395,12 +799,13 @@ export function withPrivateProjectStateTransition(root, fn) {
   optionalDirectory(projects, 'private projects directory', {
     create: true, mode: 0o700, tighten: true
   });
-  const directory = statePath(project.canonical, home);
-  return withFileLock(`${directory}.transition`, () => {
+  const legacyDirectory = statePath(project.canonical, home);
+  return withFileLock(`${legacyDirectory}.transition`, () => {
     inspectHomeAncestry(home);
     inspectDirectory(global, 'global state directory', { mode: 0o700 });
     inspectDirectory(projects, 'private projects directory', { mode: 0o700 });
     assertProjectUnchanged(project);
+    const directory = projectStateBinding(project, home).directory;
     const result = fn({
       directory, projects, project, home,
       authorityKind: () => inspectPrivateProjectAuthority(project.canonical),
@@ -448,7 +853,8 @@ function inspectPrivateProjectStateDir(project, home, create, setAuthorityKind =
   inspectHomeAncestry(home);
   const global = path.join(home, '.hello-cc');
   const projects = path.join(global, 'projects');
-  const directory = statePath(project.canonical, home);
+  const binding = projectStateBinding(project, home);
+  const directory = binding.directory;
 
   // A pre-existing 0755 global directory can be read without mutation. Only
   // create mode may tighten it, and writable-by-others directories are rejected.
@@ -483,6 +889,11 @@ function inspectPrivateProjectStateDir(project, home, create, setAuthorityKind =
       if (error?.code !== 'ENOENT') throw inspectError(error, 'project state manifest', directory);
     }
   }
+  if (manifestExists && authority === null && !binding.generation &&
+      readManifest(path.join(directory, MANIFEST_NAME)).version === LEGACY_MANIFEST_VERSION) {
+    throw new CliError('STATE_BINDING_UPGRADE_REQUIRED',
+      `Markerless historical private state requires reviewed offline recovery: ${directory}`);
+  }
   if (create && !manifestExists) {
     // Resolver callers also check the legacy source. Repeat at the actual
     // transition boundary: a concurrent purge can invalidate their earlier
@@ -506,9 +917,9 @@ function inspectPrivateProjectStateDir(project, home, create, setAuthorityKind =
     create: Boolean(create), mode: 0o700, tighten: true
   })) return null;
 
-  ensureManifest(directory, project, Boolean(create));
+  ensureManifest(directory, project, Boolean(create), binding);
   if (create && (authority === null || authority === 'pending' || authority === 'reset')) {
-    fsyncDirectory(projects);
+    fsyncDirectory(binding.parent);
     setAuthorityKind('fresh');
   }
   assertProjectUnchanged(project);
@@ -526,7 +937,7 @@ export function ensurePrivateProjectStateDir(root, { create = false } = {}) {
 // The purging marker is a durable intent record. If deletion is interrupted,
 // normal state access stays closed and an explicit purge retry completes it.
 export function purgePrivateProjectState(root) {
-  return withPrivateProjectStateTransition(root, ({ directory, projects, authorityKind, setAuthorityKind }) => {
+  return withPrivateProjectStateTransition(root, ({ directory, authorityKind, setAuthorityKind }) => {
     // The directory may be partially deleted after an earlier crash, so its
     // manifest need not remain. Its private ownership and no-follow identity
     // are still required before recursive deletion.
@@ -539,7 +950,7 @@ export function purgePrivateProjectState(root) {
     authorityKind();
     setAuthorityKind('purging');
     fs.rmSync(directory, { recursive: true, force: true });
-    fsyncDirectory(projects);
+    fsyncDirectory(path.dirname(directory));
     setAuthorityKind('reset');
     return directory;
   });

package/lib/runtime/project-path.mjs

@@ -221,13 +221,15 @@ function validateDatabaseTarget(stateDir, db) {
   }
 }
 
-export function resolveProjectDatabase({ root, db, createStateDir = false, createDatabaseParents = false }) {
+function databaseLocation({ root, db }) {
   const requestedRoot = path.resolve(String(root || ''));
   const canonicalRoot = canonicalProjectRoot(requestedRoot);
   const rawDb = path.resolve(String(db || path.join(requestedRoot, '.hello-cc', 'mesh.db')));
   const intendedStateDir = projectStateDir(canonicalRoot);
   const requestedLegacyState = legacyProjectStateDir(requestedRoot);
   const canonicalLegacyState = legacyProjectStateDir(canonicalRoot);
+  const legacySpelling = pathIsWithin(requestedLegacyState, rawDb) ||
+    pathIsWithin(canonicalLegacyState, rawDb);
   let requestedDb = pathIsWithin(requestedLegacyState, rawDb)
     ? path.join(intendedStateDir, path.relative(requestedLegacyState, rawDb))
     : pathIsWithin(canonicalLegacyState, rawDb)
@@ -246,6 +248,56 @@ export function resolveProjectDatabase({ root, db, createStateDir = false, creat
   if (!pathIsWithin(intendedStateDir, requestedDb)) {
     throw projectPathForbidden(`Database path must live under ${intendedStateDir}`);
   }
+  return { canonicalRoot, intendedStateDir, requestedDb, legacySpelling };
+}
+
+// Check an explicitly requested DB path without creating a state directory,
+// claiming a generation, or tightening permissions. The mutating resolver
+// repeats all checks after selection; this is an admission guard, not a grant.
+export function prevalidateProjectDatabaseLocation({ root, db }) {
+  const location = databaseLocation({ root, db });
+  const { canonicalRoot, intendedStateDir, requestedDb, legacySpelling } = location;
+  // A direct private path from A must not be used to provision replacement B.
+  // A legacy spelling is remapped to B's new generation after selection.
+  if (!legacySpelling && intendedStateDir !== legacyProjectStateDir(canonicalRoot)) {
+    inspectPrivateProjectAuthority(canonicalRoot);
+  }
+  const canonicalCandidate = canonicalCandidateFromExistingParent(requestedDb);
+  if (!canonicalCandidate || !pathIsWithin(intendedStateDir, canonicalCandidate)) {
+    throw projectPathForbidden(`Database path escapes project state directory: ${requestedDb}`);
+  }
+  for (let current = intendedStateDir;;) {
+    let stat;
+    try { stat = fs.lstatSync(current); }
+    catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw projectPathForbidden(`Cannot inspect database parent: ${current}`);
+      }
+    }
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+      throw projectPathForbidden(`Database parent must be a real directory: ${current}`);
+    }
+    if (current === path.dirname(requestedDb)) break;
+    const next = path.join(current, path.relative(current, path.dirname(requestedDb)).split(path.sep)[0]);
+    if (next === current) throw projectPathForbidden(`Invalid database parent: ${requestedDb}`);
+    current = next;
+  }
+  try {
+    const target = fs.lstatSync(requestedDb);
+    if (target.isSymbolicLink() || !target.isFile()) {
+      throw projectPathForbidden(`Project database must be a regular file: ${requestedDb}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      if (error instanceof CliError) throw error;
+      throw projectPathForbidden(`Cannot inspect project database: ${requestedDb}`);
+    }
+  }
+  return location;
+}
+
+export function resolveProjectDatabase({ root, db, createStateDir = false, createDatabaseParents = false }) {
+  const { canonicalRoot, intendedStateDir, requestedDb } = databaseLocation({ root, db });
   const state = ensureStateDirectory(canonicalRoot, Boolean(createStateDir));
   if (!state.exists) {
     return { root: canonicalRoot, stateDir: state.stateDir, db: requestedDb };