@tiinex/core 0.1.1

package/src/tooling/portable/lineage/lineage.publicationProviderReceipts.js

@@ -0,0 +1,141 @@
+import {
+  PORTABLE_HOST_ACTION_ACCEPTANCE_SCHEMA_ID,
+  acceptPortableHostActionReceipt
+} from '../host/tool.bindings.js';
+import { portableFinding } from '../findings.js';
+import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export function normalizePublicationProviderReceipts(input = {}) {
+  const findings = [];
+  const references = [];
+  const observations = [];
+
+  for (const item of receiptInputs(input)) {
+    const plan = item?.plan || item?.hostActionPlan || null;
+    const receipt = item?.receipt || item?.hostReceipt || null;
+    if (!plan || !receipt) {
+      findings.push(portableFinding('error', 'portable.lineage.publication-provider.receipt-pair.required', 'Publication provider receipt input requires both the original host action plan and its receipt.'));
+      references.push(Object.freeze({ actionId: String(plan?.actionId || receipt?.actionId || ''), status: 'rejected', reason: 'publication-provider-receipt-pair-required' }));
+      continue;
+    }
+    addAcceptance(acceptPortableHostActionReceipt({ plan, receipt }), observations, references, findings, 'receipt');
+  }
+
+  for (const acceptance of acceptanceInputs(input)) addAcceptance(acceptance, observations, references, findings, 'acceptance');
+
+  if (Array.isArray(input.providerResponses) && input.providerResponses.length) {
+    findings.push(portableFinding('warning', 'portable.lineage.publication-provider.responses-unaccepted', 'Direct providerResponses are not publication qualification authority; supply an accepted publication provider host receipt or acceptance.'));
+  }
+
+  return Object.freeze({
+    observations: Object.freeze(observations),
+    references: Object.freeze(references),
+    findings: Object.freeze(findings),
+    summary: Object.freeze({
+      acceptedReceipts: observations.length,
+      acceptedFiles: observations.reduce((sum, entry) => sum + entry.files.length, 0),
+      rejectedReceipts: references.filter((entry) => entry.status !== 'accepted').length
+    }),
+    boundary: Object.freeze({
+      acceptedAction: 'repository-read',
+      directProviderResponsesAreNotAuthority: true,
+      localRecordEvidenceIsDescriptiveOnly: true,
+      returnedProviderContentMustBeRehashedByLineageTooling: true
+    })
+  });
+}
+
+export function qualifiedPublicationCandidatesForParent(providerEvidence = {}, parentRecord = {}) {
+  const markdown = String(parentRecord?.markdown || '');
+  if (!markdown) return Object.freeze([]);
+  const expectedBytes = utf8Bytes(markdown);
+  const expectedSha256 = sha256Hex(expectedBytes);
+  const candidates = new Map();
+  for (const observation of providerEvidence.observations || []) {
+    for (const file of observation.files || []) {
+      const source = file.source || {};
+      const repository = String(source.repository || '').trim();
+      const commit = String(source.commit || '').trim().toLowerCase();
+      const sourcePath = normalizePath(source.path || file.path || '');
+      if (!repository || !/^[0-9a-f]{40}$/.test(commit) || !sourcePath || typeof file.content !== 'string') continue;
+      const bytes = utf8Bytes(file.content);
+      const sha256 = sha256Hex(bytes);
+      if (bytes.byteLength !== expectedBytes.byteLength || sha256.toLowerCase() !== expectedSha256.toLowerCase()) continue;
+      const locator = `https://github.com/${repository}/blob/${commit}/${sourcePath}`;
+      candidates.set(locator, Object.freeze({
+        state: 'qualified',
+        locator,
+        actionId: String(observation.actionId || ''),
+        providerId: String(file.providerId || ''),
+        source: Object.freeze({ repository, commit, path: sourcePath }),
+        materialIdentity: Object.freeze({ state: 'qualified', sha256, bytes: bytes.byteLength })
+      }));
+    }
+  }
+  return Object.freeze([...candidates.values()].sort((a, b) => a.locator.localeCompare(b.locator)));
+}
+
+function addAcceptance(acceptance = {}, observations, references, findings, sourceKind) {
+  const actionId = String(acceptance?.actionId || '');
+  if (acceptance?.schema !== PORTABLE_HOST_ACTION_ACCEPTANCE_SCHEMA_ID) {
+    reject(actionId, 'publication-provider-acceptance-schema-invalid', references, findings, 'portable.lineage.publication-provider.acceptance-schema.invalid', 'Publication provider evidence must use the portable host-action acceptance contract.');
+    return;
+  }
+  if (acceptance.status !== 'accepted') {
+    reject(actionId, 'publication-provider-receipt-rejected', references, findings, 'portable.lineage.publication-provider.acceptance-rejected', 'Rejected host/provider receipt material cannot qualify publication.');
+    return;
+  }
+  if (String(acceptance.action || '') !== 'repository-read') {
+    reject(actionId, 'publication-provider-action-mismatch', references, findings, 'portable.lineage.publication-provider.action.invalid', 'Publication qualification accepts only an explicit repository-read host action receipt.', { action: String(acceptance.action || '') });
+    return;
+  }
+
+  const providerResponses = Array.isArray(acceptance.providerResponses) ? acceptance.providerResponses : [];
+  const files = [];
+  for (const response of providerResponses) {
+    for (const file of Array.isArray(response?.files) ? response.files : []) {
+      if (file?.sourceMode !== 'portable-host-repository' || !file?.source?.repository || file?.source?.remoteFetch !== true || typeof file?.content !== 'string') continue;
+      files.push(Object.freeze({
+        providerId: String(response.providerId || ''),
+        path: normalizePath(file.path || ''),
+        content: file.content,
+        source: Object.freeze({
+          repository: String(file.source.repository || ''),
+          ref: String(file.source.ref || ''),
+          commit: String(file.source.commit || ''),
+          path: normalizePath(file.source.path || file.path || ''),
+          authority: String(file.source.authority || ''),
+          remoteFetch: true
+        })
+      }));
+    }
+  }
+  if (!files.length) {
+    reject(actionId, 'publication-provider-repository-material-missing', references, findings, 'portable.lineage.publication-provider.repository-material.missing', 'Accepted publication provider evidence did not contain repository-read UTF-8 material.');
+    return;
+  }
+
+  references.push(Object.freeze({ actionId, status: 'accepted', reason: '' }));
+  observations.push(Object.freeze({ actionId, action: 'repository-read', sourceKind, files: Object.freeze(files) }));
+}
+
+function reject(actionId, reason, references, findings, code, message, detail = {}) {
+  references.push(Object.freeze({ actionId, status: 'rejected', reason }));
+  findings.push(portableFinding('error', code, message, { actionId, ...detail }));
+}
+
+function receiptInputs(input = {}) {
+  const out = [];
+  if (input.publicationProviderReceipt) out.push(input.publicationProviderReceipt);
+  if (Array.isArray(input.publicationProviderReceipts)) out.push(...input.publicationProviderReceipts);
+  return out.filter(Boolean);
+}
+
+function acceptanceInputs(input = {}) {
+  const out = [];
+  if (input.publicationProviderAcceptance) out.push(input.publicationProviderAcceptance);
+  if (Array.isArray(input.publicationProviderAcceptances)) out.push(...input.publicationProviderAcceptances);
+  return out.filter(Boolean);
+}
+
+function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/'); }

