@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/forge/bindings.js

@@ -0,0 +1,238 @@
+// Binding index for Forge canonicalization: one entry per Identifier node in a parsed file, saying
+// whether it declares or references a binding, which binding (an opaque per-file id, never hashed) and
+// where that binding comes from: 'import' (module binding), 'global' (no binding in the file),
+// 'local' (declared somewhere in the file) or 'name' (a property name or key, not a binding at all).
+// describeIdentifier is exported so a shared audit traversal can fill the same index in its own pass.
+// Every describer reads a site { node, parent, grandparent, scope }: createBindingVisitors builds one
+// from each NodePath of a Babel traverse (the audit's merged pass), and fillBindingIndex from a plain
+// walk over the scopes Babel crawled (binding-walk.js, #5911), so both fill the same index.
+// An import entry also carries importRef '<source>#<imported>' (default, * or the exported name), so
+// `get` from 'lodash' and `get` from './api' never share a label or an anchor. A relative source is
+// resolved against the file's directory when filePath is known, and a `node:` prefix is dropped for
+// builtins that also exist without it, so the same module reads the same from every file. Only the
+// .js/.jsx/.ts/.tsx family is dropped (a TS import of './a.js' means a.ts); .mjs, .cjs, .vue and the
+// rest are distinct files and keep their extension (#2586).
+// The index also holds two non-Identifier kinds of entry (#2586): a JSX component name (`<Foo>`, the
+// root of `<foo.Bar>`) resolved like any reference, and the string source of a dynamic import() or a
+// global require(), as an import entry with importRef '<source>#*'.
+import { builtinModules } from 'node:module';
+import path from 'node:path';
+import { lazyTypes, traverse } from '../babel-lazy.js';
+import { walkBindingSites } from './binding-walk.js';
+
+const NAME_ENTRY = Object.freeze({ origin: 'name', bindingId: null, isDecl: false, importRef: null });
+const INTERCHANGEABLE_EXTENSION = /\.(js|jsx|ts|tsx)$/;
+const UNPREFIXED_BUILTINS = new Set(builtinModules.filter((name) => !name.startsWith('node:')));
+const JSX_NAME_PARENTS = new Set(['JSXOpeningElement', 'JSXClosingElement']);
+const INTRINSIC_JSX_NAME = /^[a-z]|-/;
+const IMPORTED_NAME = {
+  ImportDefaultSpecifier: () => 'default',
+  ImportNamespaceSpecifier: () => '*',
+  ImportSpecifier: (specifier) => specifier.imported.name ?? specifier.imported.value
+};
+const importRefCache = new WeakMap();
+const ALWAYS_INITIALIZED = new Set(['var', 'param', 'hoisted']);
+const LEXICAL_KINDS = new Set(['let', 'const']);
+const RELATIVE_PATH = /^\.\.?\//;
+const MODULE_SOURCE_PARENTS = new Set(['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration']);
+
+/** Module identity of an import source as seen from filePath (null: unknown file, kept verbatim). */
+export const normalizeImportSource = (source, filePath = null) => {
+  const unprefixed = source.replace(/^node:/, '');
+  const isSharedBuiltin = source.startsWith('node:') && UNPREFIXED_BUILTINS.has(unprefixed);
+  const bare = isSharedBuiltin ? unprefixed : source;
+  const isResolvable = bare.startsWith('.') && Boolean(filePath);
+  if (!isResolvable) return bare;
+  return path.posix.join(path.posix.dirname(filePath), bare).replace(INTERCHANGEABLE_EXTENSION, '');
+};
+
+const computeImportRef = (binding, filePath) => {
+  const specifier = binding.path.node;
+  const declaration = binding.path.parent;
+  const isImportDeclaration = declaration?.type === 'ImportDeclaration';
+  if (!isImportDeclaration) return null;
+  const imported = IMPORTED_NAME[specifier.type]?.(specifier) ?? specifier.local?.name ?? '';
+  return `${normalizeImportSource(declaration.source.value, filePath)}#${imported}`;
+};
+
+const importRefOf = (binding, filePath) => {
+  const isCached = importRefCache.has(binding);
+  if (isCached) return importRefCache.get(binding);
+  const ref = computeImportRef(binding, filePath);
+  importRefCache.set(binding, ref);
+  return ref;
+};
+
+const originOf = (binding) => {
+  if (!binding) return 'global';
+  return binding.kind === 'module' ? 'import' : 'local';
+};
+
+const idFor = (binding, ids) => {
+  if (!binding) return null;
+  const isKnown = ids.has(binding);
+  if (isKnown) return ids.get(binding);
+  const next = ids.size + 1;
+  ids.set(binding, next);
+  return next;
+};
+
+/**
+ * True when a read of the binding here can never hit its TDZ (#2594): a var, param or function binding,
+ * or a let/const/class declared earlier in the same function, outside a switch case (a case can be
+ * jumped over). Imports, class-expression names and reads from a nested function are never certain.
+ */
+const isInitializedAt = (binding, site) => {
+  const kind = binding?.kind;
+  const isAlwaysInitialized = ALWAYS_INITIALIZED.has(kind);
+  if (isAlwaysInitialized) return true;
+  const isLexical = LEXICAL_KINDS.has(kind);
+  if (!isLexical) return false;
+  const declaration = binding.path;
+  const end = declaration.node?.end;
+  const endsBefore = typeof end === 'number' && typeof site.node.start === 'number' && end <= site.node.start;
+  const isSameFunction = binding.scope.getFunctionParent() === site.scope.getFunctionParent();
+  const statement = declaration.isVariableDeclarator() ? declaration.parentPath : declaration;
+  const isInCase = Boolean(statement?.parentPath?.isSwitchCase());
+  return endsBefore && isSameFunction && !isInCase;
+};
+
+let babelTests = null;
+const identifierTests = () => {
+  babelTests = babelTests ?? { isReferenced: lazyTypes.isReferenced, isBinding: lazyTypes.isBinding };
+  return babelTests;
+};
+
+/** The site of a NodePath: what every describer reads (grandparent as NodePath#isReferencedIdentifier reads it). */
+export const siteOfPath = (nodePath) => ({ node: nodePath.node, parent: nodePath.parent, grandparent: nodePath.parentPath?.parent, scope: nodePath.scope });
+
+/**
+ * Describes one Identifier site ({ node, parent, grandparent, scope }, see siteOfPath). `ids` maps
+ * Babel binding objects to small per-file integers; filePath (project-relative) resolves relative
+ * import sources. isInitialized (references only) says the read cannot throw a TDZ ReferenceError
+ * (alias inlining relies on it). isRef and isDecl are t.isReferenced and t.isBinding, which is what
+ * NodePath#isReferencedIdentifier and #isBindingIdentifier compute for an Identifier.
+ */
+export const describeIdentifier = (site, ids, filePath = null) => {
+  const { node, parent, grandparent } = site;
+  const { isReferenced, isBinding } = identifierTests();
+  // Babel reports some references (the operand of `!`) as binding identifiers too: a reference wins.
+  const isRef = isReferenced(node, parent, grandparent);
+  const isDecl = !isRef && isBinding(node, parent, grandparent);
+  const isNameOnly = !isDecl && !isRef;
+  if (isNameOnly) return NAME_ENTRY;
+  const binding = site.scope.getBinding(node.name);
+  const origin = originOf(binding);
+  const importRef = origin === 'import' ? importRefOf(binding, filePath) : null;
+  const isInitialized = isRef && isInitializedAt(binding, site);
+  return { origin, bindingId: idFor(binding, ids), isDecl, importRef, isInitialized };
+};
+
+/** Entry for a JSX element name that names a value (component or member root), else null. */
+const describeJsxName = (site, ids, filePath) => {
+  const { node, parent } = site;
+  const isElementName = JSX_NAME_PARENTS.has(parent.type) && parent.name === node;
+  const isComponentName = isElementName && !INTRINSIC_JSX_NAME.test(node.name);
+  const isMemberRoot = parent.type === 'JSXMemberExpression' && parent.object === node;
+  const isReference = isComponentName || isMemberRoot;
+  if (!isReference) return null;
+  const binding = site.scope.getBinding(node.name);
+  const origin = originOf(binding);
+  const importRef = origin === 'import' ? importRefOf(binding, filePath) : null;
+  return { origin, bindingId: idFor(binding, ids), isDecl: false, importRef };
+};
+
+/** The string source of import('x') or a global require('x'), else null. */
+const dynamicSourceOf = (site) => {
+  const { node } = site;
+  const callee = node.callee;
+  const isImportCall = callee?.type === 'Import';
+  const isRequire = callee?.type === 'Identifier' && callee.name === 'require' && !site.scope.getBinding('require');
+  const source = node.type === 'ImportExpression' ? node.source : node.arguments?.[0];
+  const isCall = isImportCall || isRequire || node.type === 'ImportExpression';
+  const isStatic = source?.type === 'StringLiteral';
+  return isCall && isStatic ? source : null;
+};
+
+const indexDynamicSource = (site, index, filePath) => {
+  const source = dynamicSourceOf(site);
+  if (!source) return;
+  const importRef = `${normalizeImportSource(source.value, filePath)}#*`;
+  index.set(source, { origin: 'import', bindingId: null, isDecl: false, importRef });
+};
+
+/**
+ * Any './' or '../' string (or expression-free template) is a file-relative path anchor (#2594):
+ * createRequire's require, require.resolve, import.meta.resolve/glob, new URL(rel, import.meta.url) and
+ * vi.mock all resolve it against the file, so the same text in two directories names two files.
+ * Static import/export sources are left to their bindings.
+ */
+const indexRelativeString = (site, value, index, filePath) => {
+  const isRelative = Boolean(filePath) && typeof value === 'string' && RELATIVE_PATH.test(value);
+  const isModuleSource = MODULE_SOURCE_PARENTS.has(site.parent?.type) && site.parent.source === site.node;
+  const isAnchor = isRelative && !isModuleSource && !index.has(site.node);
+  if (!isAnchor) return;
+  const importRef = `${normalizeImportSource(value, filePath)}#*`;
+  index.set(site.node, { origin: 'import', bindingId: null, isDecl: false, importRef });
+};
+
+/** Site handlers by node type that fill `index` (Map<node, entry>); `ids` numbers bindings per file. */
+const createSiteHandlers = (index, ids, filePath) => {
+  const onCall = (site) => indexDynamicSource(site, index, filePath);
+  return {
+    Identifier(site) {
+      index.set(site.node, describeIdentifier(site, ids, filePath));
+    },
+    JSXIdentifier(site) {
+      const entry = describeJsxName(site, ids, filePath);
+      if (entry) index.set(site.node, entry);
+    },
+    CallExpression: onCall,
+    ImportExpression: onCall,
+    StringLiteral(site) {
+      indexRelativeString(site, site.node.value, index, filePath);
+    },
+    TemplateLiteral(site) {
+      const isPlain = site.node.expressions.length === 0 && site.parent?.type !== 'TaggedTemplateExpression';
+      if (isPlain) indexRelativeString(site, site.node.quasis[0]?.value.cooked, index, filePath);
+    }
+  };
+};
+
+/**
+ * Babel visitors that fill `index` (Map<node, entry>); `ids` numbers bindings per file. The audit's
+ * merged traverse uses these; fillBindingIndex builds the same index without a visitor traverse.
+ */
+export const createBindingVisitors = (index, ids, filePath = null) => {
+  const visitors = {};
+  for (const [type, handle] of Object.entries(createSiteHandlers(index, ids, filePath))) visitors[type] = (nodePath) => handle(siteOfPath(nodePath));
+  return visitors;
+};
+
+/**
+ * Fills `index` and `ids` for one Babel AST as createBindingVisitors would in a traverse of it, from a
+ * walk over the scopes Babel crawled (binding-walk.js). When the walk cannot finish (a scopable node
+ * without a crawled scope, or a root that is not a File), nothing it found is kept and a real
+ * traverse fills the index instead.
+ */
+export const fillBindingIndex = (ast, index, ids, filePath = null) => {
+  const walkedIndex = new Map();
+  const walkedIds = new Map(ids);
+  const isWalked = walkBindingSites(ast, createSiteHandlers(walkedIndex, walkedIds, filePath));
+  if (!isWalked) {
+    traverse(ast, createBindingVisitors(index, ids, filePath));
+    return;
+  }
+  for (const [node, entry] of walkedIndex) index.set(node, entry);
+  for (const [binding, id] of walkedIds) ids.set(binding, id);
+};
+
+/** Builds Map<IdentifierNode, entry> for a whole Babel File/Program AST. */
+export const buildBindingIndex = (ast, { filePath = null } = {}) => {
+  const index = new Map();
+  fillBindingIndex(ast, index, new Map(), filePath);
+  return index;
+};
+
+/** Entry for an Identifier the index never saw (synthesized nodes): treated as a global name. */
+export const UNKNOWN_IDENTIFIER = Object.freeze({ origin: 'global', bindingId: null, isDecl: false, importRef: null });

