chati-dev 4.5.28 → 4.5.29

package/node_modules/@chati/tracking-clickup/src/index.js

@@ -1,12 +1,14 @@
 import {
-  closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync,
-  openSync, readSync, readdirSync, renameSync, unlinkSync, writeSync,
+  closeSync, constants, fstatSync, fsyncSync, openSync, readSync, writeSync,
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { ContractError, canonicalize, sha256 } from '@chati/core';
+import {
+  captureHostBootMarker, ContractError, canonicalize, directoryPathSync, hostBootMarkerChanged,
+  linkAtSync, lstatAtSync, mkdirAtSync, openAtSync, readDirectorySync, renameAtSync, sha256, unlinkAtSync,
+} from '@chati/core';
 
 const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const DELIVERY_STATES = new Set(['pending', 'sent_unconfirmed', 'confirmed', 'retryable_failure', 'permanent_failure']);
@@ -158,23 +160,22 @@ function readDescriptorBounded(descriptor, maxBytes) {
 }
 
 function openPinnedTrackingDirectory(path, { create = false } = {}) {
-  if (process.platform !== 'linux') fail('UNSUPPORTED_TRACKING_STORAGE_PLATFORM', 'tracking authority storage requires Linux descriptor-relative filesystem operations');
+  if (!['linux', 'darwin'].includes(process.platform)) fail('UNSUPPORTED_TRACKING_STORAGE_PLATFORM', `tracking authority storage requires descriptor-relative operations; unsupported platform: ${process.platform}`);
   const absolute = resolve(path);
   const root = parse(absolute).root;
   let descriptor = openSync(root, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
   try {
     for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
-      const childPath = join(`/proc/self/fd/${descriptor}`, segment);
       let child;
-      try { child = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0)); }
+      try { child = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0)); }
       catch (error) {
         if (error?.code !== 'ENOENT' || !create) {
           if (['ELOOP', 'ENOTDIR'].includes(error?.code)) fail('UNSAFE_OUTBOX_DIRECTORY', 'tracking directory chain must contain only real directories');
           throw error;
         }
-        try { mkdirSync(childPath, { mode: 0o700 }); }
+        try { mkdirAtSync(descriptor, segment, { mode: 0o700 }); }
         catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
-        child = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        child = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
       }
       const stat = fstatSync(child);
       if (!stat.isDirectory()) {
@@ -184,18 +185,13 @@ function openPinnedTrackingDirectory(path, { create = false } = {}) {
       closeSync(descriptor);
       descriptor = child;
     }
-    return Object.freeze({ absolute, descriptor, identity: fstatSync(descriptor), reference: `/proc/self/fd/${descriptor}` });
+    return Object.freeze({ absolute, descriptor, identity: fstatSync(descriptor) });
   } catch (error) {
     closeSync(descriptor);
     throw error;
   }
 }
 
