@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/knowledge/code-retrieval.js

@@ -0,0 +1,307 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { CapabilityRouter } = require('../capability-router.js');
+const { admitCodeCorpus } = require('./code-corpus.js');
+const { classifyCodeQuery, searchCodeLexical } = require('./code-lexical.js');
+// Loaded on first use only: an exact or unbound request never imports the semantic provider, its
+// lifecycle (lock, Python bridge) or the task ledger (IC-002).
+const retrievalRecord = () => require('../retrieval-record.js');
+const sembleProvider = () => require('./semble-provider.js');
+const sembleLifecycle = () => require('./semble-lifecycle.js');
+const { fuseRankedCandidates } = require('./hybrid.js');
+const { validateCodeCandidates } = require('./code-validation.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const CAPABILITY                         = Object.freeze({ exact: 'code.exact-search', conceptual: 'code.semantic-search' });
+const INDEX_STATES = new Set(['FRESH', 'STALE', 'UNKNOWN', 'NOT_APPLICABLE']);
+
+function responseError(exit     , error     , details      = {}) {
+  return { exit, response: { ok: false, schemaVersion: 1, scope: 'code', error, ...details } };
+}
+
+function registeredProviders(router     , capability     ) {
+  const providers = router?.capabilities?.[capability]?.providers;
+  return Array.isArray(providers) ? providers.map((p) => p.id).filter(Boolean) : [];
+}
+
+function failureReason(reason     , freshness     ) {
+  if (reason === 'lock-contention' || reason === 'index-in-progress' || reason === 'index-source-mismatch' || reason === 'corpus-changed') return 'policy-bypass';
+  if (reason === 'provider-timeout' || reason === 'lifecycle-timeout' || reason === 'deadline') return 'timeout';
+  if (freshness === 'STALE') return 'policy-bypass';
+  if (reason === 'provider-unavailable' || reason === 'local-model-required' || reason === 'index-missing-or-corrupt') return 'provider-unavailable';
+  return 'provider-error';
+}
+
+// A lexical stop at a configured bound is partial coverage with that bound as its cause, not a provider fault.
+const LEXICAL_BOUNDS = new Set(['candidate-limit', 'output-byte-limit', 'read-byte-limit']);
+function lexicalOutcome(result     ) {
+  if (result.complete) return { failure: null, bound: null };
+  const reasons = (result.rejections || []).map((r     ) => r.reason);
+  if (reasons.includes('deadline')) return { failure: 'provider-timeout', bound: null };
+  if (reasons.length && reasons.every((r     ) => LEXICAL_BOUNDS.has(r))) return { failure: null, bound: reasons[0] };
+  return { failure: 'provider-error', bound: null };
+}
+
+function validFreshness(value     ) { return INDEX_STATES.has(value) ? value : 'UNKNOWN'; }
+
+function appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider, capability, id, candidates, indexState, failure, bound = null, complete }     ) {
+  let stored = null;
+  if (binding) {
+    let status; let reason;
+    if (failure) { status = 'UNREACHED'; reason = failureReason(failure, indexState); }
+    else if (!candidates.length && complete) {
+      if (indexState === 'STALE') { status = 'EMPTY'; reason = 'index-stale'; }
+      else if (indexState === 'UNKNOWN') { status = 'UNVERIFIED'; reason = 'index-unverifiable'; }
+      else { status = 'EMPTY'; reason = 'empty-answer'; }
+    } else if (!candidates.length) { status = 'UNREACHED'; reason = 'timeout'; }
+    if (status) {
+      const list = registeredProviders(router, capability);
+      stored = retrievalRecord().appendRetrievalAttempt({ projectRoot, taskId, intent, provider, status, reason, indexState,
+        slug, attemptRef: binding.attemptRef, expectedCapability: need.capability,
+        expectedPrimaryProvider: need.provider, registeredProviders: list });
+    }
+  }
+  return { retrievalAttemptId: id, provider, capability, indexState, candidateCount: candidates.length,
+    complete: Boolean(complete), ...(failure || bound ? { reason: failure || bound } : {}), ...(stored ? { recordedAttempt: stored.attempt } : {}) };
+}
+
+function toCandidateList(candidates     , { provider, capability, queryRef, retrievalAttemptRef, indexed = false }     ) {
+  return candidates.map((item     , index        ) => ({
+    ...item,
+    provider,
+    capability,
+    queryRef,
+    retrievalAttemptRef,
+    ...(indexed && item.indexedSourceIdentity ? { origins: [{ provider, capability, queryRef, retrievalAttemptRef,
+      originalRank: index + 1, indexedSourceHash: item.indexedSourceIdentity }] } : {}),
+  }));
+}
+
+/** Coalesce repeated attempts by one provider without granting another RRF vote. */
+function coalesceProviderLists(lists     ) {
+  const providers = new Map();
+  for (const list of lists) {
+    const provider = list.provider;
+    if (!providers.has(provider)) providers.set(provider, new Map());
+    const spans = providers.get(provider);
+    (list.candidates || []).forEach((candidate     , index        ) => {
+      const loc = candidate.locator || {};
+      const key = JSON.stringify([loc.file, loc.line, loc.endLine]);
+      const origin = { provider, capability: list.capability, queryRef: list.queryRef ?? null,
+        retrievalAttemptRef: list.retrievalAttemptRef, originalRank: index + 1,
+        sourceVersion: candidate.sourceVersion ?? null,
+        ...(candidate.indexedSourceIdentity ? { indexedSourceHash: candidate.indexedSourceIdentity } : {}) };
+      if (!spans.has(key)) spans.set(key, { ...candidate, provider, capability: list.capability, rank: index + 1, origins: [origin] });
+      else {
+        const prior = spans.get(key);
+        prior.rank = Math.min(prior.rank, index + 1);
+        if (!prior.origins.some((item     ) => item.retrievalAttemptRef === origin.retrievalAttemptRef)) prior.origins.push(origin);
+      }
+    });
+  }
+  const result = [];
+  for (const [provider, spans] of providers) {
+    const candidates = [...spans.values()].sort((a, b) => a.rank - b.rank
+      || String(a.locator?.file).localeCompare(String(b.locator?.file))
+      || (a.locator?.line || 0) - (b.locator?.line || 0)
+      || (a.locator?.endLine || 0) - (b.locator?.endLine || 0));
+    result.push({ provider, capability: candidates[0]?.capability, candidates });
+  }
+  return result;
+}
+
+/** Shared production coordinator used by CLI retrieve and benchmark C. It prints nothing. */
+async function executeCodeRetrieval(options      = {}) {
+  const query = typeof options.query === 'string' ? options.query.trim() : '';
+  const taskId = options.taskId || null;
+  const rawNeed = options.need;
+  if (Array.isArray(rawNeed) && rawNeed.length > 1) return responseError(2, 'one-need-per-request');
+  const intent = Array.isArray(rawNeed) ? rawNeed[0] || null : rawNeed || null;
+  const slug = options.slug || null;
+  const profile = options.profile || 'lexical-only';
+  const requestedTop = options.top === undefined ? 5 : Number(options.top);
+  const rootInput = options.root || options.projectRoot || options.stateRoot || process.cwd();
+  const providers = options.providers || {};
+  if (profile !== 'lexical-only' && profile !== 'hybrid') return responseError(2, 'invalid-profile', { validProfiles: ['lexical-only', 'hybrid'] });
+  if (!Number.isInteger(requestedTop) || requestedTop < 1 || requestedTop > 25) return responseError(2, 'invalid-top', { validRange: '1..25' });
+  if (options.indexAction !== undefined && !['build', 'refresh'].includes(options.indexAction)) return responseError(2, 'invalid-index-action');
+  if (options.indexAction && query) return responseError(2, 'index-action-rejects-query');
+  if (options.indexAction && (taskId || intent)) return responseError(2, 'index-action-does-not-accept-task-binding');
+  if (Boolean(taskId) !== Boolean(intent)) return responseError(2, 'task-id-and-need-required-together');
+  let searchRoot; let projectRoot;
+  try {
+    const path = require('node:path'); const fs = require('node:fs');
+    searchRoot = fs.realpathSync(path.resolve(rootInput));
+    projectRoot = fs.realpathSync(path.resolve(options.stateRoot || searchRoot));
+  }
+  catch { return responseError(2, 'invalid-root', { root: rootInput }); }
+
+  if (options.indexAction) {
+    if (!options.modelPath) return responseError(2, 'model-path-required');
+    try {
+      const inventory = (providers.admitCodeCorpus || admitCodeCorpus)({ root: searchRoot, scopes: options.scopes, limits: options.corpusLimits });
+      if (!inventory.complete) return { exit: 1, response: { schemaVersion: 1, scope: 'code', action: options.indexAction, ...inventory, complete: false, error: 'incomplete-corpus' } };
+      const run = providers.lifecycle || sembleLifecycle().runSembleLifecycle;
+      const result = await run({ inventory, modelPath: options.modelPath, action: options.indexAction, limits: options.semanticLimits });
+      return { exit: result.ok ? 0 : 1, response: { schemaVersion: 1, scope: 'code', ...result } };
+    } catch (error     ) {
+      return { exit: 1, response: { schemaVersion: 1, scope: 'code', action: options.indexAction, complete: false,
+        error: 'lifecycle-error', cause: error?.message || String(error), repair: 'Correct the cause and run an explicit bounded build or refresh.' } };
+    }
+  }
+  if (!query || Buffer.byteLength(query, 'utf8') > 4096) return responseError(2, 'invalid-query', { expected: '1..4096 UTF-8 bytes' });
+
+  let binding = null;
+  let need = null;
+  let classification;
+  try {
+    const classifier = providers.classifyCodeQuery || classifyCodeQuery;
+    classification = classifier(query, { intent });
+    if (taskId) {
+      binding = retrievalRecord().resolveRetrievalBinding({ projectRoot, taskId, intent, slug });
+      if (!binding.ok) return responseError(2, 'invalid-task-binding', { summary: binding.message });
+      need = binding.need;
+      const requiredCapability = CAPABILITY[classification.queryClass];
+      if (need.capability !== requiredCapability) return responseError(2, 'capability-mismatch', {
+        need: intent, declaredCapability: need.capability, requiredCapability, queryClass: classification.queryClass,
+      });
+    }
+  } catch (error     ) {
+    return responseError(2, 'invalid-task-binding', { summary: error?.message || String(error) });
+  }
+
+  const capability = CAPABILITY[classification.queryClass];
+  let router;
+  try { router = providers.router || new CapabilityRouter({ repoRoot: options.repoRoot || REPO_ROOT }); }
+  catch (error     ) { return { exit: 1, response: { schemaVersion: 1, scope: 'code', error: 'registry-unavailable', cause: error?.message || String(error) } }; }
+  const registered = registeredProviders(router, capability);
+  if (!registered.includes('native.rg')) return responseError(2, 'lexical-provider-not-registered', { capability });
+  if (profile === 'hybrid' && classification.queryClass === 'conceptual' && !registered.includes('semble.search')) {
+    return responseError(2, 'semantic-provider-not-registered', { capability });
+  }
+  let inventory;
+  try {
+    const admit = providers.admitCodeCorpus || admitCodeCorpus;
+    // Exact never reads an index or a corpus digest (DEC-020): admit without per-file hashes, proving each directory
+    // once; lexical hashes what it reports and live validation re-hashes every delivered candidate. Conceptual and
+    // index paths keep full hashing.
+    inventory = providers.inventory || admit({ root: searchRoot, scopes: options.scopes, limits: options.corpusLimits,
+      ...(classification.queryClass === 'exact' ? { hashFiles: false, verifyDirsOnce: true } : {}) });
+  } catch (error     ) {
+    return { exit: 1, response: { schemaVersion: 1, scope: 'code', queryClass: classification.queryClass,
+      requestedProfile: profile, effectiveProfile: 'lexical-only', error: 'corpus-admission-failed', cause: error?.message || String(error) } };
+  }
+
+  const topN = requestedTop;
+  const attempts = [];
+  const gaps = [];
+  const rankedLists = [];
+  const coverage = { corpusComplete: Boolean(inventory.complete), lexical: []         , semantic: null, live: null, complete: Boolean(inventory.complete) };
+  // Admission skips are counted coverage gaps with their cause, never a provider outcome (X3); index build and
+  // refresh still refuse an incomplete corpus (IC-003, IC-005).
+  if (!inventory.complete) {
+    const skipped = Array.isArray(inventory.skipped) ? inventory.skipped : [];
+    const byReason = new Map                ();
+    for (const entry of skipped) byReason.set(entry.reason, (byReason.get(entry.reason) || 0) + 1);
+    if (!byReason.size) byReason.set('incomplete-corpus', 1);
+    for (const [reason, count] of byReason) gaps.push({ source: 'admission', reason, count });
+  }
+  const accounting = { corpusFiles: inventory.files?.length || 0, corpusBytes: inventory.accounting?.sourceBytes || 0,
+    semanticSourceReadBytes: 0, lexicalReadBytes: 0, liveReadBytes: 0, deliveredCandidates: 0 };
+  let lexicalExecuted = false;
+  let semanticExecuted = false;
+  let semanticComplete = false;
+  const queryRef = binding?.queryRef ?? null;
+  const makeId = () => 'ra-' + crypto.randomUUID();
+  const lexical = providers.lexicalSearch || searchCodeLexical;
+  const runLexical = (id     ) => {
+    const result = lexical({ ...options.lexicalLimits, inventory, query, classification, intent, maxCandidates: 200, queryRef,
+      retrievalAttemptRef: id });
+    return result;
+  };
+
+  try {
+    const lexicalId = makeId();
+    let lexResult;
+    try { lexResult = runLexical(lexicalId); }
+    catch (error     ) { lexResult = { candidates: [], complete: false, rejections: [{ reason: 'provider-error' }], accounting: {}, coverage: { complete: false } }; }
+    lexicalExecuted = true;
+    accounting.lexicalReadBytes += lexResult.accounting?.readBytes || 0;
+    coverage.lexical.push(lexResult.coverage || { complete: Boolean(lexResult.complete) });
+    const lexCandidates = toCandidateList(lexResult.candidates || [], { provider: 'native.rg', capability, queryRef, retrievalAttemptRef: lexicalId });
+    rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: lexicalId, candidates: lexCandidates });
+    const lexOutcome = lexicalOutcome(lexResult);
+    attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
+      id: lexicalId, candidates: lexCandidates, indexState: 'NOT_APPLICABLE', ...lexOutcome, complete: Boolean(lexResult.complete && inventory.complete) }));
+    if (lexOutcome.failure || lexOutcome.bound) gaps.push({ provider: 'native.rg', reason: lexOutcome.failure || lexOutcome.bound, source: 'lexical' });
+
+    if (profile === 'hybrid' && classification.queryClass === 'conceptual') {
+      const semanticId = makeId();
+      let semResult;
+      const modelPath = options.modelPath || process.env.SEMBLE_MODEL_PATH || null;
+      if (!modelPath) semResult = { ok: false, reason: 'local-model-required', freshness: 'UNKNOWN', candidates: [] };
+      else {
+        try { semResult = await (providers.semanticQuery || sembleProvider().runSembleQuery)({ inventory, query, top: 200, modelPath, limits: options.semanticLimits }); }
+        catch (error     ) { semResult = { ok: false, reason: 'provider-error', freshness: 'UNKNOWN', cause: error?.message || String(error), candidates: [] }; }
+      }
+      const semFreshness = validFreshness(semResult.freshness);
+      accounting.semanticSourceReadBytes += semResult.accounting?.sourceReadBytes || 0;
+      if (semResult.ok) {
+        semanticExecuted = true; semanticComplete = semFreshness === 'FRESH';
+        const semCandidates = toCandidateList(semResult.candidates || [], { provider: 'semble.search', capability, queryRef,
+          retrievalAttemptRef: semanticId, indexed: true });
+        rankedLists.push({ provider: 'semble.search', capability, queryRef, retrievalAttemptRef: semanticId, candidates: semCandidates });
+        attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'semble.search', capability,
+          id: semanticId, candidates: semCandidates, indexState: semFreshness, complete: true }));
+      } else {
+        const reason = semResult.reason || 'provider-unavailable';
+        attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'semble.search', capability,
+          id: semanticId, candidates: [], indexState: semFreshness, failure: reason, complete: false }));
+        gaps.push({ provider: 'semble.search', reason, freshness: semFreshness, source: 'semantic' });
+        const fallbackId = makeId();
+        let fallback;
+        try { fallback = runLexical(fallbackId); }
+        catch (error     ) { fallback = { candidates: [], complete: false, rejections: [{ reason: 'provider-error' }], accounting: {}, coverage: { complete: false } }; }
+        accounting.lexicalReadBytes += fallback.accounting?.readBytes || 0;
+        coverage.lexical.push(fallback.coverage || { complete: Boolean(fallback.complete), fallback: true });
+        const fallbackCandidates = toCandidateList(fallback.candidates || [], { provider: 'native.rg', capability, queryRef, retrievalAttemptRef: fallbackId });
+        rankedLists.push({ provider: 'native.rg', capability, queryRef, retrievalAttemptRef: fallbackId, candidates: fallbackCandidates });
+        const fallbackOutcome = lexicalOutcome(fallback);
+        attempts.push(appendOutcome({ binding, projectRoot, taskId, slug, intent, need, router, provider: 'native.rg', capability,
+          id: fallbackId, candidates: fallbackCandidates, indexState: 'NOT_APPLICABLE', ...fallbackOutcome, complete: Boolean(fallback.complete && inventory.complete) }));
+        if (fallbackOutcome.failure || fallbackOutcome.bound) gaps.push({ provider: 'native.rg', reason: fallbackOutcome.failure || fallbackOutcome.bound, source: 'fallback' });
+      }
+    }
+
+    // Conceptual fuses by file with each provider voting for its first `top` distinct files; exact keeps span grain (DEC-025).
+    const grain = classification.queryClass === 'conceptual' ? { grain: 'file', depth: topN } : {};
+    const fused = fuseRankedCandidates({ rankedLists: coalesceProviderLists(rankedLists), projectRoot: searchRoot, corpusIdentity: inventory.identity, k: 60, ...grain });
+    if (fused.rejected?.length) gaps.push({ source: 'fusion', reason: 'invalid-candidate', count: fused.rejected.length });
+    if (fused.candidates.length > 200) gaps.push({ source: 'fusion', reason: 'candidate-limit', count: fused.candidates.length - 200 });
+    const validate = providers.validateCandidates || validateCodeCandidates;
+    const live = validate({ inventory, candidates: fused.candidates.slice(0, 200), topN });
+    coverage.live = live.coverage;
+    const semanticRequested = profile === 'hybrid' && classification.queryClass === 'conceptual';
+    coverage.complete = Boolean(inventory.complete && coverage.lexical.every((item) => item.complete !== false)
+      && (!semanticRequested || (semanticExecuted && semanticComplete)) && fused.candidates.length <= 200
+      && live.complete && gaps.length === 0);
+    accounting.liveReadBytes = live.accounting?.readBytes || 0;
+    accounting.deliveredCandidates = live.results?.length || 0;
+    for (const rejected of live.rejected || []) gaps.push({ source: 'live-validation', reason: rejected.reason });
+    // A dropped non-delivered origin is a distinct gap source: the delivered candidate stands (IC-007).
+    for (const rejected of live.rejectedOrigins || []) gaps.push({ source: 'live-validation-origin', reason: rejected.reason, provider: rejected.provider });
+    const effectiveProfile = profile === 'hybrid' && classification.queryClass === 'conceptual' && semanticExecuted && semanticComplete && lexicalExecuted
+      ? 'hybrid' : 'lexical-only';
+    return { exit: 0, response: { ok: true, schemaVersion: 1, scope: 'code', root: searchRoot,
+      queryClass: classification.queryClass, classificationBasis: classification.classificationBasis,
+      requestedProfile: profile, effectiveProfile, queryRef, activeTaskAttemptRef: binding?.attemptRef ?? null,
+      results: live.results || [], attempts, gaps, coverage, accounting, absenceEstablished: false } };
+  } catch (error     ) {
+    return { exit: 1, response: { ok: false, schemaVersion: 1, scope: 'code', queryClass: classification.queryClass,
+      requestedProfile: profile, effectiveProfile: 'lexical-only', error: 'retrieval-failed', cause: error?.message || String(error), attempts, gaps, coverage, accounting,
+      absenceEstablished: false } };
+  }
+}
+
+module.exports = { executeCodeRetrieval, coalesceProviderLists, lexicalOutcome, CAPABILITY };