package/cli/forge/blueprint-cli.js

@@ -0,0 +1,153 @@
+// `chemx blueprint <group-id|bp-id> | --item=A7 [--json]`, `chemx blueprint holes <target>` and
+// `chemx blueprint fill <target> id=value ... --as=@handle` (design doc, Surfaces). The target is a group
+// id prefix (from `chemx patterns --forge`), a stored blueprint id, or a ground-truth item. Showing a
+// blueprint refreshes the ledger, builds it from the group and stores it by id; the same group in the same
+// state always yields the same bytes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { openIndexDb } from '../search-schema.js';
+import { resolveIndexRoot } from '../search-root.js';
+import { syncFingerprints } from './fingerprint-sync.js';
+import { runForgeGroups, readLedger } from './forge-groups.js';
+import { createFacetResolver } from './facets.js';
+import { createBlueprintContext } from './blueprint-context.js';
+import { buildBlueprint, canonicalJson, withFills } from './blueprint.js';
+import { loadMatchableEntries } from './library-match.js';
+import { groupByPrefix, groupByItem } from './blueprint-target.js';
+import { saveBlueprint, readBlueprint, readFills, validateFill, saveFill } from './blueprint-store.js';
+
+const SHOWN_REJECTED = 8;
+const SUBCOMMANDS = new Set(['holes', 'fill']);
+
+const flagValue = (args, name) => args.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+
+const write = (lines) => process.stdout.write(`${lines.join('\n')}\n`);
+
+/** { sub, target, item, pairs, json, agent } from argv. */
+export const parseBlueprintArgs = (args) => {
+  const sub = SUBCOMMANDS.has(args[0]) ? args[0] : 'show';
+  const rest = sub === 'show' ? args : args.slice(1);
+  const positional = rest.filter((arg) => !arg.startsWith('-'));
+  const pairs = sub === 'fill' ? positional.filter((arg) => arg.includes('=')) : [];
+  const target = positional.find((arg) => !arg.includes('=')) ?? null;
+  return { sub, target, item: flagValue(args, 'item') ?? null, pairs, json: args.includes('--json'), agent: flagValue(args, 'as') ?? process.env.CHEMX_AGENT_ID ?? '' };
+};
+
+const fileReaderAt = (root) => (relativePath) => {
+  try {
+    return fs.readFileSync(path.join(root, relativePath), 'utf-8');
+  } catch {
+    return null;
+  }
+};
+
+const contextFor = (db, cwd, groups = []) => {
+  const root = resolveIndexRoot(cwd);
+  const resolver = createFacetResolver(root);
+  return createBlueprintContext({ root, ledger: readLedger(db), groups, readFile: fileReaderAt(root), entries: loadMatchableEntries(), packageRootOfFile: resolver.packageRootOfFile });
+};
+
+const siteLine = (site) => `    ${site.file}:${site.range[0]}-${site.range[1]}`;
+
+const holeSummary = (hole) => `${hole.id} (${hole.tier}${hole.default === null ? ', open' : `, default ${JSON.stringify(hole.default)}`})`;
+
+/** Human lines for a blueprint with its fills applied. */
+export const blueprintLines = (blueprint) => {
+  const piece = blueprint.piece;
+  const where = piece.module ? `${piece.module}${piece.moduleIsNew ? ' (new)' : ''}` : 'no module';
+  const head = [blueprint.id, blueprint.kind, piece.name, `-> ${where}`].join(' ');
+  const counts = `${blueprint.evidence.instances} sites/${blueprint.evidence.files} files`;
+  const rejected = blueprint.evidence.rejectedMembers;
+  return [
+    `${head} | ${counts} | needs ${blueprint.needs}${blueprint.autoApplicable ? ' auto' : ''} | group ${blueprint.group}`,
+    ...(piece.fromPiece ? [`  library piece ${piece.fromPiece}${piece.existing ? ` (already in the project: ${piece.existing})` : ''}`] : []),
+    `  placement: ${piece.placementReason}`,
+    '  sites:', ...blueprint.callSites.map(siteLine),
+    ...(rejected.length > 0 ? ['  rejected members (left as they are):', ...rejected.slice(0, SHOWN_REJECTED).map((entry) => `    ${entry.at}  ${entry.reason}`), ...(rejected.length > SHOWN_REJECTED ? [`    +${rejected.length - SHOWN_REJECTED} more (--json lists all)`] : [])] : []),
+    ...(blueprint.drift.length > 0 ? ['  drift (similar spans that differ):', ...blueprint.drift.map((span) => `    ${span.at}`)] : []),
+    `  holes: ${blueprint.holes.map(holeSummary).join(', ')}`,
+    `  next: chemx blueprint holes ${blueprint.id}; chemx blueprint fill ${blueprint.id} <hole>=<value> --as=@you`
+  ];
+};
+
+const holeLines = (blueprint) => blueprint.holes.flatMap((hole) => [
+  `${hole.id} ${hole.kind} ${hole.tier}${hole.default === null ? ' open' : ''}`,
+  ...(hole.default === null ? [] : [`  default: ${hole.default}`]),
+  ...(hole.candidates.length > 0 ? [`  candidates: ${hole.candidates.join(' | ')}`] : []),
+  `  constraints: ${JSON.stringify(hole.constraints)}`
+]);
+
+// A group id builds the blueprint; a stored blueprint id reads it back (fills applied by the caller).
+// options: { target, item }. Shared with `chemx heal` (heal-cli.js).
+export const resolveBlueprint = (db, cwd, options) => {
+  const isStoredId = options.target?.startsWith('bp_');
+  if (isStoredId) return readBlueprint(db, options.target);
+  syncFingerprints(cwd, { targetDir: null, includeTests: false });
+  const grouped = runForgeGroups(cwd, {});
+  const hasRun = Boolean(grouped);
+  if (!hasRun) return { error: 'no index db here (run chemx q once to create it)' };
+  const found = options.item ? groupByItem(grouped.groups, options.item) : groupByPrefix(grouped.groups, options.target);
+  const isUnresolved = Boolean(found.error);
+  if (isUnresolved) return { error: found.error };
+  const blueprint = buildBlueprint(found.group, contextFor(db, cwd, grouped.groups));
+  saveBlueprint(db, blueprint);
+  return { blueprint };
+};
+
+export const fillContextOf = (db, cwd, blueprint) => {
+  const context = contextFor(db, cwd);
+  return { declaredIn: context.declaredIn, files: blueprint.locks };
+};
+
+const runFill = (db, cwd, blueprint, options) => {
+  const isAnonymous = !options.agent.startsWith('@');
+  if (isAnonymous) return { ok: false, code: 1, error: 'usage: chemx blueprint fill <target> <hole>=<value> --as=@handle' };
+  const fillContext = fillContextOf(db, cwd, blueprint);
+  const results = options.pairs.map((pair) => {
+    const at = pair.indexOf('=');
+    const holeId = pair.slice(0, at);
+    const value = pair.slice(at + 1);
+    const verdict = validateFill(blueprint, holeId, value, fillContext);
+    const isValid = verdict.ok;
+    if (isValid) saveFill(db, blueprint.id, holeId, value, `human:${options.agent}`);
+    return { holeId, value, ...verdict };
+  });
+  const refused = results.filter((entry) => !entry.ok);
+  write(results.map((entry) => (entry.ok ? `filled ${entry.holeId} = ${entry.value}` : `refused ${entry.holeId}: ${entry.reason}`)));
+  return { ok: refused.length === 0, code: refused.length === 0 ? 0 : 1, results };
+};
+
+const PRINTERS = {
+  holes: (blueprint) => holeLines(blueprint).join('\n'),
+  show: (blueprint, options) => (options.json ? canonicalJson(blueprint).trimEnd() : blueprintLines(blueprint).join('\n'))
+};
+
+/** Runs the command; returns { ok, ... } and prints. */
+export const runBlueprintCli = (args, cwd = process.cwd()) => {
+  const options = parseBlueprintArgs(args);
+  const hasTarget = Boolean(options.target) || Boolean(options.item);
+  const isMissingTarget = !hasTarget;
+  if (isMissingTarget) {
+    write(['usage: chemx blueprint <group-id|bp-id> | --item=<A7> [--json]', '       chemx blueprint holes <target>', '       chemx blueprint fill <target> <hole>=<value> --as=@handle']);
+    return { ok: false, code: 1, error: 'no target' };
+  }
+  const db = openIndexDb(cwd);
+  const hasDb = Boolean(db);
+  if (!hasDb) {
+    write(['blueprint: no index db here (run chemx q once to create it)']);
+    return { ok: false, code: 1, error: 'no index db' };
+  }
+  const resolved = resolveBlueprint(db, cwd, options);
+  const isFailed = Boolean(resolved.error);
+  if (isFailed) {
+    write([`blueprint: ${resolved.error}`]);
+    return { ok: false, code: 1, error: resolved.error };
+  }
+  const { blueprint } = resolved;
+  const isFill = options.sub === 'fill';
+  if (isFill) return runFill(db, cwd, blueprint, options);
+  const filled = withFills(blueprint, readFills(db, blueprint.id));
+  const text = PRINTERS[options.sub](filled, options);
+  process.stdout.write(`${text}\n`);
+  return { ok: true, blueprint: filled };
+};

