@work-graph/cli 0.2.0

package/vendor/src/blockedOnebaseGoPreflightEval.mjs

@@ -0,0 +1,100 @@
+import { buildSnapshot, parseWorkItems } from './workGraphRuntime.mjs';
+import { buildVerificationSummary } from './verificationLoop.mjs';
+import { executeOnebaseVerificationCommand } from './onebaseWorkerTools.mjs';
+
+export const BLOCKED_ONEBASE_GO_PREFLIGHT_EVAL_SCHEMA = 'workgraph.blocked-onebase-go-preflight.eval.v1';
+
+export const BLOCKED_ONEBASE_GO_BACKLOG = `#Задача_blocked_onebase<[
+Базис:
+  OneBase blocked by missing Go toolchain.
+Вектор:
+  Record blocked evidence instead of failed verify.
+Цель:
+  Optional env gate.
+
+Свидетельства:
+  Blocker evidence: go version CommandNotFoundException; go not found in PATH; blocked evidence recorded.
+
+Метки:
+  atom.profile: work_item
+  work.id: onebase-implement-gross-profit-warehouse-dimension
+  work.title: OneBase gross profit warehouse
+  work.status: blocked
+  work.blocker: go not in PATH
+  trace.status: verified
+]>
+`;
+
+export function evaluateBlockedOnebaseGoPreflightDeterministic(options = {}) {
+  const items = parseWorkItems(options.backlogText ?? BLOCKED_ONEBASE_GO_BACKLOG);
+  const snapshot = buildSnapshot(items);
+  const summary = buildVerificationSummary(snapshot, { items });
+  const onebaseRow = summary.matrix.find((row) => row.id === 'onebase-go-test');
+  const blockedTask = items.find((item) => item.id === 'onebase-implement-gross-profit-warehouse-dimension');
+  const combined = JSON.stringify({ summary, onebaseRow, blockedTask });
+
+  const keywordsOk = ['blocked', 'go version', 'preflight'].every((keyword) => {
+    if (keyword === 'preflight') {
+      return combined.includes('preflightCommand') || combined.toLowerCase().includes('preflight');
+    }
+
+    return combined.toLowerCase().includes(keyword.toLowerCase());
+  });
+
+  return {
+    ok: onebaseRow?.status === 'blocked'
+      && summary.onebaseGate?.status === 'blocked'
+      && blockedTask?.status === 'blocked'
+      && keywordsOk,
+    onebaseRowStatus: onebaseRow?.status ?? null,
+    onebaseGateStatus: summary.onebaseGate?.status ?? null,
+    blockedTaskStatus: blockedTask?.status ?? null,
+    preflightCommand: summary.onebaseGate?.preflightCommand ?? null,
+    keywordsOk,
+  };
+}
+
+export function evaluateOnebaseVerificationCommandGoPreflight(options = {}) {
+  const spawnSyncImpl = options.spawnSyncImpl ?? (() => ({
+    status: 1,
+    stdout: '',
+    stderr: 'go not found in PATH',
+  }));
+
+  const result = executeOnebaseVerificationCommand({
+    policy: { allowShell: true },
+    onebaseRoot: options.onebaseRoot ?? '../onebase',
+    spawnSyncImpl,
+  });
+
+  const combined = JSON.stringify(result);
+  const keywordsOk = ['go version', 'preflight'].every((keyword) => combined.toLowerCase().includes(keyword));
+
+  return {
+    ok: result.ok === false
+      && result.blocked !== true
+      && result.reason === 'go preflight failed'
+      && keywordsOk,
+    result,
+    keywordsOk,
+  };
+}
+
+export async function runBlockedOnebaseGoPreflightEval(options = {}) {
+  const deterministic = evaluateBlockedOnebaseGoPreflightDeterministic(options);
+  const verificationCommand = evaluateOnebaseVerificationCommandGoPreflight(options);
+
+  const ok = deterministic.ok && verificationCommand.ok;
+
+  return {
+    schema: BLOCKED_ONEBASE_GO_PREFLIGHT_EVAL_SCHEMA,
+    ok,
+    failureClass: ok ? null : 'code_failure',
+    reason: ok
+      ? 'OneBase go preflight blocked path verified deterministically (no live LLM required)'
+      : 'blocked-onebase-go-preflight deterministic checks failed',
+    deterministic,
+    verificationCommand,
+    live: null,
+  };
+}