package/src/runtime/knowledge/code-validation.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('node:fs');
+const { readCorpusFile, relativeCodePath } = require('./code-corpus.js');
+
+const LIVE_LIMITS = Object.freeze({ maxFileBytes: 1024 * 1024, maxSnippetLines: 50, maxSnippetBytes: 16 * 1024, maxReadBytes: 1024 * 1024, timeoutMs: 1000, maxCandidates: 200 });
+
+function readAdmittedFile(inventory     , entry     , options      = {})      {
+  const rel = relativeCodePath(entry?.path);
+  const admitted = inventory.files.find((f     ) => f.path === rel);
+  if (!admitted) return { ok: false, reason: 'outside-corpus', bytesRead: 0 };
+  return readCorpusFile(inventory.root, admitted, options);
+}
+
+function validateCodeCandidates({ inventory, candidates, topN = 10, limits: suppliedLimits, fsImpl = fs, now = Date.now }     )      {
+  const limits = { ...LIVE_LIMITS, ...suppliedLimits };
+  for (const [name, value] of Object.entries(limits)) if (!Number.isSafeInteger(value) || Number(value) < 1) throw new Error('invalid live limit ' + name);
+  if (!Number.isInteger(topN) || topN < 1 || topN > 25) throw new Error('topN must be 1..25');
+  const deadline = now() + limits.timeoutMs;
+  const results        = [];
+  const rejected        = [];
+  const rejectedOrigins        = [];
+  let readBytes = 0;
+  let examined = 0;
+  let complete = Boolean(inventory.complete);
+  // One live read per file per call: candidates on the same file share it (and its hash check) instead of
+  // re-reading and re-charging the aggregate budget once per matching line.
+  const reads = new Map             ();
+  const reject = (candidate     , reason        ) => { rejected.push({ locator: candidate?.locator ?? null, reason }); complete = false; };
+  for (const candidate of candidates) {
+    if (results.length >= topN) break;
+    if (examined >= limits.maxCandidates) { reject(candidate, 'candidate-limit'); break; }
+    examined += 1;
+    if (now() > deadline) { reject(candidate, 'deadline'); break; }
+    const loc = candidate?.locator;
+    if (!loc || !relativeCodePath(loc.file) || !Number.isInteger(loc.line) || !Number.isInteger(loc.endLine) || loc.line < 1 || loc.endLine < loc.line) { reject(candidate, 'invalid-locator'); continue; }
+    const entry = inventory.files.find((f     ) => f.path === loc.file);
+    if (!entry) { reject(candidate, 'outside-corpus'); continue; }
+    let read = reads.get(entry.path);
+    if (!read) {
+      const remaining = limits.maxReadBytes - readBytes;
+      if (remaining <= 0) { reject(candidate, 'read-byte-limit'); break; }
+      read = readAdmittedFile(inventory, entry, { fsImpl, now, deadline, maxBytes: Math.min(limits.maxFileBytes, remaining) });
+      readBytes += read.bytesRead;
+      reads.set(entry.path, read); // budget and deadline only shrink, so a refusal stays a refusal
+    }
+    if (!read.ok) { reject(candidate, read.reason); continue; }
+    const searchedHashes = [candidate.sourceVersion?.fileHash, ...(candidate.origins || []).map((o     ) => o.sourceVersion?.fileHash || o.indexedSourceHash)].filter(Boolean);
+    if (searchedHashes.some((hash        ) => hash !== read.fileHash)) { reject(candidate, 'source-changed'); continue; }
+    const text = read.content.toString('utf8');
+    if (text.includes('\0')) { reject(candidate, 'binary-source'); continue; }
+    const lines = text.split('\n');
+    if (loc.endLine > lines.length) { reject(candidate, 'line-out-of-range'); continue; }
+    // Origin locators (file-grain fusion, DEC-025) are provider-reported: range-check each on this same read and
+    // drop an invalid one with its cause, keeping the validated delivered span.
+    let origins = candidate.origins;
+    if (Array.isArray(origins) && origins.some((o     ) => o?.locator)) {
+      origins = origins.filter((origin     ) => {
+        const ol = origin?.locator;
+        if (!ol) return true;
+        const reason = ol.file !== loc.file || !Number.isInteger(ol.line) || !Number.isInteger(ol.endLine) || ol.line < 1 || ol.endLine < ol.line
+          ? 'invalid-locator' : ol.endLine > lines.length ? 'line-out-of-range' : null;
+        if (!reason) return true;
+        rejectedOrigins.push({ locator: ol, provider: origin.provider ?? null, retrievalAttemptRef: origin.retrievalAttemptRef ?? null, reason });
+        complete = false;
+        return false;
+      });
+    }
+    const endLine = Math.min(loc.endLine, loc.line + limits.maxSnippetLines - 1);
+    let snippet = lines.slice(loc.line - 1, endLine).join('\n');
+    let byteTruncated = false;
+    if (Buffer.byteLength(snippet, 'utf8') > limits.maxSnippetBytes) {
+      let bytes = 0;
+      let bounded = '';
+      for (const char of snippet) {
+        const size = Buffer.byteLength(char, 'utf8');
+        if (bytes + size > limits.maxSnippetBytes) break;
+        bounded += char; bytes += size;
+      }
+      snippet = bounded; byteTruncated = true;
+    }
+    const { snippet: suppliedSnippet, liveRead: suppliedRead, ...safeCandidate } = candidate;
+    results.push({ ...safeCandidate, ...(origins === candidate.origins ? {} : { origins }), snippet, sourceVersion: { gitCommit: candidate.sourceVersion?.gitCommit ?? null, fileHash: read.fileHash, isDirty: candidate.sourceVersion?.isDirty ?? null },
+      liveRead: { startLine: loc.line, endLine: byteTruncated ? loc.line + snippet.split('\n').length - 1 : endLine, totalFileLines: lines.length, bytesRead: read.bytesRead, snippetBytes: Buffer.byteLength(snippet, 'utf8'), truncated: byteTruncated || endLine < loc.endLine } });
+  }
+  return { results, rejected, ...(rejectedOrigins.length ? { rejectedOrigins } : {}), complete, coverage: { complete, examinedCandidates: examined, rejectedCandidates: rejected.length }, accounting: { readBytes, deliveredCandidates: results.length, examinedCandidates: examined } };
+}
+
+/** Explicit score-free adapter input. The existing ledger stamps query/task attempt refs. */
+function projectEvidenceCandidates(candidate     , { need }      = {})        {
+  if (!candidate?.liveRead || typeof candidate.snippet !== 'string' || !candidate.sourceVersion?.fileHash) throw new Error('candidate requires a validated live read before evidence projection');
+  const out        = [];
+  const seen = new Set        ();
+  const origins = candidate.origins?.length ? candidate.origins : [{ provider: candidate.provider, capability: candidate.capability }];
+  for (const origin of origins) {
+    if (!origin.provider || !origin.capability) throw new Error('evidence origin needs a provider and capability');
+    const key = origin.provider + '\0' + origin.capability;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ candidate: { locator: { file: candidate.locator.file, line: candidate.locator.line }, provider: origin.provider, capability: origin.capability,
+      ...(need ? { need } : {}), sourceVersion: { ...candidate.sourceVersion } }, content: candidate.snippet });
+  }
+  return out;
+}
+
+module.exports = { LIVE_LIMITS, readAdmittedFile, validateCodeCandidates, projectEvidenceCandidates };