package/cli/forge/blueprint-context.js

@@ -0,0 +1,69 @@
+// Everything a blueprint reads, built once per run from the ledger (never from the clock or the input
+// order): rows in file and line order, the tree reader the near-miss search uses, enclosing and declared
+// names, sibling specs and the matchable library entries.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createTreeReader } from './unit-trees.js';
+import { createUbiquityIndex } from './gates.js';
+import { byCodePoint } from './group-shape.js';
+
+const byRowOrder = (a, b) => byCodePoint(a.file_path, b.file_path) || a.start_line - b.start_line || a.start - b.start || a.id - b.id;
+
+const SPEC_SUFFIXES = ['spec', 'test'];
+
+const siblingSpecsOf = (file) => {
+  const extension = path.posix.extname(file);
+  const stem = file.slice(0, file.length - extension.length);
+  return SPEC_SUFFIXES.map((suffix) => `${stem}.${suffix}${extension}`);
+};
+
+/**
+ * Context over a ledger ({ rows, contentHashes }). options: { root, readFile(relative) => text | null,
+ * groups (the run's accepted groups, for drift reported on overlapping groups), entries (library-match.js loadMatchableEntries), fileExists, packageRootOfFile }.
+ */
+export const createBlueprintContext = ({ root, ledger, groups = [], readFile, entries = [], fileExists = (relative) => fs.existsSync(path.join(root, relative)), packageRootOfFile = () => '.' }) => {
+  const rows = [...ledger.rows].sort(byRowOrder);
+  const rowsById = new Map(rows.map((row) => [row.id, row]));
+  const treeReader = createTreeReader(readFile, rows, { contentHashes: ledger.contentHashes });
+  const ubiquitousOf = createUbiquityIndex(rows);
+  const fnsByFile = new Map();
+  for (const row of rows.filter((candidate) => candidate.kind === 'fn' && candidate.decl_name)) {
+    fnsByFile.set(row.file_path, [...(fnsByFile.get(row.file_path) ?? []), row]);
+  }
+
+  const enclosingNameOf = (instance) => {
+    const row = rowsById.get(instance.unitIds[0]);
+    const isNamedFunction = row?.kind === 'fn' && Boolean(row.decl_name);
+    if (isNamedFunction) return row.decl_name;
+    const around = (fnsByFile.get(instance.file) ?? []).filter((fn) => fn.start <= instance.start && fn.end >= instance.end);
+    const innermost = around.sort((a, b) => (a.end - a.start) - (b.end - b.start) || a.id - b.id)[0];
+    return innermost?.decl_name ?? null;
+  };
+
+  const declaredIn = (files) => new Set(files.flatMap((file) => (fnsByFile.get(file) ?? []).map((row) => row.decl_name)));
+
+  const instancesByFile = new Map();
+  for (const group of groups) {
+    for (const instance of group.instances) instancesByFile.set(instance.file, [...(instancesByFile.get(instance.file) ?? []), { group, instance }]);
+  }
+
+  const isOverlapping = (a, b) => a.file === b.file && a.startLine <= b.endLine && a.endLine >= b.startLine;
+
+  // Drift spans other accepted groups report over the same code (a window around an expression idiom
+  // sees spans the expression group's own search cannot), minus spans inside the group itself.
+  const relatedDriftOf = (group) => {
+    const others = group.instances.flatMap((instance) => (instancesByFile.get(instance.file) ?? [])
+      .filter((entry) => entry.group.id !== group.id && isOverlapping(entry.instance, instance))
+      .map((entry) => entry.group));
+    const spans = [...new Map(others.sort((a, b) => byCodePoint(a.id, b.id)).map((other) => [other.id, other])).values()]
+      .flatMap((other) => (other.drift ?? []).map((span) => ({ ...span, reason: `reported by overlapping group ${other.id}` })));
+    return spans.filter((span) => !group.instances.some((instance) => isOverlapping(span, instance)));
+  };
+
+  const coveringSpecsOf = (file) => siblingSpecsOf(file).filter(fileExists);
+
+  return {
+    root, rows, rowsById, contentHashes: ledger.contentHashes, entries, fileExists, packageRootOfFile, readFile,
+    treeOf: treeReader.treeOf, ubiquitousOf, enclosingNameOf, declaredIn, coveringSpecsOf, relatedDriftOf
+  };
+};

