@blamejs/core 0.8.43 → 0.8.49

package/lib/deprecate.js

@@ -1,53 +1,49 @@
 "use strict";
 /**
- * deprecate — runtime deprecation API for the framework's LTS contract.
+ * @module b.deprecate
+ * @nav    Production
+ * @title  Deprecate
  *
- * Operators see a one-time stderr warning the first time deprecated
- * surface is used, with the version it was deprecated in and the
- * version it'll be removed in. Production runs suppress warnings by
- * default (operators don't want stderr noise from deprecated paths in
- * code they don't own), but BLAMEJS_DEPRECATIONS env var inverts that
- * for visibility-on-demand.
+ * @intro
+ *   Runtime deprecation-warning system for the framework's LTS
+ *   contract. Operators see a one-time stderr warning the first time
+ *   deprecated surface is used, naming the version it was deprecated
+ *   in and the version it will be removed in — so behavior changes
+ *   ship visible at least one minor before the breakage lands in a
+ *   major.
  *
- *   var dep = b.deprecate;
+ *   Three usage shapes:
  *
- *   // Direct warning at the call site
- *   dep.warn("auth.legacyVerify", {
- *     since:    "0.2.0",
- *     removeIn: "0.4.0",
- *     message:  "use auth.password.verify(stored, plain) instead",
- *     hint:     "see MIGRATING.md#0-2-to-0-4",
- *   });
+ *     - `warn(name, opts)` — emit a warning at the call site of an
+ *       inline deprecated path.
+ *     - `wrap(fn, name, opts)` — return a wrapper around the
+ *       replacement function so calls to the old name auto-warn and
+ *       delegate.
+ *     - `alias(target, oldKey, newKey, opts)` — define `oldKey` on
+ *       `target` as a getter/setter that warns on access and reads
+ *       through to `newKey`.
  *
- *   // Wrap an old function so calls trigger the warning automatically
- *   var legacyVerify = dep.wrap(newVerify, "auth.legacyVerify", {
- *     since: "0.2.0", removeIn: "0.4.0",
- *     message: "renamed to auth.password.verify",
- *   });
+ *   Warnings dedupe by `(name, since)` — calling `warn` ten thousand
+ *   times with the same args emits a single stderr line; the per-name
+ *   call counter is still incremented so `list()` reflects real usage
+ *   volume for ops dashboards.
  *
- *   // Mark a property as deprecated; access triggers the warning
- *   dep.alias(targetObj, "oldKey", "newKey", {
- *     since: "0.2.0", removeIn: "0.4.0",
- *   });
- *
- *   dep.list();   // → [{ name, since, removeIn, callCount, firstSeen }]
- *   dep.reset();  // clears the seen-set; tests
+ *   `BLAMEJS_DEPRECATIONS` env var controls runtime behavior:
  *
- * BLAMEJS_DEPRECATIONS env var controls runtime behavior:
- *   "warn"    — stderr warning on first use of each (name, since) pair
- *               (default outside production)
- *   "silent"  — skip entirely (default in production)
- *   "error"   — throw on first use; development tool to surface every
- *               deprecated call site as a hard failure during a sweep
+ *     - `"warn"`   — stderr warning on first use (default outside
+ *                    production).
+ *     - `"silent"` — skip entirely (default in production; operators
+ *                    do not want stderr noise from deprecated paths
+ *                    in code they do not own).
+ *     - `"error"`  — throw on first use; development tool to surface
+ *                    every deprecated call site as a hard failure
+ *                    during a sweep.
  *
- * Mode resolution order:
- *   1. process.env.BLAMEJS_DEPRECATIONS if set
- *   2. "silent" when process.env.NODE_ENV === "production"
- *   3. "warn" otherwise
+ *   Mode resolution: explicit env var first, then `"silent"` when
+ *   `NODE_ENV=production`, otherwise `"warn"`.
  *
- * Warnings dedupe by (name, since) — calling deprecate.warn(...) ten
- * thousand times with the same args produces one stderr line. The
- * call counter is still incremented so dep.list() shows usage volume.
+ * @card
+ *   Runtime deprecation-warning system for the framework's LTS contract.
  */
 
 var safeEnv = require("./parsers/safe-env");
