@gregiteen/ssss-cli 0.9.0 → 0.9.1

package/src/bundle.mjs

@@ -197,6 +197,17 @@ export function exportBundle(vaultRoot, opts = {}) {
   }
 
   const files = canonicalFiles(kept);
+  const hash = contentHash(files);
+  const primitiveDeps = Object.keys(inventory).sort();
+  const migrationDeps = files
+    .map((file) => {
+      try {
+        const { data } = parseDocument(file.content);
+        return data.type === 'migration' ? (data.migration_id || data.slug || file.path) : null;
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort();
   const manifest = {
     name, description, version,
     exported_at: exportedAt,
@@ -204,10 +215,16 @@ export function exportBundle(vaultRoot, opts = {}) {
     required_extensions: requiredExtensions,
     export_profile: profile,
     primitive_inventory: inventory,
+    dependencies: {
+      primitives: primitiveDeps,
+      extensions: [...requiredExtensions].sort(),
+      migrations: migrationDeps,
+      integrity: { content_hash: hash, ssss_core_version: core.spec_version },
+    },
     provisioning: manifestProvisioning,
     parameters: manifestParameters,
     file_count: files.length,
-    provenance: { content_hash: contentHash(files), exporter },
+    provenance: { content_hash: hash, exporter },
   };
   // source_workspace_id is operator-identifying — only carried in a backup (§16.2).
   if (profile === 'backup' && sourceWorkspaceId) manifest.source_workspace_id = sourceWorkspaceId;
@@ -240,6 +257,25 @@ export function validateBundle(bundle, opts = {}) {
   if (!m.primitive_inventory || typeof m.primitive_inventory !== 'object' || Array.isArray(m.primitive_inventory)) {
     errors.push('manifest.primitive_inventory must be an object');
   }
+  if (m.dependencies !== undefined) {
+    if (!m.dependencies || typeof m.dependencies !== 'object' || Array.isArray(m.dependencies)) {
+      errors.push('manifest.dependencies must be an object');
+    } else {
+      for (const key of ['primitives', 'extensions', 'migrations']) {
+        if (!Array.isArray(m.dependencies[key])) errors.push(`manifest.dependencies.${key} must be an array`);
+      }
+      if (!m.dependencies.integrity || typeof m.dependencies.integrity !== 'object' || Array.isArray(m.dependencies.integrity)) {
+        errors.push('manifest.dependencies.integrity must be an object');
+      } else if (typeof m.dependencies.integrity.content_hash !== 'string' || !m.dependencies.integrity.content_hash.startsWith('sha256:')) {
+        errors.push('manifest.dependencies.integrity.content_hash must be a sha256 digest');
+      } else if (
+        m.provenance?.content_hash
+        && m.dependencies.integrity.content_hash !== m.provenance.content_hash
+      ) {
+        errors.push('manifest.dependencies.integrity.content_hash must match provenance.content_hash');
+      }
+    }
+  }
   for (const ext of requiredExtensions) {
     if (typeof ext !== 'string' || !ext) {
       errors.push('required extension ids must be non-empty strings');

package/src/events.mjs

@@ -33,12 +33,12 @@ export function createCanonicalEvent(input, options = {}) {
 
 export class MemoryEventStore {
   #events = [];
+  #ids = new Set();
   async append(event) {
-    if (this.#events.some((existing) => existing.event_id === event.event_id)) {
-      throw new Error(`Duplicate event_id '${event.event_id}'.`);
-    }
+    if (this.#ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
     const frozen = structuredClone(event);
     this.#events.push(frozen);
+    this.#ids.add(frozen.event_id);
     return structuredClone(frozen);
   }
   async *replay(options = {}) {
@@ -51,7 +51,46 @@ export class MemoryEventStore {
   async size() { return this.#events.length; }
 }
 
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const APPEND_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | NOFOLLOW;
+
+function openLog(file, flags, mode) {
+  try { return fs.openSync(file, flags, mode); }
+  catch (error) {
+    if (error.code === 'ELOOP') throw new Error('Symlinked event logs are forbidden.');
+    throw error;
+  }
+}
+
+function sameStat(a, b) {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+/** Read every event_id in a log, bounded to the bytes covered by the returned stat. */
+function loadIndex(file) {
+  const fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW);
+  try {
+    const stat = fs.fstatSync(fd);
+    const bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (read === 0) break;
+      offset += read;
+    }
+    const ids = new Set();
+    for (const line of bytes.subarray(0, offset).toString('utf8').split('\n')) {
+      if (line.trim()) ids.add(JSON.parse(line).event_id);
+    }
+    return { ids, stat };
+  } finally { fs.closeSync(fd); }
+}
+
 export class JsonlEventStore {
+  // Per-log index of event_ids, built on the first append to that log. Each
+  // index records the stat of the bytes it covers; any change (another store
+  // instance or process appended, or the file was replaced) rebuilds it.
+  #indexes = new Map();
   constructor(root) {
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
@@ -60,15 +99,41 @@ export class JsonlEventStore {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(workspaceId || '')) throw new Error('Unsafe event workspace_id.');
     return path.join(this.root, `${workspaceId}.jsonl`);
   }
+  #index(file) {
+    let stat;
+    try { stat = fs.lstatSync(file); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      this.#indexes.delete(file);
+      return { ids: new Set(), stat: null };
+    }
+    if (stat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
+    const cached = this.#indexes.get(file);
+    if (cached && sameStat(cached.stat, stat)) return cached;
+    const index = loadIndex(file);
+    this.#indexes.set(file, index);
+    return index;
+  }
   async append(event) {
     const file = this.#file(event.workspace_id);
-    if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
-    if (fs.existsSync(file)) {
-      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-        if (line.trim() && JSON.parse(line).event_id === event.event_id) throw new Error(`Duplicate event_id '${event.event_id}'.`);
-      }
+    const index = this.#index(file);
+    if (index.ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
+    const line = `${JSON.stringify(event)}\n`;
+    this.#indexes.delete(file);
+    const fd = openLog(file, APPEND_FLAGS, 0o600);
+    let after;
+    try {
+      fs.writeFileSync(fd, line);
+      after = fs.fstatSync(fd);
+    } finally { fs.closeSync(fd); }
+    // Keep the index only when the log grew by exactly this line on the same
+    // file; otherwise another writer interleaved and the next append rebuilds.
+    const before = index.stat;
+    const expectedSize = (before?.size || 0) + Buffer.byteLength(line);
+    if (after.size === expectedSize && (!before || (before.dev === after.dev && before.ino === after.ino))) {
+      index.ids.add(event.event_id);
+      this.#indexes.set(file, { ids: index.ids, stat: after });
     }
-    fs.appendFileSync(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
     return structuredClone(event);
   }
   async *replay(options = {}) {

package/src/leases.mjs

@@ -46,6 +46,11 @@ export class MemoryLeaseStore {
   }
 }
 
+export function leaseStatePath(root, workspaceId, target) {
+  const hash = crypto.createHash('sha256').update(`${workspaceId}\0${target}`).digest('hex');
+  return path.join(root, `${hash}.lease.json`);
+}
+
 export class FileLeaseStore {
   constructor(root, options = {}) {
     fs.mkdirSync(root, { recursive: true });
@@ -53,8 +58,7 @@ export class FileLeaseStore {
     this.clock = options.clock || (() => Date.now());
   }
   #file(workspaceId, target) {
-    const hash = crypto.createHash('sha256').update(`${workspaceId}\0${target}`).digest('hex');
-    return path.join(this.root, `${hash}.lease.json`);
+    return leaseStatePath(this.root, workspaceId, target);
   }
   #load(workspaceId, target) {
     const file = this.#file(workspaceId, target);
@@ -117,9 +121,53 @@ export async function runLeaseContract(store, { clock } = {}) {
   record('acquire returns bound lease', acquired.lease_id && acquired.principal_id === input.principal_id);
   record('matching lease verifies', (await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
   record('mismatched owner fails closed', !(await store.verify({ ...input, principal_id: 'other', lease_id: acquired.lease_id })).valid);
+  record('mismatched lease_id fails closed', !(await store.verify({ ...input, lease_id: crypto.randomUUID() })).valid);
+  record('missing lease fails closed', !(await store.verify({
+    workspace_id: input.workspace_id,
+    target: `missing/${crypto.randomUUID()}.md`,
+    principal_id: input.principal_id,
+    operation_id: input.operation_id,
+    lease_id: acquired.lease_id,
+  })).valid);
   const renewed = await store.renew({ ...input, lease_id: acquired.lease_id }, 20_000);
   record('renew extends expiry', renewed.expires_at >= acquired.expires_at);
   await store.release({ ...input, lease_id: acquired.lease_id });
   record('released lease is missing', !(await store.verify({ ...input, lease_id: acquired.lease_id })).valid);
+
+  // Controllable clock proves expiry fail-closed for any store that accepts injection.
+  if (typeof store.clock === 'function' || clock) {
+    let now = 1_000_000;
+    const timed = store.constructor === MemoryLeaseStore
+      ? new MemoryLeaseStore({ clock: () => now })
+      : store.constructor === FileLeaseStore
+        ? new FileLeaseStore(path.join(store.root, `expiry-${crypto.randomUUID()}`), { clock: () => now })
+        : null;
+    if (timed) {
+      const timedInput = { ...input, target: `rules/expiry-${crypto.randomUUID()}.md` };
+      const short = await timed.acquire(timedInput, 50);
+      now = short.expires_at + 1;
+      record('expired lease fails closed', !(await timed.verify({ ...timedInput, lease_id: short.lease_id })).valid);
+    }
+  }
+
+  // Filesystem stores must fail closed on corrupt/unreadable state.
+  if (store instanceof FileLeaseStore) {
+    const corruptInput = {
+      workspace_id: `ws-${crypto.randomUUID()}`,
+      target: `rules/corrupt-${crypto.randomUUID()}.md`,
+      principal_id: 'principal',
+      operation_id: 'operation',
+    };
+    const good = await store.acquire(corruptInput, 30_000);
+    fs.writeFileSync(leaseStatePath(store.root, corruptInput.workspace_id, corruptInput.target), '{not-json', { mode: 0o600 });
+    let unreadable = false;
+    try {
+      await store.verify({ ...corruptInput, lease_id: good.lease_id });
+    } catch (error) {
+      unreadable = /unreadable/i.test(error.message);
+    }
+    record('unreadable lease state fails closed', unreadable);
+  }
+
   return { passed: checks.every((check) => check.passed), checks };
 }

package/src/projections.mjs

@@ -1,4 +1,4 @@
-/** Replayable, cursor-aware SSSS projection coordinator. */
+/** Replayable, cursor-aware SSSS projection coordinator and host adapter examples. */
 import crypto from 'node:crypto';
 
 function stable(value) {
@@ -11,6 +11,77 @@ export function projectionHash(value) {
   return `sha256:${crypto.createHash('sha256').update(JSON.stringify(stable(value))).digest('hex')}`;
 }
 
+/**
+ * Reference projection destination adapters.
+ * Hosts own durable destination writes; these prove the shared apply/reset/snapshot contract.
+ */
+export function createSqlProjectionAdapter({ table = 'ssss_events' } = {}) {
+  const rows = new Map();
+  return {
+    id: `sql:${table}`,
+    kind: 'sql',
+    apply: async (event) => {
+      rows.set(event.event_id, {
+        event_id: event.event_id,
+        subject: event.subject,
+        action: event.action,
+        after_hash: event.after_hash,
+        workspace_id: event.workspace_id,
+      });
+    },
+    reset: async () => rows.clear(),
+    snapshot: async () => Object.fromEntries([...rows.entries()].sort()),
+  };
+}
+
+export function createSearchProjectionAdapter({ index = 'ssss' } = {}) {
+  const documents = new Map();
+  return {
+    id: `search:${index}`,
+    kind: 'search',
+    apply: async (event) => {
+      documents.set(event.subject, {
+        subject: event.subject,
+        terms: [event.action, event.primitive_id, event.subject].filter(Boolean).join(' '),
+        after_hash: event.after_hash,
+      });
+    },
+    reset: async () => documents.clear(),
+    snapshot: async () => Object.fromEntries([...documents.entries()].sort()),
+  };
+}
+
+export function createQueueProjectionAdapter({ topic = 'ssss.mutations' } = {}) {
+  const messages = [];
+  return {
+    id: `queue:${topic}`,
+    kind: 'queue',
+    apply: async (event) => {
+      messages.push({ topic, event_id: event.event_id, subject: event.subject, action: event.action });
+    },
+    reset: async () => { messages.length = 0; },
+    snapshot: async () => messages.map((message) => ({ ...message })),
+  };
+}
+
+export function createViewModelProjectionAdapter({ view = 'detail' } = {}) {
+  const models = new Map();
+  return {
+    id: `view:${view}`,
+    kind: 'view_model',
+    apply: async (event) => {
+      models.set(event.subject, {
+        subject: event.subject,
+        version: event.after_hash || event.before_hash || null,
+        last_action: event.action,
+        principal_id: event.principal?.id || null,
+      });
+    },
+    reset: async () => models.clear(),
+    snapshot: async () => Object.fromEntries([...models.entries()].sort()),
+  };
+}
+
 export class ProjectionCoordinator {
   constructor({ eventStore, cursorStore = new Map() } = {}) {
     if (!eventStore) throw new Error('ProjectionCoordinator requires an eventStore.');