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

PathResponsibility
packages/core/ingest.mjsformat parsing, strict time, normalisation, redaction, limits, dedup, ordering
packages/core/analyze.mjsclassification, hypotheses, report build, verifyReport, verifySources, compareReports
packages/core/benchmark.mjs26 synthetic cases and runner
packages/core/audit.mjs20 automated checks, corpora
packages/core/schema.mjsminimal JSON Schema validator for project contracts
packages/core/meta.mjstool name, version, rule version, schema ids
packages/reporter/Markdown, HTML, postmortem, register and audit renderers
packages/server/loopback read-only API
packages/cli/index.mjscommand dispatch
skills/, agents/generated by scripts/build-skills.mjs
schemas/incident-event, incident-report, agent-output (JSON Schema 2020-12)
policies/default.jsonread-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.