@starci/hfs 4.7.33 → 4.7.35

package/runtime/scripts/gates/canon-pins.mjs

@@ -3,14 +3,117 @@
 // The gates read the pins here; scripts/checks/check-canon-pins.mjs is the self-check that judges them.
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
+import { grammarLintFor } from '../lib/grammar-lint.mjs';
+import { locateDeclaration } from '../hfs/slots.mjs';
+import { pathKey, posixPath } from '../lib/path-key.mjs';
+import { canonContentDigest, installedFiles } from './canon-digest.mjs';
 
 export const PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const SCHEMA_FILE = 'modules/schemas/canon-pins.schema.yaml';
 export const PROFILES_FILE = 'modules/models/code-patterns.yaml';
+/** A missing, mismatched or unjudged installed canon remains a failing gate. */
+export const CANON_INSTALL_CODES = Object.freeze({ missing: 'CANON_INSTALL_MISSING', mismatch: 'CANON_INSTALL_MISMATCH', unjudged: 'CANON_INSTALL_UNJUDGED' });
 
 /** The parsed canon pins of the runtime at `root`. */
 export function loadPins(root = skillRoot) {
   return parseYaml(fs.readFileSync(path.join(root, PINS_FILE), 'utf8'));
 }
+
+/** Every independently published canon binding of a profile, including each declared Grammar family. */
+export function profileCanonBindings(profile) {
+  return [
+    { binding: 'canon', canon: profile?.canon },
+    ...Object.entries(profile?.familyCanons ?? {}).map(([family, canon]) => ({ binding: `familyCanons.${family}`, family, canon })),
+  ];
+}
+
+/** The zero-based source lines that author actual profile canon versions, including named family bindings. */
+export function canonBindingVersionLines(text) {
+  const profiles = parseYaml(text)?.profiles ?? {};
+  const bindings = new Map(Object.entries(profiles).flatMap(([profile, value]) => profileCanonBindings(value)
+    .filter(row => typeof row.canon?.package === 'string' && typeof row.canon?.version === 'string')
+    .map(row => [JSON.stringify(['profiles', profile, ...row.binding.split('.')]), row.canon])));
+  const leaves = new Map(), stack = [];
+  text.split('\n').forEach((line, index) => {
+    const separator = line.indexOf(':'), field = line.slice(0, separator), key = field.trim();
+    if (separator < 0 || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) return;
+    const indent = field.length - field.trimStart().length, value = line.slice(separator + 1).trimStart();
+    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
+    const keys = [...stack.map(entry => entry.key), key];
+    let binding = bindings.get(JSON.stringify(keys));
+    if (key === 'version') binding = bindings.get(JSON.stringify(keys.slice(0, -1)));
+    if (binding && (key === 'version' || /^\{.*\bversion\s*:/.test(value))) leaves.set(index, { package: binding.package, version: binding.version });
+    stack.push({ key, indent });
+  });
+  return leaves;
+}
+
+/** The universal binding and the explicitly selected family's binding; no absent selection implies a family. */
+export function selectedProfileCanonBindings(profile, family) {
+  const bindings = [{ binding: 'canon', canon: profile?.canon }];
+  if (!profile?.familyCanons) return bindings;
+  const contract = grammarLintFor(family);
+  if (contract.package === null) return bindings;
+  const canon = profile.familyCanons[contract.family];
+  if (!canon || canon.package !== contract.package) {
+    throw new Error(`Grammar family ${contract.family} has no matching code-pattern canon binding for ${contract.package}`);
+  }
+  return [...bindings, { binding: `familyCanons.${contract.family}`, family: contract.family, canon }];
+}
+
+/** The package root resolved from a side's npm install, without admitting an install above the app boundary. */
+function installedPackageRoot(directory, name, bound) {
+  const top = pathKey(bound);
+  const searched = (createRequire(path.join(directory, 'package.json')).resolve.paths(name) ?? []).filter(modules => pathKey(modules).startsWith(`${top}/`));
+  for (const modules of searched) {
+    const candidate = path.join(modules, ...name.split('/'));
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);
+  }
+  return null;
+}
+
+/** Inspect one selected binding's actual installed bytes; errors remain unavailable and mismatches remain findings. */
+function inspectBinding(root, bound, pins, profile, row, out) {
+  const { canon, family } = row, side = pins[canon?.package]?.side;
+  const label = row.binding === 'canon' ? profile : `${profile}.${row.binding}`;
+  if (!canon?.package || typeof side !== 'string') { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: canon.package ${canon?.package} has no pinned side`); return; }
+  const installed = installedPackageRoot(path.join(root, side), canon.package, bound);
+  if (!installed) { out.errors.push(`${CANON_INSTALL_CODES.missing} profile ${label}: ${canon.package} does not resolve from ${side}/ of the app; install the pinned ${canon.version}`); return; }
+  const where = posixPath(path.relative(root, installed));
+  let manifest, version, digest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8'));
+    version = manifest.version ?? null;
+    digest = canonContentDigest(installed, canon.contentDigest, installedFiles(installed));
+  } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: ${error.code ?? 'ERROR'} ${error.message}`); return; }
+  out.checked.push({ profile: label, ...(family ? { family } : {}), package: canon.package, side, path: where, version, digest: digest.value, files: digest.files });
+  if (version !== canon.version || digest.value !== canon.contentDigest.value || digest.files !== canon.contentDigest.files) {
+    out.findings.push({ engine: 'canon', rule: 'installed-canon-mismatch', path: where, line: null,
+      message: `${canon.package} installed for ${side}/ is ${version} with ${digest.files} files digesting ${digest.value}; profile ${label} binds ${canon.version} with ${canon.contentDigest.files} files digesting ${canon.contentDigest.value} (${CANON_INSTALL_CODES.mismatch}: reinstall the pinned version from the registry)` });
+  }
+  return Object.keys(manifest.dependencies ?? {});
+}
+
+/** Judge the universal and explicitly selected family installs against their independent version/content bindings. */
+export function inspectInstalledCanons(root, { pins, profiles, bound = root }) {
+  const out = { checked: [], findings: [], errors: [] };
+  for (const [profile, value] of Object.entries(profiles)) {
+    let bindings;
+    try {
+      const declaration = value?.familyCanons ? JSON.parse(fs.readFileSync(locateDeclaration(root).file, 'utf8')) : null;
+      bindings = selectedProfileCanonBindings(value, declaration?.sides?.fe?.grammar);
+    } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${profile}: ${error.message}`); continue; }
+    const available = profileCanonBindings(value), checked = new Set();
+    for (const row of bindings) {
+      if (checked.has(row.canon?.package)) continue;
+      checked.add(row.canon?.package);
+      const dependencies = inspectBinding(root, bound, pins, profile, row, out) ?? [];
+      // A family adapter's digest does not cover its independently published implementation dependency.
+      bindings.push(...available.filter(entry => dependencies.includes(entry.canon?.package) && !checked.has(entry.canon.package)));
+    }
+  }
+  return out;
+}

package/runtime/scripts/gates/gate.mjs

@@ -53,8 +53,7 @@ import { APP_SCOPE, HFS_DECLARATION_FILE, locateDeclaration } from '../hfs/slots
 import { runNode } from '../api/node/run-node.mjs';
 import { sha256 } from '../../engine/digest.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { canonContentDigest, installedFiles } from './canon-digest.mjs';
-import { PROFILES_FILE, loadPins } from './canon-pins.mjs';
+import { CANON_INSTALL_CODES, PROFILES_FILE, inspectInstalledCanons, loadPins } from './canon-pins.mjs';
 import { gateGit as git, gateGitText as gitText, resolveGateBase, gateDelta, gateInputSnapshot } from './gate-input.mjs';
 export { resolveGateBase, gateInputSnapshot } from './gate-input.mjs';
 import { jestRunError, reduceJest } from './test-world-run.mjs';
@@ -438,21 +437,6 @@ export function mergeGuard(root, { base, head = 'HEAD', mainTip = mainTipOf(root
 }
 
 /* ----------------------------------------------------------------------------------------- installed canon */
-const INSTALL = Object.freeze({ missing: 'CANON_INSTALL_MISSING', mismatch: 'CANON_INSTALL_MISMATCH', unjudged: 'CANON_INSTALL_UNJUDGED' });
-
-/**
- * The installed root of package `name` as node resolves it from `directory` (its node_modules walk), never above `bound` (the
- * app root, appRootOf): a canon in an enclosing repository's node_modules is not this app's install. Null when none.
- */
-function installedPackageRoot(directory, name, bound) {
-  const top = pathKey(bound);
-  const searched = (createRequire(path.join(directory, 'package.json')).resolve.paths(name) ?? []).filter((modules) => pathKey(modules).startsWith(`${top}/`));
-  for (const modules of searched) {
-    const candidate = path.join(modules, ...name.split('/'));
-    if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);
-  }
-  return null;
-}
 /**
  * Every profile's canon as installed under the app at `root`, judged against its binding in `runtime`'s code-patterns.yaml:
  * the package resolved from the pin's side directory must have the bound version and content digest.
@@ -464,25 +448,8 @@ export function installedCanonFindings(root, { runtime = runtimeRoot } = {}) {
   try {
     pins = loadPins(runtime).pins ?? {};
     profiles = parseYaml(fs.readFileSync(path.join(runtime, PROFILES_FILE), 'utf8'))?.profiles ?? {};
-  } catch (error) { out.errors.push(`${INSTALL.unjudged} the canon bindings are unreadable: ${error.message}`); return out; }
-  for (const [profile, value] of Object.entries(profiles)) {
-    const canon = value?.canon, side = pins[canon?.package]?.side;
-    if (!canon?.package || typeof side !== 'string') { out.errors.push(`${INSTALL.unjudged} profile ${profile}: canon.package ${canon?.package} has no pinned side`); continue; }
-    const installed = installedPackageRoot(path.join(root, side), canon.package, appRootOf(root, path.join(side, 'package.json')));
-    if (!installed) { out.errors.push(`${INSTALL.missing} profile ${profile}: ${canon.package} does not resolve from ${side}/ of the app; install the pinned ${canon.version}`); continue; }
-    const where = posixPath(path.relative(root, installed));
-    let version, digest;
-    try {
-      version = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8')).version ?? null;
-      digest = canonContentDigest(installed, canon.contentDigest, installedFiles(installed));
-    } catch (error) { out.errors.push(`${INSTALL.unjudged} profile ${profile}: ${error.code ?? 'ERROR'} ${error.message}`); continue; }
-    out.checked.push({ profile, package: canon.package, side, path: where, version, digest: digest.value, files: digest.files });
-    if (version !== canon.version || digest.value !== canon.contentDigest.value || digest.files !== canon.contentDigest.files) {
-      out.findings.push({ engine: 'canon', rule: 'installed-canon-mismatch', path: where, line: null,
-        message: `${canon.package} installed for ${side}/ is ${version} with ${digest.files} files digesting ${digest.value}; profile ${profile} binds ${canon.version} with ${canon.contentDigest.files} files digesting ${canon.contentDigest.value} (${INSTALL.mismatch}: reinstall the pinned version from the registry)` });
-    }
-  }
-  return out;
+  } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} the canon bindings are unreadable: ${error.message}`); return out; }
+  return inspectInstalledCanons(root, { pins, profiles, bound: appRootOf(root, 'package.json') });
 }
 
 /* ----------------------------------------------------------------------------------------------- gate */

