@clear-capabilities/agentic-security-scanner 0.183.1 → 0.185.0

package/src/lineage/DESIGN_GRAPH_BUILDER.md

@@ -32,7 +32,7 @@ both are settled here:
 1. **Seeding** (§3) — how a real call site becomes a field-identity entry
    state. Today the shipped driver hardcodes `emptyState()` and produces
    **exactly zero hops** on real code. Measured, twice, in `E1/1`.
-2. **Projection** (§6) — how a provenance DAG that is *variable*-granular
+2. **Projection** (§6) — how a provenance graph that is *variable*-granular
    (494 pnodes for a 33-file project) becomes a `DataFlowGraph v1` document
    that is *system*-granular (14 nodes for a whole synthetic platform).
 

package/src/lineage/DESIGN_PATH_PROVENANCE.md

@@ -1,5 +1,11 @@
 # Path Provenance Recording — Design Record
 
+> Terminology note (DAG-01): this record predates the SCC work and says "DAG"
+> for the recorded provenance structure. That structure is a **provenance
+> graph** and can be cyclic (see section 9.3). The acyclic "DAG" is the derived
+> component view built by `scanner/src/graph/scc.js`. Read every "DAG" below as
+> "provenance graph". Decisions here are unchanged.
+
 Scope: Sub-project C of Milestone 1, increment C1 (see
 `docs/superpowers/plans/2026-08-30-data-flow-explorer-m1-subproject-c-scoping.md`).
 This document decides **how provenance is recorded** as data flows through

package/src/lineage/boundary-contract.js