-function trackingEntry(directory, name) {
-  if (basename(name) !== name || name === '.' || name === '..') fail('UNSAFE_OUTBOX_FILE', 'tracking entry must be one path segment');
-  return join(directory.reference, name);
-}
-
 function assertPinnedTrackingDirectory(directory) {
   const pinned = fstatSync(directory.descriptor);
   if (!pinned.isDirectory() || !sameIdentity(pinned, directory.identity)) fail('UNSAFE_OUTBOX_DIRECTORY', 'pinned tracking directory changed');
@@ -217,10 +213,9 @@ function readRegular(path, { allowMissing = false, maxBytes = OUTBOX_MAX_BYTES,
     try { activeDirectory = openPinnedTrackingDirectory(dirname(path)); }
     catch (error) { if (allowMissing && error?.code === 'ENOENT') return null; throw error; }
   }
-  const entry = trackingEntry(activeDirectory, basename(path));
   let descriptor;
   try {
-    descriptor = openSync(entry, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    descriptor = openAtSync(activeDirectory.descriptor, basename(path), constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
   } catch (error) {
     if (ownedDirectory) closeSync(activeDirectory.descriptor);
     if (allowMissing && error?.code === 'ENOENT') return null;
@@ -252,12 +247,12 @@ function writeAtomic(path, data, maxBytes = OUTBOX_MAX_BYTES, { directory = null
   if (bytes.length > maxBytes) fail('OUTBOX_SIZE_LIMIT', `tracking state exceeds the ${maxBytes}-byte safety limit`);
   const activeDirectory = directory ?? openPinnedTrackingDirectory(dirname(path), { create: true });
   const ownedDirectory = directory === null;
-  const temporary = trackingEntry(activeDirectory, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
-  const destination = trackingEntry(activeDirectory, basename(path));
+  const temporaryName = `${basename(path)}.${process.pid}.${randomUUID()}.tmp`;
+  const name = basename(path);
   let temporaryDescriptor;
   try {
     const existing = readRegular(path, { allowMissing: true, maxBytes, directory: activeDirectory });
-    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    temporaryDescriptor = openAtSync(activeDirectory.descriptor, temporaryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
     let offset = 0;
     while (offset < bytes.length) offset += writeSync(temporaryDescriptor, bytes, offset, bytes.length - offset);
     fsyncSync(temporaryDescriptor);
@@ -265,18 +260,18 @@ function writeAtomic(path, data, maxBytes = OUTBOX_MAX_BYTES, { directory = null
     temporaryDescriptor = undefined;
     assertPinnedTrackingDirectory(activeDirectory);
     let current = null;
-    try { current = lstatSync(destination); } catch (error) { if (error?.code !== 'ENOENT') throw error; }
+    try { current = lstatAtSync(activeDirectory.descriptor, name); } catch (error) { if (error?.code !== 'ENOENT') throw error; }
     if ((existing === null && current !== null)
       || (existing !== null && (!current || current.isSymbolicLink() || !current.isFile()
         || current.nlink !== 1 || !sameIdentity(current, existing.stat)))) {
       fail('OUTBOX_STORAGE_CONFLICT', 'tracking state changed during atomic persistence');
     }
-    renameSync(temporary, destination);
+    renameAtSync(activeDirectory.descriptor, temporaryName, activeDirectory.descriptor, name);
     fsyncSync(activeDirectory.descriptor);
     assertPinnedTrackingDirectory(activeDirectory);
   } finally {
     if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
-    try { unlinkSync(temporary); } catch { /* leave an unverified temporary untouched */ }
+    try { unlinkAtSync(activeDirectory.descriptor, temporaryName); } catch { /* leave an unverified temporary untouched */ }
     if (ownedDirectory) closeSync(activeDirectory.descriptor);
   }
 }
@@ -320,8 +315,10 @@ export function persistImmutableClickUpDocument(path, data, { maxBytes = OUTBOX_
   const bytes = Buffer.from(content);
   if (bytes.length > maxBytes) fail('OUTBOX_SIZE_LIMIT', `tracking document exceeds the ${maxBytes}-byte safety limit`);
   const directory = openPinnedTrackingDirectory(dirname(path), { create: true });
-  const temporary = trackingEntry(directory, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
-  const destination = trackingEntry(directory, basename(path));
+  const name = basename(path);
+  const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
+  // Diagnostic/test-hook path only; mutations use the pinned descriptor.
+  const temporary = join(directoryPathSync(directory.descriptor), temporaryName);
   let temporaryDescriptor;
   try {
     const existing = readRegular(path, { allowMissing: true, maxBytes, directory });
@@ -330,7 +327,7 @@ export function persistImmutableClickUpDocument(path, data, { maxBytes = OUTBOX_
       return Object.freeze({ written: false, path });
     }
     runSecurityTestHook('beforeTrackingDocumentTempOpen', { path, temporary, directory: directory.absolute });
-    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    temporaryDescriptor = openAtSync(directory.descriptor, temporaryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
     runSecurityTestHook('afterTrackingDocumentTempOpen', { path, temporary, directory: directory.absolute });
     let offset = 0;
     while (offset < bytes.length) offset += writeSync(temporaryDescriptor, bytes, offset, bytes.length - offset);
@@ -338,7 +335,7 @@ export function persistImmutableClickUpDocument(path, data, { maxBytes = OUTBOX_
     closeSync(temporaryDescriptor);
     temporaryDescriptor = undefined;
     assertPinnedTrackingDirectory(directory);
-    try { linkSync(temporary, destination); }
+    try { linkAtSync(directory.descriptor, temporaryName, directory.descriptor, name); }
     catch (error) {
       if (error?.code !== 'EEXIST') throw error;
       const raced = readRegular(path, { maxBytes, directory });
@@ -350,7 +347,7 @@ export function persistImmutableClickUpDocument(path, data, { maxBytes = OUTBOX_
     return Object.freeze({ written: true, path });
   } finally {
     if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
-    try { unlinkSync(temporary); } catch { /* leave an unverified temporary untouched */ }
+    try { unlinkAtSync(directory.descriptor, temporaryName); } catch { /* leave an unverified temporary untouched */ }
     closeSync(directory.descriptor);
   }
 }
@@ -358,7 +355,7 @@ export function persistImmutableClickUpDocument(path, data, { maxBytes = OUTBOX_
 export function listClickUpDocumentPaths(directoryPath) {
   const directory = openPinnedTrackingDirectory(directoryPath);
   try {
-    const names = readdirSync(directory.reference).filter((name) => /^[A-Za-z0-9._-]+\.json$/.test(name)).sort();
+    const names = readDirectorySync(directory.descriptor).filter((name) => /^[A-Za-z0-9._-]+\.json$/.test(name)).sort();
     assertPinnedTrackingDirectory(directory);
     return names.map((name) => join(directory.absolute, name));
   } finally { closeSync(directory.descriptor); }
@@ -366,16 +363,16 @@ export function listClickUpDocumentPaths(directoryPath) {
 
 export function removeImmutableClickUpDocument(path, { maxBytes = OUTBOX_MAX_BYTES } = {}) {
   const directory = openPinnedTrackingDirectory(dirname(path));
-  const destination = trackingEntry(directory, basename(path));
+  const name = basename(path);
   try {
     const existing = readRegular(path, { allowMissing: true, maxBytes, directory });
     if (existing === null) return false;
-    const current = lstatSync(destination);
+    const current = lstatAtSync(directory.descriptor, name);
     if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || !sameIdentity(current, existing.stat)) {
       fail('OUTBOX_STORAGE_CONFLICT', 'tracking document changed before removal');
     }
     assertPinnedTrackingDirectory(directory);
-    unlinkSync(destination);
+    unlinkAtSync(directory.descriptor, name);
     fsyncSync(directory.descriptor);
     assertPinnedTrackingDirectory(directory);
     return true;
@@ -392,10 +389,10 @@ function processIsAlive(pid) {
   try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
 }
 
-function readOutboxLock(path) {
+function readOutboxLock(directory, name) {
   let descriptor;
   try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    descriptor = openAtSync(directory.descriptor, name, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
     const before = fstatSync(descriptor);
     if (!before.isFile() || before.nlink !== 1 || before.size > 16 * 1024) return null;
     const content = readDescriptorBounded(descriptor, 16 * 1024);
@@ -408,45 +405,54 @@ function readOutboxLock(path) {
 }
 
 
-function recoverStaleOutboxLock(path) {
+function recoverStaleOutboxLock(directory, name) {
   let stat;
-  try { stat = lstatSync(path); } catch (error) { return error?.code === 'ENOENT'; }
+  try { stat = lstatAtSync(directory.descriptor, name); } catch (error) { return error?.code === 'ENOENT'; }
   if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) return false;
-  const owner = readOutboxLock(path);
-  if (owner?.hostname === hostname() && processIsAlive(owner.pid)) return false;
+  const owner = readOutboxLock(directory, name);
+  // A rebooted host may recycle the owner's pid onto an unrelated live process.
+  // Prove the reboot from the boot marker before ever trusting PID liveness.
+  if (owner?.hostname === hostname() && !hostBootMarkerChanged(owner.host_boot_marker, captureHostBootMarker())
+    && processIsAlive(owner.pid)) return false;
   // A process on another host cannot be proven dead from this host. Keep the
   // lock until an operator explicitly reconciles it.
   if (owner?.hostname && owner.hostname !== hostname()) return false;
   if (!owner && Date.now() - stat.mtimeMs < OUTBOX_LOCK_STALE_MS) return false;
-  const recoveryPath = `${path}.recovery`;
+  const recoveryName = `${name}.recovery`;
   let recoveryFd;
   try {
-    recoveryFd = openSync(recoveryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
-    const bytes = Buffer.from(JSON.stringify({ pid: process.pid, hostname: hostname(), token: randomUUID() }));
+    recoveryFd = openAtSync(directory.descriptor, recoveryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    const recoveryMarker = captureHostBootMarker();
+    const bytes = Buffer.from(JSON.stringify({ pid: process.pid, hostname: hostname(), token: randomUUID(), ...(recoveryMarker ? { host_boot_marker: recoveryMarker } : {}) }));
     writeSync(recoveryFd, bytes, 0, bytes.length);
     fsyncSync(recoveryFd);
   } catch {
     if (recoveryFd !== undefined) closeSync(recoveryFd);
     return false;
   }
-  const quarantine = `${path}.stale.${process.pid}.${randomUUID()}`;
+  const quarantine = `${name}.stale.${process.pid}.${randomUUID()}`;
   try {
-    const current = lstatSync(path);
-    const currentOwner = readOutboxLock(path);
+    const current = lstatAtSync(directory.descriptor, name);
+    const currentOwner = readOutboxLock(directory, name);
     if (!sameIdentity(stat, current) || currentOwner?.token !== owner?.token) return false;
-    renameSync(path, quarantine);
-    const quarantined = lstatSync(quarantine);
-    const quarantinedOwner = readOutboxLock(quarantine);
+    renameAtSync(directory.descriptor, name, directory.descriptor, quarantine);
+    const quarantined = lstatAtSync(directory.descriptor, quarantine);
+    const quarantinedOwner = readOutboxLock(directory, quarantine);
     if (!sameIdentity(stat, quarantined) || quarantinedOwner?.token !== owner?.token) {
-      try { if (!existsSync(path)) renameSync(quarantine, path); } catch { /* preserve quarantine fail-closed */ }
+      try {
+        let missing = false;
+        try { lstatAtSync(directory.descriptor, name); }
+        catch (error) { if (error.code !== 'ENOENT') throw error; missing = true; }
+        if (missing) renameAtSync(directory.descriptor, quarantine, directory.descriptor, name);
+      } catch { /* preserve quarantine fail-closed */ }
       return false;
     }
-    unlinkSync(quarantine);
+    unlinkAtSync(directory.descriptor, quarantine);
     return true;
   } catch (error) { return error?.code === 'ENOENT'; }
   finally {
     if (recoveryFd !== undefined) closeSync(recoveryFd);
-    try { unlinkSync(recoveryPath); } catch { /* fail closed if recovery ownership changed */ }
+    try { unlinkAtSync(directory.descriptor, recoveryName); } catch { /* fail closed if recovery ownership changed */ }
   }
 }
 
@@ -512,10 +518,12 @@ export class TrackingClickUp {
     if (this.#requireAuthenticatedState && (!this.#stateAuthority || !this.#authorityContext)) {
       fail('CLICKUP_STATE_AUTHORITY_REQUIRED', 'production ClickUp state requires a host authority and project context');
     }
-    this.#loadState({ allowMissing: true });
     // Project Evolution is a derivative, never the only copy of evidence.
-    // Rebuild it after an interrupted outbox/evolution write sequence.
-    for (const projectId of new Set(this.#state.projections.map((item) => item.project_id))) this.#evolve(projectId);
+    // Rebuild under the same lock as enqueue: another constructor or writer may
+    // otherwise replace a snapshot during this read/atomic persistence sequence.
+    this.#exclusive(() => {
+      for (const projectId of new Set(this.#state.projections.map((item) => item.project_id))) this.#evolve(projectId);
+    });
   }
 
   get projections() { return Object.freeze(this.#state.projections.map((item) => Object.freeze(canonicalize(item)))); }
@@ -562,7 +570,7 @@ export class TrackingClickUp {
   #exclusive(action) {
     if (this.#lockDepth > 0) return action();
     const directory = openPinnedTrackingDirectory(dirname(this.#outboxPath), { create: true });
-    const path = trackingEntry(directory, `${basename(this.#outboxPath)}.lock`);
+    const name = `${basename(this.#outboxPath)}.lock`;
     let descriptor;
     let token;
     try {
@@ -570,16 +578,17 @@ export class TrackingClickUp {
       while (performance.now() < lockDeadline) {
         let candidate;
         try {
-          candidate = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+          candidate = openAtSync(directory.descriptor, name, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
         } catch (error) {
           if (error?.code !== 'EEXIST') throw error;
-          if (recoverStaleOutboxLock(path)) continue;
+          if (recoverStaleOutboxLock(directory, name)) continue;
           Atomics.wait(OUTBOX_LOCK_WAIT, 0, 0, 4);
           continue;
         }
         token = randomUUID();
         try {
-          const bytes = Buffer.from(JSON.stringify({ schema_version: 1, pid: process.pid, hostname: hostname(), token, acquired_at: new Date().toISOString() }));
+          const ownerMarker = captureHostBootMarker();
+          const bytes = Buffer.from(JSON.stringify({ schema_version: 1, pid: process.pid, hostname: hostname(), token, acquired_at: new Date().toISOString(), ...(ownerMarker ? { host_boot_marker: ownerMarker } : {}) }));
           writeSync(candidate, bytes, 0, bytes.length);
           fsyncSync(candidate);
           fsyncSync(directory.descriptor);
@@ -587,7 +596,7 @@ export class TrackingClickUp {
           break;
         } catch (error) {
           closeSync(candidate);
-          try { unlinkSync(path); } catch { /* acquisition failed closed */ }
+          try { unlinkAtSync(directory.descriptor, name); } catch { /* acquisition failed closed */ }
           throw error;
         }
       }
@@ -604,7 +613,7 @@ export class TrackingClickUp {
         if (descriptor !== undefined) {
           closeSync(descriptor);
           assertPinnedTrackingDirectory(directory);
-          if (readOutboxLock(path)?.token === token) { unlinkSync(path); fsyncSync(directory.descriptor); }
+          if (readOutboxLock(directory, name)?.token === token) { unlinkAtSync(directory.descriptor, name); fsyncSync(directory.descriptor); }
         }
       } finally {
         closeSync(directory.descriptor);