Technical specification
Platform
Node.js 20, 22 or 24. ES modules (.mjs). Zero runtime and dev dependencies; only node: built-ins (fs, path, crypto, http, url, os, child_process in tests and scripts only).
Repository layout
| Path | Responsibility |
|---|---|
packages/core/ingest.mjs | format parsing, strict time, normalisation, redaction, limits, dedup, ordering |
packages/core/analyze.mjs | classification, hypotheses, report build, verifyReport, verifySources, compareReports |
packages/core/benchmark.mjs | 26 synthetic cases and runner |
packages/core/audit.mjs | 20 automated checks, corpora |
packages/core/schema.mjs | minimal JSON Schema validator for project contracts |
packages/core/meta.mjs | tool name, version, rule version, schema ids |
packages/reporter/ | Markdown, HTML, postmortem, register and audit renderers |
packages/server/ | loopback read-only API |
packages/cli/index.mjs | command dispatch |
skills/, agents/ | generated by scripts/build-skills.mjs |
schemas/ | incident-event, incident-report, agent-output (JSON Schema 2020-12) |
policies/default.json | read-only policy |
tests/ | node:test suites |
Event schema v2 (summary)
id (evt_ + 20 hex), schema, timestamp (UTC ms ISO), timestampNs (integer string), timePrecision (s/ms/us/ns), timeBasis (event/observed), originalTimestamp, originalOffset, observedTimestamp?, type, service, environment, severity, message, traceId, spanId, deployment, releaseId, metricValue?, attributes, dimensions, confidenceClass: observed, sensitivityClass, ingestionWarnings[], source{file, record, sha256}.
ID: sha256(sourceSha256:file:record:isoTime) first 20 hex. Stable across runs and machines.
Ordering
timestamp string, then timestampNs as BigInt, then source file name, then record number, then ID. Deterministic for identical input.
Time parsing
Regex for RFC3339, then explicit validation: month 1-12, day within month including leap years, hour 0-23, minute 0-59, second 0-59, offset hours 0-23 and minutes 0-59. Epoch milliseconds via Date.UTC minus offset; fractional digits padded to 9 and combined into a BigInt nanosecond string. The previous implementation relied on Date.parse, which silently accepts 2026-02-30 (returns 2026-03-02) and 24:00:00; those are now rejected.
Redaction
Ordered rule list (private key, JWT, URL credentials, key=value secrets, bearer, token prefixes, AWS keys, email, Luhn-checked card, SSN, IPv4, phone). Object keys matching a sensitive pattern are masked wholesale. Depth cap 8, 100 array items, 80 keys. Counts by kind go into the report. Idempotent. Guarded against catastrophic backtracking by test (200 KB hostile input under 3 s).
Report identity and verification
reportId = "inc_" + sha256(JSON.stringify(report without reportId))[0:20]. Deterministic: the report contains no wall-clock time. verifyReport checks schema id, reference integrity, no confirmed status, decision and not-run guard fields, and the digest. verifySources reloads the input and compares per-file SHA-256.
Local API
GET only; /health, /v1/report, /v1/summary, /v1/timeline, /v1/events, /v1/hypotheses, /v1/gaps. Bound to 127.0.0.1. Bearer token (24+ chars) with timingSafeEqual. Host header allowlist (127.0.0.1, localhost, [::1]). Cache-Control: no-store, nosniff, CSP default-src 'none'. 10 s request and header timeouts. Prototype-safe routing via Object.hasOwn.
Skills generation
scripts/build-skills.mjs holds one table of 20 roles and writes skills/*/SKILL.md, agents/*.md, agents/manifest.json and docs/AGENT_CATALOG.md. --check fails on drift (CI and a unit test).
Performance
2,000 events analysed within the benchmark budget of 5 s (C23); typical runs are a few milliseconds. Memory is bounded by the 2 MB x 100 files and 5,000-event caps.
Testing
node --test (no shell glob, works on Windows with Node 20). Suites: ingest, analysis, security, cli, server, project (benchmark, audit, skills, schema, compatibility). Symlink tests return early where the OS forbids symlink creation. npm run test:report writes machine-generated results to documents/IncidentSutra-AI/evidence.
Known technical limits
Keyword classification can misread unusual vocabularies. Deduplication is only across files. No streaming; files are read whole. Redaction is regex based. Clock skew is not measured.