package/src/runtime/knowledge/gp3-gate.js

@@ -0,0 +1,74 @@
+'use strict';
+
+                       
+               
+                                              
+                  
+             
+                                                                      
+                                                                                
+                                                                                   
+    
+                              
+                    
+ 
+
+function evaluateGP3Gate(report     )              {
+  const reduction = report.delta?.missedDependenciesReduction ?? 0;
+  const latencyDeltaMs = report.delta?.latencyDeltaMs ?? 0;
+  const unreachedBaseline = report.arms?.lexical?.unreachedCount ?? 0;
+  const unreachedGraph = report.arms?.graphImpact?.unreachedCount ?? 0;
+
+  const missedDependenciesReductionMet = reduction >= 0.15;
+  const latencyOverheadMet = latencyDeltaMs <= 250;
+  const zeroUnreachedRegression = unreachedGraph <= unreachedBaseline;
+
+  const passed =
+    missedDependenciesReductionMet &&
+    latencyOverheadMet &&
+    zeroUnreachedRegression;
+
+  let verdict                                    ;
+  let rationale = '';
+
+  if (passed) {
+    verdict = 'KEEP';
+    rationale = `Passed G-P3 criteria: missedDependenciesReduction ${(reduction * 100).toFixed(1)}% (threshold >= 15%), latency delta ${latencyDeltaMs}ms <= 250ms budget, zero unreached regressions.`;
+  } else {
+    verdict = 'DISABLE';
+    const failures           = [];
+    if (!missedDependenciesReductionMet) {
+      failures.push(
+        `missedDependenciesReduction ${(reduction * 100).toFixed(1)}% fell below 15% threshold`
+      );
+    }
+    if (!latencyOverheadMet) {
+      failures.push(
+        `latency overhead +${latencyDeltaMs}ms exceeded 250ms budget`
+      );
+    }
+    if (!zeroUnreachedRegression) {
+      failures.push(
+        `unreached queries regressed from ${unreachedBaseline} to ${unreachedGraph}`
+      );
+    }
+    rationale = `Failed G-P3 criteria: ${failures.join('; ')}. Graph reranking must be disabled to avoid unproven latency overhead.`;
+  }
+
+  return {
+    gate: 'G-P3',
+    verdict,
+    passed,
+    criteria: {
+      missedDependenciesReductionMet,
+      latencyOverheadMet,
+      zeroUnreachedRegression,
+    },
+    headlineMetricDelta: Number(reduction.toFixed(4)),
+    rationale,
+  };
+}
+
+module.exports = {
+  evaluateGP3Gate,
+};