package/vendor/src/bracketIrTraceSignal.mjs

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+
+export const BRACKET_IR_PARSER_ENGINE_VERSION = 'bracket-ir-engine-v1-port-ref';
+
+const BRACKET_PREFIX = /^bracket:\s*/iu;
+
+export function normalizeBracketIrTextForHash(text) {
+  let normalized = String(text ?? '').replace(/\r\n/gu, '\n').replace(/\r/gu, '\n');
+  normalized = normalized.replace(/[ \t\u00a0]+$/gmu, '');
+  return normalized;
+}
+
+export function extractBracketBodyForHash(vectorRaw) {
+  const trimmed = String(vectorRaw ?? '').trimStart();
+  const body = trimmed.replace(BRACKET_PREFIX, '');
+  if (trimmed === body) {
+    return null;
+  }
+
+  return body;
+}
+
+export function computeBracketIrVectorHash(bracketBody, options = {}) {
+  const normalizedBody = normalizeBracketIrTextForHash(bracketBody);
+  const engineVersion = options.engineVersion ?? BRACKET_IR_PARSER_ENGINE_VERSION;
+  const vectorHash = createHash('sha256').update(`${normalizedBody}\0${engineVersion}`, 'utf8').digest('hex');
+
+  return { vectorHash, normalizedBody, engineVersion };
+}
+
+export function extractBracketVectorFromStepText(stepText) {
+  const vectorSection = /(?:^|\n)Вектор:\s*\n([\s\S]*?)(?=\n(?:Цель:|Метки:|критерии_готовности:|Проверки:)|\n#|\s*$)/u.exec(String(stepText ?? ''));
+  if (vectorSection === null) {
+    return null;
+  }
+
+  return extractBracketBodyForHash(vectorSection[1]);
+}
+
+export function buildBracketIrTraceSignal(item, options = {}) {
+  const storedHash = String(item.labels?.['trace.bracket_ir_hash'] ?? '').trim();
+  const stepPath = String(item.labels?.['trace.bracket_ir_step'] ?? item.labels?.['trace.source_step'] ?? '').trim();
+  const stepText = options.stepTextByPath?.[stepPath] ?? options.stepText ?? '';
+  const bracketBody = extractBracketVectorFromStepText(stepText);
+
+  if (bracketBody === null) {
+    return {
+      schema: 'bracket-ir.trace-signal.v1',
+      workId: item.id,
+      stepPath,
+      hasBracketSection: false,
+      storedHash,
+      currentHash: '',
+      drift: false,
+    };
+  }
+
+  const { vectorHash } = computeBracketIrVectorHash(bracketBody, options);
+  const drift = storedHash !== '' && storedHash !== vectorHash;
+
+  return {
+    schema: 'bracket-ir.trace-signal.v1',
+    workId: item.id,
+    stepPath,
+    hasBracketSection: true,
+    storedHash,
+    currentHash: vectorHash,
+    engineVersion: options.engineVersion ?? BRACKET_IR_PARSER_ENGINE_VERSION,
+    drift,
+  };
+}
+
+export function evaluateBracketIrDrift(item, options = {}) {
+  const signal = buildBracketIrTraceSignal(item, options);
+  if (!signal.hasBracketSection || !signal.storedHash) {
+    return { ok: true, signal, diagnostics: [] };
+  }
+
+  if (!signal.drift) {
+    return { ok: true, signal, diagnostics: [] };
+  }
+
+  return {
+    ok: false,
+    signal,
+    diagnostics: [{
+      severity: 'error',
+      code: 'bracket_ir.hash_drift',
+      message: `WorkItem ${item.id} Bracket IR hash drift detected for ${signal.stepPath || 'unknown step'}.`,
+      actionable: 'Re-run compiler round-trip or update trace.bracket_ir_hash after reviewed step edit.',
+    }],
+  };
+}

package/vendor/src/bvcAtomParser.mjs

@@ -0,0 +1,210 @@
+import {
+  detectDialectFromBvcSectionTitle,
+  getDialect,
+  normalizeDialectId,
+  parseBvcFilePragma,
+  REGISTERED_DIALECT_IDS,
+} from './bvcDialectRegistry.mjs';
+
+export const BVC_LINT_E_DIALECT_MIX = 'E_BVC_DIALECT_MIX';
+export const BVC_LINT_E_DIALECT_LANG_MISMATCH = 'E_BVC_DIALECT_LANG_MISMATCH';
+export const BVC_LINT_W_LANG_FALLBACK_EN = 'W_BVC_LANG_FALLBACK_EN';
+
+export const BVC_ATOM_AST_SCHEMA = 'bvc-atom.ast.v1';
+export const BVC_DOCUMENT_AST_SCHEMA = 'bvc-document.ast.v1';
+
+/** @param {string} text */
+export function stripBvcFilePragmaLine(text) {
+  const lines = text.split(/\r?\n/u);
+  if (lines.length === 0) {
+    return text;
+  }
+  if (parseBvcFilePragma(text) !== null) {
+    return lines.slice(1).join('\n');
+  }
+  return text;
+}
+
+/**
+ * @param {string} rawHeader
+ * @returns {{ name: string, headerLang: string | null }}
+ */
+export function parseBvcAtomHeader(rawHeader) {
+  const trimmed = String(rawHeader ?? '').trim();
+  const atIndex = trimmed.lastIndexOf('@');
+  if (atIndex === -1) {
+    return { name: trimmed, headerLang: null };
+  }
+  const name = trimmed.slice(0, atIndex).trim();
+  const langToken = trimmed.slice(atIndex + 1).trim().toLowerCase();
+  if (!REGISTERED_DIALECT_IDS.includes(langToken)) {
+    return { name: trimmed, headerLang: null };
+  }
+  return { name, headerLang: langToken };
+}
+
+/**
+ * @param {string} body
+ * @returns {{ dialects: Set<string>, firstBvcDialect: string | null }}
+ */
+export function scanBvcSectionDialects(body) {
+  /** @type {Set<string>} */
+  const dialects = new Set();
+  let firstBvcDialect = null;
+
+  for (const rawLine of body.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line.endsWith(':')) {
+      continue;
+    }
+    const title = line.slice(0, -1);
+    const detected = detectDialectFromBvcSectionTitle(title);
+    if (detected === null) {
+      continue;
+    }
+    dialects.add(detected);
+    if (firstBvcDialect === null) {
+      firstBvcDialect = detected;
+    }
+  }
+
+  return { dialects, firstBvcDialect };
+}
+
+/**
+ * @param {{
+ *   headerLang?: string | null,
+ *   labelsLang?: string | null,
+ *   filePragmaLang?: string | null,
+ *   autoDetectLang?: string | null,
+ * }} sources
+ */
+export function resolveAtomLang(sources) {
+  const warnings = [];
+  const headerLang = sources.headerLang ? normalizeDialectId(sources.headerLang) : null;
+  const labelsLang = sources.labelsLang ? normalizeDialectId(sources.labelsLang) : null;
+  const filePragmaLang = sources.filePragmaLang ? normalizeDialectId(sources.filePragmaLang) : null;
+  const autoDetectLang = sources.autoDetectLang ? normalizeDialectId(sources.autoDetectLang) : null;
+
+  if (headerLang !== null) {
+    return { lang: headerLang, source: 'atom_header', warnings };
+  }
+  if (labelsLang !== null) {
+    return { lang: labelsLang, source: 'labels.lang', warnings };
+  }
+  if (filePragmaLang !== null) {
+    return { lang: filePragmaLang, source: 'file_pragma', warnings };
+  }
+  if (autoDetectLang !== null) {
+    return { lang: autoDetectLang, source: 'auto_detect', warnings };
+  }
+
+  warnings.push(BVC_LINT_W_LANG_FALLBACK_EN);
+  return { lang: 'en', source: 'fallback_en', warnings };
+}
+
+/**
+ * @param {string} body
+ * @param {string} resolvedLang
+ */
+export function lintBvcAtomDialect(body, resolvedLang) {
+  /** @type {Array<{ code: string, message: string }>} */
+  const lints = [];
+  const { dialects } = scanBvcSectionDialects(body);
+
+  if (dialects.size > 1) {
+    lints.push({
+      code: BVC_LINT_E_DIALECT_MIX,
+      message: `Mixed BVC dialect keys in one atom: ${Array.from(dialects).join(', ')}`,
+    });
+  }
+
+  if (dialects.size === 1) {
+    const [onlyDialect] = dialects;
+    if (onlyDialect !== resolvedLang) {
+      lints.push({
+        code: BVC_LINT_E_DIALECT_LANG_MISMATCH,
+        message: `Resolved lang=${resolvedLang} but BVC keys use dialect ${onlyDialect}`,
+      });
+    }
+  }
+
+  return lints;
+}
+
+/**
+ * @param {import('./stepAtomFormatter.mjs').StepAtomDraftLike} draft
+ * @param {string} lang
+ * @param {Array<{ code: string, message: string }>} lints
+ */
+export function buildBvcAtomAst(draft, lang, lints = []) {
+  return {
+    schema: BVC_ATOM_AST_SCHEMA,
+    name: draft.name,
+    lang,
+    bvc: {
+      basis: [...(draft.basis ?? [])],
+      vector: [...(draft.vector ?? [])],
+      goal: [...(draft.goal ?? [])],
+    },
+    labels: { ...(draft.labels ?? {}) },
+    optional: {
+      checks: draft.checks ? [...draft.checks] : [],
+      evidence: draft.evidence ? [...draft.evidence] : [],
+      analysis: draft.analysis ? [...draft.analysis] : [],
+      decision: draft.decision ? [...draft.decision] : [],
+      uiRefs: draft.uiRefs ? [...draft.uiRefs] : [],
+    },
+    profile: draft.profile ?? draft.labels?.['atom.profile'] ?? '',
+    lints,
+  };
+}
+
+/**
+ * @param {string} text
+ */
+export function parseBvcDocument(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('text must be a string');
+  }
+
+  const fileLang = parseBvcFilePragma(text);
+  const bodyText = stripBvcFilePragmaLine(text);
+
+  return {
+    schema: BVC_DOCUMENT_AST_SCHEMA,
+    fileLang,
+    bodyText,
+  };
+}
+
+/** @param {string} name @param {string} [lang] */
+export function formatBvcAtomHeader(name, lang) {
+  const trimmed = String(name ?? '').trim();
+  if (lang === 'en') {
+    return `#${trimmed}@en<[` ;
+  }
+  return `#${trimmed}<[` ;
+}
+
+/**
+ * Compare normalized BVC content (EN-canonical arrays) for conformance.
+ * @param {ReturnType<typeof buildBvcAtomAst>} left
+ * @param {ReturnType<typeof buildBvcAtomAst>} right
+ */
+export function bvcAtomAstEquivalent(left, right) {
+  return JSON.stringify({
+    bvc: left.bvc,
+    profile: left.profile,
+    labels: left.labels,
+  }) === JSON.stringify({
+    bvc: right.bvc,
+    profile: right.profile,
+    labels: right.labels,
+  });
+}
+
+/** @param {string} lang @param {string} field */
+export function localizedBvcTitle(lang, field) {
+  return getDialect(lang).bvc[field];
+}