package/cli/forge/blueprint-members.js

@@ -0,0 +1,82 @@
+// Members of a group whose LGG has no holes (N1 groups): what the piece must take and where the members
+// disagree. Text-level and conservative: a name is a parameter when the home member reads it and no import
+// or module-level declaration of its file binds it. A member that is the negation of the home member is a
+// polarity difference, reported as behaviorDelta and a variant hole, never merged silently.
+import { byCodePoint } from './group-shape.js';
+
+const KEYWORDS = new Set(['await', 'break', 'case', 'catch', 'const', 'continue', 'default', 'delete', 'do', 'else', 'export', 'false', 'finally', 'for', 'function', 'if', 'in', 'instanceof', 'let', 'new', 'null', 'of', 'return', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'undefined', 'var', 'void', 'while', 'yield', 'async']);
+const IDENTIFIER_G = /(?<![\w$.])[A-Za-z_$][\w$]*/g;
+
+const withoutLiterals = (text) => text
+  .replace(/\/\*[\s\S]*?\*\//g, ' ')
+  .replace(/\/\/[^\n]*/g, ' ')
+  .replace(/'(?:[^'\\\n]|\\.)*'|"(?:[^"\\\n]|\\.)*"|`(?:[^`\\]|\\.)*`/g, '""');
+
+const moduleBindingsOf = (fileText) => {
+  const names = new Set();
+  for (const match of fileText.matchAll(/^import\s+([^;]+?)\s+from\s+['"]/gm)) {
+    for (const part of match[1].replace(/[{}*]/g, ',').split(',')) {
+      const binding = part.trim().split(/\s+as\s+/).pop().trim();
+      const isBinding = binding !== '' && binding !== 'type';
+      if (isBinding) names.add(binding);
+    }
+  }
+  for (const match of fileText.matchAll(/^(?:export\s+)?(?:async\s+)?(?:const|let|var|function\*?|class)\s+([A-Za-z_$][\w$]*)/gm)) names.add(match[1]);
+  return names;
+};
+
+const localsOf = (code) => {
+  const names = new Set();
+  for (const match of code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g)) names.add(match[1]);
+  for (const match of code.matchAll(/\(([^()]*)\)\s*=>|\b([A-Za-z_$][\w$]*)\s*=>/g)) {
+    for (const name of (match[1] ?? match[2]).split(',')) names.add(name.trim().replace(/^\.\.\./, '').split('=')[0].trim());
+  }
+  return names;
+};
+
+/** Names the member text reads but does not bind (module bindings, globals and its own locals excluded), in first-read order. */
+export const freeNamesOf = (text, fileText = '') => {
+  const code = withoutLiterals(text);
+  const bound = new Set([...moduleBindingsOf(fileText), ...localsOf(code)]);
+  const names = [];
+  for (const [name] of code.matchAll(IDENTIFIER_G)) {
+    const isFree = !KEYWORDS.has(name) && !bound.has(name) && !(name in globalThis) && !names.includes(name);
+    const afterKey = new RegExp(`[{,]\\s*${name.replace(/\$/g, '\\$')}\\s*:`).test(code);
+    const isParam = isFree && !afterKey;
+    if (isParam) names.push(name);
+  }
+  return names;
+};
+
+/** 'negated' when the member expression is a leading `!` form (or a chain of them), else 'plain'. */
+export const polarityOf = (text) => (/^\s*\(*\s*!/.test(text) ? 'negated' : 'plain');
+
+const sliceOf = (instance, context) => {
+  const fileText = context.readFile(instance.file) ?? '';
+  const hasOffsets = Number.isInteger(instance.start) && Number.isInteger(instance.end) && instance.end > instance.start;
+  return { fileText, text: hasOffsets ? fileText.slice(instance.start, instance.end) : '' };
+};
+
+/**
+ * { params, sites, polarity, behaviorDelta } for ordered instances (the first is the home member).
+ * sites: per instance { names (its own free names), polarity }. polarity: { plain: [at], negated: [at] },
+ * behaviorDelta lists the members whose polarity differs from the majority (ties keep plain).
+ */
+export const deriveMembers = (instances, context) => {
+  const sites = instances.map((instance) => {
+    const { fileText, text } = sliceOf(instance, context);
+    return { at: `${instance.file}:${instance.startLine}-${instance.endLine}`, names: freeNamesOf(text, fileText), polarity: text ? polarityOf(text) : 'plain' };
+  });
+  const home = sites[0]?.names ?? [];
+  const params = home.map((name) => ({ name, kind: 'value', type: null, source: 'home-member-free-variable' }));
+  const polarity = { plain: [], negated: [] };
+  for (const site of sites) polarity[site.polarity].push(site.at);
+  polarity.plain.sort(byCodePoint);
+  polarity.negated.sort(byCodePoint);
+  const majority = polarity.negated.length > polarity.plain.length ? 'negated' : 'plain';
+  const minority = majority === 'plain' ? 'negated' : 'plain';
+  const behaviorDelta = polarity[minority].length > 0 && polarity[majority].length > 0
+    ? polarity[minority].map((at) => ({ at, kind: 'polarity', detail: `member is the ${minority === 'negated' ? 'negation' : 'complement'} of the ${majority} members; calling the piece there needs a leading !` }))
+    : [];
+  return { params, sites, polarity, majority, behaviorDelta };
+};

package/cli/forge/blueprint-store.js

@@ -0,0 +1,106 @@
+// Blueprints in index.db (design doc, Data model: blueprints, blueprint_fills) and the fill rules.
+// A blueprint row holds the canonical JSON of the unfilled blueprint; fills are separate rows, so
+// (blueprint, fills) is the whole input a heal replays. updated_seq is a counter, not a clock.
+import { withIndexTransaction } from '../search-index-write.js';
+import { canonicalJson } from './blueprint.js';
+import { isIdentifier } from './naming.js';
+
+const DDL = `
+  CREATE TABLE IF NOT EXISTS blueprints (
+    id TEXT PRIMARY KEY, group_id TEXT NOT NULL, kind TEXT NOT NULL, needs TEXT NOT NULL,
+    auto_applicable INTEGER NOT NULL DEFAULT 0, json TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'planned',
+    task_id INTEGER, piece_ref TEXT, updated_seq INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE TABLE IF NOT EXISTS blueprint_fills (
+    blueprint_id TEXT NOT NULL, hole_id TEXT NOT NULL, value TEXT NOT NULL, filled_by TEXT NOT NULL,
+    model TEXT, valid INTEGER NOT NULL DEFAULT 1, reason TEXT, attempts INTEGER NOT NULL DEFAULT 1,
+    PRIMARY KEY (blueprint_id, hole_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_blueprints_group ON blueprints(group_id);
+`;
+
+const SQL = {
+  nextSeq: 'SELECT COALESCE(MAX(updated_seq), 0) + 1 AS seq FROM blueprints',
+  existing: 'SELECT id FROM blueprints WHERE id = ?',
+  insert: `INSERT INTO blueprints (id, group_id, kind, needs, auto_applicable, json, status, piece_ref, updated_seq)
+    VALUES (?, ?, ?, ?, ?, ?, 'planned', ?, ?)`,
+  byPrefix: 'SELECT id, json, status FROM blueprints WHERE id LIKE ? ORDER BY id LIMIT 2',
+  fills: 'SELECT hole_id, value FROM blueprint_fills WHERE blueprint_id = ? AND valid = 1 ORDER BY hole_id',
+  fill: `INSERT INTO blueprint_fills (blueprint_id, hole_id, value, filled_by, valid, attempts)
+    VALUES (?, ?, ?, ?, 1, 1)
+    ON CONFLICT(blueprint_id, hole_id) DO UPDATE SET value = excluded.value, filled_by = excluded.filled_by,
+      valid = 1, reason = NULL, attempts = blueprint_fills.attempts + 1`
+};
+
+export const ensureBlueprintTables = (db) => db.exec(DDL);
+
+/** Stores the blueprint when its id is new (a known id keeps its status, fills and task). */
+export const saveBlueprint = (db, blueprint) => {
+  ensureBlueprintTables(db);
+  return withIndexTransaction(db, () => {
+    const isKnown = Boolean(db.prepare(SQL.existing).get(blueprint.id));
+    if (isKnown) return { id: blueprint.id, isNew: false };
+    const { seq } = db.prepare(SQL.nextSeq).get();
+    db.prepare(SQL.insert).run(blueprint.id, blueprint.group, blueprint.kind, blueprint.needs, blueprint.autoApplicable ? 1 : 0, canonicalJson(blueprint), blueprint.piece.fromPiece, seq);
+    return { id: blueprint.id, isNew: true };
+  });
+};
+
+/** The stored blueprint whose id starts with idOrPrefix: { blueprint, status } or { error }. */
+export const readBlueprint = (db, idOrPrefix) => {
+  ensureBlueprintTables(db);
+  const isUsable = /^bp_[0-9a-f]{4,12}$/.test(idOrPrefix ?? '');
+  if (!isUsable) return { error: 'a blueprint id is bp_ and 4 to 12 hex characters' };
+  const rows = db.prepare(SQL.byPrefix).all(`${idOrPrefix}%`);
+  const isUnique = rows.length === 1;
+  if (isUnique) return { blueprint: JSON.parse(rows[0].json), status: rows[0].status };
+  return { error: rows.length === 0 ? `no stored blueprint ${idOrPrefix}` : `blueprint id ${idOrPrefix} is ambiguous` };
+};
+
+/** Valid fills of a blueprint: Map holeId -> value. */
+export const readFills = (db, blueprintId) => {
+  ensureBlueprintTables(db);
+  return new Map(db.prepare(SQL.fills).all(blueprintId).map((row) => [row.hole_id, row.value]));
+};
+
+const EM_DASH = String.fromCharCode(0x2014);
+
+const FILL_RULES = {
+  name: (hole, value, context) => {
+    const isBad = !isIdentifier(value);
+    if (isBad) return 'a name is one identifier (letters, digits, _ and $; no leading digit)';
+    const isTaken = context.declaredIn(context.files).has(value) && value !== hole.default;
+    return isTaken ? `${value} is already declared in the piece module or a member file` : null;
+  },
+  wording: (hole, value) => {
+    const limit = hole.constraints.maxLen;
+    const problems = [
+      [value.trim().length === 0, 'the wording is empty'],
+      [value.length > limit, `the wording is ${value.length} characters; the limit is ${limit}`],
+      [value.includes(EM_DASH), 'the wording has an em dash (TYPOGRAPHY_EM_DASH)']
+    ];
+    return problems.find(([isProblem]) => isProblem)?.[1] ?? null;
+  },
+  decision: (hole, value) => (hole.candidates.includes(value) ? null : `choose one of: ${hole.candidates.join(', ')}`),
+  variant: (hole, value) => (value.trim().length > 0 ? null : 'the variant is empty')
+};
+
+/**
+ * Checks a fill against its hole. context: { files (the piece module and the member files), declaredIn }.
+ * Returns { ok: true } or { ok: false, reason }; a hole kind with no rule (design) takes no fill.
+ */
+export const validateFill = (blueprint, holeId, value, context) => {
+  const hole = blueprint.holes.find((entry) => entry.id === holeId);
+  const isMissing = !hole;
+  if (isMissing) return { ok: false, reason: `no hole ${holeId} (holes: ${blueprint.holes.map((entry) => entry.id).join(', ')})` };
+  const rule = FILL_RULES[hole.kind];
+  const takesNoFill = !rule;
+  if (takesNoFill) return { ok: false, reason: `a ${hole.kind} hole is a design decision and takes no fill` };
+  const reason = rule(hole, value, context);
+  return reason ? { ok: false, reason } : { ok: true };
+};
+
+export const saveFill = (db, blueprintId, holeId, value, agent) => {
+  ensureBlueprintTables(db);
+  db.prepare(SQL.fill).run(blueprintId, holeId, value, agent);
+};