package/runtime/scripts/gates/output.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {redactBytes} from '../lib/redact.mjs';
+
+/** Print a gate summary, retain an optional scratch copy, and return its measured exit code. */
+export function emitGateSummary(summary, out = null, write = text => process.stdout.write(text)) {
+  const text = `${JSON.stringify(summary, null, 2)}\n`;
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, text);
+  }
+  write(text);
+  return summary.exit;
+}
+
+/**
+ * Write a check result to scratch, stdout, or the external content-addressed store. A blob is redacted first when its
+ * media type is text (scripts/lib/redact.mjs); the printed {sha, redaction} is what a check_runs row cites.
+ */
+export async function emitCheckOutput(value, {out = null, blob = false, mediaType = 'application/json',
+  write = text => process.stdout.write(text), put = null} = {}) {
+  if (out && blob) throw new Error('--out and --blob are mutually exclusive');
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, bytes);
+    return {out: file};
+  }
+  if (blob) {
+    const putBlob = put ?? (await import('../../engine/db/blob.mjs')).putBlob;
+    const clean = redactBytes(bytes, mediaType);
+    const {sha} = await putBlob(clean.bytes, {mediaType});
+    write(`${JSON.stringify({sha, redaction: clean.redaction})}\n`);
+    return {sha, redaction: clean.redaction};
+  }
+  write(bytes.toString());
+  return {};
+}