package/vendor/src/bvcDialectRegistry.mjs

@@ -0,0 +1,86 @@
+import enDialect from '../packages/bvc-dialects/en.json' with { type: 'json' };
+import ruDialect from '../packages/bvc-dialects/ru.json' with { type: 'json' };
+
+/** @type {Record<string, import('./bvcDialectRegistry.types').BvcDialectV1>} */
+const DIALECTS = {
+  en: enDialect,
+  ru: ruDialect,
+};
+
+export const REGISTERED_DIALECT_IDS = Object.freeze(Object.keys(DIALECTS));
+
+const BVC_FIELDS = ['basis', 'vector', 'goal', 'labels'];
+const OPTIONAL_FIELDS = ['checks', 'evidence', 'analysis', 'decision', 'uiRefs'];
+const ALL_SECTION_FIELDS = [...BVC_FIELDS, ...OPTIONAL_FIELDS];
+
+/** @param {string} [lang] */
+export function normalizeDialectId(lang) {
+  const id = String(lang ?? '').trim().toLowerCase();
+  if (id === '') {
+    return 'ru';
+  }
+  if (!Object.hasOwn(DIALECTS, id)) {
+    throw new Error(`Unknown BVC dialect: ${lang}`);
+  }
+  return id;
+}
+
+/** @param {string} [lang] */
+export function getDialect(lang) {
+  return DIALECTS[normalizeDialectId(lang)];
+}
+
+/** @param {string} [lang] */
+export function getSectionTitle(lang, field) {
+  const dialect = getDialect(lang);
+  if (BVC_FIELDS.includes(field)) {
+    return dialect.bvc[field];
+  }
+  if (OPTIONAL_FIELDS.includes(field)) {
+    return dialect.optional?.[field] ?? DIALECTS.ru.optional[field];
+  }
+  throw new Error(`Unknown BVC section field: ${field}`);
+}
+
+/** @param {string} [lang] */
+export function getFieldSectionsForDialect(lang) {
+  return ALL_SECTION_FIELDS.map((field) => [field, getSectionTitle(lang, field)]);
+}
+
+export function buildSectionTitleToFieldMap() {
+  /** @type {Map<string, string>} */
+  const map = new Map();
+  for (const dialectId of REGISTERED_DIALECT_IDS) {
+    for (const [field, title] of getFieldSectionsForDialect(dialectId)) {
+      map.set(title, field);
+    }
+  }
+  map.set('критерии_готовности', 'checks');
+  return map;
+}
+
+/**
+ * @param {string} title
+ * @returns {'en' | 'ru' | null}
+ */
+export function detectDialectFromBvcSectionTitle(title) {
+  for (const dialectId of REGISTERED_DIALECT_IDS) {
+    const dialect = DIALECTS[dialectId];
+    if (Object.values(dialect.bvc).includes(title)) {
+      return /** @type {'en' | 'ru'} */ (dialectId);
+    }
+  }
+  return null;
+}
+
+const FILE_PRAGMA_PATTERN = /^#!bvc\s+lang=([a-z]{2})\s*$/u;
+
+/** @param {string} text */
+export function parseBvcFilePragma(text) {
+  const firstLine = text.split(/\r?\n/u)[0]?.trim() ?? '';
+  const match = firstLine.match(FILE_PRAGMA_PATTERN);
+  if (!match) {
+    return null;
+  }
+  return normalizeDialectId(match[1]);
+}