@@ -95,6 +91,38 @@ function _validateOpts(opts, fnName) {
   validateOpts.requireNonEmptyString(opts.removeIn, fnName + ": opts.removeIn (version string)", DeprecateError, "deprecate/bad-opts");
 }
 
+/**
+ * @primitive b.deprecate.warn
+ * @signature b.deprecate.warn(name, opts)
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.wrap, b.deprecate.alias, b.deprecate.list
+ *
+ * Emit a deprecation warning for an inline call site. First call for a
+ * given `(name, since)` pair writes a single line to stderr in `"warn"`
+ * mode, throws `DeprecateError` in `"error"` mode, and is suppressed
+ * in `"silent"` mode. Subsequent calls dedupe but still increment the
+ * per-name call counter so `list()` reports real usage volume. Throws
+ * `DeprecateError` (`deprecate/bad-name`) on missing `name` and
+ * (`deprecate/bad-opts`) when `since` or `removeIn` are missing or
+ * empty.
+ *
+ * @opts
+ *   since:     string,   // required; semver this surface was deprecated in
+ *   removeIn:  string,   // required; semver of planned removal
+ *   message:   string,   // optional human-readable replacement guidance
+ *   hint:      string,   // optional cross-reference (MIGRATING.md anchor)
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.deprecate.warn("auth.legacyVerify", {
+ *     since:    "0.2.0",
+ *     removeIn: "0.4.0",
+ *     message:  "use auth.password.verify(stored, plain) instead",
+ *     hint:     "see MIGRATING.md#0-2-to-0-4",
+ *   });
+ *   // → undefined  (stderr: [blamejs:deprecated] auth.legacyVerify (since 0.2.0); removed in 0.4.0 — ...)
+ */
 function warn(name, opts) {
   if (typeof name !== "string" || name.length === 0) {
     throw new DeprecateError("deprecate/bad-name",
@@ -137,6 +165,38 @@ function warn(name, opts) {
 // Wrap a function so calling it issues a deprecation warning + delegates.
 // The wrapper preserves the original function's `.length` (arity) so
 // callers introspecting it as a callable see the same shape.
+/**
+ * @primitive b.deprecate.wrap
+ * @signature b.deprecate.wrap(fn, name, opts)
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.warn, b.deprecate.alias
+ *
+ * Return a function that warns on first invocation then delegates to
+ * `fn` with the same `this` and arguments. Use to keep the old export
+ * name working through one minor version after rename. The wrapper's
+ * `.name` is set to `<name>:deprecated` for stack-trace clarity. Same
+ * dedupe + mode rules as `warn`. Throws `DeprecateError`
+ * (`deprecate/bad-target`) when `fn` is not a function and
+ * (`deprecate/bad-name`) on missing `name`.
+ *
+ * @opts
+ *   since:     string,   // required; semver this surface was deprecated in
+ *   removeIn:  string,   // required; semver of planned removal
+ *   message:   string,   // optional human-readable replacement guidance
+ *   hint:      string,   // optional cross-reference (MIGRATING.md anchor)
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   function passwordVerify(stored, plain) { return stored === plain; }
+ *   var legacyVerify = b.deprecate.wrap(passwordVerify, "auth.legacyVerify", {
+ *     since:    "0.2.0",
+ *     removeIn: "0.4.0",
+ *     message:  "renamed to auth.password.verify",
+ *   });
+ *   var ok = legacyVerify("stored", "plain");
+ *   // → false  (stderr warns once on first call)
+ */
 function wrap(fn, name, opts) {
   if (typeof fn !== "function") {
     throw new DeprecateError("deprecate/bad-target",
@@ -159,6 +219,39 @@ function wrap(fn, name, opts) {
 // Define `oldKey` on `target` as a getter that warns then returns
 // `target[newKey]`. The setter writes through so existing assignments
 // still work, but the getter access trips the warning.
+/**
+ * @primitive b.deprecate.alias
+ * @signature b.deprecate.alias(target, oldKey, newKey, opts)
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.wrap, b.deprecate.warn
+ *
+ * Define a getter/setter on `target.oldKey` that warns on access and
+ * reads/writes through to `target.newKey`. Use to keep a renamed
+ * property accessible for one minor without losing visibility into
+ * who still reads the old name. The aliased property is non-
+ * enumerable (so it does not leak into `Object.keys` / JSON
+ * serialization) but configurable so tests can redefine it. Throws
+ * `DeprecateError` (`deprecate/bad-target`) when `target` is not an
+ * object and (`deprecate/bad-name`) on missing `oldKey` / `newKey`.
+ *
+ * @opts
+ *   since:     string,   // required; semver this surface was deprecated in
+ *   removeIn:  string,   // required; semver of planned removal
+ *   message:   string,   // optional override; defaults to "use 'newKey' instead"
+ *   hint:      string,   // optional cross-reference (MIGRATING.md anchor)
+ *   aliasName: string,   // optional override for the warned identifier
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var settings = { timeout: 5000 };
+ *   b.deprecate.alias(settings, "timeoutMs", "timeout", {
+ *     since:    "0.3.0",
+ *     removeIn: "0.5.0",
+ *   });
+ *   var v = settings.timeoutMs;
+ *   // → 5000  (stderr warns once on first read)
+ */
 function alias(target, oldKey, newKey, opts) {
   if (!target || typeof target !== "object") {
     throw new DeprecateError("deprecate/bad-target",
@@ -187,6 +280,28 @@ function alias(target, oldKey, newKey, opts) {
   });
 }
 
+/**
+ * @primitive b.deprecate.list
+ * @signature b.deprecate.list()
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.warn, b.deprecate.reset, b.deprecate.getMode
+ *
+ * Return an array of every deprecated identifier hit during this
+ * process's lifetime — `{ name, since, removeIn, callCount,
+ * firstSeen }`. Sorted most-frequent first, ties broken by earliest
+ * `firstSeen`. Use from an ops dashboard or boot diagnostic to surface
+ * which deprecated paths the running deployment still exercises so
+ * the team can prioritize migrations before the `removeIn` major
+ * lands.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.deprecate.warn("auth.legacyVerify", { since: "0.2.0", removeIn: "0.4.0" });
+ *   var rows = b.deprecate.list();
+ *   // → [{ name: "auth.legacyVerify", since: "0.2.0", removeIn: "0.4.0",
+ *   //      callCount: 1, firstSeen: "2026-05-09T12:00:00.000Z" }]
+ */
 function list() {
   var out = [];
   _seen.forEach(function (v) {
@@ -206,9 +321,49 @@ function list() {
   return out;
 }
 
+/**
+ * @primitive b.deprecate.reset
+ * @signature b.deprecate.reset()
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.list, b.deprecate.warn
+ *
+ * Clear the seen-set so subsequent `warn` / `wrap` / `alias` calls
+ * re-emit their first-use warnings. Used by tests that exercise the
+ * deprecation path repeatedly; not meant for production code, where
+ * the dedupe is intentional.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   b.deprecate.warn("auth.legacyVerify", { since: "0.2.0", removeIn: "0.4.0" });
+ *   b.deprecate.reset();
+ *   var seen = b.deprecate.list();
+ *   // → []
+ */
 function reset() { _seen.clear(); }
 
 // Export the resolved mode so tests + ops dashboards can introspect
+/**
+ * @primitive b.deprecate.getMode
+ * @signature b.deprecate.getMode()
+ * @since     0.1.90
+ * @status    stable
+ * @related   b.deprecate.warn, b.deprecate.list
+ *
+ * Return the resolved deprecation mode for the current process —
+ * `"warn"`, `"silent"`, or `"error"`. Resolution order: explicit
+ * `BLAMEJS_DEPRECATIONS` env var, then `"silent"` when
+ * `NODE_ENV=production`, otherwise `"warn"`. Use from boot diagnostics
+ * or test setup to confirm the active posture before exercising
+ * deprecated paths.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var mode = b.deprecate.getMode();
+ *   // → "warn"     (development default)
+ *   // → "silent"   (NODE_ENV=production)
+ *   // → "error"    (BLAMEJS_DEPRECATIONS=error)
+ */
 function getMode() { return _modeFromEnv(); }
 
 module.exports = {

package/lib/dev.js

@@ -1,50 +1,51 @@
 "use strict";
 /**
- * dev — file-watch + child-process restart for iteration loops.
+ * @module b.dev
+ * @nav    Tools
+ * @title  Dev
  *
- * The framework's hot-reload primitive. Spawn the app as a child
- * process, watch the source directories, and restart the child when a
- * file changes. On-disk state (vault keys, encrypted DB, sealed
- * cookies) survives the restart because the child re-opens the files
- * — only in-process state is lost, which is the correct semantic for
- * "I just edited a route handler and want to see it."
+ * @intro
+ *   Dev-mode helpers — hot-reload signal (file watch + child-process
+ *   restart), route-list dump exposed via `dev.stats()`, and a request
+ *   inspector courtesy of `stdio: 'inherit'` so the operator sees the
+ *   spawned app's logs unchanged.
  *
- *   var dev = b.dev.create({
- *     command: "node",
- *     args:    ["./server.js"],
- *     watch:   ["./routes", "./views", "./public", "./lib"],
- *     ignore:  [/node_modules/, /\.db$/, /\.tmp$/, /^\./],
- *     graceMs: 250,           // debounce: collapse bursts into one restart
- *     killSignal:    "SIGTERM",
- *     killTimeoutMs: 4000,    // SIGKILL after this if SIGTERM is ignored
- *     log:     logInstance,   // optional structured logger
- *     env:     { ...process.env, BLAMEJS_DEV: "1" },
- *     cwd:     process.cwd(),
- *   });
+ *   The hot-reload loop spawns the app as a child process, watches the
+ *   source directories with `fs.watch({ recursive: true })`, and
+ *   restarts the child when an unignored file changes. On-disk state
+ *   (vault keys, encrypted DB, sealed cookies) survives the restart
+ *   because the child re-opens the files; only in-process state is
+ *   lost, which is the correct semantic for "I just edited a route
+ *   handler and want to see it."
  *
- *   await dev.start();        // launches child + arms watchers
- *   await dev.stop();         // signals child + closes watchers
+ *   Hygiene baked in:
+ *     - Bursts of file events (save-everything keystrokes, multi-file
+ *       format-on-save) collapse into one restart via the `graceMs`
+ *       debounce (default 250 ms).
+ *     - A restart-in-flight queues at most one follow-up — many edits
+ *       during a slow restart yield two restarts, not N.
+ *     - Ignored kinds by default: `node_modules/`, `.git/`, dotfiles,
+ *       SQLite journal/WAL/SHM siblings, `.log`, editor scratch files
+ *       (`.swp`, `~$`).
+ *     - Crash without a pending stop/restart leaves the child corpse
+ *       in place and waits for a file change rather than spawn-thrashing.
+ *     - Graceful kill via `SIGTERM`; `SIGKILL` escalation after
+ *       `killTimeoutMs` (default 4000 ms) if the child ignores it.
  *
- *   dev.stats();              // → { pid, running, restarts, lastRestartAt }
+ *   Production refusal: `dev.create()` throws `dev/refused-in-production`
+ *   when `NODE_ENV=production`, unless the operator explicitly sets
+ *   `opts.allowProduction: true` with an audited reason. This is what
+ *   `blamejs dev` (CLI) calls; production deployments that accidentally
+ *   wire it crash loudly at boot rather than spawning shells on every
+ *   save.
  *
- * Operator-side, this is what `blamejs dev` will call (next CLI slice).
+ *   Test seams: `opts._spawn(cmd, args, sopts)` and
+ *   `opts._watch(dir, wopts, listener)` default to `child_process.spawn`
+ *   and `fs.watch`; unit tests pass fakes to drive the engine without
+ *   real subprocesses.
  *
- * Engine hygiene:
- *   - Bursts of file events (a saved-everything keystroke, a multi-
- *     file format-on-save) collapse into one restart via debounce.
- *   - The child is spawned with stdio: 'inherit' so the operator sees
- *     their app's output unchanged.
- *   - Parent SIGINT/SIGTERM are forwarded: stop() before exit so an
- *     orphan child can't outlive the dev session.
- *   - Restart in-flight when a new event arrives: queue one followup,
- *     no more — many edits during a slow restart still result in only
- *     two restarts, not N.
- *
- * Test seams:
- *   opts._spawn(cmd, args, sopts)        → child-process-shaped object
- *   opts._watch(dir, wopts, listener)    → fs.watcher-shaped object
- *   These default to child_process.spawn and fs.watch; tests pass
- *   fakes to drive the engine without real subprocesses.
+ * @card
+ *   Dev-mode helpers — hot-reload signal (file watch + child-process restart), route-list dump exposed via `dev.stats()`, and a request inspector courtesy of `stdio: 'inherit'` so the operator sees the spawned app's logs unchanged.
  */
 
 var path = require("path");
@@ -114,6 +115,48 @@ function _logVia(log, level, message, fields) {
   emit(line);
 }
 
+/**
+ * @primitive b.dev.create
+ * @signature b.dev.create(opts)
+ * @since     0.4.0
+ * @status    stable
+ *
+ * Build a hot-reload supervisor — spawn `opts.command` with `opts.args`,
+ * watch `opts.watch` directories, and restart the child on every
+ * unignored file change. Returns `{ start, stop, restart, stats }`;
+ * `stats()` reports `{ pid, running, restarts, lastRestartAt, watchers }`.
+ *
+ * Throws `DevError` at config time on a missing command, a non-finite
+ * `graceMs` / `killTimeoutMs`, or an attempt to load with
+ * `NODE_ENV=production` (without `opts.allowProduction`).
+ *
+ * @opts
+ *   command:        string,                       // required — program to spawn (e.g. "node")
+ *   args:           [string],                     // argv after command; default []
+ *   watch:          [string],                     // directories to watch (recursive); default ["."]
+ *   ignore:         [RegExp | string],            // appended to the framework default-ignore list
+ *   graceMs:        number,                       // debounce window (ms); default 250
+ *   killSignal:     string,                       // initial kill signal; default "SIGTERM"
+ *   killTimeoutMs:  number,                       // SIGKILL escalation budget (ms); default 4000
+ *   log:            object,                       // structured logger ({ info, warn, error })
+ *   env:            object,                       // child env; default process.env
+ *   cwd:            string,                       // child cwd; default process.cwd()
+ *   stdio:          string | array,               // child stdio; default "inherit"
+ *   allowProduction: boolean,                     // override the production refusal (audited reason required)
+ *
+ * @example
+ *   var dev = b.dev.create({
+ *     command: "node",
+ *     args:    ["./server.js"],
+ *     watch:   ["./routes", "./views", "./lib"],
+ *     ignore:  [/\.tmp$/],
+ *     graceMs: 250,
+ *   });
+ *
+ *   // await dev.start();
+ *   // dev.stats();   // → { pid: <number>, running: true, restarts: 0, lastRestartAt: null, watchers: 3 }
+ *   // await dev.stop();
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.command, "dev.create: opts.command (the program to spawn)", DevError, "dev/no-command");

package/lib/dora.js

@@ -1,56 +1,29 @@
 "use strict";
 /**
- * b.dora — DORA Article 17 ICT-related incident-reporting workflow.
+ * @module b.dora
+ * @nav    Compliance
+ * @title  DORA
  *
- * Digital Operational Resilience Act (Regulation (EU) 2022/2554)
- * Article 17 requires every "financial entity" subject to DORA to
- * classify, document, and report ICT-related incidents according to
- * the harmonized RTS template (Commission Delegated Regulation
- * 2024/1772). This primitive is the framework hook — operators wire
- * it into their incident-management workflow; the framework owns the
- * classification rubric, the three-stage report shape (initial /
- * intermediate / final), and the audit-chain integration.
+ * @intro
+ *   DORA Article 17 ICT-related incident-reporting workflow. The
+ *   Digital Operational Resilience Act (Regulation (EU) 2022/2554)
+ *   Article 17 requires every "financial entity" subject to DORA to
+ *   classify, document, and report ICT-related incidents according to
+ *   the harmonized RTS template (Commission Delegated Regulation
+ *   2024/1772). The framework owns the classification rubric, the
+ *   three-stage report shape (initial / intermediate / final), and
+ *   the audit-chain integration; operators wire the produced
+ *   RTS-template-shaped records into their submission code (channel
+ *   + ESA / national-supervisor credentials are operator-specific —
+ *   the framework does NOT submit on the operator's behalf).
  *
- *   var dora = b.dora.create({ audit: b.audit });
+ *   Adjacent regimes (NIS2 Art. 23, CRA Art. 14, HIPAA breach
+ *   notification) share the deadline-tracking shape; reference
+ *   constants live on the module so operators don't pin literal hour
+ *   counts in their reporters.
  *
- *   var classification = dora.classify({
- *     dataAffected:        "phi" | "financial" | "personal" | "operational" | "none",
- *     systemsAffected:     ["payments-gateway", "core-ledger"],
- *     durationMs:          C.TIME.hours(4),
- *     severityIndicator:   "critical" | "high" | "medium" | "low",
- *     economicImpact:      { eur: 50000 },
- *     affectedClients:     1200,
- *     geographicScope:     ["DE", "FR"],
- *     reputationalImpact:  "media" | "internal" | "none",
- *   });
- *   // → { classification: "major" | "significant" | "minor",
- *   //     mustReport: true|false, mustReportInitialBy: ms-since-detection,
- *   //     reasons: [...] }
- *
- *   var initial = dora.report({
- *     incidentId:        "INC-2026-0042",
- *     classification:    "major",
- *     stage:             "initial",
- *     detectedAt:        Date.now() - C.TIME.minutes(60),
- *     description:       "Payment-gateway outage — 2-hour customer-facing impact",
- *     causeKnown:        false,
- *     mitigationStarted: true,
- *   });
- *
- *   // 72h after detection: intermediate update
- *   dora.report(Object.assign({}, initial, { stage: "intermediate", ... }));
- *   // 1 month later (or upon closure): final report
- *   dora.report(Object.assign({}, initial, { stage: "final", rootCause: "...", ... }));
- *
- * Audit posture (audit namespace "dora"):
- *   - dora.incident.classified  — every classify() call
- *   - dora.incident.reported    — every report() submission
- *   - dora.incident.draftFinal  — every draftFinalReport() generation
- *
- * The primitive does NOT submit to ESAs / national supervisors — that
- * step is operator-side (channel + credentials are operator-specific).
- * The primitive produces the RTS-template-shaped record that the
- * operator's submission code drops into the regulator's API.
+ * @card
+ *   DORA Article 17 ICT-related incident-reporting workflow.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -253,6 +226,52 @@ function _validateReportInput(input) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive b.dora.create
+ * @signature b.dora.create(opts)
+ * @since     0.7.25
+ * @status    stable
+ * @compliance dora, nis2, cra, hipaa
+ * @related   b.audit.safeEmit
+ *
+ * Build a DORA reporter handle exposing `classify`, `report`, and
+ * `draftFinalReport`. `classify` runs the RTS 2024/1772 Articles
+ * 1-12 thresholds (severity / affected clients / economic impact /
+ * geographic scope / duration / reputational / sensitive-data
+ * classes) and returns the regulatory tier (`"major"` / `"significant"`
+ * / `"minor"`) plus a deadline hint. `report` validates and shapes
+ * the operator's payload into an RTS-template record carrying the
+ * `nextStageDueAt` deadline (Art. 19 — 24h initial / 72h intermediate
+ * / 30-day final). `draftFinalReport` clones a prior record into a
+ * Stage-final skeleton with the operator-fillable fields zeroed.
+ * Each call emits an audit row in the `dora.*` namespace.
+ *
+ * @opts
+ *   audit:          boolean (default true; set false to skip audit emits),
+ *   observability:  boolean (reserved — observability counter is always
+ *                  best-effort and ignored on failure),
+ *
+ * @example
+ *   var dora = b.dora.create({ audit: true });
+ *   var rv = dora.classify({
+ *     dataAffected:       "financial",
+ *     severityIndicator:  "critical",
+ *     affectedClients:    1200,
+ *     economicImpact:     { eur: 50000 },
+ *     durationMs:         4 * 60 * 60 * 1000,
+ *   });
+ *   rv.classification;     // → "major"
+ *   rv.mustReport;         // → true
+ *
+ *   var initial = dora.report({
+ *     incidentId:    "INC-2026-0042",
+ *     classification: rv.classification,
+ *     stage:         "initial",
+ *     detectedAt:    Date.now(),
+ *     description:   "Payment-gateway outage — 2h customer-facing impact",
+ *   });
+ *   initial.stage;         // → "initial"
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["audit", "observability"], "dora.create");