package/runtime/scripts/gates/test-world-run.mjs

@@ -26,6 +26,7 @@ import { valueFlags } from '../lib/cli-arg.mjs';
 import { isMain } from '../lib/is-main.mjs'; import { walkFiles } from '../lib/walk.mjs';
 import { opGateRules } from '../lib/op-gate.mjs';
 import { makeTempDir } from '../api/fs/make-temp-dir.mjs';
+import { emitGateSummary } from './output.mjs';
 
 export const TEST_WORLD_RUN_SCHEMA = 'starci/test-world-run@1';
 const WORLD_PROJECTS = Object.freeze({
@@ -243,10 +244,7 @@ if (isMain(import.meta.url)) {
   try {
     const opts = parseTestWorldArgs(process.argv.slice(2));
     const summary = buildTestWorldRun({ root: opts.root ?? process.cwd(), project: opts.project, tests: opts.tests });
-    const text = `${JSON.stringify(summary, null, 2)}\n`;
-    if (opts.out) { fs.mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true }); fs.writeFileSync(path.resolve(opts.out), text); }
-    process.stdout.write(text);
-    process.exitCode = summary.exit;
+    process.exitCode = emitGateSummary(summary, opts.out);
   } catch (error) {
     process.stderr.write(`test-world-run: ${error.message}\n`);
     process.exitCode = 2;

package/runtime/scripts/hfs/architecture/config.mjs

@@ -5,6 +5,7 @@ import { readJsonFile as readJson } from '../../lib/json.mjs';
 import { isInside } from '../../lib/walk.mjs';
 import { openHfs } from '../slots.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { grammarContractFor } from '../../lib/grammar-lint.mjs';
 
 
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -270,19 +271,18 @@ function derivedOwners(root, resolver) {
 
 const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
 
-const GRAMMAR_PACKAGE = '@starci/grammar';
-
 /**
- * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
- * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
+ * The selected family's component contract with derived consumers: every app's globals.css is a style
+ * source, every app and every workspace package that depends on its package is a consumer. null when no app has
  * a globals.css to judge (the contract is then reported unavailable, never passed).
  */
-function derivedGrammar(root, packageRoot, workspaces, apps = []) {
+function derivedGrammar(root, packageRoot, workspaces, apps, family) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
+  const contract = grammarContractFor(family);
   // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
   // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
-  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
+  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, contract.package)));
   const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
   const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
@@ -292,7 +292,7 @@ function derivedGrammar(root, packageRoot, workspaces, apps = []) {
     if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
-  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react', '@xyflow/react'] };
+  return { ...contract, styleSources, consumerManifests };
 }
 
 /**
@@ -328,7 +328,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
     hooks: inferred.hooks,
     modules: inferred.modules,
     transport: inferred.transport,
-    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
+    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps, opened.repo.grammar) : null,
   };
   if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
   return {

package/runtime/scripts/hfs/check.mjs

@@ -341,7 +341,7 @@ function mergeBaseOf(repoRoot, base) {
 }
 
 /** Tracked paths that differ from the merge-base (commits, staged and unstaged edits; deletions are not paths to judge). */
-function changedSince(repoRoot, base) {
+export function changedSince(repoRoot, base) {
   const sha = mergeBaseOf(repoRoot, base);
   if (!sha) {
     throw new Error(base

package/runtime/scripts/hfs/db-restamp-verb.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { invocationDir } from '../lib/roots.mjs';
 import { migrationStamp } from './rules/database-migrations.mjs';
-import { MIGRATIONS_DIR, MIGRATIONS_ARCHIVE_DIR } from './rules/database-constants.mjs';
+import { MIGRATIONS_DIR } from './rules/database-constants.mjs';
 import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbSupabase, repairArgs, dbFailure } from './db-baseline-verb.mjs';
 
 /** The map value of one old version: a new version, or { file, to, applied } for the colliding-versions case. */
@@ -56,7 +56,7 @@ function restampPlan(root, mapFile, { local = false, ports = {} } = {}) {
   const mapping = document?.versions ?? document;
   if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || !Object.keys(mapping).length) throw new DbVerbError('restamp map must contain old-to-new version pairs');
   const active = dbSqlFiles(root);
-  const occupied = new Set([...active, ...dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR)].map((entry) => entry.stamp));
+  const occupied = new Set(active.map((entry) => entry.stamp));
   const targets = new Set();
   const steps = Object.entries(mapping).map(([old, raw]) => {
     const entry = mapEntry(old, raw);

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -73,11 +73,17 @@ function extraPackageProblems(side, entries) {
   return [];
 }
 
+function grammarProblems(side, grammar) {
+  if (grammar === undefined) return [];
+  if (side !== 'fe') return ['grammar belongs to the fe side'];
+  return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
+}
+
 function declarationSideProblems(side, value, names) {
   const bad = [];
   const at = `sides.${side}`;
   if (!isPlainObject(value)) return [`${at} must be an object`];
-  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
   bad.push(...appShapeProblems(value.apps, at, side, names));
   if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
   if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
@@ -85,7 +91,7 @@ function declarationSideProblems(side, value, names) {
   bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
   if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
   if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
-  bad.push(...extraPackageProblems(side, value.extraPackages));
+  bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
   return bad;
 }
 

package/runtime/scripts/hfs/grammar-presentation.mjs

@@ -0,0 +1,152 @@
+// Family presentation data decorates universal proof cases without moving their semantic identities.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { openHfs } from './slots.mjs';
+import { grammarFamilyFor } from '../lib/grammar-lint.mjs';
+
+const GRAMMARS = fileURLToPath(new URL('../../knowledge/grammars/', import.meta.url));
+const PADDING_TOPIC = 'presentation/padding.yaml';
+const TOPIC_NAMES = ['padding', 'font'];
+const REM_PX = 16;
+const TEXT_WEIGHT_NAMES = ['normal', 'medium', 'semibold'];
+
+/** The Common text-weight matrix is complete only when each public weight has one declared class. */
+function fontWeightClasses(guidance) {
+  const matrix = guidance?.familyRequirement ?? guidance?.requirement ?? '';
+  const pattern = new RegExp('`font-(' + TEXT_WEIGHT_NAMES.join('|') + ')`', 'g');
+  const names = [...String(matrix).matchAll(pattern)].map(match => match[1]);
+  if (names.length !== TEXT_WEIGHT_NAMES.length || new Set(names).size !== TEXT_WEIGHT_NAMES.length) {
+    throw new Error('Grammar font weight matrix is missing or incomplete');
+  }
+  return names;
+}
+
+/** Resolve a recorded rem, px or unitless scale value at the proof's baseline root; unsupported values stay unavailable. */
+export const remPx = (value) => {
+  const match = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(rem|px)?$/.exec(String(value ?? '').trim());
+  if (!match) return null;
+  const px = Number(match[1]) * (match[2] === 'px' ? 1 : REM_PX);
+  return Number.isFinite(px) ? px : null;
+};
+
+/** Resolve the selected family's published text weights through the active CSS token scope. */
+export function fontWeightsOf(guidance, scope) {
+  const weights = fontWeightClasses(guidance).map(name => Number(scope?.variable(`--font-weight-${name}`)?.value));
+  if (weights.some(weight => !Number.isFinite(weight))) throw new Error('Grammar font weight tokens are unresolved');
+  return weights;
+}
+
+/** Missing or ambiguous family weight data cannot remove the render's weight proof. */
+function validateFontGuidance(data) {
+  const weights = (data.guidance ?? []).filter(item => item.id === 'weight');
+  if (weights.length !== 1) throw new Error('Grammar font guidance needs one concrete weight matrix');
+  fontWeightClasses(weights[0]);
+}
+
+/** Read the explicit family or the app declaration; CSS discovery never chooses presentation law. */
+function selectedFamily(family, repo) {
+  if (family !== null && family !== undefined) return grammarFamilyFor(family).id;
+  if (!repo) throw new Error('Presentation proof needs an explicit Grammar family or an app repository');
+  const declaration = openHfs({ root: skillRoot, repoRoot: repo }).repo;
+  return grammarFamilyFor(declaration.grammar ?? declaration.sides?.fe?.grammar).id;
+}
+
+/** The one declared presentation owner, following only explicit inheritance and rejecting cycles. */
+function presentationOwner(family, name, seen = new Set()) {
+  if (seen.has(family)) throw new Error(`Grammar ${name} inheritance cycles at ${family}`);
+  seen.add(family);
+  const entry = grammarFamilyFor(family);
+  if (typeof entry.productComposition !== 'string' || !entry.productComposition) {
+    throw new Error(`Grammar family ${family} has no presentation playbook`);
+  }
+  const file = path.resolve(GRAMMARS, entry.productComposition);
+  const relative = path.relative(GRAMMARS, file);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`Grammar family ${family} has an invalid presentation path`);
+  const doc = parseYaml(fs.readFileSync(file, 'utf8'));
+  const data = doc?.presentation?.[name];
+  if (!data || typeof data !== 'object') throw new Error(`Grammar family ${family} has no ${name} presentation data`);
+  if (Object.hasOwn(data, 'inherits')) {
+    if (Object.keys(data).some(key => !['inherits', 'ownership', 'contract'].includes(key))) {
+      throw new Error(`Grammar family ${family} mixes inherited and replacement ${name} data`);
+    }
+    return presentationOwner(data.inherits, name, seen);
+  }
+  if (!Array.isArray(data.scale?.steps) || !data.scale.steps.length
+    || !Array.isArray(data.componentOwnership?.rows) || !data.componentOwnership.rows.length
+    || !Array.isArray(data.recipes) || !data.recipes.length) {
+    throw new Error(`Grammar family ${family} has incomplete ${name} presentation data`);
+  }
+  const steps = new Map(data.scale.steps.map(step => [step.id, step]));
+  if (steps.size !== data.scale.steps.length || data.scale.steps.some(step => typeof step.id !== 'string'
+    || !step.id || (name === 'padding' && (remPx(step.value) === null || remPx(step.value) < 0)))) {
+    throw new Error(`Grammar family ${family} has duplicate or unusable ${name} scale steps`);
+  }
+  if (data.componentOwnership.rows.some(row => !steps.has(row.rule))) {
+    throw new Error(`Grammar family ${family} has a component ${name === 'padding' ? 'inset' : 'font rank'} without a scale value`);
+  }
+  if (data.recipes.some(recipe => typeof recipe.title !== 'string' || !recipe.title.trim())) {
+    throw new Error(`Grammar family ${family} has a ${name} recipe without its concrete title`);
+  }
+  if (name === 'font') validateFontGuidance(data);
+  return { data, source: `knowledge/grammars/${relative.split(path.sep).join('/')}#presentation.${name}` };
+}
+
+/** Preserve every universal case while attaching the exact renderer recipe and its numerical owner. */
+function presentationTopic(topic, owner, name) {
+  const { data, source } = owner;
+  const recipes = new Map(data.recipes.map(recipe => [recipe.rule, recipe]));
+  const rules = topic.doc.rules ?? [];
+  if (recipes.size !== data.recipes.length || recipes.size !== rules.length) {
+    throw new Error(`Grammar ${name} recipes do not cover the universal rule identities exactly once`);
+  }
+  const attached = rules.map(rule => {
+    const recipe = recipes.get(rule.id);
+    const byCase = new Map((recipe?.cases ?? []).map(item => [item.id, item]));
+    if (!recipe || byCase.size !== recipe.cases.length || byCase.size !== (rule.cases ?? []).length) {
+      throw new Error(`Grammar ${name} recipe ${rule.id} does not cover its universal cases exactly once`);
+    }
+    const cases = rule.cases.map(item => {
+      const concrete = byCase.get(item.id);
+      if (!concrete || typeof concrete.render !== 'string' || typeof concrete.owner !== 'string') {
+        throw new Error(`Grammar ${name} recipe ${rule.id}/${item.id} has no renderer contract`);
+      }
+      return { ...item, owner: concrete.owner, render: concrete.render, recipeSource: source };
+    });
+    return { ...rule, familyTitle: recipe.title, cases };
+  });
+  const guidance = new Map((topic.doc.guidance ?? []).map(item => [item.id, item]));
+  for (const concrete of data.guidance ?? []) {
+    const semantic = guidance.get(concrete.id);
+    guidance.set(concrete.id, semantic ? { ...semantic, familyRequirement: concrete.requirement, familySource: source }
+      : { ...concrete, familySource: source });
+  }
+  return {
+    ...topic,
+    familySource: source,
+    doc: { ...topic.doc, scale: data.scale, componentOwnership: data.componentOwnership,
+      guidance: [...guidance.values()], rules: attached },
+  };
+}
+
+/**
+ * Bind supported universal presentation cases to the selected family's numerical recipes without mutation.
+ * Missing family data and incomplete coverage fail visibly rather than selecting another family.
+ * @param {object[]} knowledge - Universal topics with stable relative paths and parsed documents.
+ * @param {{ family?: string, repo?: string }} input - Explicit family or the app whose declaration selects it.
+ * @returns {{ family: string, knowledge: object[] }} Selected family and proof-ready topics with owner provenance.
+ */
+export function familyPresentationKnowledge(knowledge, { family = null, repo = null } = {}) {
+  const selected = selectedFamily(family, repo);
+  const topics = knowledge.filter(topic => topic.rel.endsWith(PADDING_TOPIC));
+  if (topics.length !== 1) throw new Error('Presentation proof needs exactly one universal padding topic');
+  const decorated = new Map();
+  for (const name of TOPIC_NAMES) {
+    const matches = knowledge.filter(topic => topic.rel.endsWith(`presentation/${name}.yaml`));
+    if (matches.length > 1) throw new Error(`Presentation proof has duplicate universal ${name} topics`);
+    if (matches.length) decorated.set(matches[0], presentationTopic(matches[0], presentationOwner(selected, name), name));
+  }
+  return { family: selected, knowledge: knowledge.map(topic => decorated.get(topic) ?? topic) };
+}

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -12,7 +12,7 @@ import { fail } from './slot-errors.mjs';
 
 const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
 const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
-const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
+const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'eslint-grammar-starci', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
 const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
 const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -346,7 +346,7 @@ export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_R
     /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
     lintCode: (ruleId) => {
       const [plugin, id] = String(ruleId ?? '').split('/');
-      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || null;
+      const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || (plugin === 'starci-grammar' && 'eslint-grammar-starci') || null;
       return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
     },
     /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -42,6 +42,7 @@ import { feBuildArgsFindings } from './fe-build-args.mjs';
 /** The failure codes the finders above emit, so `starci app check` ships their labels (check.mjs adds them to CHECK_CODES). Append-only; the coordinator regenerates it at merge time. */
 export const A15_CODES = [
   // codes-begin
+  'FE_STACK_FAMILY_LINT_MISSING',
   'HFS_TEXT_CORRUPT',
   'FE_PUBLIC_BUILD_ARG_MISSING',
   'HFS_WORKFLOW_CONTEXT',

package/runtime/scripts/hfs/rules/fe-stack.mjs

@@ -12,10 +12,15 @@ import { found, readJson } from './read.mjs';
 import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
 import { editionRuleParams } from '../edition-slots.mjs';
 import { globExpression } from '../../lib/glob.mjs';
+import { grammarLintFor } from '../../lib/grammar-lint.mjs';
+import { numericMatch } from '../../lib/numeric-match.mjs';
 
 export const FE_STACK_FORBIDDEN = 'FE_STACK_FORBIDDEN';
 export const FE_STACK_UNLISTED = 'FE_STACK_UNLISTED';
 export const FE_STACK_CORE_MISSING = 'FE_STACK_CORE_MISSING';
+export const FE_STACK_FAMILY_LINT_MISSING = 'FE_STACK_FAMILY_LINT_MISSING';
+const UNIVERSAL_CANON = '@starci/eslint-canon-fe';
+const FAMILY_SPLIT_MAJOR = 9;
 const CATALOG_FILE = new URL('../../../knowledge/hfs/fe-stack.yaml', import.meta.url);
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
 const APP_ROOT_MANIFEST = 'package.json';
@@ -109,6 +114,42 @@ function unlistedFindings(rel, pkg, allowed, extras, workspaces) {
   return findings;
 }
 
+/** The major version a dependency spec admits, or null when the spec names no plain semver (a tag, a path or a protocol). */
+const declaredMajor = (spec) => numericMatch(spec, /^[\^~>=v\s]*(\d+)(?:\.|$)/);
+
+/** The universal canon's declared spec in any front-end or app-root manifest, or null when none declares it. */
+function universalCanonSpec(manifests) {
+  for (const [, pkg] of manifests) for (const section of DEPENDENCY_SECTIONS) {
+    const spec = pkg?.[section]?.[UNIVERSAL_CANON];
+    if (spec !== undefined) return spec;
+  }
+  return null;
+}
+
+/**
+ * From canon-fe 9 the Grammar component rules ship in the selected family's lint package; an app that installs the
+ * universal canon without that package would silently lose them, so the stack refuses it. An unparseable spec is judged
+ * like 9 rather than waved through.
+ */
+function familyLintFindings(declaration, repo, packages, rootManifest) {
+  const family = declaration?.sides?.fe?.grammar ?? repo.grammar;
+  if (typeof family !== 'string' || !family) return [];
+  const manifests = [...packages, ['../package.json', rootManifest]];
+  const product = (repo.apps ?? []).find(app => app.kind === 'next' && app.name !== 'landing');
+  const anchor = product ? `apps/${product.name}/package.json` : 'package.json';
+  const spec = universalCanonSpec(manifests);
+  if (spec === null) return [];
+  const major = declaredMajor(spec);
+  if (major !== null && major < FAMILY_SPLIT_MAJOR) return [];
+  const lint = grammarLintFor(family);
+  if (lint.package === null) return [];
+  if (manifests.some(([, pkg]) => dependenciesOf(pkg).has(lint.package))) return [];
+  const nextStep = `Add ${lint.package} beside ${UNIVERSAL_CANON} (the app root devDependencies or the fe workspace), compose ${lint.factory}({ hfs }) after starciFeConfig({ hfs }) in fe/eslint.config.mjs, or run starci app sync.`;
+  return [found(FE_STACK_FAMILY_LINT_MISSING, anchor,
+    `hfs.json selects sides.fe.grammar ${family} and the front end declares ${UNIVERSAL_CANON} ${spec}, but no manifest declares ${lint.package}: from ${UNIVERSAL_CANON} ${FAMILY_SPLIT_MAJOR} that package carries the ${family} Grammar component rules, so without it they are not enforced. ${nextStep}`,
+    { dependency: lint.package, family, nextStep })];
+}
+
 /** Closed FE catalog and core presence over the front-end side (the mixed root also holds BE tools). */
 export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, inScope = () => true }) {
   if (repo.profile !== 'fe' || repo.kind === 'runtime') return [];
@@ -119,7 +160,9 @@ export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, i
   const { allowed, core } = stackCatalog();
   const extras = extraPackages(declaration);
   const findings = [...packages].filter(([file]) => inScope(file)).flatMap(([file, pkg]) => unlistedFindings(file, pkg, allowed, extras, workspaces));
-  const rootTools = dependenciesOf(readJson(repoRoot, '../package.json'));
+  const rootManifest = readJson(repoRoot, '../package.json');
+  const rootTools = dependenciesOf(rootManifest);
+  findings.push(...familyLintFindings(declaration, repo, packages, rootManifest));
   for (const app of repo.apps ?? []) {
     if (app.kind !== 'next' || app.name === 'landing') continue;
     const rel = `apps/${app.name}/package.json`;

package/runtime/scripts/hfs/slots.mjs

@@ -120,6 +120,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
     connections: Object.freeze((s.connections ?? []).map(connectionView)),
     providers,
     reads: Object.freeze([...(s.reads ?? [])]),
+    ...(s.grammar === undefined ? {} : { grammar: s.grammar }),
     ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
     manifestVersion: manifest.version,
   });

package/runtime/scripts/hfs/view.mjs

@@ -33,6 +33,7 @@ function hfsView(opened, repoRoot) {
     profile: opened.repo.profile,
     side: opened.repo.side ?? null,
     edition: opened.repo.edition ?? 'full',
+    ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
     apps: opened.repo.apps,
     connections: opened.repo.connections,
     patterns: Object.freeze([...(opened.repo.patterns ?? [])]),