package/vendor/src/bvcFileFormat.mjs

@@ -0,0 +1,218 @@
+import { parseBvcDocument } from './bvcAtomParser.mjs';
+import { formatStepAtomDraft, parseStepAtomDrafts } from './stepAtomFormatter.mjs';
+import { extensionFromPath } from './languageAdapters/shared.mjs';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export const BVC_EXTENSION_CANON = '.bvc';
+export const BVC_EXTENSION_LEGACY = '.step';
+export const BVC_READ_EXTENSIONS = Object.freeze([BVC_EXTENSION_CANON, BVC_EXTENSION_LEGACY]);
+export const BVC_LINT_W_LEGACY_EXTENSION = 'W_BVC_LEGACY_STEP_EXTENSION';
+export const BVC_LEGACY_STEP_READ_WARNING = 'W_BVC_LEGACY_STEP_READ';
+
+/** @type {Set<string>} */
+const legacyStepReadWarnings = new Set();
+
+/** Reset once-per-path legacy read warnings (tests only). */
+export function resetLegacyStepReadWarningsForTests() {
+  legacyStepReadWarnings.clear();
+}
+
+/**
+ * @param {string} resolvedPath
+ * @param {{ onLegacyStepRead?: (detail: { resolvedPath: string, message: string }) => void }} [options]
+ */
+export function warnLegacyStepRead(resolvedPath, options = {}) {
+  if (!isLegacyStepPath(resolvedPath)) {
+    return;
+  }
+
+  const key = resolve(resolvedPath);
+  if (legacyStepReadWarnings.has(key)) {
+    return;
+  }
+  legacyStepReadWarnings.add(key);
+
+  const message = `Legacy ${BVC_EXTENSION_LEGACY} read: ${key}; prefer ${BVC_EXTENSION_CANON} for new writes (deprecation until v2).`;
+  if (typeof options.onLegacyStepRead === 'function') {
+    options.onLegacyStepRead({ resolvedPath: key, message });
+    return;
+  }
+  console.warn(`[bvc] ${message}`);
+}
+
+/** @param {string} filePath */
+export function bvcExtensionFromPath(filePath) {
+  return extensionFromPath(filePath);
+}
+
+/** @param {string} filePath */
+export function isBvcReadablePath(filePath) {
+  return BVC_READ_EXTENSIONS.includes(bvcExtensionFromPath(filePath));
+}
+
+/** @param {string} filePath */
+export function isLegacyStepPath(filePath) {
+  return bvcExtensionFromPath(filePath) === BVC_EXTENSION_LEGACY;
+}
+
+/**
+ * @param {string} filePath
+ * @param {{ preferCanon?: boolean }} [options]
+ */
+export function swapBvcExtension(filePath, options = {}) {
+  const preferCanon = options.preferCanon !== false;
+  const ext = bvcExtensionFromPath(filePath);
+  if (preferCanon && ext === BVC_EXTENSION_LEGACY) {
+    return `${filePath.slice(0, -BVC_EXTENSION_LEGACY.length)}${BVC_EXTENSION_CANON}`;
+  }
+  if (!preferCanon && ext === BVC_EXTENSION_CANON) {
+    return `${filePath.slice(0, -BVC_EXTENSION_CANON.length)}${BVC_EXTENSION_LEGACY}`;
+  }
+  return filePath;
+}
+
+/**
+ * Resolve on-disk path for dual-read: try canonical `.bvc` when legacy `.step` is missing (and vice versa).
+ * @param {string} filePath
+ * @param {string} [cwd]
+ */
+export function resolveBvcReadablePath(filePath, cwd = process.cwd()) {
+  const absolute = resolve(cwd, filePath);
+  if (existsSync(absolute)) {
+    return absolute;
+  }
+
+  if (!isBvcReadablePath(absolute)) {
+    return absolute;
+  }
+
+  const preferCanon = isLegacyStepPath(absolute);
+  const canonCandidate = swapBvcExtension(absolute, { preferCanon });
+  if (canonCandidate !== absolute && existsSync(canonCandidate)) {
+    return canonCandidate;
+  }
+
+  const legacyCandidate = swapBvcExtension(absolute, { preferCanon: false });
+  if (legacyCandidate !== absolute && existsSync(legacyCandidate)) {
+    return legacyCandidate;
+  }
+
+  return absolute;
+}
+
+/**
+ * @param {string} filePath
+ * @param {{ cwd?: string, onLegacyStepRead?: (detail: { resolvedPath: string, message: string }) => void }} [options]
+ */
+export async function readBvcTextFile(filePath, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const resolved = resolveBvcReadablePath(filePath, cwd);
+  warnLegacyStepRead(resolved, options);
+  return readFile(resolved, 'utf8');
+}
+
+/** @param {string} filePath */
+export function lintBvcFilePath(filePath) {
+  /** @type {Array<{ code: string, message: string }>} */
+  const lints = [];
+  if (isLegacyStepPath(filePath)) {
+    lints.push({
+      code: BVC_LINT_W_LEGACY_EXTENSION,
+      message: `Legacy extension ${BVC_EXTENSION_LEGACY}; prefer ${BVC_EXTENSION_CANON} for new writes (ADR adr-bvc-format-naming.md).`,
+    });
+  }
+  return lints;
+}
+
+/**
+ * @param {string} content
+ * @param {{ filePath?: string, stripFilePragma?: boolean }} [options]
+ */
+export function parseBvcFileContent(content, options = {}) {
+  const document = parseBvcDocument(content);
+  const atoms = parseStepAtomDrafts(content, {
+    filePragmaLang: document.fileLang,
+    stripFilePragma: options.stripFilePragma !== false,
+  });
+
+  const pathLints = options.filePath ? lintBvcFilePath(options.filePath) : [];
+
+  return {
+    schema: 'bvc-file.parse.v1',
+    filePath: options.filePath ?? null,
+    extension: options.filePath ? bvcExtensionFromPath(options.filePath) : null,
+    document,
+    atoms,
+    pathLints,
+    lints: [
+      ...pathLints,
+      ...atoms.flatMap((entry) => entry.lints ?? []),
+    ],
+  };
+}
+
+/**
+ * @param {ReturnType<typeof parseBvcFileContent>} left
+ * @param {ReturnType<typeof parseBvcFileContent>} right
+ */
+export function bvcParseResultsEquivalent(left, right) {
+  if (left.atoms.length !== right.atoms.length) {
+    return false;
+  }
+  for (let index = 0; index < left.atoms.length; index += 1) {
+    const a = left.atoms[index]?.ast;
+    const b = right.atoms[index]?.ast;
+    if (!a || !b) {
+      return false;
+    }
+    if (JSON.stringify(a.bvc) !== JSON.stringify(b.bvc)) {
+      return false;
+    }
+    if (JSON.stringify(a.labels) !== JSON.stringify(b.labels)) {
+      return false;
+    }
+    if (a.profile !== b.profile) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Canonical formatter: preserve resolved atom.lang and optional file pragma.
+ * @param {string} content
+ * @param {{ filePath?: string, stripFilePragma?: boolean }} [options]
+ */
+export function formatBvcFileContent(content, options = {}) {
+  const parsed = parseBvcFileContent(content, options);
+  const blocks = [];
+
+  if (parsed.document.fileLang) {
+    blocks.push(`#!bvc lang=${parsed.document.fileLang}`);
+  }
+
+  for (const atom of parsed.atoms) {
+    if (atom.errors?.length > 0) {
+      const error = new Error(
+        `Cannot format atom ${atom.draft.name}: ${atom.errors.join('; ')}`,
+      );
+      error.code = 'E_BVC_FORMAT_INVALID_ATOM';
+      throw error;
+    }
+
+    const draft = {
+      ...atom.draft,
+      profile: atom.draft.profile || atom.draft.labels?.['atom.profile'] || '',
+      lang: atom.draft.lang,
+    };
+    blocks.push(formatStepAtomDraft(draft).trimEnd());
+  }
+
+  if (blocks.length === 0) {
+    return parsed.document.fileLang ? `#!bvc lang=${parsed.document.fileLang}\n` : '';
+  }
+
+  return `${blocks.join('\n\n')}\n`;
+}