package/src/tooling/portable/lineage/lineage.publicationQualification.js

@@ -0,0 +1,183 @@
+import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export function classifyPortablePublicationOrigin(parentEnvelope = {}, childRecord = {}, parentRecord = null, providerEvidence = {}) {
+  const entries = Array.isArray(parentEnvelope.originEntries) ? parentEnvelope.originEntries : [];
+  const relative = entries.filter((entry) => String(entry.label || '') === 'relative');
+  const browse = entries.filter((entry) => String(entry.label || '') === 'browse + git');
+  if (relative.length > 1 || browse.length > 1) return publicationState('contradictory', 'duplicate-parent-origin-representation', browse[0]?.target || '', { locatorState: 'contradictory', evidenceState: 'rejected' });
+  if (relative.length === 1 && parentEnvelope.trace && String(relative[0].target || '') !== String(parentEnvelope.trace || '')) return publicationState('contradictory', 'relative-origin-disagrees-with-trace', browse[0]?.target || '', { locatorState: 'contradictory', evidenceState: 'rejected' });
+  if (!browse.length) {
+    const localTarget = String(relative[0]?.target || parentEnvelope.trace || '');
+    if (relative.length === 1 && localTarget && parentRecord?.markdown) return publicationState('qualified-local-relative', 'exact-loaded-parent-via-declared-relative-origin', localTarget, { locatorState: 'declared-relative-local', evidenceState: 'exact-loaded-parent' });
+    return publicationState('missing', 'browse-git-origin-missing', '', { locatorState: 'missing', evidenceState: 'not-applicable' });
+  }
+  const locator = String(browse[0].target || '');
+  if (!locator) return publicationState('unresolved', 'browse-git-origin-empty', '', { locatorState: 'empty', evidenceState: 'missing' });
+
+  const locatorState = declaredPublicationLocatorState(locator);
+  const qualification = qualifyPublicationEvidence({ locator, parentRecord, childRecord, providerEvidence });
+  if (locatorState === 'mutable-or-noncanonical-github-blob') return publicationState('stale', 'mutable-or-noncanonical-github-blob', locator, { locatorState, evidenceState: qualification.state, evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, true) });
+  if (qualification.state === 'qualified') return publicationState('qualified', 'accepted-provider-publication-material', locator, { locatorState, evidenceState: 'qualified', evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, false) });
+  if (qualification.state === 'contradictory') return publicationState('contradictory', qualification.reason, locator, { locatorState, evidenceState: 'rejected', evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, true) });
+  if (locatorState === 'commit-pinned-github-blob') return publicationState('unresolved', qualification.reason || 'publication-provider-receipt-required', locator, { locatorState, evidenceState: qualification.state, evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, true) });
+  if (/^https?:\/\//i.test(locator)) return publicationState('unresolved', qualification.reason || 'publication-locator-not-independently-qualified', locator, { locatorState, evidenceState: qualification.state, evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, true) });
+  return publicationState('unresolved', 'publication-locator-unsupported', locator, { locatorState, evidenceState: qualification.state, evidence: qualification.evidence, providerRequirement: providerRequirement(locator, parentRecord, true) });
+}
+
+function qualifyPublicationEvidence({ locator = '', parentRecord = null, childRecord = {}, providerEvidence = {} } = {}) {
+  const recordEvidence = inspectRecordPublicationEvidence({ locator, parentRecord, childRecord });
+  if (recordEvidence.state === 'contradictory') return recordEvidence;
+  if (!parentRecord?.markdown) return Object.freeze({ state: 'unresolved', reason: 'publication-parent-material-unavailable', evidence: recordEvidence.evidence || null });
+
+  const locatorIdentity = parseGithubBlobLocator(locator);
+  if (!locatorIdentity) return Object.freeze({ state: recordEvidence.state, reason: recordEvidence.reason || 'publication-provider-receipt-required', evidence: recordEvidence.evidence || null });
+
+  const eligible = eligibleProviderObservations(providerEvidence, recordEvidence.receiptReference);
+  if (recordEvidence.receiptReference && !eligible.length) {
+    const reference = (providerEvidence.references || []).find((entry) => entry.actionId === recordEvidence.receiptReference);
+    return Object.freeze({
+      state: 'unresolved',
+      reason: reference?.reason || 'publication-evidence-receipt-reference-unresolved',
+      evidence: recordEvidence.evidence || null
+    });
+  }
+
+  const parentBytes = utf8Bytes(parentRecord.markdown || '');
+  const parentSha256 = sha256Hex(parentBytes);
+  for (const observation of eligible) {
+    for (const file of observation.files || []) {
+      const source = file.source || {};
+      const repository = String(source.repository || '');
+      const commit = String(source.commit || '').toLowerCase();
+      const sourcePath = normalizePath(source.path || file.path || '');
+      if (repository !== locatorIdentity.repository || commit !== locatorIdentity.commit || sourcePath !== locatorIdentity.path) continue;
+      const providerBytes = utf8Bytes(file.content || '');
+      const providerSha256 = sha256Hex(providerBytes);
+      if (providerSha256.toLowerCase() !== parentSha256.toLowerCase() || providerBytes.byteLength !== parentBytes.byteLength) {
+        return Object.freeze({ state: 'contradictory', reason: 'publication-provider-material-mismatch', evidence: summarizeProviderEvidence(locator, observation, file, providerSha256, providerBytes.byteLength) });
+      }
+      return Object.freeze({ state: 'qualified', reason: '', evidence: summarizeProviderEvidence(locator, observation, file, providerSha256, providerBytes.byteLength) });
+    }
+  }
+
+  if (recordEvidence.receiptReference && eligible.length) return Object.freeze({ state: 'contradictory', reason: 'publication-provider-identity-mismatch', evidence: recordEvidence.evidence || null });
+  return Object.freeze({ state: 'unresolved', reason: 'publication-provider-receipt-required', evidence: recordEvidence.evidence || null });
+}
+
+function inspectRecordPublicationEvidence({ locator = '', parentRecord = null, childRecord = {} } = {}) {
+  const candidates = publicationEvidenceCandidates(parentRecord, childRecord);
+  if (!candidates.length) return Object.freeze({ state: 'missing', reason: 'publication-provider-receipt-required', evidence: null, receiptReference: '' });
+  for (const supplied of candidates) {
+    const evidence = supplied?.evidence || supplied?.resolutionEvidence || null;
+    if (!evidence || typeof evidence !== 'object') continue;
+    const summary = summarizePublicationEvidence(evidence, supplied);
+    const evidenceTarget = summary.target;
+    const evidenceState = summary.state;
+    const receiptReference = publicationEvidenceReceiptReference(evidence, supplied);
+    if (evidenceTarget && evidenceTarget !== locator) return Object.freeze({ state: 'contradictory', reason: 'publication-evidence-target-mismatch', evidence: summary, receiptReference });
+    if (evidenceState !== 'qualified') continue;
+    if (!parentRecord?.markdown) return Object.freeze({ state: 'unresolved', reason: 'publication-parent-material-unavailable', evidence: summary, receiptReference });
+
+    const identity = evidence.materialIdentity || evidence.material || {};
+    const actualBytes = utf8Bytes(parentRecord.markdown || '');
+    const actualSha256 = sha256Hex(actualBytes);
+    if (String(identity.state || '') === 'qualified' && String(identity.sha256 || '')) {
+      if (String(identity.sha256 || '').toLowerCase() !== actualSha256.toLowerCase()) return Object.freeze({ state: 'contradictory', reason: 'publication-evidence-material-sha256-mismatch', evidence: summary, receiptReference });
+      if (identity.bytes !== undefined && Number(identity.bytes) !== actualBytes.byteLength) return Object.freeze({ state: 'contradictory', reason: 'publication-evidence-material-bytes-mismatch', evidence: summary, receiptReference });
+    }
+
+    const locatorIdentity = parseGithubBlobLocator(locator);
+    const source = evidence.source || evidence.providerSource || evidence.provider || {};
+    if (source && typeof source === 'object' && Object.keys(source).length && locatorIdentity) {
+      const repository = String(source.repository || source.repo || '');
+      const commit = String(source.commit || source.ref || '');
+      const sourcePath = normalizePath(source.path || source.repositoryPath || '');
+      if (repository !== locatorIdentity.repository || commit.toLowerCase() !== locatorIdentity.commit || sourcePath !== locatorIdentity.path) return Object.freeze({ state: 'contradictory', reason: 'publication-evidence-provider-identity-mismatch', evidence: summary, receiptReference });
+    }
+    return Object.freeze({ state: 'unresolved', reason: 'publication-provider-receipt-required', evidence: summary, receiptReference });
+  }
+  return Object.freeze({ state: 'unresolved', reason: 'publication-provider-receipt-required', evidence: null, receiptReference: '' });
+}
+
+function eligibleProviderObservations(providerEvidence = {}, receiptReference = '') {
+  const observations = Array.isArray(providerEvidence.observations) ? providerEvidence.observations : [];
+  if (!receiptReference) return observations;
+  return observations.filter((entry) => String(entry.actionId || '') === receiptReference);
+}
+
+function publicationEvidenceCandidates(parentRecord = null, childRecord = {}) {
+  return [
+    parentRecord?.publishedReference,
+    parentRecord?.publicationEvidence,
+    childRecord?.parentPublishedReference,
+    childRecord?.parentPublicationEvidence
+  ].filter((value) => value && typeof value === 'object');
+}
+
+function publicationEvidenceReceiptReference(evidence = {}, supplied = {}) {
+  return String(evidence.receiptRef || evidence.providerReceiptRef || evidence.hostActionId || evidence.actionId || supplied.receiptRef || supplied.providerReceiptRef || supplied.hostActionId || supplied.actionId || '');
+}
+
+function summarizePublicationEvidence(evidence = {}, supplied = {}) {
+  const identity = evidence.materialIdentity || evidence.material || {};
+  const source = evidence.source || evidence.providerSource || evidence.provider || {};
+  return Object.freeze({
+    target: String(evidence.target || supplied.target || supplied.url || ''),
+    state: String(evidence.state || evidence.resolutionState || supplied.state || supplied.resolutionState || ''),
+    kind: String(evidence.kind || ''),
+    receiptReference: publicationEvidenceReceiptReference(evidence, supplied),
+    source: Object.freeze({ repository: String(source.repository || source.repo || ''), commit: String(source.commit || source.ref || ''), path: normalizePath(source.path || source.repositoryPath || ''), target: String(source.target || source.url || '') }),
+    materialIdentity: Object.freeze({ state: String(identity.state || ''), sha256: String(identity.sha256 || ''), bytes: identity.bytes === undefined ? null : Number(identity.bytes) })
+  });
+}
+
+function summarizeProviderEvidence(locator, observation = {}, file = {}, sha256 = '', bytes = 0) {
+  const source = file.source || {};
+  return Object.freeze({
+    target: locator,
+    state: 'qualified',
+    kind: 'accepted-provider-material',
+    receiptReference: String(observation.actionId || ''),
+    providerId: String(file.providerId || ''),
+    source: Object.freeze({ repository: String(source.repository || ''), commit: String(source.commit || ''), path: normalizePath(source.path || file.path || ''), target: locator }),
+    materialIdentity: Object.freeze({ state: 'qualified', sha256, bytes: Number(bytes) })
+  });
+}
+
+function providerRequirement(locator = '', parentRecord = null, required = true) {
+  const parsed = parseGithubBlobLocator(locator);
+  const markdown = String(parentRecord?.markdown || '');
+  const bytes = markdown ? utf8Bytes(markdown) : new Uint8Array();
+  return Object.freeze({
+    required,
+    mode: 'host-mediated',
+    action: parsed ? 'repositoryRead' : 'sourceRead',
+    target: String(locator || ''),
+    expected: Object.freeze({
+      repository: parsed?.repository || '',
+      commit: parsed?.commit || '',
+      path: parsed?.path || '',
+      materialSha256: markdown ? sha256Hex(bytes) : '',
+      materialBytes: markdown ? bytes.byteLength : 0
+    }),
+    remoteFetchPerformed: false,
+    remoteWriteAuthorized: false
+  });
+}
+
+function declaredPublicationLocatorState(locator = '') {
+  if (isCommitPinnedGithubBlob(locator)) return 'commit-pinned-github-blob';
+  if (/^https:\/\/github\.com\/[^/]+\/[^/]+\/blob\//i.test(locator)) return 'mutable-or-noncanonical-github-blob';
+  if (/^https?:\/\//i.test(locator)) return 'declared-http-locator';
+  return 'unsupported-locator';
+}
+
+function parseGithubBlobLocator(value = '') {
+  const match = String(value || '').match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([0-9a-f]{40})\/(.+)$/i);
+  if (!match) return null;
+  return Object.freeze({ repository: `${match[1]}/${match[2]}`, commit: match[3].toLowerCase(), path: normalizePath(match[4]) });
+}
+
+function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/'); }
+function publicationState(value, reason = '', locator = '', details = {}) { return Object.freeze({ state: value, reason, locator, locatorState: String(details.locatorState || ''), evidenceState: String(details.evidenceState || ''), evidence: details.evidence || null, providerRequirement: details.providerRequirement || null }); }
+function isCommitPinnedGithubBlob(value = '') { return /^https:\/\/github\.com\/[^/]+\/[^/]+\/blob\/[0-9a-f]{40}\//i.test(String(value || '')); }

package/src/tooling/portable/lineage/lineage.search.js

@@ -0,0 +1,301 @@
+import { runAudit } from '../../../audit/audit.run.js';
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+import { LineageResolutionStatus } from '../../../lineage/lineage.model.js';
+import { traverseLoadedLineage } from '../../../lineage/lineage.traverse.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { portableFinding } from '../findings.js';
+import { portableRuntimeValidationContractForSchema } from '../schema/qualifiedLocalRoot.runtime.js';
+
+export const PORTABLE_LINEAGE_SEARCH_SCHEMA_ID = 'tiinex.portable.lineage-search.v1';
+
+export function searchPortableLineage(input = {}, options = {}) {
+  const material = normalizePortableInput(input.materials || input);
+  const query = String(input.query ?? options.query ?? '').trim();
+  const filters = normalizeFilters(input.filters || options.filters || legacyFilterInput(input));
+  const resolved = resolveLineage(material.records, { depth: 'loaded-portable-search' });
+  const scopedIds = resolveScopeIds(material.records, resolved, input, options);
+  const relationIndex = buildRelationIndex(resolved);
+  const audits = needsAudits(filters) ? new Map(material.records.map((record) => {
+    const runtimeProjection = portableRuntimeValidationContractForSchema(record.schemaId || record.currentSchemaId || '');
+    return [record.id, runAudit({ record, markdown: record.markdown, validationContractOverride: runtimeProjection.state === 'qualified' ? runtimeProjection.compiledContract : null })];
+  })) : new Map();
+  const candidates = material.records.filter((record) => !scopedIds || scopedIds.has(record.id));
+  const matches = [];
+  for (const record of candidates) {
+    const node = resolved.nodes.find((item) => item.id === record.id) || {};
+    const audit = audits.get(record.id) || null;
+    const relation = relationIndex.get(record.id) || { root: false, leaf: false, parents: [], children: [] };
+    if (!matchesFilters(record, node, audit, relation, filters)) continue;
+    const score = queryScore(record, node, query, filters.searchFields);
+    if (query && score <= 0) continue;
+    matches.push(buildMatch(record, node, audit, relation, score, query, filters));
+  }
+  matches.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  const limited = matches.slice(filters.offset, filters.offset + filters.limit);
+  const findings = [...material.findings];
+  if (!query && !hasActiveFilters(filters)) findings.push(portableFinding('info', 'portable.lineage-search.unfiltered', 'No query or restrictive filter was supplied; all loaded lineage records are eligible.'));
+  return Object.freeze({
+    schema: PORTABLE_LINEAGE_SEARCH_SCHEMA_ID,
+    boundary: Object.freeze({
+      material: 'loaded-only',
+      remoteFetch: false,
+      inferredEdges: false,
+      fullTextFields: Object.freeze(filters.searchFields)
+    }),
+    query,
+    filters,
+    scope: Object.freeze({
+      mode: String(input.scope || options.scope || (scopedIds ? 'traversal' : 'all-loaded')),
+      startIds: Object.freeze(normalizeList(input.startIds || input.startId || options.startIds || options.startId)),
+      eligibleRecords: candidates.length
+    }),
+    matches: Object.freeze(limited),
+    page: Object.freeze({ offset: filters.offset, limit: filters.limit, returned: limited.length, total: matches.length }),
+    facets: buildFacets(matches),
+    findings: Object.freeze(findings)
+  });
+}
+
+function resolveScopeIds(records, resolved, input, options) {
+  const startIds = normalizeList(input.startIds || input.startId || options.startIds || options.startId);
+  const scope = String(input.scope || options.scope || '').toLowerCase();
+  if (!startIds.length && !['ancestors', 'descendants', 'both', 'traversal'].includes(scope)) return null;
+  if (!startIds.length) return null;
+  const traversal = traverseLoadedLineage(records, {
+    resolvedLineage: resolved,
+    startIds,
+    direction: scope === 'descendants' ? 'descendants' : scope === 'both' ? 'both' : 'ancestors',
+    maxDepth: Number(input.maxDepth ?? options.maxDepth ?? 16)
+  });
+  return new Set((traversal.nodes || []).map((node) => node.id));
+}
+
+const TOPOLOGICAL_PARENT_EDGE_STATUSES = new Set([
+  LineageResolutionStatus.resolved,
+  LineageResolutionStatus.verified,
+  LineageResolutionStatus.probable,
+  LineageResolutionStatus.mismatch
+]);
+
+function buildRelationIndex(resolved = {}) {
+  const map = new Map((resolved.nodes || []).map((node) => [node.id, { root: true, leaf: true, parents: [], children: [] }]));
+  for (const edge of resolved.edges || []) {
+    if (edge.kind !== 'parent' || !TOPOLOGICAL_PARENT_EDGE_STATUSES.has(edge.status) || !edge.from || !edge.to) continue;
+    const parent = map.get(edge.from);
+    const child = map.get(edge.to);
+    if (parent && child) {
+      parent.leaf = false;
+      child.root = false;
+      parent.children.push(edge.to);
+      child.parents.push(edge.from);
+    }
+  }
+  return map;
+}
+
+function matchesFilters(record, node, audit, relation, filters) {
+  if (filters.schemaIds.length && !filters.schemaIds.includes(String(record.schemaId || node.schemaId || ''))) return false;
+  if (filters.parentSchemaIds.length && !filters.parentSchemaIds.includes(String(record.parentSchemaId || node.parentSchemaId || ''))) return false;
+  if (filters.sourceModes.length && !filters.sourceModes.includes(String(record.sourceMode || node.sourceMode || ''))) return false;
+  if (filters.paths.length && !filters.paths.some((prefix) => String(record.path || '').toLowerCase().startsWith(prefix.toLowerCase()))) return false;
+  if (filters.hasIntegrity !== null && Boolean(record.hasIntegrity ?? node.hasIntegrity) !== filters.hasIntegrity) return false;
+  if (filters.hasContinuityContext !== null && Boolean(record.hasContinuityContext ?? node.hasContinuityContext) !== filters.hasContinuityContext) return false;
+  if (filters.relation === 'root' && !relation.root) return false;
+  if (filters.relation === 'leaf' && !relation.leaf) return false;
+  if (filters.relation === 'intermediate' && (relation.root || relation.leaf)) return false;
+  if (filters.findingSeverities.length) {
+    const severities = new Set((audit?.findings || []).map((finding) => String(finding.severity || 'info')));
+    if (!filters.findingSeverities.some((severity) => severities.has(severity))) return false;
+  }
+  if (filters.qualification.length) {
+    const status = auditQualification(audit);
+    if (!filters.qualification.includes(status)) return false;
+  }
+  return true;
+}
+
+function queryScore(record, node, query, fields) {
+  if (!query) return 1;
+  const tokens = tokenize(query);
+  if (!tokens.length) return 1;
+  const values = searchValues(record, node, fields);
+  let score = 0;
+  for (const token of tokens) {
+    let best = 0;
+    for (const entry of values) {
+      if (!entry.value.includes(token)) continue;
+      const exact = entry.value === token ? 3 : entry.value.startsWith(token) ? 2 : 1;
+      best = Math.max(best, exact * entry.weight);
+    }
+    if (!best) return 0;
+    score += best;
+  }
+  return score;
+}
+
+function searchValues(record, node, fields) {
+  const enabled = new Set(fields);
+  const values = [];
+  const add = (field, value, weight) => {
+    if (!enabled.has(field)) return;
+    const normalized = normalizeText(value);
+    if (normalized) values.push({ field, value: normalized, weight });
+  };
+  add('title', record.title || node.title, 8);
+  add('summary', record.summary, 6);
+  add('path', record.path || node.path, 5);
+  add('schema', record.schemaId || node.schemaId, 5);
+  add('body', record.markdown, 2);
+  add('origin', record.origin || node.origin, 3);
+  add('trace', record.trace || node.trace, 3);
+  add('source', [record.sourceMode, record.source?.label, record.source?.path, record.source?.boundary].filter(Boolean).join(' '), 3);
+  return values;
+}
+
+function buildMatch(record, node, audit, relation, score, query, filters) {
+  return Object.freeze({
+    id: record.id,
+    path: record.path || '',
+    title: record.title || node.title || record.id,
+    summary: record.summary || '',
+    schemaId: record.schemaId || node.schemaId || '',
+    parentSchemaId: record.parentSchemaId || node.parentSchemaId || '',
+    sourceMode: record.sourceMode || node.sourceMode || '',
+    relation: Object.freeze({ root: relation.root, leaf: relation.leaf, parents: Object.freeze(relation.parents), children: Object.freeze(relation.children) }),
+    integrity: Boolean(record.hasIntegrity ?? node.hasIntegrity),
+    continuity: Boolean(record.hasContinuityContext ?? node.hasContinuityContext),
+    qualification: audit ? auditQualification(audit) : 'not-evaluated',
+    findingSummary: audit ? summarizeFindings(audit.findings || []) : null,
+    score,
+    snippet: buildSnippet(record, query, filters.snippetChars)
+  });
+}
+
+function auditQualification(audit = null) {
+  if (!audit) return 'not-evaluated';
+  if (audit.resolution?.fallbackUsed) return 'fallback';
+  if ((audit.findings || []).some((finding) => finding.code === 'audit.validator.unavailable')) return 'partial';
+  return 'exact';
+}
+
+function buildSnippet(record, query, maxChars) {
+  const source = String(record.summary || record.markdown || '').replace(/\s+/g, ' ').trim();
+  if (!source) return '';
+  const token = tokenize(query)[0] || '';
+  const lower = source.toLowerCase();
+  const index = token ? lower.indexOf(token) : 0;
+  const start = Math.max(0, index - Math.floor(maxChars / 3));
+  const snippet = source.slice(start, start + maxChars).trim();
+  return `${start > 0 ? '…' : ''}${snippet}${start + maxChars < source.length ? '…' : ''}`;
+}
+
+function buildFacets(matches = []) {
+  return Object.freeze({
+    schemas: countBy(matches, (item) => item.schemaId || 'unknown'),
+    sourceModes: countBy(matches, (item) => item.sourceMode || 'unknown'),
+    relation: Object.freeze({
+      roots: matches.filter((item) => item.relation.root).length,
+      leaves: matches.filter((item) => item.relation.leaf).length,
+      intermediate: matches.filter((item) => !item.relation.root && !item.relation.leaf).length
+    }),
+    qualification: countBy(matches, (item) => item.qualification)
+  });
+}
+
+function countBy(items, keyFn) {
+  const counts = {};
+  for (const item of items) {
+    const key = String(keyFn(item) || 'unknown');
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return Object.freeze(Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b))));
+}
+
+function summarizeFindings(findings = []) {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const finding of findings) counts[finding.severity === 'error' ? 'error' : finding.severity === 'warning' ? 'warning' : 'info'] += 1;
+  return Object.freeze({ ...counts, total: counts.error + counts.warning + counts.info });
+}
+
+function legacyFilterInput(input = {}) {
+  const materialPayloadPresent = Boolean(input.materials || input.markdown || input.files || input.records || input.assets);
+  return Object.freeze({
+    schemaIds: input.schemaIds || input.schemaId,
+    parentSchemaIds: input.parentSchemaIds || input.parentSchemaId,
+    sourceModes: input.sourceModes || (!materialPayloadPresent ? input.sourceMode : undefined),
+    paths: input.paths || input.pathPrefix,
+    relation: input.relation || input.lineageRole,
+    hasIntegrity: input.hasIntegrity,
+    hasContinuityContext: input.hasContinuityContext,
+    findingSeverities: input.findingSeverities || input.findingSeverity,
+    qualification: input.qualification,
+    searchFields: input.searchFields,
+    snippetChars: input.snippetChars,
+    offset: input.offset,
+    limit: input.limit
+  });
+}
+
+function normalizeFilters(raw = {}) {
+  return Object.freeze({
+    schemaIds: Object.freeze(normalizeList(raw.schemaIds || raw.schemaId)),
+    parentSchemaIds: Object.freeze(normalizeList(raw.parentSchemaIds || raw.parentSchemaId)),
+    sourceModes: Object.freeze(normalizeList(raw.sourceModes || raw.sourceMode)),
+    paths: Object.freeze(normalizeList(raw.paths || raw.pathPrefix)),
+    relation: normalizeRelation(raw.relation || raw.lineageRole),
+    hasIntegrity: normalizeBooleanFilter(raw.hasIntegrity),
+    hasContinuityContext: normalizeBooleanFilter(raw.hasContinuityContext),
+    findingSeverities: Object.freeze(normalizeList(raw.findingSeverities || raw.findingSeverity).map((value) => value.toLowerCase())),
+    qualification: Object.freeze(normalizeList(raw.qualification).map((value) => value.toLowerCase())),
+    searchFields: Object.freeze(normalizeSearchFields(raw.searchFields)),
+    snippetChars: normalizeInteger(raw.snippetChars, 280, 80, 2000),
+    offset: normalizeInteger(raw.offset, 0, 0, 100000),
+    limit: normalizeInteger(raw.limit, 50, 1, 500)
+  });
+}
+
+function normalizeSearchFields(value) {
+  const allowed = new Set(['title', 'summary', 'path', 'schema', 'body', 'origin', 'trace', 'source']);
+  const selected = normalizeList(value).filter((field) => allowed.has(field));
+  return selected.length ? selected : ['title', 'summary', 'path', 'schema', 'body', 'origin', 'trace', 'source'];
+}
+
+function normalizeRelation(value = '') {
+  const relation = String(value || '').toLowerCase();
+  return ['root', 'leaf', 'intermediate'].includes(relation) ? relation : '';
+}
+
+function normalizeBooleanFilter(value) {
+  if (value === true || value === false) return value;
+  const normalized = String(value ?? '').toLowerCase();
+  if (['true', 'yes', '1'].includes(normalized)) return true;
+  if (['false', 'no', '0'].includes(normalized)) return false;
+  return null;
+}
+
+function needsAudits(filters) {
+  return filters.findingSeverities.length > 0 || filters.qualification.length > 0;
+}
+
+function hasActiveFilters(filters) {
+  return Boolean(filters.schemaIds.length || filters.parentSchemaIds.length || filters.sourceModes.length || filters.paths.length || filters.relation || filters.hasIntegrity !== null || filters.hasContinuityContext !== null || filters.findingSeverities.length || filters.qualification.length);
+}
+
+function tokenize(value = '') {
+  return normalizeText(value).split(' ').filter(Boolean);
+}
+
+function normalizeText(value = '') {
+  return String(value || '').toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9._:/-]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function normalizeList(value) {
+  const list = Array.isArray(value) ? value : value ? String(value).split(',') : [];
+  return [...new Set(list.map((item) => String(item || '').trim()).filter(Boolean))];
+}
+
+function normalizeInteger(value, fallback, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(number)));
+}