@@ -0,0 +1,273 @@
+// boundary-contract.js: DAG-08. Versioned, field-aware contracts for the HTTP, queue and storage edges between services.
+//
+// A contract is an OPERATOR DECLARATION that a producer site hands named fields to a consumer site across a trust boundary.
+// What it can establish, and what it cannot:
+//   * It establishes a MODELED untrusted input at the consumer: the declared consumer parameter/record fields are treated as
+//     attacker-influenced when the taint engine runs. It does not establish that any value was observed on the wire, nor that a
+//     sink in the consumer is exploited. Every attribution carries `modeledInput: true, observed: false`.
+//   * It is bound to a parser-resolved local site (a function in the call graph and one of its parameters). A declaration that
+//     cannot be bound (no such file/function/parameter, an ambiguous name, a field the Haskell record does not have) becomes an
+//     explicit COVERAGE GAP. It never becomes a finding at a guessed function.
+//   * Field mappings carry renames (`customer_id` -> `customerId`). The consumer is seeded only at the mapped consumer fields
+//     (consumer projection), so a sibling field such as `displayName` is not attributed to the boundary.
+//   * `persistence` separates an immediate call edge (http) from a handoff that outlives the request (storage, durable queue).
+//     A storage write and a later read correlate only under a declared storage contract that names the same store, table and
+//     key/schema version. Two sites that merely share a field name are never joined.
+//   * Evidence kinds stay separately attributable: foreign graph validation, digest check, manual assertion, code mapping and
+//     observed connection. Only an `observed-connection` item can make `observed` true, and this module never creates one.
+//
+// Pure: no file access, no dependency on the taint engine. The seeding step that needs the engine lives in
+// dataflow/cross-service-taint.js and consumes the bindings built here.
+
+import { createHash } from 'node:crypto';
+import { EDGE_PROVENANCE_VALUES } from './schema.js';
+import { computeScc } from '../graph/scc.js';
+
+export const BOUNDARY_CONTRACT_VERSION = '1.0.0';
+export const BOUNDARY_CONTRACTS_FILENAME = 'boundary-contracts.json';
+export const BOUNDARY_KINDS = Object.freeze(['http', 'queue', 'storage']);
+export const PERSISTENCE_VALUES = Object.freeze(['immediate', 'persisted']);
+export const EVIDENCE_KINDS = Object.freeze(['foreign-graph-validation', 'digest-check', 'manual-assertion', 'code-mapping', 'observed-connection']);
+
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const sorted = (a) => [...a].sort((x, y) => (x < y ? -1 : x > y ? 1 : 0));
+
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (isObj(v)) return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+  return JSON.stringify(v === undefined ? null : v);
+}
+
+/** Digest of everything that defines what the contract says (not who declared it or when). */
+export function contractDigest(c) {
+  const basis = {
+    version: c.version, kind: c.kind, persistence: c.persistence, channel: c.channel, schema: c.schema,
+    producer: { service: c.producer && c.producer.service, site: (c.producer && c.producer.site) || null, untrustedFields: sorted((c.producer && c.producer.untrustedFields) || []) },
+    consumer: { service: c.consumer && c.consumer.service, site: (c.consumer && c.consumer.site) || null },
+    fieldMappings: (c.fieldMappings || []).map((m) => ({ from: m.from, to: m.to })).sort((a, b) => (a.from + a.to < b.from + b.to ? -1 : 1)),
+  };
+  return `sha256:${createHash('sha256').update(canonical(basis)).digest('hex')}`;
+}
+
+function channelKey(c) {
+  const ch = c.channel || {};
+  if (c.kind === 'http') return `http:${String(ch.method || '*').toUpperCase()} ${ch.route || ''}`;
+  if (c.kind === 'queue') return `queue:${ch.topic || ''}`;
+  return `storage:${ch.store || ''}/${ch.table || ''}#${ch.key || ''}`;
+}
+
+/** Structural validation. Never throws, never touches a graph. */
+export function validateBoundaryContract(c) {
+  const errors = [];
+  const err = (path, message) => errors.push({ path, message });
+  if (!isObj(c)) return { valid: false, errors: [{ path: '$', message: 'contract must be an object' }] };
+  if (!isStr(c.id) || !c.id.startsWith('boundary:')) err('$.id', 'id is required and must start with "boundary:"');
+  if (c.version !== BOUNDARY_CONTRACT_VERSION) err('$.version', `unsupported contract version "${c.version}" (supported: ${BOUNDARY_CONTRACT_VERSION})`);
+  if (!BOUNDARY_KINDS.includes(c.kind)) err('$.kind', `kind must be one of ${BOUNDARY_KINDS.join('|')}`);
+  if (!PERSISTENCE_VALUES.includes(c.persistence)) err('$.persistence', `persistence must be one of ${PERSISTENCE_VALUES.join('|')}`);
+  else if (c.kind === 'storage' && c.persistence !== 'persisted') err('$.persistence', 'a storage contract is persisted: the value outlives the request');
+  else if (c.kind === 'http' && c.persistence !== 'immediate') err('$.persistence', 'an http contract is an immediate call edge');
+  if (!isObj(c.channel)) err('$.channel', 'channel is required');
+  else if (c.kind === 'http' && !isStr(c.channel.route)) err('$.channel.route', 'http channel needs a route');
+  else if (c.kind === 'queue' && !isStr(c.channel.topic)) err('$.channel.topic', 'queue channel needs a topic');
+  else if (c.kind === 'storage') {
+    if (!isStr(c.channel.store)) err('$.channel.store', 'storage channel needs a store');
+    if (!isStr(c.channel.table)) err('$.channel.table', 'storage channel needs a table');
+    if (!isStr(c.channel.key)) err('$.channel.key', 'storage channel needs a key contract');
+  }
+  if (!isObj(c.schema) || !isStr(c.schema.name) || !isStr(c.schema.version)) err('$.schema', 'schema {name, version} is required');
+  for (const side of ['producer', 'consumer']) {
+    const s = c[side];
+    if (!isObj(s) || !isStr(s.service)) { err(`$.${side}.service`, `${side}.service is required`); continue; }
+    if (s.site !== undefined && s.site !== null) {
+      if (!isObj(s.site) || !isStr(s.site.file) || !isStr(s.site.function)) err(`$.${side}.site`, `${side}.site needs file and function`);
+      else if (side === 'consumer' && !isStr(s.site.param)) err('$.consumer.site.param', 'consumer.site needs the handler parameter that receives the record');
+    } else if (side === 'consumer') err('$.consumer.site', 'consumer.site is required to seed taint');
+  }
+  if (!Array.isArray(c.fieldMappings)) err('$.fieldMappings', 'fieldMappings must be an array');
+  else c.fieldMappings.forEach((m, i) => { if (!isObj(m) || !isStr(m.from) || !isStr(m.to)) err(`$.fieldMappings[${i}]`, 'mapping needs from and to'); });
+  if (!EDGE_PROVENANCE_VALUES.includes(c.provenance)) err('$.provenance', `provenance must be one of ${EDGE_PROVENANCE_VALUES.join('|')}`);
+  if (!isObj(c.evidence) || c.evidence.declared !== true || c.evidence.observed !== false) err('$.evidence', 'evidence must be {declared: true, observed: false}: a contract is never an observed flow');
+  if (c.configDigest !== undefined && !isStr(c.configDigest)) err('$.configDigest', 'configDigest must be a string');
+  if (!isStr(c.declaredBy)) err('$.declaredBy', 'declaredBy is required');
+  return { valid: errors.length === 0, errors };
+}
+
+/** Build a well-formed contract (the digest is computed, never trusted from input). */
+export function createBoundaryContract(spec) {
+  const c = {
+    version: BOUNDARY_CONTRACT_VERSION, provenance: 'manual', evidence: { declared: true, observed: false }, ...spec,
+  };
+  if (!c.persistence) c.persistence = c.kind === 'storage' ? 'persisted' : c.kind === 'http' ? 'immediate' : 'persisted';
+  c.configDigest = contractDigest(c);
+  return c;
+}
+
+/** Evidence items; each keeps its own kind and basis. `observed` is true only for an observed-connection item. */
+export function evidenceItem(kind, detail = {}) {
+  if (!EVIDENCE_KINDS.includes(kind)) throw new TypeError(`unknown evidence kind "${kind}"`);
+  return { kind, observed: kind === 'observed-connection', ...detail };
+}
+
+export function attributeEvidence(items) {
+  const byKind = Object.fromEntries(EVIDENCE_KINDS.map((k) => [k, []]));
+  for (const it of items || []) if (it && byKind[it.kind]) byKind[it.kind].push(it);
+  return { byKind, observed: byKind['observed-connection'].length > 0 && byKind['observed-connection'].every((i) => i.observed === true), declaredOnly: byKind['observed-connection'].length === 0 };
+}
+
+/** Evidence available for one contract. A passed digest check is a digest check, not an observation. */
+export function contractEvidence(c, { binding = null, foreignValidation = null } = {}) {
+  const items = [];
+  if (c.provenance === 'manual' || c.provenance === 'schema') items.push(evidenceItem('manual-assertion', { declaredBy: c.declaredBy, provenance: c.provenance }));
+  if (c.configDigest) items.push(evidenceItem('digest-check', { expected: c.configDigest, actual: contractDigest(c), ok: c.configDigest === contractDigest(c) }));
+  if (binding) items.push(evidenceItem('code-mapping', { file: binding.file, line: binding.line, qid: binding.qid }));
+  if (foreignValidation) items.push(evidenceItem('foreign-graph-validation', { ok: foreignValidation.ok === true, graphDigest: foreignValidation.graphDigest || null }));
+  return items;
+}
+
+const paramNameOf = (p) => (typeof p === 'string' ? p : p && p.name);
+const norm = (f) => String(f || '').replace(/^\.\//, '').replace(/\\/g, '/');
+
+function resolveSite(site, callGraph) {
+  const fns = [...(callGraph && callGraph.functions && callGraph.functions.values ? callGraph.functions.values() : [])];
+  const file = norm(site.file);
+  const hits = fns.filter((f) => norm(f.file) === file && (f.name === site.function || String(f.name).endsWith(`.${site.function}`)));
+  if (hits.length === 1) return { fn: hits[0] };
+  if (hits.length > 1) return { gap: 'ambiguous-site', detail: `${hits.length} functions named ${site.function} in ${site.file}` };
+  return { gap: fns.some((f) => norm(f.file) === file) ? 'function-not-found' : 'file-not-found', detail: `${site.function} in ${site.file}` };
+}
+
+/**
+ * Bind consumer (and, when given, producer) sites to parser-resolved functions.
+ * Returns `{bindings, gaps, rejected}`; nothing is guessed. A consumer binding carries the access paths to seed.
+ */
+export function bindBoundaryContracts(contracts, callGraph, { language = null } = {}) {
+  const bindings = []; const gaps = []; const rejected = [];
+  for (const c of contracts || []) {
+    const v = validateBoundaryContract(c);
+    if (!v.valid) { rejected.push({ contractId: c && c.id, errors: v.errors }); continue; }
+    const gap = (side, reason, detail, extra = {}) => gaps.push({ contractId: c.id, kind: 'unbound-boundary', side, reason, detail, service: c[side].service, site: c[side].site || null, ...extra });
+    if (c.producer.site) {
+      const r = resolveSite(c.producer.site, callGraph);
+      if (r.gap) gap('producer', r.gap, r.detail);
+    }
+    const site = c.consumer.site;
+    const r = resolveSite(site, callGraph);
+    if (r.gap) { gap('consumer', r.gap, r.detail); continue; }
+    const fn = r.fn;
+    const rec = ((fn.hs && fn.hs.recordParams) || []).find((p) => p.name === site.param) || null;
+    if (!(fn.params || []).map(paramNameOf).includes(site.param)) { gap('consumer', 'param-not-found', `${site.param} is not a parameter of ${fn.name}`); continue; }
+    if (!c.fieldMappings.length) { gap('consumer', 'no-field-mappings', 'a contract with no field mappings seeds nothing'); continue; }
+    const seeds = []; const mapped = [];
+    for (const m of c.fieldMappings) {
+      if (rec && !(rec.fields || []).includes(m.to)) { gap('consumer', 'field-not-in-record', `${m.to} is not a field of ${rec.type}`, { field: m.to }); continue; }
+      seeds.push([site.param, site.recordPath, m.to].filter(Boolean).join('.'));
+      mapped.push({ from: m.from, to: m.to, renamed: m.from !== m.to });
+    }
+    if (!seeds.length) continue;
+    bindings.push({
+      contractId: c.id, kind: c.kind, persistence: c.persistence, digest: contractDigest(c), schema: c.schema,
+      channel: channelKey(c), upstream: { service: c.producer.service, site: c.producer.site || null },
+      consumerService: c.consumer.service, qid: fn.qid, file: fn.file, line: fn.line, param: site.param,
+      language: language || (/\.l?hs$/i.test(fn.file) ? 'haskell' : null), record: rec ? { type: rec.type, fields: rec.fields } : null,
+      originalLocation: { file: fn.file, line: fn.line }, seeds, mappedFields: mapped,
+      evidence: contractEvidence(c, { binding: { file: fn.file, line: fn.line, qid: fn.qid } }),
+    });
+  }
+  return { bindings, gaps, rejected };
+}
+
+/** The attribution stamped on a finding that came from a bound boundary seed. A declaration is a modeled input only. */
+export function boundaryAttribution(binding) {
+  return {
+    contractId: binding.contractId, contractVersion: BOUNDARY_CONTRACT_VERSION, digest: binding.digest, kind: binding.kind,
+    persistence: binding.persistence, channel: binding.channel, schema: binding.schema, upstream: binding.upstream,
+    consumerService: binding.consumerService, param: binding.param, mappedFields: binding.mappedFields,
+    modeledInput: true, observed: false, exploited: false, evidence: binding.evidence,
+    attribution: attributeEvidence(binding.evidence),
+  };
+}
+
+/**
+ * Storage correlation. A write and a later read join only under a declared storage contract that names the same store and
+ * table, and (when both sites state it) the same key and schema version. Field names alone never join two sites.
+ * @param {object[]} contracts
+ * @param {Array<{store,table,key?,schemaVersion?,fields:string[],site?:any}>} writes
+ * @param {Array<{store,table,key?,schemaVersion?,fields:string[],site?:any}>} reads
+ */
+export function correlateStorage(contracts, writes, reads) {
+  const storage = (contracts || []).filter((c) => c.kind === 'storage' && validateBoundaryContract(c).valid);
+  const joins = []; const unjoined = [];
+  const matches = (c, s) => c.channel.store === s.store && c.channel.table === s.table
+    && (!s.key || s.key === c.channel.key) && (!s.schemaVersion || s.schemaVersion === c.schema.version);
+  const used = new Set();
+  for (const w of writes || []) {
+    const c = storage.find((x) => matches(x, w));
+    if (!c) { unjoined.push({ side: 'write', site: w.site || null, reason: 'no-storage-contract', store: w.store, table: w.table }); continue; }
+    for (const r of reads || []) {
+      if (!matches(c, r)) continue;
+      used.add(r);
+      const map = new Map(c.fieldMappings.map((m) => [m.from, m.to]));
+      const fields = (w.fields || []).filter((f) => map.has(f) && (r.fields || []).includes(map.get(f))).map((f) => ({ from: f, to: map.get(f) }));
+      joins.push({ contractId: c.id, persistence: 'persisted', immediate: false, store: w.store, table: w.table, key: c.channel.key, schemaVersion: c.schema.version, write: w.site || null, read: r.site || null, fields });
+    }
+  }
+  for (const r of reads || []) if (!used.has(r)) unjoined.push({ side: 'read', site: r.site || null, reason: 'no-storage-contract', store: r.store, table: r.table });
+  return { joins, unjoined };
+}
+
+export const DEFAULT_SERVICE_ROUNDS = 16;
+export const DEFAULT_SERVICE_FACTS = 2000;
+
+/**
+ * Which fields are modeled-tainted in which service, through contract edges. The service graph may contain cycles: it is
+ * condensed with SCC (graph/scc.js) and each recursive component is solved by a worklist under a round and fact budget.
+ * A budget hit is reported (`truncated`), never silently treated as convergence.
+ */
+export function analyzeServiceBoundaries(contracts, { entry = {}, maxRounds = DEFAULT_SERVICE_ROUNDS, maxFacts = DEFAULT_SERVICE_FACTS } = {}) {
+  const valid = (contracts || []).filter((c) => validateBoundaryContract(c).valid);
+  const nodes = sorted([...new Set(valid.flatMap((c) => [c.producer.service, c.consumer.service]))]);
+  const edges = valid.map((c) => [c.producer.service, c.consumer.service]);
+  const scc = computeScc({ nodes, edges });
+  const tainted = new Map(nodes.map((n) => [n, new Set(entry[n] || [])]));
+  const origins = new Map();                  // service\0field -> {contractId, from}
+  let facts = nodes.reduce((a, n) => a + tainted.get(n).size, 0);
+  let truncated = false; let rounds = 0; let converged = true;
+  const out = new Map();
+  for (const c of valid) { if (!out.has(c.producer.service)) out.set(c.producer.service, []); out.get(c.producer.service).push(c); }
+
+  const step = (svc) => {
+    let changed = false;
+    for (const c of out.get(svc) || []) {
+      const have = tainted.get(svc);
+      const dst = tainted.get(c.consumer.service);
+      for (const m of c.fieldMappings) {
+        if (!(have.has(m.from) || (c.producer.untrustedFields || []).includes(m.from))) continue;
+        if (dst.has(m.to)) continue;
+        if (facts >= maxFacts) { truncated = true; continue; }
+        dst.add(m.to); facts++; changed = true;
+        origins.set(`${c.consumer.service}\0${m.to}`, { contractId: c.id, from: `${svc}.${m.from}` });
+      }
+    }
+    return changed;
+  };
+
+  for (const id of scc.order) {
+    const comp = scc.components[id];
+    if (!comp.recursive) { for (const s of comp.members) step(s); continue; }
+    let r = 0; let again = true;
+    while (again && r < maxRounds && !truncated) { again = false; r++; for (const s of comp.members) if (step(s)) again = true; }
+    rounds = Math.max(rounds, r);
+    if (again) { converged = false; }
+  }
+  if (truncated) converged = false;
+  return {
+    services: nodes,
+    cycles: scc.components.filter((c) => c.recursive).map((c) => c.members),
+    taintedFields: Object.fromEntries(nodes.map((n) => [n, sorted([...tainted.get(n)])])),
+    origins: Object.fromEntries([...origins].map(([k, v]) => [k.replace('\0', '.'), v])),
+    rounds, converged, truncated,
+    note: 'Fields are modeled from declarations; none is an observed runtime flow.',
+  };
+}

package/src/lineage/completion.js

@@ -0,0 +1,205 @@
+// completion.js: the shared completion envelope (DAG-07 R07.1/R07.2, PRD 5.2).
+//
+// One small, pure vocabulary that every long-running or bounded step uses to
+// say how far it got: field analysis, summary computation, source seeding,
+// graph construction, reverse selection and path queries. It imports nothing
+// from any analysis engine, so both the lineage package and the executable
+// taint package can produce and consume it.
+//
+// Two facts are kept apart on purpose:
+//   - queryExhausted: did THIS step run to the end of its own frontier?
+//   - modelCoverage:  does the MODEL it ran over describe the whole software?
+// Exhausting a modeled graph never proves the software has no missing edges,
+// so `negativeClaimAllowed` (the only license to say "no modeled path") needs
+// a complete status, an exhausted query and an empty frontier, and even then
+// the claim is scoped to the modeled graph, never to "no vulnerability".
+
+export const COMPLETION_SCHEMA_VERSION = '1.0.0';
+
+export const COMPLETION_STATUSES = Object.freeze(['complete', 'partial', 'cancelled', 'unavailable', 'invalid']);
+export const MODEL_COVERAGE = Object.freeze(['complete', 'partial', 'unknown']);
+
+// Higher rank wins when records are combined: the combined answer is only as
+// good as its worst part.
+const RANK = { complete: 0, partial: 1, unavailable: 2, cancelled: 3, invalid: 4 };
+
+export const NEGATIVE_CLAIM_SCOPE = 'modeled-graph-only';
+
+function nonNegInt(v) {
+  return Number.isInteger(v) && v >= 0 ? v : 0;
+}
+
+function uniqSorted(list) {
+  return [...new Set((list ?? []).filter((x) => typeof x === 'string' && x.length > 0))].sort();
+}
+
+/**
+ * Build a validated completion envelope. Unknown statuses become `invalid`
+ * (with a reason) rather than being passed through, so a consumer can trust
+ * the vocabulary. `negativeClaimAllowed` is always derived here, never taken
+ * from the caller.
+ */
+export function makeCompletion(fields = {}) {
+  const reasons = uniqSorted(fields.reasons);
+  let status = fields.status;
+  if (!COMPLETION_STATUSES.includes(status)) {
+    status = 'invalid';
+    reasons.push('unknown-completion-status');
+  }
+  const unexplored = nonNegInt(fields.unexploredFrontierCount);
+  const modelCoverage = MODEL_COVERAGE.includes(fields.modelCoverage)
+    ? fields.modelCoverage
+    : (status === 'complete' ? 'complete' : 'partial');
+  // Partial work is never an exhausted query, whatever the caller says.
+  const queryExhausted = status === 'complete' && fields.queryExhausted !== false && unexplored === 0;
+  const env = {
+    schemaVersion: COMPLETION_SCHEMA_VERSION,
+    status,
+    queryExhausted,
+    modelCoverage,
+    negativeClaimAllowed: status === 'complete' && queryExhausted && unexplored === 0 && reasons.length === 0,
+    reasons: uniqSorted(reasons),
+    limits: fields.limits && typeof fields.limits === 'object' ? { ...fields.limits } : {},
+    unexploredFrontierCount: unexplored,
+  };
+  if (env.negativeClaimAllowed) env.negativeClaimScope = NEGATIVE_CLAIM_SCOPE;
+  if (typeof fields.unit === 'string') env.unit = fields.unit;
+  return env;
+}
+
+/** Combine several envelopes: worst status wins, reasons union, frontier sums, limits namespaced by unit. */
+export function combineCompletions(list, unit) {
+  const items = (list ?? []).filter(Boolean);
+  if (items.length === 0) return makeCompletion({ status: 'unavailable', reasons: ['no-completion-records'], unit });
+  let status = 'complete';
+  let modelCoverage = 'complete';
+  let unexplored = 0;
+  const reasons = [];
+  const limits = {};
+  for (const c of items) {
+    if ((RANK[c.status] ?? 4) > RANK[status]) status = c.status;
+    if (c.modelCoverage === 'partial' || (c.modelCoverage === 'unknown' && modelCoverage === 'complete')) modelCoverage = c.modelCoverage;
+    unexplored += nonNegInt(c.unexploredFrontierCount);
+    reasons.push(...(c.reasons ?? []));
+    if (c.unit) limits[c.unit] = c.limits ?? {};
+  }
+  return makeCompletion({ status, modelCoverage, unexploredFrontierCount: unexplored, reasons, limits, unit });
+}
+
+/**
+ * Adapter for the roll-up the field-identity driver / graph builder produce
+ * (`analysisCompletion`): {status, functionsAnalyzed, functionsNotAnalyzed,
+ * incomplete[], degraded[], storeLimits?, seeding?}.
+ */
+export function fromAnalysisCompletion(ac) {
+  if (!ac || typeof ac !== 'object') return makeCompletion({ status: 'unavailable', reasons: ['no-analysis-completion-record'], unit: 'analysis' });
+  const reasons = [];
+  for (const u of ac.incomplete ?? []) reasons.push(...(u.reasons ?? ['analysis-incomplete']));
+  for (const d of ac.degraded ?? []) reasons.push(d.reason === 'context-cap' ? 'context-cap' : d.reason === 'recursion-nonconverged' ? 'recursion-nonconverged' : 'degraded-context');
+  if (ac.status === 'cancelled') reasons.push('cancelled');
+  if (ac.storeLimits?.hit) reasons.push('construction-limit');
+  if (ac.seeding && ac.seeding.status && ac.seeding.status !== 'complete') reasons.push(...(ac.seeding.reasons ?? ['seeding-incomplete']));
+  if (ac.incremental && ac.incremental.status && ac.incremental.status !== 'complete') reasons.push(...(ac.incremental.reasons ?? []));
+  const unfinished = (ac.incomplete ?? []).reduce((n, u) => n + nonNegInt(u.unfinishedWork), 0) + nonNegInt(ac.functionsNotAnalyzed);
+  const status = COMPLETION_STATUSES.includes(ac.status) ? ac.status : 'invalid';
+  const limits = {
+    functionsAnalyzed: nonNegInt(ac.functionsAnalyzed),
+    functionsNotAnalyzed: nonNegInt(ac.functionsNotAnalyzed),
+    incompleteUnits: (ac.incomplete ?? []).length,
+    degradedContexts: (ac.degraded ?? []).length,
+  };
+  if (ac.storeLimits?.hit) {
+    limits.hopsRefused = nonNegInt(ac.storeLimits.hopsRefused);
+    limits.groupsSkipped = (ac.storeLimits.groupsSkipped ?? []).length;
+    limits.edgesRefused = nonNegInt(ac.storeLimits.edgesRefused);
+  }
+  return makeCompletion({
+    status: status === 'complete' && reasons.length ? 'partial' : status,
+    modelCoverage: status === 'complete' && reasons.length === 0 ? 'complete' : 'partial',
+    unexploredFrontierCount: unfinished,
+    reasons, limits, unit: 'analysis',
+  });
+}
+
+/** Adapter for a `reconstructPaths` result (path-query.js). */
+export function fromQueryResult(r) {
+  if (!r || typeof r !== 'object') return makeCompletion({ status: 'unavailable', reasons: ['no-query-result'], unit: 'query' });
+  const reasons = [...(r.truncationReasons ?? [])];
+  if (r.status === 'invalid') reasons.push('invalid-budget');
+  if (r.unknownStartNode) reasons.push('unknown-start-node');
+  if (r.analysisTruncated) reasons.push('analysis-truncated');
+  const status = r.status === 'invalid' ? 'invalid' : (r.status === 'cancelled' ? 'cancelled' : (r.status === 'complete' ? 'complete' : 'partial'));
+  return makeCompletion({
+    status,
+    modelCoverage: r.analysisTruncated ? 'partial' : undefined,
+    unexploredFrontierCount: nonNegInt(r.unexploredFrontierCount) || nonNegInt(r.droppedPathCount),
+    reasons,
+    limits: { ...(r.budget ?? {}) },
+    unit: 'query',
+  });
+}
+
+/**
+ * Completion of a whole DataFlowGraph, derived from what the graph already
+ * carries. A graph with no completion record at all is NOT assumed complete
+ * unless its own scanHealth says so; zero projected flows next to an
+ * incomplete analysis is called out explicitly, because an empty result is
+ * the case where the limit is easiest to miss.
+ */
+export function completionOfGraph(graph) {
+  if (!graph || typeof graph !== 'object') return makeCompletion({ status: 'unavailable', reasons: ['no-graph'], unit: 'graph' });
+  const ac = graph.coverage?.analysisCompletion ?? graph.scanHealth?.analysisCompletion ?? null;
+  let env;
+  if (ac) {
+    env = fromAnalysisCompletion(ac);
+  } else if (graph.scanHealth?.status === 'complete') {
+    env = makeCompletion({ status: 'complete', modelCoverage: 'complete', unit: 'graph' });
+  } else if (graph.scanHealth?.status === 'partial' || graph.scanHealth?.status === 'cancelled') {
+    env = makeCompletion({ status: graph.scanHealth.status, reasons: [graph.scanHealth.reason ?? 'scan-health-not-complete'], unit: 'graph' });
+  } else {
+    env = makeCompletion({ status: 'unavailable', reasons: ['no-completion-record'], unit: 'graph' });
+  }
+  const flows = Array.isArray(graph.flows) ? graph.flows.length : null;
+  if (flows === 0 && env.status !== 'complete') {
+    env = makeCompletion({ ...env, reasons: [...env.reasons, 'zero-flows-with-incomplete-analysis'], limits: { ...env.limits, flowsProjected: 0 } });
+  } else if (flows !== null) {
+    env.limits = { ...env.limits, flowsProjected: flows };
+  }
+  env.unit = 'graph';
+  return env;
+}
+
+const REASON_TEXT = {
+  'analysis-iteration-budget': 'a function hit its analysis iteration budget',
+  'context-cap': 'a call context fell back to a coarser summary (context cap)',
+  'recursion-nonconverged': 'recursion did not converge',
+  'degraded-context': 'a call context was degraded',
+  cancelled: 'the analysis was cancelled',
+  'construction-limit': 'a provenance construction limit was reached',
+  'zero-flows-with-incomplete-analysis': 'zero flows were projected from an incomplete analysis',
+  'seeding-limit': 'source seeding stopped at its limit',
+  'incremental-empty-entry-reuse': 'a cached empty-entry summary stood in for a tainted entry',
+  'caller-depth-limit': 'the reverse call-graph walk stopped at its depth limit',
+  'worklist-limit': 'the reverse selection stopped at its worklist limit',
+  'slice-node-budget': 'a backward slice stopped at its node budget',
+  'no-completion-record': 'no completion record is available',
+};
+
+/** Human-readable lines for CLI output. Empty for a complete envelope. */
+export function describeCompletion(env) {
+  if (!env || env.status === 'complete') return [];
+  const lines = [`analysis ${env.status}: absence of a flow is not evidence that none exists`];
+  for (const r of env.reasons ?? []) lines.push(`  - ${REASON_TEXT[r] ?? r}`);
+  if (env.unexploredFrontierCount > 0) lines.push(`  - ${env.unexploredFrontierCount} unit(s) of work were left unexplored`);
+  return lines;
+}
+
+/** Wire digest-neutral summary used by scan health. */
+export function summarizeForHealth(env) {
+  return {
+    status: env.status,
+    reasons: env.reasons,
+    unexploredFrontierCount: env.unexploredFrontierCount,
+    negativeClaimAllowed: env.negativeClaimAllowed,
+  };
+}

package/src/lineage/continuation.js

@@ -0,0 +1,140 @@
+// continuation.js: resumable path queries (DAG-07 R07.9).
+//
+// A path query that stopped at a budget leaves a frontier. This module keeps
+// that frontier in memory under an opaque token so the next page can pick up
+// where the previous one stopped, instead of repeating the work.
+//
+// Resume is a convenience and never a source of soundness:
+//   - a token is bound to the EXACT graph digest and to the digest of the
+//     query configuration it was issued under; a different graph or a
+//     different configuration is rejected, never silently re-based;
+//   - tokens expire (TTL) and the store is bounded in entries and bytes, so a
+//     client cannot make it grow without limit; the oldest token is evicted
+//     first and an evicted token reports `evicted`, never a wrong answer;
+//   - a resumed page is always marked `resumed` and can never license a
+//     negative claim (path-query.js enforces that), so partial results stay
+//     partial however many times they are resumed.
+
+import { createHash, randomBytes } from 'node:crypto';
+import { reconstructPaths, DEFAULTS } from './path-query.js';
+
+export const CONTINUATION_DEFAULTS = Object.freeze({
+  maxEntries: 64,
+  maxBytes: 64 * 1024 * 1024,
+  ttlMs: 10 * 60 * 1000,
+});
+
+function stableJson(v) {
+  if (Array.isArray(v)) return `[${v.map(stableJson).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stableJson(v[k])}`).join(',')}}`;
+  return JSON.stringify(v);
+}
+
+/** Digest of the query configuration that affects results (budgets and start). */
+export function configDigest(startNodeId, opts = {}) {
+  const budget = {};
+  for (const k of Object.keys(DEFAULTS)) budget[k] = opts[k] ?? DEFAULTS[k];
+  return createHash('sha256').update(stableJson({ startNodeId, budget })).digest('hex');
+}
+
+function approxBytes(state) {
+  // Frames and edges are small objects; a coarse, deliberately generous estimate.
+  return 256 + (state.stack?.length ?? 0) * 160 + (state.edgesRev?.length ?? 0) * 320 + (state.nodesRev?.length ?? 0) * 96;
+}
+
+export class ContinuationStore {
+  constructor(limits = {}) {
+    const pick = (k) => (Number.isInteger(limits[k]) && limits[k] > 0 ? limits[k] : CONTINUATION_DEFAULTS[k]);
+    this.limits = { maxEntries: pick('maxEntries'), maxBytes: pick('maxBytes'), ttlMs: pick('ttlMs') };
+    this._now = typeof limits.now === 'function' ? limits.now : Date.now;
+    this._entries = new Map(); // token -> {graphDigest, configDigest, state, bytes, expiresAt}
+    this._evicted = new Set();
+    this._bytes = 0;
+  }
+
+  size() { return this._entries.size; }
+  bytes() { return this._bytes; }
+
+  _drop(token, evicted) {
+    const e = this._entries.get(token);
+    if (!e) return;
+    this._bytes -= e.bytes;
+    this._entries.delete(token);
+    if (evicted) {
+      this._evicted.add(token);
+      if (this._evicted.size > 1024) this._evicted.delete(this._evicted.values().next().value);
+    }
+  }
+
+  _sweep() {
+    const now = this._now();
+    for (const [t, e] of this._entries) if (e.expiresAt <= now) this._drop(t, false);
+  }
+
+  /** Store a frontier. Returns {ok, token} or {ok:false, reason:'too-large'}. */
+  issue({ graphDigest, configDigest: cfg, state }) {
+    this._sweep();
+    const bytes = approxBytes(state);
+    if (bytes > this.limits.maxBytes) return { ok: false, reason: 'too-large' };
+    while (this._entries.size >= this.limits.maxEntries || this._bytes + bytes > this.limits.maxBytes) {
+      const oldest = this._entries.keys().next().value;
+      if (oldest === undefined) break;
+      this._drop(oldest, true);
+    }
+    const token = `cont:${randomBytes(12).toString('hex')}`;
+    this._entries.set(token, { graphDigest, configDigest: cfg, state, bytes, expiresAt: this._now() + this.limits.ttlMs });
+    this._bytes += bytes;
+    return { ok: true, token };
+  }
+
+  /**
+   * Redeem a token against the CURRENT graph and configuration digests.
+   * One-shot: a successful redeem removes the entry (the next page issues a
+   * new token), so a token cannot be replayed to fork the frontier.
+   */
+  redeem(token, { graphDigest, configDigest: cfg }) {
+    this._sweep();
+    const e = this._entries.get(token);
+    if (!e) return { ok: false, reason: this._evicted.has(token) ? 'evicted' : 'unknown-or-expired' };
+    if (e.graphDigest !== graphDigest) return { ok: false, reason: 'graph-changed' };
+    if (e.configDigest !== cfg) return { ok: false, reason: 'config-changed' };
+    this._drop(token, false);
+    return { ok: true, state: e.state };
+  }
+}
+
+/**
+ * Run (or resume) a path query. `continuationToken` in `opts` resumes.
+ * Returns the reconstructPaths result plus `continuation`:
+ * { token|null, rejected: reason|null }. A token is issued only when the
+ * query stopped with work left.
+ */
+export function queryWithContinuation(store, continuations, startNodeId, opts = {}) {
+  const { continuationToken, ...queryOpts } = opts;
+  const graphDigest = store.digest();
+  const cfg = configDigest(startNodeId, queryOpts);
+  let resumeState;
+  if (continuationToken !== undefined) {
+    const r = continuations.redeem(continuationToken, { graphDigest, configDigest: cfg });
+    if (!r.ok) {
+      // Rejected: report invalid, never fall back to a fresh query that
+      // would look like the continuation worked.
+      return {
+        status: 'invalid', paths: [], truncated: true, truncationReasons: [], negativeClaimAllowed: false,
+        budgetErrors: [`continuation rejected: ${r.reason}`],
+        continuation: { token: null, rejected: r.reason },
+      };
+    }
+    resumeState = r.state;
+  }
+  const result = reconstructPaths(store, startNodeId, { ...queryOpts, ...(resumeState ? { resumeState } : {}) });
+  let token = null;
+  let note = null;
+  if (result.resumeState) {
+    const issued = continuations.issue({ graphDigest, configDigest: cfg, state: result.resumeState });
+    if (issued.ok) token = issued.token; else note = issued.reason;
+    delete result.resumeState;
+  }
+  result.continuation = { token, rejected: null, ...(note ? { notIssued: note } : {}) };
+  return result;
+}