@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/project/durable-state.mjs

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow, syncPrivateDirectory } from './private-state.mjs';
+
+const host = createHash('sha256').update(hostname()).digest('hex');
+const pendingPattern = /^\.atelier-write-[a-f0-9-]{36}\.tmp$/;
+export const isPendingPrivateWrite = name => pendingPattern.test(name);
+
+export { syncPrivateDirectory };
+
+// Publish a complete immutable file with an atomic, non-overwriting hard link.
+// A process interruption can leave a private staging file, never a partial final.
+export function publishPrivateFile(file, bytes) {
+  const directory = path.dirname(file);
+  const pending = path.join(directory, `.atelier-write-${randomUUID()}.tmp`);
+  let fd;
+  try {
+    fd = openRegularFileNoFollow(pending, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    try { fs.linkSync(pending, file); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const existing = openRegularFileNoFollow(file);
+      try { if (!fs.readFileSync(existing).equals(Buffer.from(bytes))) throw error; }
+      finally { fs.closeSync(existing); }
+    }
+    syncPrivateDirectory(directory);
+    const actual = openRegularFileNoFollow(file);
+    try { if (!fs.readFileSync(actual).equals(Buffer.from(bytes))) throw new Error('published file readback mismatch'); }
+    finally { fs.closeSync(actual); }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try { fs.unlinkSync(pending); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+
+function unavailable(diagnostic = { reason: 'ownership changed' }) {
+  return Object.assign(new Error(`EEXIST: private state is locked (${diagnostic.reason}${diagnostic.file ? `: ${diagnostic.file}` : ''}); inspectPrivateLock and preserve ownership records before offline recovery`), { code: 'EEXIST', diagnostic });
+}
+function ownerState(record, legacy = false) {
+  const pid = typeof record === 'number' ? record : record?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return 'invalid owner';
+  if (!legacy && record?.host !== host) return 'host identity differs';
+  try { process.kill(pid, 0); return 'process exists'; }
+  catch (error) { return error.code === 'ESRCH' ? 'absent' : 'process identity unavailable'; }
+}
+
+// Read-only diagnosis. Older tickets were superseded by a successful successor;
+// only the newest ticket owns this lock. A release marker prevents a completed
+// successor from disappearing and resurrecting an obsolete owner on PID reuse.
+export function inspectPrivateLock(lockPath) {
+  const directory = `${lockPath}.owners`;
+  let names;
+  try {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return { available: false, reason: 'unsafe ownership directory' };
+    names = fs.readdirSync(directory).filter(name => !isPendingPrivateWrite(name)).sort();
+  } catch (error) { if (error.code !== 'ENOENT') throw error; names = []; }
+  const unexpected = names.find(name => !/^\d{12}\.(json|released)$/.test(name));
+  if (unexpected) return { available: false, reason: 'unknown ownership file', file: unexpected };
+  const nameSet = new Set(names);
+  const tickets = names.filter(name => name.endsWith('.json'));
+  const orphan = names.find(name => name.endsWith('.released') && !nameSet.has(name.replace(/\.released$/, '.json')));
+  if (orphan) return { available: false, reason: 'release without owner', file: orphan };
+  let legacy, legacyDigest = null;
+  try {
+    const bytes = readRegularTextNoFollow(lockPath);
+    legacy = JSON.parse(bytes); legacyDigest = createHash('sha256').update(bytes).digest('hex');
+  } catch (error) {
+    if (error.code !== 'ENOENT') return { available: false, reason: 'unreadable legacy owner', file: path.basename(lockPath) };
+  }
+  if (tickets.length) {
+    const file = tickets.at(-1), generation = Number(file.slice(0, 12));
+    let body, record;
+    try { body = readRegularTextNoFollow(path.join(directory, file)); record = JSON.parse(body); }
+    catch { return { available: false, reason: 'unreadable owner', file }; }
+    if (!Number.isSafeInteger(record?.pid) || record.pid <= 0 || !/^[a-f0-9]{64}$/.test(record?.host) || !/^[a-f0-9-]{36}$/.test(record?.nonce)) return { available: false, reason: 'invalid owner', file };
+    if (legacyDigest !== null && record.legacyDigest !== legacyDigest) {
+      const reason = ownerState(legacy, true);
+      if (reason !== 'absent') return { available: false, reason: `legacy ${reason}`, file: path.basename(lockPath) };
+    }
+    const marker = file.replace(/\.json$/, '.released');
+    if (names.includes(marker)) {
+      try {
+        if (readRegularTextNoFollow(path.join(directory, marker)) !== body) return { available: false, reason: 'release identity differs', file: marker };
+      } catch { return { available: false, reason: 'unreadable release', file: marker }; }
+      return { available: true, reason: 'released', generation, file, legacyDigest };
+    }
+    const reason = ownerState(record);
+    return { available: reason === 'absent', reason, generation, file, legacyDigest };
+  }
+  if (legacyDigest === null) return { available: true, reason: 'unused', generation: 0, legacyDigest };
+  const reason = ownerState(legacy, true);
+  return { available: reason === 'absent', reason, generation: 0, file: path.basename(lockPath), legacyDigest };
+}
+
+export function acquirePrivateLock(lockPath) {
+  const parent = path.dirname(lockPath);
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: parent, directory: `${lockPath}.owners`, label: 'private lock' });
+  let ticket, body;
+  try {
+    const status = inspectPrivateLock(lockPath);
+    if (!status.available) throw unavailable(status);
+    const generation = status.generation;
+    if (generation >= 999999999999) throw unavailable({ reason: 'ownership generation exhausted' });
+    ticket = path.join(directory, `${String(generation + 1).padStart(12, '0')}.json`);
+    body = JSON.stringify({ pid: process.pid, host, nonce: randomUUID(), legacyDigest: status.legacyDigest });
+    publishPrivateFile(ticket, body);
+    let released = false;
+    return () => {
+      if (released) return;
+      if (readRegularTextNoFollow(ticket) !== body) throw unavailable();
+      publishPrivateFile(ticket.replace(/\.json$/, '.released'), body);
+      released = true;
+    };
+  } catch (error) {
+    // No operation has started: clean up only this exact attempted owner.
+    if (ticket && body) {
+      try { if (readRegularTextNoFollow(ticket) === body) fs.unlinkSync(ticket); }
+      catch { /* Preserve uncertain ownership for offline diagnosis. */ }
+    }
+    if (error.code === 'EEXIST' && !error.diagnostic) throw unavailable(); throw error;
+  }
+}
+
+export function withPrivateLock(lockPath, operation) {
+  const release = acquirePrivateLock(lockPath);
+  try { return operation(); } finally { release(); }
+}
+
+// Revalidate file identities on every read; unchanged prefixes reuse their
+// verified result. A changed existing file forces replay, a missing tail is
+// refused for the lifetime of this reader. Startup always verifies all history.
+export function createVerifiedFileSequence({ directory, initial, apply, ignoreFiles = [] }) {
+  let names = [], identities = [], value = initial();
+  const identity = file => {
+    const s = fs.lstatSync(file, { bigint: true });
+    if (!s.isFile() || s.isSymbolicLink()) throw new Error('non-regular history refused');
+    return [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(':');
+  };
+  return () => {
+    const listed = fs.readdirSync(directory).filter(n => !isPendingPrivateWrite(n)).sort();
+    // Explicit adapter metadata exceptions must still be regular files. Never
+    // hide unknown filenames or malformed committed records behind a glob.
+    for (const name of listed.filter(n => ignoreFiles.includes(n))) identity(path.join(directory, name));
+    const next = listed.filter(n => !ignoreFiles.includes(n));
+    if (next.length < names.length) throw new Error('history shortened; preserve and inspect');
+    const ids = next.map(n => identity(path.join(directory, n)));
+    const reuse = names.every((n, i) => n === next[i] && identities[i] === ids[i]);
+    let result = reuse ? value : initial();
+    for (let i = reuse ? names.length : 0; i < next.length; i++) {
+      const file = path.join(directory, next[i]);
+      result = apply(readRegularTextNoFollow(file), result, i + 1, next[i]);
+      if (identity(file) !== ids[i]) throw new Error('history changed during verification');
+    }
+    names = next; identities = ids; value = result;
+    return structuredClone(result);
+  };
+}

package/src/project/file-class.mjs

@@ -1,3 +1,5 @@
+import fs from 'node:fs'
+import path from 'node:path'
 import { basenameOf, matchesPathPattern, normalizeRelPath } from './path-match.mjs'
 
 export const FILE_CLASS_SCHEMA = 'mnstry.atelier-file-classes@v1'
@@ -6,8 +8,13 @@ export const SOURCE = 'source'
 export const GENERATED_PROJECTION = 'generated-projection'
 export const DISTRIBUTED_RUNTIME_COPY = 'distributed-runtime-copy'
 
+// Declarable classes for tracked files. The kit manifest schema closes this set.
 export const FILE_CLASSES = Object.freeze([SOURCE, GENERATED_PROJECTION, DISTRIBUTED_RUNTIME_COPY])
 
+// A machine-local file that git never tracks. It is not declarable: nothing
+// tracked can be ignored-local, so it stays out of FILE_CLASSES.
+export const IGNORED_LOCAL = 'ignored-local'
+
 // What each class means for automated handling. Sync loops, merge policies, upgrade
 // tooling, and CI guards all read this instead of each keeping a list of filenames
 // that drifts out of step with the others.
@@ -15,8 +22,17 @@ export const FILE_CLASS_HANDLING = Object.freeze({
   [SOURCE]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
   [GENERATED_PROJECTION]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
   [DISTRIBUTED_RUNTIME_COPY]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
+  // Holds this machine's only reference to external editable state. Never
+  // swept, never synced, never a merge conflict.
+  [IGNORED_LOCAL]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: false }),
 })
 
+// The one repo-local file the Obsidian view leaves in a repository or
+// workspace: a pointer to the external data directory and its local settings.
+// It lives under the existing ignored local-state directory.
+export const OBSIDIAN_LOCAL_POINTER = '.atelier-local/obsidian.json'
+export const IGNORED_LOCAL_PATTERNS = Object.freeze([`**/${OBSIDIAN_LOCAL_POINTER}`])
+
 // The kit's own declaration — the single place these paths are classified. A
 // distributed-runtime-copy is canonical in exactly one repo role and rederivable
 // everywhere else; that is why the class carries `canonicalRepoRole` rather than
@@ -75,6 +91,12 @@ export function validateFileClasses(entries, { label = 'fileClasses' } = {}) {
  */
 export function classifyPath(filePath, { repoRole = null, fileClasses = KIT_FILE_CLASSES } = {}) {
   const rel = normalizeRelPath(filePath)
+  // Not overridable: a declaration cannot turn a local pointer into something
+  // a sync loop may discard or commit.
+  const localPattern = IGNORED_LOCAL_PATTERNS.find((pattern) => matchesPathPattern(pattern, rel))
+  if (localPattern) {
+    return { path: rel, class: IGNORED_LOCAL, pattern: localPattern, canonicalRepoRole: null, canonicalHere: true, declared: false, handling: FILE_CLASS_HANDLING[IGNORED_LOCAL] }
+  }
   let matched = null
   for (const entry of fileClasses) {
     if (matchesPathPattern(entry.pattern, rel)) matched = entry
@@ -125,3 +147,147 @@ export function generatedProjectionDirectoryBasenames(fileClasses = KIT_FILE_CLA
   }
   return names
 }
+
+// ---------------------------------------------------------------------------
+// External managed data root: <data>/obsidian/<workspace-id>/
+// ---------------------------------------------------------------------------
+
+export const EDITABLE_VAULT = 'editable-vault'
+export const TRUSTED_STATE = 'trusted-state'
+export const RECOVERY_RECORD = 'recovery-record'
+export const DISPOSABLE_STAGING = 'disposable-staging'
+export const UNKNOWN_MANAGED = 'unknown-managed'
+
+// Only staging is discardable. A vault holds a person's edits and recovery
+// holds the only other copy of them, so neither is ever generated output, and
+// anything unrecognized is kept.
+export const MANAGED_AREA_HANDLING = Object.freeze({
+  [EDITABLE_VAULT]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [TRUSTED_STATE]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [RECOVERY_RECORD]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [DISPOSABLE_STAGING]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
+  [UNKNOWN_MANAGED]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+})
+
+const MANAGED_AREAS = Object.freeze({ vaults: EDITABLE_VAULT, state: TRUSTED_STATE, recovery: RECOVERY_RECORD, staging: DISPOSABLE_STAGING })
+
+// Classify a path relative to one workspace's managed data root. Matching is
+// exact and case-sensitive, and a path that climbs, is absolute or names only
+// the area directory itself is never discardable.
+export function classifyManagedPath(relativePath) {
+  const rel = normalizeRelPath(relativePath).replace(/\/+$/, '')
+  const segments = rel.split('/')
+  const contained = rel !== '' && !rel.startsWith('/') && !/^[A-Za-z]:/.test(rel) && !segments.some((part) => part === '..' || part === '.' || part === '')
+  const area = contained && segments.length > 1 && Object.hasOwn(MANAGED_AREAS, segments[0]) ? segments[0] : null
+  const resolved = area ? MANAGED_AREAS[area] : UNKNOWN_MANAGED
+  return { path: rel, area, class: resolved, handling: MANAGED_AREA_HANDLING[resolved] }
+}
+
+// The real path of a target that may not exist yet: the deepest existing
+// ancestor is resolved and the missing tail is appended. Only "does not exist"
+// moves up a level. Any other failure (a directory that cannot be searched,
+// a link loop) is thrown: a lexical path standing in for a real one would
+// weaken the alias check exactly where it matters.
+function realLocation(target, realpath) {
+  const missing = []
+  let current = path.resolve(target)
+  for (;;) {
+    try {
+      return path.join(realpath(current), ...missing.reverse())
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error
+      const parent = path.dirname(current)
+      if (parent === current) return path.resolve(target)
+      missing.push(path.basename(current))
+      current = parent
+    }
+  }
+}
+
+const containsPath = (outer, inner) => inner === outer || inner.startsWith(outer.endsWith(path.sep) ? outer : `${outer}${path.sep}`)
+
+function isSymbolicLink(target, lstat) {
+  try {
+    return lstat(target).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+// True when the path or any of its ancestors is a symbolic link.
+function crossesSymbolicLink(target, lstat) {
+  for (let current = path.resolve(target); ; current = path.dirname(current)) {
+    if (isSymbolicLink(current, lstat)) return true
+    if (path.dirname(current) === current) return false
+  }
+}
+
+// Refuse a managed root that overlaps an enrolled repository in either
+// direction, under lexical or real paths. `realpath` and `lstat` are the only
+// filesystem reads, and both can be supplied; nothing is created or changed.
+// A real path that cannot be established refuses; it is never replaced by the
+// lexical path.
+export function checkManagedRoots({ managedRoots = [], repositoryRoots = [], realpath = fs.realpathSync.native, lstat = fs.lstatSync } = {}) {
+  const refusals = []
+  const refuse = (code, managedRoot, repositoryRoot, message) => refusals.push({ code, managedRoot, repositoryRoot, message })
+  const locate = (root) => {
+    try {
+      return { given: root, lexical: path.resolve(root), real: realLocation(root, realpath) }
+    } catch (error) {
+      return { given: root, lexical: path.resolve(root), real: null, errorCode: error?.code ?? 'unknown' }
+    }
+  }
+  const repositories = repositoryRoots.map(locate)
+
+  for (const managedRoot of managedRoots) {
+    if (typeof managedRoot !== 'string' || !path.isAbsolute(managedRoot)) {
+      refuse('managed-root-not-absolute', managedRoot, null, 'a managed root must be an absolute path')
+      continue
+    }
+    const managed = locate(managedRoot)
+    if (managed.real === null) {
+      refuse('managed-root-realpath-failed', managedRoot, null, `the real path of a managed root cannot be established (${managed.errorCode})`)
+      continue
+    }
+    if (isSymbolicLink(managed.lexical, lstat)) {
+      refuse('managed-root-symlink-alias', managedRoot, null, 'a managed root must not be a symbolic link')
+    }
+    for (const repository of repositories) {
+      const inside = (kind) => containsPath(repository[kind], managed[kind])
+      const around = (kind) => containsPath(managed[kind], repository[kind])
+      if (inside('lexical')) refuse('managed-root-inside-repository', managedRoot, repository.given, 'a managed root must sit outside every enrolled repository')
+      else if (around('lexical')) refuse('repository-inside-managed-root', managedRoot, repository.given, 'an enrolled repository must not sit inside a managed root')
+      else if (repository.real === null) {
+        refuse('managed-root-realpath-failed', managedRoot, repository.given, `the real path of an enrolled repository cannot be established (${repository.errorCode})`)
+      } else if (inside('real') || around('real')) {
+        // Name the cause that is actually there. Folding letter case and
+        // Unicode normalization alone may explain the overlap; otherwise a
+        // symbolic link on either path does; otherwise something else presents
+        // one location under two names (a mount, for example).
+        const folded = (value) => value.normalize('NFC').toLowerCase()
+        const byFolding = containsPath(folded(repository.lexical), folded(managed.lexical)) || containsPath(folded(managed.lexical), folded(repository.lexical))
+        if (!byFolding && (crossesSymbolicLink(managed.lexical, lstat) || crossesSymbolicLink(repository.lexical, lstat))) {
+          refuse('managed-root-symlink-alias', managedRoot, repository.given, 'a symbolic link makes the managed root and an enrolled repository overlap')
+        } else {
+          refuse('managed-root-realpath-overlap', managedRoot, repository.given,
+            'the managed root and an enrolled repository are written differently but name overlapping locations, and no symbolic link explains it: look for a difference in letter case or Unicode normalization on a filesystem that folds them, or a mount that presents one location under two names')
+        }
+      }
+    }
+  }
+  return { ok: refusals.length === 0, refusals }
+}
+
+// The same guard at enrolment time: a repository that would contain, sit
+// inside or alias an existing managed root cannot be enrolled.
+export function checkRepositoryEnrollment({ repositoryRoot, managedRoots = [], realpath, lstat } = {}) {
+  const { refusals } = checkManagedRoots({ managedRoots, repositoryRoots: [repositoryRoot], ...(realpath ? { realpath } : {}), ...(lstat ? { lstat } : {}) })
+  const codes = {
+    'managed-root-inside-repository': 'enrollment-contains-managed-root',
+    'repository-inside-managed-root': 'enrollment-inside-managed-root',
+    'managed-root-symlink-alias': 'enrollment-aliases-managed-root',
+    'managed-root-realpath-overlap': 'enrollment-realpath-overlaps-managed-root',
+  }
+  const blocking = refusals.filter((item) => item.repositoryRoot !== null).map((item) => ({ ...item, code: codes[item.code] ?? item.code }))
+  return { ok: blocking.length === 0, refusals: blocking }
+}

package/src/project/private-state.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { randomUUID } from 'node:crypto'
 
 function escapes(root, candidate) {
   const relative = path.relative(root, candidate)
@@ -79,12 +80,20 @@ export function readRegularTextNoFollow(file) {
   }
 }
 
+export function syncPrivateDirectory(directory) {
+  let fd;
+  try { fd = fs.openSync(directory, fs.constants.O_RDONLY); fs.fsyncSync(fd); }
+  catch (error) {
+    if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EINVAL', 'EISDIR'].includes(error.code)) throw error;
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
 export function atomicReplacePrivateText(file, text, mode = 0o600) {
   const existing = lstatIfPresent(file)
   if (existing && (existing.isSymbolicLink() || !existing.isFile())) {
     throw new Error('state leaf is not a regular file')
   }
-  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`
+  const tmp = `${file}.${randomUUID()}.tmp`
   let descriptor
   try {
     descriptor = openRegularFileNoFollow(
@@ -98,6 +107,7 @@ export function atomicReplacePrivateText(file, text, mode = 0o600) {
     fs.closeSync(descriptor)
     descriptor = null
     fs.renameSync(tmp, file)
+    syncPrivateDirectory(path.dirname(file))
   } catch (error) {
     if (descriptor != null) fs.closeSync(descriptor)
     try {