@gregiteen/ssss-cli 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-13
+### Added
+- `trigger` gains `event_subject` and `event_match`, and `assistant` gains `owns`.
+  `@gregiteen/ssss-cli/runtime` exports `triggerMatchesEvent`, `subjectMatches`
+  and `resolveSubjectOwner`; the spec (§11.8) defines event matching and subject
+  ownership, which `source: event` previously left undefined.
+
+### Fixed
+- Work caused by an event is now keyed by `event_id` (and carries it as
+  `causation_id`), not by the event's timestamp. Two events in the same
+  millisecond no longer collapse into one task path and key.
+
+## [0.10.3] - 2026-10-01
+### Fixed
+- Read event logs in 64 KiB chunks when building duplicate-ID indexes or
+  replaying events. Large histories no longer require one full-log string.
+  UTF-8 decoding, replay cursors, file locks and duplicate detection retain
+  their contracts. A regression check guards bounded reads and corrupt-log
+  rejection.
+
 ## [0.10.2] - 2026-09-28
 ### Fixed
 - The 0.10.0 notes promised pointer fields for large-file assets, but the

package/VERSION

@@ -1 +1 @@
-0.10.2
+0.11.0

package/conformance/reference-bundle.ucw.json

@@ -106,7 +106,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@gregiteen/ssss-cli@0.10.2"
+      "exporter": "@gregiteen/ssss-cli@0.10.3"
     }
   },
   "files": [

package/docs/ssss-spec.md

@@ -1487,6 +1487,24 @@ Core trigger types are:
 | `file_change` | A matching vault path is created, patched, or deleted. |
 | `condition` | A host-defined predicate over vault/projection state becomes true. |
 
+An `event` trigger selects canonical events (§8) with two optional fields on the
+`trigger` primitive, evaluated as a pure function of the trigger and the event:
+
+- `event_subject` is a glob over the event `subject`. `*` matches within one `/`
+  segment and `**` matches across segments.
+- `event_match` maps dotted event paths (for example `principal.kind`) to a literal
+  or an array of allowed literals. Every entry MUST hold.
+
+A trigger with neither field matches nothing. An event nobody matches is only
+recorded. Work an event causes MUST carry the event's `event_id` as `causation_id`,
+and its idempotency basis uses `event_id` in place of `scheduled_for`, so a replayed
+event creates no second task and two events at the same instant create two.
+
+An `assistant` MAY declare `owns`, a list of subject globs it is responsible for.
+The owner of a subject is the assistant whose claim has the longest literal prefix.
+Equal best claims are a conflict that a host MUST surface rather than resolve
+silently. Ownership says who is responsible; a lease (§7) says who is acting now.
+
 Trigger entries SHOULD use the fields documented in §5.4 `workflow`. Hosts MAY add
 type-specific `x_` fields, but MUST preserve unknown fields when rewriting the
 workflow document (§4.2).
@@ -1497,6 +1515,7 @@ The idempotency basis for runtime-created work is:
 
 ```text
 workspace_id + workflow_id + trigger_id + scheduled_for
+workspace_id + workflow_id + trigger_id + event_id        (event-driven work)
 ```
 
 Two daemon ticks evaluating the same trigger for the same scheduled instant MUST

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {
@@ -56,7 +56,7 @@
   ],
   "scripts": {
     "conformance": "node ./scripts/conformance.mjs conformance",
-    "test": "node ./scripts/conformance.mjs conformance --engine"
+    "test": "node ./scripts/conformance.mjs conformance --engine && node ./scripts/check-events-streaming.mjs"
   },
   "keywords": [
     "ssss",

package/registry/core.json

@@ -115,6 +115,7 @@
       "append_only": false,
       "portability": "structural",
       "required_fields": ["type", "name"],
+      "optional_fields": ["owns"],
       "spec_ref": "§5.4 assistant"
     },
     "workflow": {
@@ -132,7 +133,7 @@
       "append_only": false,
       "portability": "structural",
       "required_fields": ["type", "name", "source", "status"],
-      "optional_fields": ["slug", "description", "cron", "interval", "timezone", "target_workflow", "target_params", "concurrency", "misfire_policy"],
+      "optional_fields": ["slug", "description", "cron", "interval", "timezone", "target_workflow", "target_params", "concurrency", "misfire_policy", "event_subject", "event_match"],
       "enums": {
         "source": ["cron", "interval", "webhook", "event", "file_change", "condition", "manual"],
         "status": ["active", "paused", "disabled"],

package/scripts/check-events-streaming.mjs

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { JsonlEventStore, createCanonicalEvent } from '../src/events.mjs';
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-event-stream-'));
+const file = path.join(root, 'acme.jsonl');
+const make = index => createCanonicalEvent({
+  workspace_id: 'acme', action: 'event', subject: 'stream-test',
+  principal: { id: 'test', kind: 'service' }, operation_id: `operation-${index}`,
+  idempotency_key: `key-${index}`, payload: { text: 'a'.repeat(65500) + '🧠é'.repeat(25000) }
+});
+const events = [make(1), make(2)];
+const originals = { alloc: Buffer.alloc, readFileSync: fs.readFileSync, readSync: fs.readSync };
+try {
+  fs.writeFileSync(file, events.map(event => JSON.stringify(event)).join('\n') + '\n');
+  Buffer.alloc = (size, ...rest) => { assert.ok(size <= 65536, 'Event reader allocated the whole log'); return originals.alloc(size, ...rest); };
+  fs.readFileSync = (target, ...rest) => { assert.notEqual(target, file, 'Event reader loaded the whole log'); return originals.readFileSync(target, ...rest); };
+  let largestRead = 0;
+  fs.readSync = (fd, buffer, offset, length, position) => {
+    largestRead = Math.max(largestRead, length);
+    assert.ok(length <= 65536, 'Event reader requested the whole log');
+    return originals.readSync(fd, buffer, offset, Math.min(length, 4093), position);
+  };
+  const store = new JsonlEventStore(root);
+  await assert.rejects(store.append(events[0]), /Duplicate event_id/);
+  const third = make(3);
+  await store.append(third);
+  const replayed = [];
+  for await (const entry of store.replay({ workspaceId: 'acme', cursor: 1 })) replayed.push(entry);
+  assert.deepEqual(replayed.map(entry => entry.cursor), [2, 3]);
+  assert.deepEqual(replayed.map(entry => entry.event), [events[1], third]);
+  await assert.rejects(new JsonlEventStore(root).append(third), /Duplicate event_id/);
+  fs.appendFileSync(file, '{invalid JSON}\n');
+  await assert.rejects(new JsonlEventStore(root).append(make(4)), SyntaxError);
+  console.log(JSON.stringify({ ok: true, boundedReads: true, utf8: true, cursor: true, duplicate: true, corruptFailClosed: true, largestRead }));
+} finally {
+  Buffer.alloc = originals.alloc; fs.readFileSync = originals.readFileSync; fs.readSync = originals.readSync;
+  fs.rmSync(root, { recursive: true });
+}

package/scripts/conformance.mjs

@@ -29,7 +29,7 @@ import {
 } from '../src/bundle.mjs';
 import { parseDocument } from '../src/frontmatter.mjs';
 import { loadRegistries } from '../src/registry.mjs';
-import { createRunEnvelope, planWorkflowTrigger } from '../src/runtime.mjs';
+import { createRunEnvelope, planWorkflowTrigger, resolveSubjectOwner, subjectMatches, triggerMatchesEvent } from '../src/runtime.mjs';
 import {
   buildSemanticIndex,
   enrichSemanticIndex,
@@ -970,6 +970,32 @@ async function runRuntimeConformance() {
     `${firstPlan.envelopes[1].path} !== ${secondPlan.envelopes[1].path}`);
   check('same workflow trigger plans the same task idempotency key',
     firstPlan.envelopes[1].idempotency_key === secondPlan.envelopes[1].idempotency_key);
+  const eventTrigger = { source: 'event', status: 'active', event_subject: 'tool/*/exec', event_match: { 'principal.kind': ['agent', 'user'] } };
+  const toolEvent = { event_id: 'e1', timestamp: scheduledFor, subject: 'tool/ssh/exec', principal: { kind: 'agent', id: 'a' } };
+  check('event trigger matches by subject glob and payload predicate',
+    triggerMatchesEvent(eventTrigger, toolEvent) === true
+    && triggerMatchesEvent(eventTrigger, { ...toolEvent, subject: 'tool/ssh/a/exec' }) === false
+    && triggerMatchesEvent(eventTrigger, { ...toolEvent, principal: { kind: 'service', id: 's' } }) === false
+    && triggerMatchesEvent({ ...eventTrigger, status: 'paused' }, toolEvent) === false
+    && triggerMatchesEvent({ source: 'event', status: 'active' }, toolEvent) === false
+    && triggerMatchesEvent({ ...eventTrigger, source: 'cron' }, toolEvent) === false);
+  check('subject globs: * stays in a segment, ** crosses segments',
+    subjectMatches('secrets/*', 'secrets/KEY') && !subjectMatches('secrets/*', 'secrets/a/b') && subjectMatches('secrets/**', 'secrets/a/b'));
+  const planEvent = (event) => planWorkflowTrigger({ workflowPath, workflowContent, workspaceId: 'TEST_WORKSPACE_ID', trigger: { type: 'event', event_type: 'tool' }, event });
+  const planA = planEvent(toolEvent);
+  const planB = planEvent({ ...toolEvent, event_id: 'e2' });
+  check('event-driven work is keyed by the event: same event same task, same instant different event different task',
+    planEvent(toolEvent).envelopes[1].idempotency_key === planA.envelopes[1].idempotency_key
+    && planA.envelopes[1].idempotency_key !== planB.envelopes[1].idempotency_key
+    && planA.envelopes[1].path !== planB.envelopes[1].path
+    && JSON.parse(planA.envelopes[0].content).causation_id === 'e1');
+  const ownerA = { name: 'gate', owns: ['tool/**'] };
+  const ownerB = { name: 'mesh-warden', owns: ['tool/ssh/*'] };
+  check('subject ownership is the longest claim; equal claims are a conflict, not a pick',
+    resolveSubjectOwner('tool/ssh/exec', [ownerA, ownerB]).owner === ownerB
+    && resolveSubjectOwner('tool/other/x', [ownerA, ownerB]).owner === ownerA
+    && resolveSubjectOwner('x/y', [ownerA, ownerB]).owner === null
+    && resolveSubjectOwner('tool/ssh/exec', [ownerB, { name: 'twin', owns: ['tool/ssh/*'] }]).conflict.length === 2);
   check('runtime emits event then task envelopes',
     firstPlan.envelopes[0].type === 'event' && firstPlan.envelopes[1].type === 'operation');
 

package/src/events.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
 import { withFileLock } from './file-lock.mjs';
 
 // UUIDv5 namespace for event ids derived from idempotency keys.
@@ -83,22 +84,33 @@ 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. */
+/** Decode one line at a time, never materializing the complete log as a string. */
+function* logLines(fd, size) {
+  const buffer = Buffer.alloc(64 * 1024);
+  const decoder = new StringDecoder('utf8');
+  let offset = 0, pending = '';
+  while (offset < size) {
+    const read = fs.readSync(fd, buffer, 0, Math.min(buffer.length, size - offset), offset);
+    if (read === 0) break;
+    offset += read;
+    const text = pending + decoder.write(buffer.subarray(0, read));
+    let start = 0, newline;
+    while ((newline = text.indexOf('\n', start)) !== -1) {
+      yield text.slice(start, newline);
+      start = newline + 1;
+    }
+    pending = text.slice(start);
+  }
+  pending += decoder.end();
+  if (pending) yield pending;
+}
+
+/** Read every event_id, 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);
-    }
+    const stat = fs.fstatSync(fd), ids = new Set();
+    for (const line of logLines(fd, stat.size)) if (line.trim()) ids.add(JSON.parse(line).event_id);
     return { ids, stat };
   } finally { fs.closeSync(fd); }
 }
@@ -168,12 +180,15 @@ export class JsonlEventStore {
     for (const file of files) {
       if (!fs.existsSync(file)) continue;
       if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
-      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-        if (!line.trim()) continue;
-        cursor++;
-        if (cursor <= (options.cursor || 0)) continue;
-        yield { cursor, event: JSON.parse(line) };
-      }
+      const fd = openLog(file, fs.constants.O_RDONLY | NOFOLLOW);
+      try {
+        for (const line of logLines(fd, fs.fstatSync(fd).size)) {
+          if (!line.trim()) continue;
+          cursor++;
+          if (cursor <= (options.cursor || 0)) continue;
+          yield { cursor, event: JSON.parse(line) };
+        }
+      } finally { fs.closeSync(fd); }
     }
   }
 }

package/src/runtime.mjs

@@ -69,6 +69,59 @@ export function normalizeRuntimeTrigger(trigger = {}) {
   };
 }
 
+/** Glob over event subjects: `*` stays within one `/` segment, `**` crosses segments. */
+export function subjectMatches(pattern, subject) {
+  if (typeof pattern !== 'string' || typeof subject !== 'string' || !pattern) return false;
+  const re = pattern.split('**').map((part) => part.split('*').map((lit) => lit.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*');
+  return new RegExp(`^${re}$`).test(subject);
+}
+
+function valueAt(object, dotted) {
+  return String(dotted).split('.').reduce((value, key) => (value && typeof value === 'object' ? value[key] : undefined), object);
+}
+
+/**
+ * Whether an `event` trigger selects a canonical event (§5.4 trigger, §11.8).
+ * `event_subject` is a subject glob. `event_match` maps dotted event paths to a
+ * literal or an array of allowed literals; every entry must hold. Pure and
+ * deterministic: no clock, no I/O. A trigger that is not `source: event`, or
+ * is not active, never matches.
+ */
+export function triggerMatchesEvent(trigger = {}, event = {}) {
+  const source = trigger.source || trigger.type;
+  if (source !== 'event') return false;
+  if (trigger.status && trigger.status !== 'active') return false;
+  if (!trigger.event_subject && !trigger.event_match) return false;
+  if (trigger.event_subject && !subjectMatches(trigger.event_subject, event.subject)) return false;
+  for (const [key, expected] of Object.entries(trigger.event_match || {})) {
+    const actual = valueAt(event, key);
+    const allowed = Array.isArray(expected) ? expected : [expected];
+    if (!allowed.some((candidate) => candidate === actual)) return false;
+  }
+  return true;
+}
+
+/**
+ * The assistant that owns a subject: the one whose `owns` globs claim it with
+ * the longest literal prefix. Equal best claims are a conflict, never a silent
+ * pick. Returns { owner, conflict } where `conflict` lists the tied assistants.
+ */
+export function resolveSubjectOwner(subject, assistants = []) {
+  let best = -1;
+  let winners = [];
+  for (const assistant of assistants) {
+    for (const pattern of [].concat(assistant?.owns || [])) {
+      if (!subjectMatches(pattern, subject)) continue;
+      const specificity = pattern.split('*')[0].length;
+      if (specificity > best) { best = specificity; winners = [assistant]; }
+      else if (specificity === best && !winners.includes(assistant)) winners.push(assistant);
+    }
+  }
+  if (winners.length === 0) return { owner: null, conflict: [] };
+  if (winners.length === 1) return { owner: winners[0], conflict: [] };
+  return { owner: null, conflict: winners };
+}
+
 export function planWorkflowTrigger({
   workflowPath,
   workflowContent,
@@ -78,6 +131,7 @@ export function planWorkflowTrigger({
   firedAt = scheduledFor || new Date().toISOString(),
   payload = {},
   actor = { role: 'system' },
+  event = null,
 } = {}) {
   if (!workflowPath) throw new Error('workflowPath is required.');
   if (!workflowContent) throw new Error('workflowContent is required.');
@@ -89,11 +143,14 @@ export function planWorkflowTrigger({
 
   const normalizedTrigger = normalizeRuntimeTrigger(trigger);
   const workflow_id = workflowIdFromPath(workflowPath, data);
-  const scheduled_for = iso(scheduledFor || firedAt, 'scheduledFor');
+  // Event-driven work is identified by the event that caused it, so two events in the
+  // same millisecond make two tasks and a replayed event makes none.
+  const eventId = event?.event_id || null;
+  const scheduled_for = iso(scheduledFor || event?.timestamp || firedAt, 'scheduledFor');
   const fired_at = iso(firedAt || scheduled_for, 'firedAt');
-  const basis = `${workspaceId}:${workflow_id}:${normalizedTrigger.trigger_id}:${scheduled_for}`;
+  const basis = `${workspaceId}:${workflow_id}:${normalizedTrigger.trigger_id}:${eventId || scheduled_for}`;
   const dedupe_key = `runtime:${hash(basis, 40)}`;
-  const stamp = compactTimestamp(scheduled_for);
+  const stamp = compactTimestamp(scheduled_for) + (eventId ? `-${hash(eventId, 8)}` : '');
   const taskPath = `tasks/${workflow_id}/${normalizedTrigger.trigger_id}-${stamp}.md`;
   const eventPath = `events/workflows/${workflow_id}/${normalizedTrigger.trigger_id}-${stamp}`;
 
@@ -107,6 +164,7 @@ export function planWorkflowTrigger({
     fired_at,
     dedupe_key,
     payload,
+    ...(eventId ? { source_event_id: eventId, causation_id: eventId, correlation_id: event.correlation_id || eventId } : {}),
   };
 
   const taskContent = [