@work-graph/cli 0.2.0

package/vendor/src/intentGraphGbcSliceBoundary.mjs

@@ -0,0 +1,258 @@
+import { access, constants, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { RELEASE_GATE_ROWS } from './releaseGateMatrix.mjs';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export const INTENT_GRAPH_GBC_SLICE_SCHEMA = 'intent.graph.gbc.slice.boundary.v1';
+
+export const INTENT_GRAPH_GBC_SOURCE_INPUTS = [
+  {
+    id: 'intent-index',
+    path: 'intent/index.bvc',
+    role: 'canonical-index',
+    required: true,
+    format: 'bvc',
+  },
+  {
+    id: 'intent-work-items',
+    path: 'intent/**/**/*.work.bvc',
+    role: 'canonical-task-mirror',
+    required: true,
+    format: 'bvc',
+  },
+  {
+    id: 'backlog-projection',
+    path: 'work/backlog.bvc',
+    role: 'migration-compatibility-projection',
+    required: false,
+    format: 'bvc',
+  },
+];
+
+export const INTENT_GRAPH_GBC_DERIVED_OUTPUTS = [
+  {
+    id: 'intent-graph-slice-gbc',
+    path: '.iohasc/cache/intent-graph-slice.gbc',
+    role: 'optional-derived-binary',
+    required: false,
+    format: 'flatbuffers',
+    status: 'deferred',
+  },
+  {
+    id: 'intent-graph-slice-b64',
+    path: '.iohasc/cache/intent-graph-slice.b64',
+    role: 'optional-transport',
+    required: false,
+    format: 'base64-flatbuffers',
+    status: 'deferred',
+  },
+  {
+    id: 'intent-graph-json-cache',
+    path: '.iohasc/cache/intent-graph.v1.json',
+    role: 'optional-json-cache',
+    required: false,
+    format: 'json',
+    status: 'roadmap',
+  },
+];
+
+export const INTENT_GRAPH_GBC_CONSUMERS = [
+  {
+    id: 'agent-context',
+    title: 'Agent context assembly',
+    requiredWithoutGbc: true,
+    jsonFallback: 'workgraph.snapshot.v1 + intent tree summary',
+    gbcOptional: true,
+  },
+  {
+    id: 'pvrg-graph-augment',
+    title: 'PVRG / trace-link graph augment',
+    requiredWithoutGbc: false,
+    jsonFallback: 'unifiedLinkageProjection.v1 + trace envelope',
+    gbcOptional: true,
+  },
+  {
+    id: 'operator-dashboard',
+    title: 'Operator dashboard / architecture map',
+    requiredWithoutGbc: true,
+    jsonFallback: 'operator-shell.snapshot.v2 + architecture.snapshot.v1',
+    gbcOptional: true,
+  },
+  {
+    id: 'cross-process-worker',
+    title: 'Cross-process worker interchange',
+    requiredWithoutGbc: false,
+    jsonFallback: 'worker-input.v1 JSON payload',
+    gbcOptional: true,
+  },
+];
+
+export const INTENT_GRAPH_GBC_RETURN_TRIGGERS = [
+  'JSON snapshot parse/render or agent context assembly becomes measured bottleneck',
+  'Cross-process worker needs schema-stable binary interchange',
+  'GFS overlay requires mapped binary slices for intent graph',
+  'Dashboard or graph needs zero-copy read path at scale',
+];
+
+const MANDATORY_GATE_IDS = RELEASE_GATE_ROWS.filter((row) => row.blocksRelease).map((row) => row.id);
+
+export function buildIntentGraphGbcSliceBoundary() {
+  const sourceInputs = [...INTENT_GRAPH_GBC_SOURCE_INPUTS].sort((left, right) => compareText(left.id, right.id));
+  const derivedOutputs = [...INTENT_GRAPH_GBC_DERIVED_OUTPUTS].sort((left, right) => compareText(left.id, right.id));
+  const consumers = [...INTENT_GRAPH_GBC_CONSUMERS].sort((left, right) => compareText(left.id, right.id));
+  const returnTriggers = [...INTENT_GRAPH_GBC_RETURN_TRIGGERS];
+
+  const mandatoryConsumersWithoutGbc = consumers.filter((entry) => entry.requiredWithoutGbc);
+  const optionalDerivedOutputs = derivedOutputs.filter((entry) => !entry.required);
+
+  return {
+    schema: INTENT_GRAPH_GBC_SLICE_SCHEMA,
+    policy: {
+      canonicalStore: 'intent-tree-step',
+      interchangeFirst: 'json-snapshot-v1',
+      gbcStatus: 'deferred-optional-derived',
+      donorReference: '../project/docs/adr-iohasc-gbc-gfs-slice-consumer-matrix.md',
+      relatedProtocols: [
+        'gbc-gvm-zig-deferral-boundary',
+        'flatbuffers-gbc-slice-evaluation',
+        'intent-graph-gbc-slice-boundary-v1',
+      ],
+    },
+    sourceInputs,
+    derivedOutputs,
+    consumers,
+    returnTriggers,
+    mvpIndependence: {
+      blocksMandatoryGate: false,
+      mandatoryGateIds: [...MANDATORY_GATE_IDS].sort(compareText),
+      mandatoryConsumersCoveredByJson: mandatoryConsumersWithoutGbc.every((entry) => Boolean(entry.jsonFallback)),
+      optionalDerivedOutputCount: optionalDerivedOutputs.length,
+    },
+  };
+}
+
+export function evaluateIntentGraphGbcMvpIndependence(boundary = buildIntentGraphGbcSliceBoundary()) {
+  const gbcRequiredOutputs = boundary.derivedOutputs.filter((entry) => entry.required);
+  const blockingConsumers = boundary.consumers.filter((entry) => !entry.requiredWithoutGbc && !entry.gbcOptional);
+
+  return {
+    schema: 'intent.graph.gbc.slice.mvp-independence.v1',
+    ok: boundary.mvpIndependence.blocksMandatoryGate === false
+      && gbcRequiredOutputs.length === 0
+      && blockingConsumers.length === 0
+      && boundary.mvpIndependence.mandatoryConsumersCoveredByJson === true,
+    gbcRequiredOutputCount: gbcRequiredOutputs.length,
+    blockingConsumerCount: blockingConsumers.length,
+  };
+}
+
+export const INTENT_GRAPH_GBC_PILOT_SCHEMA = 'intent.graph.gbc.slice.pilot.v1';
+
+export const DONOR_GBC_MODULE_SLICE_CANDIDATES = [
+  {
+    id: 'module-registry-json',
+    relativePath: '.iohasc/cache/iohasc-gbc-module-registry.json',
+    format: 'json',
+  },
+  {
+    id: 'module-object-slice-gbc',
+    relativePath: '.iohasc/cache/module-object-slice.gbc',
+    format: 'flatbuffers',
+  },
+  {
+    id: 'step-file-slice-b64',
+    relativePath: '.iohasc/cache/step-file-slice.b64',
+    format: 'base64-flatbuffers',
+  },
+];
+
+export function resolveDonorProjectRoot(options = {}) {
+  const env = options.env ?? process.env;
+  const raw = options.donorRoot ?? env.WORKGRAPH_IOHASC_DONOR_ROOT ?? '../project';
+  return resolve(options.cwd ?? process.cwd(), raw);
+}
+
+export async function probeDonorGbcModuleSlice(options = {}) {
+  const donorRoot = options.donorRoot
+    ? resolve(options.cwd ?? process.cwd(), options.donorRoot)
+    : resolveDonorProjectRoot(options);
+  const candidates = [];
+
+  for (const candidate of DONOR_GBC_MODULE_SLICE_CANDIDATES) {
+    const absolutePath = resolve(donorRoot, candidate.relativePath);
+    let exists = false;
+    try {
+      await access(absolutePath, constants.R_OK);
+      exists = true;
+    } catch {
+      exists = false;
+    }
+
+    candidates.push({
+      ...candidate,
+      absolutePath,
+      exists,
+    });
+  }
+
+  const foundCount = candidates.filter((entry) => entry.exists).length;
+
+  return {
+    donorRoot,
+    candidates,
+    foundCount,
+  };
+}
+
+async function summarizeModuleRegistryJson(absolutePath) {
+  try {
+    const text = await readFile(absolutePath, 'utf8');
+    const parsed = JSON.parse(text);
+    return {
+      schemaVersion: parsed.schema_version ?? parsed.schemaVersion ?? null,
+      moduleCount: Array.isArray(parsed.modules) ? parsed.modules.length : 0,
+    };
+  } catch (error) {
+    return {
+      parseError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function buildIntentGraphGbcSlicePilotReport(options = {}) {
+  const boundary = buildIntentGraphGbcSliceBoundary();
+  const cwd = options.cwd ?? process.cwd();
+  let probe = await probeDonorGbcModuleSlice({ ...options, cwd });
+  let source = 'donor';
+
+  if (probe.foundCount === 0 && options.sampleRoot) {
+    probe = await probeDonorGbcModuleSlice({
+      ...options,
+      cwd,
+      donorRoot: options.sampleRoot,
+    });
+    source = probe.foundCount > 0 ? 'sample-fixture' : 'skip';
+  } else if (probe.foundCount === 0) {
+    source = 'skip';
+  }
+
+  const registryCandidate = probe.candidates.find(
+    (entry) => entry.id === 'module-registry-json' && entry.exists,
+  );
+  const moduleRegistrySummary = registryCandidate
+    ? await summarizeModuleRegistryJson(registryCandidate.absolutePath)
+    : null;
+
+  return {
+    schema: INTENT_GRAPH_GBC_PILOT_SCHEMA,
+    status: source === 'skip' ? 'skip' : (source === 'sample-fixture' ? 'sample' : 'donor'),
+    source,
+    boundarySchema: boundary.schema,
+    mvpIndependence: evaluateIntentGraphGbcMvpIndependence(boundary),
+    probe,
+    moduleRegistrySummary,
+    blocksMandatoryGate: false,
+  };
+}

package/vendor/src/intentGraphProjection.mjs

@@ -0,0 +1,208 @@
+import { attachDerivedWorkItemHierarchy, readWorkItemParentId } from './workItemHierarchy.mjs';
+import {
+  attachDerivedIntentNodeChildren,
+  readIntentNodeLink,
+} from './intentNodeRuntime.mjs';
+
+export const INTENT_GRAPH_PROJECTION_SCHEMA = 'workgraph.intent-graph.projection.v1';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+const DONE_STATUSES = new Set(['done', 'verified']);
+
+function summarizeIntentNode(node) {
+  return {
+    id: node.id,
+    nodeKind: node.nodeKind,
+    parentId: node.parentId,
+    title: node.title,
+    selected: node.selected === true,
+    childIds: [...(node.childIds ?? [])],
+    links: { ...(node.links ?? {}) },
+  };
+}
+
+function summarizeWorkItemBranch(item, itemsById) {
+  const enriched = itemsById.get(item.id) ?? item;
+  const childIds = enriched.childIds ?? [];
+  const doneChildCount = childIds.filter((childId) => {
+    const child = itemsById.get(childId);
+    return child && DONE_STATUSES.has(child.status);
+  }).length;
+
+  return {
+    id: item.id,
+    title: item.title ?? item.id,
+    status: item.status ?? '',
+    parentId: readWorkItemParentId(item),
+    childIds,
+    doneChildCount,
+    childCount: childIds.length,
+    intentQuestionId: String(item.labels?.['intent.question_id'] ?? '').trim(),
+    intentOptionId: String(item.labels?.['intent.option_id'] ?? '').trim(),
+    intentDecisionId: String(item.labels?.['intent.decision_id'] ?? '').trim(),
+  };
+}
+
+export function buildIntentGraphLinks(nodes) {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const links = [];
+
+  for (const node of nodes) {
+    if (node.parentId !== '' && nodeById.has(node.parentId)) {
+      const parent = nodeById.get(node.parentId);
+      let relation = 'child_of';
+      if (parent.nodeKind === 'question' && node.nodeKind === 'option') {
+        relation = 'offers_option';
+      } else if (parent.nodeKind === 'question' && node.nodeKind === 'decision') {
+        relation = 'analyzes';
+      } else if (node.nodeKind === 'work_ref') {
+        relation = 'creates_work';
+      }
+
+      links.push({
+        id: `intent:${parent.id}:${relation}:${node.id}`,
+        from: { kind: 'intent_node', id: parent.id },
+        to: { kind: 'intent_node', id: node.id },
+        relation,
+      });
+    }
+
+    const analyticsRef = readIntentNodeLink(node, 'analytics_ref');
+    if (analyticsRef !== '') {
+      links.push({
+        id: `intent:${node.id}:analyzes:${analyticsRef}`,
+        from: { kind: 'intent_node', id: node.id },
+        to: { kind: 'analytics_record', id: analyticsRef },
+        relation: 'analyzes',
+      });
+    }
+
+    const optionId = readIntentNodeLink(node, 'option_id');
+    if (node.nodeKind === 'decision' && optionId !== '') {
+      links.push({
+        id: `intent:${node.id}:selects:${optionId}`,
+        from: { kind: 'intent_node', id: node.id },
+        to: { kind: 'intent_node', id: optionId },
+        relation: 'selects',
+      });
+    }
+
+    const workId = readIntentNodeLink(node, 'work_id');
+    if (node.nodeKind === 'work_ref' && workId !== '') {
+      links.push({
+        id: `intent:${node.id}:creates_work:${workId}`,
+        from: { kind: 'intent_node', id: node.id },
+        to: { kind: 'work', id: workId },
+        relation: 'creates_work',
+      });
+    }
+  }
+
+  return links.sort((left, right) => compareText(left.id, right.id));
+}
+
+export function buildIntentGraphProjection(intentNodes, workItems = [], options = {}) {
+  const nodes = attachDerivedIntentNodeChildren(intentNodes);
+  const enrichedWorkItems = attachDerivedWorkItemHierarchy(workItems);
+  const itemsById = new Map(enrichedWorkItems.map((item) => [item.id, item]));
+
+  return {
+    schema: INTENT_GRAPH_PROJECTION_SCHEMA,
+    readOnly: true,
+    source: options.source ?? 'intent-tree',
+    nodeCount: nodes.length,
+    linkCount: 0,
+    nodes: nodes.map(summarizeIntentNode),
+    links: buildIntentGraphLinks(nodes),
+    workItems: enrichedWorkItems.map((item) => summarizeWorkItemBranch(item, itemsById)),
+  };
+}
+
+export function resolveIntentBranchForAnalyticsRecord(record, projection) {
+  const analyticsRef = String(record?.id ?? '').trim();
+  if (analyticsRef === '' || !projection) {
+    return null;
+  }
+
+  const nodes = projection.nodes ?? [];
+  const question = nodes.find((node) =>
+    node.nodeKind === 'question'
+    && (readIntentNodeLink(node, 'analytics_ref') === analyticsRef
+      || node.links?.analytics_ref === analyticsRef),
+  ) ?? nodes.find((node) => node.nodeKind === 'question' && node.childIds?.length > 0
+    && nodes.some((child) => child.parentId === node.id && readIntentNodeLink(child, 'analytics_ref') === analyticsRef));
+
+  if (!question) {
+    const fallbackQuestion = nodes.find((node) =>
+      node.nodeKind === 'question'
+      && String(node.id).includes(analyticsRef.replace(/^analytics:/u, '')),
+    );
+    if (!fallbackQuestion) {
+      return null;
+    }
+    return buildBranchFromQuestion(fallbackQuestion, nodes, projection.workItems ?? []);
+  }
+
+  return buildBranchFromQuestion(question, nodes, projection.workItems ?? []);
+}
+
+function buildBranchFromQuestion(question, nodes, workItems) {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const decisions = nodes.filter((node) => node.nodeKind === 'decision');
+  const selectedDecision = decisions.find((node) => node.selected === true)
+    ?? decisions.find((node) => readIntentNodeLink(node, 'analytics_ref') !== '')
+    ?? null;
+  const selectedOptionId = selectedDecision
+    ? readIntentNodeLink(selectedDecision, 'option_id')
+    : '';
+
+  const options = (question.childIds ?? [])
+    .map((childId) => nodeById.get(childId))
+    .filter((node) => node?.nodeKind === 'option')
+    .map((node) => ({
+      ...summarizeIntentNode(node),
+      selected: node.selected === true || node.id === selectedOptionId,
+    }));
+
+  const decisionId = selectedDecision?.id ?? '';
+  const branchWorkItems = workItems.filter((item) =>
+    item.intentDecisionId === decisionId
+    || (decisionId !== '' && item.intentQuestionId === question.id),
+  );
+
+  const relatedIntentNodes = nodes.filter((node) =>
+    node.id === question.id
+    || node.parentId === question.id
+    || (selectedDecision && (node.id === selectedDecision.id || node.parentId === selectedDecision.id)),
+  ).map(summarizeIntentNode);
+
+  return {
+    question: summarizeIntentNode(question),
+    options,
+    selectedDecision: selectedDecision ? summarizeIntentNode(selectedDecision) : null,
+    relatedIntentNodes,
+    branchWorkItems,
+  };
+}
+
+export function attachIntentGraphToAnalyticsRecords(records, intentGraph) {
+  if (!Array.isArray(records)) {
+    throw new TypeError('records must be an array');
+  }
+
+  return records.map((record) => {
+    const branch = resolveIntentBranchForAnalyticsRecord(record, intentGraph);
+    if (!branch) {
+      return record;
+    }
+
+    return {
+      ...record,
+      intentGraph: branch,
+      relatedIntentNodes: branch.relatedIntentNodes,
+      intentQuestion: branch.question,
+      intentOptions: branch.options,
+      selectedDecision: branch.selectedDecision,
+    };
+  });
+}

package/vendor/src/intentHierarchy.mjs

@@ -0,0 +1,241 @@
+import { workItemPathInFolder } from './bvcNewWritePolicy.mjs';
+
+export const INTENT_HIERARCHY_SCHEMA = 'intent.hierarchy.snapshot.v1';
+
+export const INTENT_LAYERS = ['system', 'ui', 'domain', 'research', 'memory', 'plans'];
+
+export const INTENT_FEATURES = {
+  runtime: 'runtime',
+  storage: 'storage',
+  dashboard: 'dashboard',
+  onebase: 'onebase',
+  marketplace: 'marketplace',
+  pvrg: 'pvrg',
+  memory: 'memory',
+  plans: 'plans',
+};
+
+const DOMAIN_LABELS = {
+  'system/runtime': 'Системный runtime',
+  'system/storage': 'Системное хранилище',
+  'ui/dashboard': 'UI и dashboard',
+  'domain/onebase': 'OneBase',
+  'domain/marketplace': 'Marketplace',
+  'research/pvrg': 'PVRG и retrieval',
+  'memory/work': 'Project Memory',
+  'plans/work': 'Планы',
+};
+
+export function classifyIntentFolder(item) {
+  const searchable = [
+    item.id,
+    item.title,
+    item.department,
+    item.ownerRole,
+    item.nextAction,
+    ...item.targetFiles,
+  ]
+    .join(' ')
+    .toLowerCase();
+
+  if (item.department === 'domain-marketplace' || searchable.includes('intent/domains/marketplace') || /\bmarketplace\b/u.test(searchable)) {
+    return 'intent/domains/marketplace/work';
+  }
+
+  if (searchable.includes('onebase') || searchable.includes('../onebase')) {
+    return 'intent/domains/onebase/work';
+  }
+
+  if (item.department === 'frontend-ui' || /\b(ui|dashboard|board|graph-viewer|atom-inspector)\b/u.test(searchable)) {
+    return 'intent/ui/dashboard/work';
+  }
+
+  if (searchable.includes('memory')) {
+    return 'intent/memory/work';
+  }
+
+  if (searchable.includes('pvrg') || searchable.includes('rag') || searchable.includes('retrieval')) {
+    return 'intent/research/pvrg/work';
+  }
+
+  if (
+    item.department === 'devops-runtime' ||
+    searchable.includes('storage') ||
+    searchable.includes('serialization') ||
+    searchable.includes('sqlite') ||
+    searchable.includes('gbc') ||
+    searchable.includes('flatbuffers') ||
+    searchable.includes('intent tree') ||
+    searchable.includes('intent hierarchy')
+  ) {
+    return 'intent/system/storage/work';
+  }
+
+  return 'intent/system/runtime/work';
+}
+
+export function classifyIntentNode(item) {
+  const folder = classifyIntentFolder(item);
+  const segments = folder.split('/');
+  const layer = segments[1] === 'domains' ? 'domain' : segments[1];
+  const feature = segments[2] ?? 'runtime';
+  const domain = `${layer}/${feature}`;
+  const path = workItemPathInFolder(folder, item.id, { preferCanon: true });
+
+  return {
+    workId: item.id,
+    title: item.title,
+    layer,
+    feature,
+    domain,
+    domainLabel: DOMAIN_LABELS[domain] ?? domain,
+    folder,
+    path,
+    projectedLabels: {
+      'intent.domain': layer,
+      'intent.feature': feature,
+      'intent.path': path,
+    },
+  };
+}
+
+export function toIntentPath(item) {
+  return classifyIntentNode(item).path;
+}
+
+export function buildIntentHierarchySnapshot(entries) {
+  const nodes = entries.map((entry) => {
+    const item = entry.item ?? entry;
+    return classifyIntentNode(item);
+  });
+
+  const domains = new Map();
+  for (const node of nodes) {
+    const bucket = domains.get(node.domain) ?? {
+      id: node.domain,
+      label: node.domainLabel,
+      layer: node.layer,
+      feature: node.feature,
+      count: 0,
+      workIds: [],
+    };
+
+    bucket.count += 1;
+    bucket.workIds.push(node.workId);
+    domains.set(node.domain, bucket);
+  }
+
+  return {
+    schema: INTENT_HIERARCHY_SCHEMA,
+    count: nodes.length,
+    domains: [...domains.values()]
+      .map((domain) => ({
+        ...domain,
+        workIds: [...domain.workIds].sort(compareText),
+      }))
+      .sort((left, right) => compareText(left.id, right.id)),
+    nodes: nodes.sort((left, right) => compareText(left.workId, right.workId)),
+  };
+}
+
+export function resolveIntentPathFromIndex(indexText, workId) {
+  if (typeof indexText !== 'string' || typeof workId !== 'string' || workId.trim() === '') {
+    return null;
+  }
+
+  const pattern = new RegExp(`^\\s*-\\s*${escapeRegExp(workId)}:\\s*(\\S+)\\s*$`, 'mu');
+  const match = indexText.match(pattern);
+  return match?.[1] ?? null;
+}
+
+export function buildCatalogPassportAlignment(entries, options = {}) {
+  const catalogSource = options.catalogIndexPath ?? '../project/.iohasc/catalog-index.v1.json';
+  const indexByWorkId = new Map((options.indexEntries ?? []).map((entry) => [entry.id, entry.path]));
+  const nodes = entries.map((entry) => classifyIntentNode(entry.item ?? entry));
+
+  return {
+    schema: 'catalog-passport.intent-alignment.v1',
+    catalogSource,
+    passportField: 'stepGuid | stepTitle | catalog.packageId',
+    mappings: nodes.map((node) => {
+      const indexedPath = indexByWorkId.get(node.workId) ?? null;
+      const intentPath = indexedPath ?? node.path;
+      return {
+        workId: node.workId,
+        intentPath,
+        projectedIntentPath: indexedPath && indexedPath !== node.path ? node.path : null,
+        intentDomain: node.domain,
+        passportLookup: `catalog-index -> stepTitle/work.id match -> ${node.workId}`,
+        traceRefs: [`trace.artifact_refs: ${intentPath}`, `trace.links: work:${node.workId}`],
+      };
+    }),
+    rules: [
+      'catalog-index остаётся derived/read model из старого ioHasC',
+      'canonical identity для rebuild — work.id + intent.path из intent/index.bvc',
+      'passport section в .bvc atom сопоставляется через stepTitle/guid, не через file path alone',
+      'projectedIntentPath — heuristic drift hint only; index path wins for validation',
+    ],
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildCatalogPassportAlignment>} alignment
+ * @param {{ cwd?: string, indexEntries?: Array<{ id: string, path: string }> }} [options]
+ */
+export async function validateCatalogPassportIntentAlignment(alignment, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const { access } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const errors = [];
+
+  if (!alignment?.mappings?.length) {
+    errors.push('alignment mappings are empty');
+  }
+
+  const indexEntries = options.indexEntries ?? [];
+  const indexByWorkId = new Map(indexEntries.map((entry) => [entry.id, entry.path]));
+
+  for (const row of alignment.mappings ?? []) {
+    if (!row.workId || !row.intentPath) {
+      errors.push(`mapping missing workId or intentPath: ${JSON.stringify(row)}`);
+      continue;
+    }
+
+    const indexedPath = indexByWorkId.get(row.workId);
+    const canonicalPath = indexedPath ?? row.intentPath;
+    if (indexedPath && row.projectedIntentPath && indexedPath.replace(/\\/g, '/') !== row.projectedIntentPath.replace(/\\/g, '/')) {
+      // Drift between index manifest and classifyIntentFolder heuristic — index wins; not a gate failure.
+    }
+
+    try {
+      await access(join(cwd, canonicalPath));
+    } catch {
+      errors.push(`intent file missing for ${row.workId}: ${canonicalPath}`);
+    }
+
+    if (!Array.isArray(row.traceRefs) || row.traceRefs.length < 1) {
+      errors.push(`trace refs missing for ${row.workId}`);
+    }
+  }
+
+  return {
+    schema: 'catalog-passport.intent-alignment.validation.v1',
+    ok: errors.length === 0,
+    mappingCount: alignment?.mappings?.length ?? 0,
+    errors,
+  };
+}
+
+export async function buildAndValidateCatalogPassportAlignment(entries, options = {}) {
+  const alignment = buildCatalogPassportAlignment(entries, options);
+  const validation = await validateCatalogPassportIntentAlignment(alignment, options);
+  return { alignment, validation };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+function compareText(left, right) {
+  return left.localeCompare(right, 'en', { sensitivity: 'variant' });
+}