@gregiteen/ssss-cli 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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

package/VERSION

@@ -1 +1 @@
-0.10.3
+0.11.0

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.3",
+  "version": "0.11.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {

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/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/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 = [