@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

package/src/lineage/obligation-mapping.js

@@ -0,0 +1,126 @@
+// obligation-mapping.js — Milestone 4 sub-project 6a: the ObligationMapping
+// extension contract (FR-504 §7.12, PRD §10.10's own field list).
+//
+// A PURE schema/validation module for ObligationMapping records. Zero
+// imports, matching flow-grade.js's own "pure function library" precedent
+// — this file has even less reason to import anything, since a record's
+// shape check needs no graph traversal.
+//
+// ObligationMapping records are explicitly NOT DataFlowGraph v1 entities
+// (PRD §10.10: extension records are "associated with, but not required
+// inside" the immutable base graph) — never added to
+// dataflow-graph.schema.json, never routed through validate.js's
+// validateGraph(), never given a node:/edge:/flow:/data: canonical ID.
+// See ids.js's obligationId() for the id scheme and its own header
+// comment for why (mirrors provenanceNodeId/provenanceEdgeId's own
+// precedent for "a real, stable-ID'd entity that deliberately is not a
+// base-graph entity").
+//
+// The predicate/mapping ENGINE that actually produces real records from a
+// real graph is a separate, later sub-project — this file only defines
+// what a valid record looks like.
+
+// PRD line 503-508's own six states.
+export const OBLIGATION_STATES = Object.freeze([
+  'evidence_supported', 'gap_detected', 'unknown',
+  'manual_required', 'not_applicable', 'accepted_exception',
+]);
+
+// PRD §10.10's cross-cutting fact-typing rule, applied to every extension
+// contract, not just this one.
+export const OBLIGATION_FACT_TYPES = Object.freeze([
+  'code_inferred', 'config_correlated', 'runtime_observed',
+  'declared', 'manual', 'hypothetical',
+]);
+
+// FR-504's own applicability-inputs list (line 512): "entity role,
+// jurisdiction, data subject, business process, merchant level, system
+// scope, AI-system role... must be explicitly configured or marked
+// unknown — never guessed from a field name." Every key defaults to
+// null (== "not configured") rather than being omitted, so a record can
+// never silently lack an input the PRD requires be shown.
+export const APPLICABILITY_INPUT_KEYS = Object.freeze([
+  'entityRole', 'jurisdiction', 'dataSubject', 'businessProcess',
+  'merchantLevel', 'systemScope', 'aiSystemRole',
+]);
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+function _isStringOrNull(v) {
+  return v === null || v === undefined || typeof v === 'string';
+}
+
+function _isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+/**
+ * Structural validation only — no cross-reference into any real graph
+ * (this module has zero graph access by design). Returns {valid, errors}
+ * — errors is an array of {path, message}, mirroring validate.js's own
+ * shape. Never throws.
+ */
+export function validateObligationMapping(record) {
+  const errors = [];
+  const err = (path, message) => errors.push({ path, message });
+
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    err('$', 'obligation mapping record must be an object');
+    return { valid: false, errors };
+  }
+
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('obligation:')) {
+    err('$.id', 'id is required and must start with "obligation:"');
+  }
+  if (!_isNonEmptyString(record.graphId)) err('$.graphId', 'graphId is required');
+  if (!_isNonEmptyString(record.graphDigest)) err('$.graphDigest', 'graphDigest is required');
+  if (!_isNonEmptyString(record.framework)) err('$.framework', 'framework is required');
+  if (!_isNonEmptyString(record.frameworkVersion)) err('$.frameworkVersion', 'frameworkVersion is required');
+  if (!_isNonEmptyString(record.requirementId)) err('$.requirementId', 'requirementId is required');
+  if (!_isStringOrNull(record.requirementSource)) err('$.requirementSource', 'requirementSource must be a string or null');
+
+  if (!record.applicabilityInputs || typeof record.applicabilityInputs !== 'object' || Array.isArray(record.applicabilityInputs)) {
+    err('$.applicabilityInputs', 'applicabilityInputs is required and must be an object');
+  } else {
+    for (const key of APPLICABILITY_INPUT_KEYS) {
+      if (!_isStringOrNull(record.applicabilityInputs[key])) {
+        err(`$.applicabilityInputs.${key}`, `applicabilityInputs.${key} must be a string or null`);
+      }
+    }
+  }
+
+  if (!OBLIGATION_STATES.includes(record.state)) {
+    err('$.state', `unrecognized state "${record.state}" — must be one of ${OBLIGATION_STATES.join('|')}`);
+  }
+  if (!_isNonEmptyString(record.predicate)) err('$.predicate', 'predicate is required');
+  if (!OBLIGATION_FACT_TYPES.includes(record.factType)) {
+    err('$.factType', `unrecognized factType "${record.factType}" — must be one of ${OBLIGATION_FACT_TYPES.join('|')}`);
+  }
+
+  if (!_isStringArray(record.contributingGraphIds ?? [])) err('$.contributingGraphIds', 'contributingGraphIds must be an array of strings');
+  if (!_isStringArray(record.evidence ?? [])) err('$.evidence', 'evidence must be an array of strings');
+  if (!_isStringArray(record.conflicts ?? [])) err('$.conflicts', 'conflicts must be an array of strings');
+  if (!_isStringArray(record.missingManualArtifacts ?? [])) err('$.missingManualArtifacts', 'missingManualArtifacts must be an array of strings');
+
+  if (!_isStringOrNull(record.reviewer)) err('$.reviewer', 'reviewer must be a string or null');
+  if (!_isStringOrNull(record.reviewedAt)) err('$.reviewedAt', 'reviewedAt must be a string or null');
+  if (!_isStringOrNull(record.expiresAt)) err('$.expiresAt', 'expiresAt must be a string or null');
+
+  // AC-28's own binding rule: PRD line 514 is explicit that
+  // evidence_supported means only "this predicate's evidence is
+  // supported," never organizational compliance — this module does NOT
+  // reject a record for having some null applicability inputs alongside
+  // evidence_supported (an input can be genuinely inapplicable to a
+  // given predicate). What IS enforced structurally: accepted_exception
+  // requires a real reviewer and expiresAt — an exception with no owner
+  // or no expiry is exactly the silent-permanent-waiver failure mode
+  // this state exists to prevent from being invisible.
+  if (record.state === 'accepted_exception') {
+    if (!_isNonEmptyString(record.reviewer)) err('$.reviewer', 'accepted_exception requires a reviewer');
+    if (!_isNonEmptyString(record.expiresAt)) err('$.expiresAt', 'accepted_exception requires an expiresAt');
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/lineage/obligation-predicates.js

@@ -0,0 +1,235 @@
+// obligation-predicates.js — Milestone 4 sub-project 6b: the graph-fact
+// predicate evaluator + ObligationMapping record builder (FR-504 §7.12).
+//
+// A `graph-flow` predicate spec is a small declarative match object,
+// mirroring dataflow/catalog.js's own established `match`-object +
+// hand-written-matcher pattern (this codebase's convention for "a small
+// declarative query, evaluated by a hand-written function," rather than a
+// general query language) — {type:'graph-flow', dataClass, sinkKind,
+// dimension, requiredVerdict}. No pre-joined "enriched flow" view exists
+// on a shipped DataFlowGraph v1 document, so evaluateGraphFlowPredicate
+// builds its own id->entity Maps and joins flow.dataElementIds/.sink
+// against dataElements[]/nodes[], exactly as graph-builder.js's own
+// internal loops already do.
+//
+// buildObligationMappingFromGraphPredicate mints a real ObligationMapping
+// record (sub-project 6a) from an evaluation result. State derivation
+// (scoping doc ruling 4, REVISED — see the "worst case wins" note below,
+// found by the final whole-branch review): graph absent -> unknown;
+// predicate matches zero relevant flows -> not_applicable; at least one
+// relevant flow is genuinely, ASSESSED-and-failing -> gap_detected; no
+// genuine failure but at least one relevant flow was never assessed ->
+// unknown; every relevant flow was assessed and cleared ->
+// evidence_supported. applicabilityInputs stays all-null (ruling 5 — no
+// operator-config source for it exists anywhere in this codebase yet, a
+// deliberately deferred, separate increment).
+//
+// WORST-CASE-WINS STATE DERIVATION (found by the final whole-branch
+// review, reproduced live against this repo's own real
+// bench/data-lineage/ corpus): the original version collapsed an
+// UNASSESSED protection verdict (`not_assessed`/`unknown` — e.g. every
+// external category other than external-api, which is the only one
+// transit-protection.js actually evaluates) into "failed the requirement"
+// exactly the same as a genuine `unprotected` verdict. On the real
+// corpus this produced a false `gap_detected` — a HIPAA transmission-
+// security gap asserted with zero real evidence — for the ONE non-
+// not_applicable case the predicate reached, and did so silently (no
+// warning, `evidence: []`). This directly violated the same "missing
+// evidence must read as unknown/not_assessed, never a verdict" rule
+// this codebase already leans on for AC-06 (`at-rest-protection.test.js`)
+// and `docs/OSCAL.md`'s own "an unassessed control gets no finding" rule.
+// Fixed by tracking assessed-vs-unassessed per flow and prioritizing a
+// genuine failure > genuine unassessment > genuine success — mirroring
+// `protection.js`'s own `aggregateVerdicts()` risk-precedence
+// convention (the pessimistic answer wins), the established precedent
+// this package already follows elsewhere (`flow-grade.js`'s `gradePath`,
+// `graph-builder.js`'s `flow.protectionSummary` computation).
+//
+// KIND-VS-UNRESOLVED MATCHING (found by the same review, reproduced live
+// against this repo's own AC-07 flagship fixture — PHI reaching an AI
+// model provider): FR-203 (`coverage.js#resolveSiteDecision`) rewrites a
+// sink node's `kind` to `'unresolved'` when its destination can't be
+// statically resolved, retaining `subtype`/`category` — the highest-risk
+// shape (a dynamic destination) was therefore silently excluded from
+// this predicate's own sink-kind filter, reporting `not_applicable`
+// ("this requirement does not apply") for exactly the case that most
+// needs it to apply. Fixed by also matching `kind === 'unresolved'`, but
+// (found by the fix round's own scoped re-review, also reproduced live)
+// NOT unconditionally: FR-203 rewrites `kind: 'unresolved'` for `store`
+// and `queue` sinks too (`coverage.js`'s `FR203_ELIGIBLE_KINDS`), so a
+// bare `kind === 'unresolved'` OR-match let a purely local, in-process
+// database write read as applicable to an `external`-scoped requirement
+// — the exact same false-applicability failure mode as the bug just
+// fixed, just moved one category over. The category is still recoverable
+// via `sinkNode.subtype` (FR-203 retains it) and `CATEGORY_NODE_KIND`
+// (`sink-registry.js`), the same table `graph-builder.js` used to assign
+// the node's kind in the first place — so an unresolved sink now only
+// matches when ITS OWN real category still maps to `spec.sinkKind`. Once
+// matched, the worst-case-wins state derivation above correctly resolves
+// it to `unknown` (an unresolved destination has no real transit verdict
+// either), never a false `not_applicable` or a false `gap_detected`.
+//
+// EVIDENCE GAP, DISCLOSED (found by the same review): `evidence` is
+// sourced from `edge.evidenceRefs`, but `graph-builder.js` hardcodes
+// every real edge's `evidenceRefs` to `[]` and nothing downstream ever
+// populates it — confirmed by grep, zero write sites beyond that one
+// literal. So `record.evidence` is structurally always empty on any
+// graph the real pipeline produces, including a genuine
+// `evidence_supported` record. This is a real, upstream gap in
+// `graph-builder.js` (no edge-level evidence producer exists for
+// protection verdicts today), not something this module can close on
+// its own — named here rather than silently shipped as if it worked.
+//
+// KNOWN LIMITATION: evaluateGraphFlowPredicate reads only
+// flow.edgeIds[0] — a flow with multiple edges is evaluated using its
+// first edge only, silently ignoring the rest. Not currently reachable:
+// graph-builder.js (the only real producer of flows) always mints a
+// single-element edgeIds array. This is a latent gap for any future
+// multi-edge-flow producer, or a hand-built graph conforming to the
+// schema (which places no length constraint on flow.edgeIds) — worth
+// revisiting (e.g. worst-verdict-wins across all edges, mirroring
+// aggregateVerdicts()'s own precedent) if that assumption ever changes.
+//
+// NEVER THROWS, defensively, not just by convention (found by the same
+// review: 7 of 11 malformed-graph shapes tried threw a raw TypeError
+// that propagated all the way out of auditor-walkthrough.js's
+// evaluateFramework, losing every control's evaluation for the whole
+// framework — a total compliance-report outage from one degraded
+// graph). Every array field is defensively coerced via Array.isArray
+// before use; a non-object entry inside an array is filtered out rather
+// than dereferenced.
+
+import { computeGraphDigest } from './export-json.js';
+import { obligationId } from './ids.js';
+import { CATEGORY_NODE_KIND } from './sink-registry.js';
+
+function _asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+export function evaluateGraphFlowPredicate(spec, graph) {
+  const dataElementsById = new Map(_asArray(graph?.dataElements).filter(Boolean).map((d) => [d.id, d]));
+  const nodesById = new Map(_asArray(graph?.nodes).filter(Boolean).map((n) => [n.id, n]));
+  const edgesById = new Map(_asArray(graph?.edges).filter(Boolean).map((e) => [e.id, e]));
+
+  const relevantFlows = _asArray(graph?.flows).filter((f) => {
+    if (!f || typeof f !== 'object') return false;
+    const des = _asArray(f.dataElementIds).map((id) => dataElementsById.get(id)).filter(Boolean);
+    const hasClass = des.some((d) => _asArray(d.dataClasses).includes(spec.dataClass));
+    if (!hasClass) return false;
+    const sinkNode = nodesById.get(f.sink);
+    if (!sinkNode) return false;
+    // Also match 'unresolved', but only when the sink's OWN real category
+    // (subtype) still maps to spec.sinkKind — see the KIND-VS-UNRESOLVED
+    // MATCHING note above. A bare kind==='unresolved' OR-match would also
+    // admit unresolved store/queue sinks, which FR-203 rewrites the same
+    // way.
+    return sinkNode.kind === spec.sinkKind ||
+      (sinkNode.kind === 'unresolved' && CATEGORY_NODE_KIND[sinkNode.subtype] === spec.sinkKind);
+  });
+
+  if (relevantFlows.length === 0) {
+    return {
+      applicable: false, matched: null, hasFailure: false, hasUnassessed: false,
+      contributingGraphIds: [], evidence: [], resultsCount: 0, failedCount: 0, notAssessedCount: 0,
+    };
+  }
+
+  // A verdict of 'not_assessed'/'unknown'/'not_applicable' means "never
+  // checked" (or "this dimension doesn't apply here"), never "checked and
+  // failed" — see the WORST-CASE-WINS STATE DERIVATION note above for why
+  // this distinction is load-bearing. 'not_applicable' is included
+  // defensively (found by the fix round's own scoped re-review): no real
+  // producer emits it on a `protection.<dimension>.verdict` today, but it
+  // IS a member of `protection.js`'s own `PROTECTION_VERDICTS`, and that
+  // module's own `_PRECEDENCE` ranks it below `protected` — treating it as
+  // a failure here would contradict the very precedent this worst-case-
+  // wins ordering is modeled on.
+  const UNASSESSED_VERDICTS = new Set(['not_assessed', 'unknown', 'not_applicable']);
+  const results = relevantFlows.map((f) => {
+    const edge = edgesById.get(_asArray(f.edgeIds)[0]);
+    const verdict = edge?.protection?.[spec.dimension]?.verdict ?? 'not_assessed';
+    const assessed = !UNASSESSED_VERDICTS.has(verdict);
+    return { flow: f, edge, verdict, assessed, cleared: verdict === spec.requiredVerdict };
+  });
+
+  const hasFailure = results.some((r) => r.assessed && !r.cleared);
+  const hasUnassessed = results.some((r) => !r.assessed);
+
+  return {
+    applicable: true,
+    // Kept for backward compatibility with any caller reading the
+    // simple boolean — true only in the unambiguous "every relevant
+    // flow was assessed and cleared" case; buildObligationMappingFromGraphPredicate
+    // itself reads hasFailure/hasUnassessed directly for the real,
+    // worst-case-wins state derivation.
+    matched: !hasFailure && !hasUnassessed,
+    hasFailure,
+    hasUnassessed,
+    contributingGraphIds: results.map((r) => r.flow.id).filter((id) => typeof id === 'string'),
+    // Filtered to strings, matching the contributingGraphIds hardening
+    // just above and validateObligationMapping's own "evidence must be an
+    // array of strings" invariant (found by the fix round's own scoped
+    // re-review: a malformed edge.evidenceRefs entry used to reach the
+    // record unfiltered and fail validation downstream instead of here).
+    evidence: results.flatMap((r) => _asArray(r.edge?.evidenceRefs)).filter((e) => typeof e === 'string'),
+    resultsCount: results.length,
+    failedCount: results.filter((r) => r.assessed && !r.cleared).length,
+    notAssessedCount: results.filter((r) => !r.assessed).length,
+  };
+}
+
+const _NULL_APPLICABILITY_INPUTS = Object.freeze({
+  entityRole: null, jurisdiction: null, dataSubject: null, businessProcess: null,
+  merchantLevel: null, systemScope: null, aiSystemRole: null,
+});
+
+export function buildObligationMappingFromGraphPredicate({
+  framework, frameworkVersion, requirementId, requirementSource, predicateLabel, graph, evaluation,
+}) {
+  const graphId = graph?.graphId ?? null;
+  const graphDigest = graph ? computeGraphDigest(graph) : null;
+
+  // Found by this task's own review: a caller-contract violation (a
+  // truthy graph paired with a missing/null evaluation — i.e. forgetting
+  // to call evaluateGraphFlowPredicate first) used to throw here,
+  // inconsistent with this package's "public API never throws on
+  // malformed input" convention (obligation-mapping.js's own JSDoc,
+  // path-query.js, flow-grade.js). Not reachable through this sub-
+  // project's own documented calling convention (Task 2's wiring always
+  // pairs graph/evaluation correctly), but degrading to 'unknown' here
+  // — the same answer a genuinely absent graph gets — is honest and
+  // matches every sibling module's own never-throw contract.
+  //
+  // Worst-case-wins (found by the final whole-branch review — see the
+  // WORST-CASE-WINS STATE DERIVATION note at the top of this file): a
+  // genuine assessed failure always outranks a genuine unassessment,
+  // which always outranks a genuine clean pass.
+  let state;
+  if (!graph || !evaluation) state = 'unknown';
+  else if (!evaluation.applicable) state = 'not_applicable';
+  else if (evaluation.hasFailure) state = 'gap_detected';
+  else if (evaluation.hasUnassessed) state = 'unknown';
+  else state = 'evidence_supported';
+
+  return {
+    id: obligationId({ framework, frameworkVersion, requirementId, graphId: graphId ?? '', graphDigest: graphDigest ?? '' }),
+    graphId: graphId ?? '(no graph)',
+    graphDigest: graphDigest ?? '(no graph)',
+    framework,
+    frameworkVersion,
+    requirementId,
+    requirementSource: requirementSource ?? null,
+    applicabilityInputs: { ..._NULL_APPLICABILITY_INPUTS },
+    state,
+    predicate: predicateLabel,
+    factType: 'code_inferred',
+    contributingGraphIds: evaluation?.contributingGraphIds ?? [],
+    evidence: evaluation?.evidence ?? [],
+    conflicts: [],
+    missingManualArtifacts: [],
+    reviewer: null,
+    reviewedAt: null,
+    expiresAt: null,
+  };
+}

package/src/lineage/observation-adapters.js

@@ -0,0 +1,282 @@
+// observation-adapters.js — the RuntimeObservation ADAPTER interface, plus
+// the one shipped implementation (`native-jsonl`) (M5 deliverable #7,
+// "Runtime-Corroborated Digital Twin" — the runtime-observed half only,
+// "7b"; "7a", config-declared edges, is out of scope for this whole
+// sub-project — see the scoping doc's §4.0). FR-505, AC-29. Pure by
+// contract: zero imports (mirrors `runtime-observation.js`'s/
+// `observation-correlation.js`'s/`flow-grade.js`'s own precedent, one step
+// stricter even than `observation-correlation.js`'s single-file import
+// list — see AD/6a), no fs, no I/O, never throws.
+//
+// ── Why only ONE adapter ships here ─────────────────────────────────────
+//
+// FR-505 itself names an open-ended adapter list: "beginning with approved
+// OpenTelemetry traces/service graphs, gateway/mesh metadata, cloud flow
+// metadata, and application-provided schema-safe events." The scoping
+// doc's §4.3 ruling is to ship the INTERFACE plus a native, operator-
+// authored JSONL adapter first, and defer OTLP to a second increment —
+// not because OTLP is unimportant, but because an OTLP `resourceSpans`
+// document carries an unbounded attribute surface (`http.url` with a live
+// query string, `db.statement`, `messaging.message.payload`, arbitrary
+// `gen_ai.*` prompt/completion attributes under active, ongoing extension
+// by the OpenTelemetry semantic-conventions project). Mapping that surface
+// safely means writing and defending an allowlist against an adversarial,
+// EVOLVING external vocabulary — real, separately-scoped work with its
+// own review, not something to bundle into the increment that also
+// invents the RuntimeObservation contract (Task 1), the correlation match
+// ladder (Task 2), and the import-keyed store (Task 4). This module exists
+// so THAT increment is "write a second implementation of an
+// already-proven interface," not "invent the interface and the mapping at
+// the same time."
+//
+// ── Why external evidence arrives as a FILE, never live ingestion ──────
+//
+// FR-505's own no-egress rule, the root `CLAUDE.md`'s "no runtime cloud
+// calls" convention, and `posture/runtime-correlation.js`'s own already-
+// proven offline-file contract (an operator-supplied eBPF trace JSONL,
+// read from disk, never pulled from a live collector by this codebase)
+// all point the same direction: this module takes a TEXT STRING an
+// operator has already exported and already has on disk, and returns
+// drafts — it has no fetch, no socket, no fs call of any kind (AD/6a pins
+// this structurally, not just by convention). The CLI that will eventually
+// call this (a future task) is what reads the file; this module never
+// does.
+//
+// ── Why the wire key set is CLOSED, exactly like the record it feeds ───
+//
+// `runtime-observation.js`'s own header explains at length why a
+// RuntimeObservation is closed-world rather than open-world: it is built
+// from operator-supplied telemetry this codebase never generated and
+// cannot vouch for, and PRD line 983's own "reject fields capable of
+// carrying payload values" requirement is a REJECT requirement, not a
+// redact-and-hope one. That reasoning applies one layer further out, at
+// the WIRE itself: `NATIVE_JSONL_RECORD_KEYS` is a closed allowlist of the
+// only top-level JSON keys a native-JSONL record may carry, and any other
+// top-level key — an attacker's `prompt`, an operator's well-meaning
+// `note`, or (the smuggling attempt nobody would think to test on their
+// own) a pre-declared `matchedNodeIds`/`matchConfidence` — is rejected,
+// never ignored (AD/4c). `id`/`matchedNodeIds`/`matchedEdgeIds`/
+// `matchedFlowIds`/`matchMethod`/`matchConfidence` are refused from the
+// wire for a reason specific to THIS module: those six fields are
+// minted/derived downstream (an id at import time, a match at correlation
+// time) — if the wire could supply them directly, a compromised exporter,
+// or an operator simply copy-pasting an already-matched record from one
+// import into a hand-edited new one, could dictate what the graph BELIEVES
+// was observed, bypassing the match ladder (`observation-correlation.js`,
+// Task 2) entirely. None of the six are members of `NATIVE_JSONL_RECORD_KEYS`,
+// so the SAME closed-world sweep that rejects an unrecognized field also
+// rejects every one of these — there is no separate check to keep in sync
+// (AD/4b, error 4).
+//
+// ── The two-layer rejection split (this module vs. `validateRuntimeObservation`) ──
+//
+// This module enforces the WIRE SHAPE only: `attributes` must be a plain
+// object whose every value is a scalar (string/number/boolean) or an
+// array of strings, no top-level key outside `NATIVE_JSONL_RECORD_KEYS`,
+// and `eventCountBand`/`firstObservedAt`/`lastObservedAt` must each be a
+// non-empty string. It does NOT validate WHICH attribute keys are
+// approved — `validateRuntimeObservation` (Task 1, `runtime-observation.js`)
+// is the single authority on that allowlist, and this module never
+// duplicates it (a duplicated allowlist is exactly the kind of thing that
+// silently drifts). Against the payload fixture, this means the adapter
+// itself catches only 2 of the fixture's 4 smuggling attempts (line 3's
+// top-level `prompt`, line 4's `matchedNodeIds`/`matchConfidence`) — the
+// other two (line 1's `http.url` attribute key, line 2's `db.statement`
+// attribute key) are structurally fine at the wire layer and are caught
+// one layer up, by `validateRuntimeObservation`, at IMPORT time
+// (`CLI/import-4`, a future task's own test — not a hole in this one).
+// Any adapter error means the whole file yields nothing usable: this
+// module always returns whatever drafts it produced regardless of
+// `errors.length`, but the IMPORT command (a future task) refuses the
+// file WHOLE the moment `errors.length > 0` — that refuse-the-whole-import
+// behavior is that future task's own to prove, not this module's.
+//
+// ── The native-JSONL wire format, worked example ────────────────────────
+//
+// One JSON object per line (no comments — JSONL admits none), each with
+// up to 5 top-level keys (`NATIVE_JSONL_RECORD_KEYS`):
+//
+//   {"environment":"production","attributes":{"destination.host":"api.stripe.com","destination.scheme":"https","tls.version":"1.3"},"eventCountBand":"101-1k","firstObservedAt":"2026-08-02T10:00:00.000Z","lastObservedAt":"2026-08-30T10:00:00.000Z"}
+//
+// `environment` is optional per line — when omitted, the record inherits
+// the default environment of the surrounding call, `context.environment`
+// (supplied by the CALLER, never by the file). `attributes` keys must be
+// drawn from `RUNTIME_ATTRIBUTE_KEYS` (`runtime-observation.js`) — this
+// module does not check that, but a key outside that list will be
+// rejected one layer up, at import time. `eventCountBand` is a BAND
+// (`RUNTIME_OBSERVATION_VERSION`'s sibling `EVENT_COUNT_BANDS`, e.g.
+// `'1'`/`'2-10'`/`'11-100'`/`'101-1k'`/`'1k+'`), never a raw count.
+// `firstObservedAt`/`lastObservedAt` are ISO-8601 date-times.
+//
+// ── `version` is caller-supplied, not read from `runtime-observation.js` ──
+//
+// This is precisely why this module has NO import at all, not even of
+// `runtime-observation.js`'s own `RUNTIME_OBSERVATION_VERSION` constant:
+// the CLI (a future task) passes that value in as `context.version`. A
+// zero-import module can never itself drift from the contract it feeds —
+// there is no cached/stale constant here to go stale.
+
+// The 5 allowed top-level keys of a native-JSONL wire record. Any other
+// top-level key — including every one of the six RuntimeObservation
+// fields that are minted/derived downstream (`id`, `matchedNodeIds`,
+// `matchedEdgeIds`, `matchedFlowIds`, `matchMethod`, `matchConfidence`) —
+// is rejected by the closed-world sweep below, never ignored.
+export const NATIVE_JSONL_RECORD_KEYS = Object.freeze([
+  'environment', 'attributes', 'eventCountBand', 'firstObservedAt', 'lastObservedAt',
+]);
+
+function _isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+function _isScalar(v) {
+  const t = typeof v;
+  return t === 'string' || t === 'number' || t === 'boolean';
+}
+
+// The WIRE shape only — never which attribute keys are approved. A value
+// must be a scalar, or an array of strings (mirroring
+// `RUNTIME_ARRAY_ATTRIBUTE_KEYS`'s own shape one layer up, without this
+// module knowing which specific key that applies to).
+function _attributesShapeOk(attrs) {
+  if (!_isPlainObject(attrs)) return false;
+  for (const value of Object.values(attrs)) {
+    if (Array.isArray(value)) {
+      if (!value.every((x) => typeof x === 'string')) return false;
+    } else if (!_isScalar(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Parses native-JSONL runtime-observation text into RuntimeObservation
+ * DRAFTS — every field a RuntimeObservation record needs EXCEPT `id`,
+ * `matchedNodeIds`, `matchedEdgeIds`, `matchedFlowIds`, `matchMethod`,
+ * `matchConfidence`, which are minted/derived downstream and can never be
+ * supplied by the wire. `context` is
+ * `{version, adapter, source, environment, windowStart, windowEnd, importedAt, retention}`
+ * — every draft carries these verbatim, EXCEPT `environment`, which a
+ * per-line `environment` key overrides.
+ *
+ * Never throws. `text` must be a string and `context` a plain object, or
+ * this returns `{drafts: [], errors: [{line: 0, message: '...'}]}`
+ * immediately. Blank lines (and the trailing newline JSONL files
+ * ordinarily end with) are skipped silently — never reported as errors.
+ * A malformed line (invalid JSON, wrong top-level shape, an unapproved
+ * top-level key, a malformed `attributes`/`eventCountBand`/
+ * `firstObservedAt`/`lastObservedAt`) yields exactly ONE `{line, message}`
+ * error for that line (`line` 1-based) and is skipped — every OTHER line
+ * still parses, so an operator sees every problem in one pass rather than
+ * stopping at the first.
+ */
+export function parseNativeJsonlObservations(text, context) {
+  if (typeof text !== 'string' || !_isPlainObject(context)) {
+    return {
+      drafts: [],
+      errors: [{ line: 0, message: 'parseNativeJsonlObservations requires a string text and a plain-object context' }],
+    };
+  }
+
+  const {
+    version, adapter, source, environment: defaultEnvironment,
+    windowStart, windowEnd, importedAt, retention,
+  } = context;
+
+  const drafts = [];
+  const errors = [];
+
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    if (rawLine.trim().length === 0) continue; // blank line, or the trailing newline's own empty tail
+    const line = i + 1;
+
+    let record;
+    try {
+      record = JSON.parse(rawLine);
+    } catch {
+      // M2 (final review): every OTHER rejection path in this module is
+      // key-only/value-free by design — V8's own JSON.parse error message
+      // quotes a snippet of the offending input (`e.message`), which would
+      // make this the sole value-echo channel in the whole command. Name
+      // only the line number, never the parse error's own text.
+      errors.push({ line, message: `invalid JSON on line ${line}` });
+      continue;
+    }
+
+    if (!_isPlainObject(record)) {
+      const gotType = record === null ? 'null' : Array.isArray(record) ? 'array' : typeof record;
+      errors.push({ line, message: `record must be a JSON object, got ${gotType}` });
+      continue;
+    }
+
+    const unknownKeys = Object.keys(record).filter((k) => !NATIVE_JSONL_RECORD_KEYS.includes(k));
+    if (unknownKeys.length > 0) {
+      errors.push({
+        line,
+        message: `unknown field(s) not permitted on the wire: ${unknownKeys.join(', ')} — native-JSONL records are closed-world (mirroring RuntimeObservation's own closed-world rule): only ${NATIVE_JSONL_RECORD_KEYS.join('/')} are accepted, and this rejects every one of id/matchedNodeIds/matchedEdgeIds/matchedFlowIds/matchMethod/matchConfidence too, since none are members of that allowlist`,
+      });
+      continue;
+    }
+
+    if (!_attributesShapeOk(record.attributes)) {
+      errors.push({
+        line,
+        message: 'attributes must be a plain object whose every value is a scalar (string/number/boolean) or an array of strings',
+      });
+      continue;
+    }
+
+    if (!_isNonEmptyString(record.eventCountBand)
+      || !_isNonEmptyString(record.firstObservedAt)
+      || !_isNonEmptyString(record.lastObservedAt)) {
+      errors.push({
+        line,
+        message: 'eventCountBand, firstObservedAt, and lastObservedAt must each be present and a non-empty string',
+      });
+      continue;
+    }
+
+    drafts.push({
+      version,
+      adapter,
+      source,
+      environment: 'environment' in record ? record.environment : defaultEnvironment,
+      windowStart,
+      windowEnd,
+      attributes: record.attributes,
+      eventCountBand: record.eventCountBand,
+      firstObservedAt: record.firstObservedAt,
+      lastObservedAt: record.lastObservedAt,
+      retention,
+      importedAt,
+    });
+  }
+
+  return { drafts, errors };
+}
+
+// The adapter registry — a frozen, module-level lookup. `adapterFor`
+// returns `null` for anything unknown, NEVER a default: an unimplemented
+// adapter name (e.g. `'otlp'`, deferred per the scoping doc's §4.3 ruling)
+// must be rejected outright, not silently accepted on faith that it will
+// someday exist.
+const _ADAPTERS = Object.freeze({
+  'native-jsonl': Object.freeze({ name: 'native-jsonl', parse: parseNativeJsonlObservations }),
+});
+
+/**
+ * `adapterFor(name) -> {name, parse} | null` — the registry lookup.
+ * `parse` has the `(text, context) -> {drafts, errors}` signature of
+ * `parseNativeJsonlObservations` above.
+ */
+export function adapterFor(name) {
+  if (typeof name !== 'string') return null;
+  return Object.prototype.hasOwnProperty.call(_ADAPTERS, name) ? _ADAPTERS[name] : null;
+}