simt-dev 0.7.0 → 0.8.0

package/src/projection/rules.mjs

@@ -27,10 +27,13 @@ import { dirname, join, resolve } from 'node:path';
 
 import { fingerprint, KNOWN_TAGS } from '../resolve/fingerprint.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
-import { foldsRules, frontmatterBlock, resolveSurfaces, rulePath, canScope } from './surfaces.mjs';
+import { foldsRules, resolveSurfaces, rulePath, canScope } from './surfaces.mjs';
 import { ruleTargets } from './targets.mjs';
 import { compose } from './markers.mjs';
-import { declaredBudget, declaredShared, manifestPath, readManifest } from './manifest.mjs';
+import { desiredRegion } from './region.mjs';
+export { desiredRegion } from './region.mjs';
+import { declaredBudget, declaredShared, readManifest } from './manifest.mjs';
+import { loadManifest } from '../manifest/schema.mjs';
 import { commandCard, CARD_LIMIT_BYTES } from '../kernel/card.mjs';
 import { packToBudget } from '../kernel/budget.mjs';
 import { filterInferable, inferableDefect, inferableProofs } from '../kernel/inferability.mjs';
@@ -41,6 +44,7 @@ import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { installedSkills } from './disclosure.mjs';
 import { PACK_DIR, resolvePacks } from '../packs.mjs';
 import { discoverPackages } from '../monorepo.mjs';
+import { parseFrontmatter as splitBlock, stripFrontmatter as stripBlock } from '../text/frontmatter.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const ROOT = resolve(HERE, '..', '..');
@@ -255,7 +259,7 @@ export function isEligible(rule, signals, optedIn) {
 export async function readDeclared(root) {
   let parsed = {};
   try {
-    parsed = JSON.parse(await readFile(await manifestPath(root), 'utf8')) ?? {};
+    parsed = (await loadManifest(root)).manifest ?? {};
   } catch {
     parsed = {};
   }
@@ -267,8 +271,6 @@ export async function readDeclared(root) {
   };
 }
 
-
-
 /**
  * Render every canonical `.mdc` rule into its own generated region.
  *
@@ -350,7 +352,7 @@ export function ruleValues(rule, declared, surfaces) {
   return values;
 }
 
-async function ruleBodies(root, manifest, flags) {
+export async function ruleBodies(root, manifest, flags) {
   const problems = [];
   const notes = [];
   const skipped = [];
@@ -444,7 +446,7 @@ async function ruleBodies(root, manifest, flags) {
  * card comes back alongside because the caller that needs the proofs also needs the card's
  * bytes, and building it twice would read the manifest twice for no second answer.
  */
-async function inferableEvidence(root, { stack, facts, manifest }) {
+export async function inferableEvidence(root, { stack, facts, manifest }) {
   const card = await commandCard({ root, manifest, stack, facts });
   return { card, proofs: inferableProofs({ facts, stack, card, manifest }) };
 }
@@ -465,540 +467,10 @@ async function inferableEvidence(root, { stack, facts, manifest }) {
  * shared file, which is how the first version of this predicate lost three of five rules
  * in a two-repository measurement without failing anything.
  */
-function toolRule(rule) {
+export function toolRule(rule) {
   return rule.origin !== undefined ? rule.origin === 'central' : rule.source.startsWith('rules/');
 }
 
-export async function desiredRegion(root, flags) {
-  const { stack, facts, manifest } = await fingerprint(root);
-  const lockedVariants =
-    flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
-  const all = await loadRules(root);
-  const { selected, fallback, notes } = select(all, stack, facts);
-  const { resolved, bodies, problems, notes: ruleNotes } = await ruleBodies(
-    root,
-    manifest,
-    { ...(flags ?? {}), variants: lockedVariants },
-  );
-  notes.push(...ruleNotes);
-
-  // A profile that declares a scope leaves the region only when every selected surface
-  // can load it narrowly. The alternative is a profile written only as a scoped file for
-  // a reader whose surface cannot scope — a rule nobody loads, which is worse than one
-  // that loads eagerly (ADR-071). A surface that cannot scope it therefore keeps the
-  // profile in the region and says so, rather than letting the region quietly shrink.
-  const narrowing = resolved.surfaces.every((s) => canScope(s));
-  const scoped = [];
-  const inRegion = [];
-  for (const r of selected) {
-    const declares = Array.isArray(r.scope) && r.scope.length > 0 && r.error === null;
-    if (!declares) {
-      inRegion.push(r);
-      continue;
-    }
-    // A profile only leaves the region when a narrowed file can replace it. When any
-    // selected surface cannot narrow, the file would be the only home for a rule that
-    // reader cannot reach — so it stays, and says why.
-    if (narrowing) {
-      const vf = foldVariants(r.body, r.id ?? '', lockedVariants);
-      scoped.push(vf.changed ? { ...r, body: vf.body } : r);
-      continue;
-    }
-    inRegion.push(r);
-    notes.push(
-      `${r.id} declares simt-scope, but ${resolved.source} selects a surface that cannot narrow a rule, so it stays in the region`,
-    );
-  }
-
-// The kernel. In `kernel` mode only the hard and command classes are packed into the
-  // region and every other rule is deferred to `rules show <id>`, which is what makes
-  // R08's accept criterion reachable at all: a budget cannot be met by a projection that
-  // never tries. `full` is the default and stays it until R02 has measured that a
-  // kernel does not lose compliance, because nobody has measured it yet.
-  //
-  // A rule with no stated class is deferred, not packed. The two mistakes are not
-  // symmetric: packing a line that should have been deferred spends the budget the mode
-  // exists to save, while deferring a line that should have been packed costs a reader
-  // one `rules show`. The mode is a promise about bytes, so it is the bytes that win.
-  // An explicit `mode` flag overrides the declared one. The caller is the MCP
-  // `simt://kernel` resource, which by name promises the kernel's bytes for any
-  // repository: the declared mode governs what `sync` writes to disk, not what a read
-  // path may look at, so the read renders in the mode the URI names instead of
-  // re-reading a manifest it must not obey (ADR-002).
-  const mode = typeof flags?.mode === 'string' ? flags.mode : await projectionMode(root);
-  const packed = [];
-  const deferred = [];
-  for (const r of inRegion) {
-    if (mode === 'kernel' && (r.error !== null || !KERNEL_CLASSES.has(r.priority))) deferred.push(r);
-    else packed.push(r);
-  }
-  // The command card leads the region. The exact commands for this repository are the
-  // bytes a reader cannot infer from rules that are identical everywhere (plan 0003 R10),
-  // so they go first — above even the core rules. It is derived from committed evidence
-  // only, in one place, so `plan` and `checkTarget` cannot disagree about it and two
-  // machines render it byte-identically.
-  const { card, proofs } = await inferableEvidence(root, { stack, facts, manifest });
-  if (card.dropped.length > 0) {
-    // Reported where every other projection note is reported. A card that lost a command
-    // in silence is a card a reader cannot tell is incomplete.
-    notes.push(
-      `command card: dropped ${card.dropped.join(', ')} to stay within ${CARD_LIMIT_BYTES} bytes`,
-    );
-  }
-  // Inferability (R09). A marked line leaves when the repository proves the evidence it
-  // names. `shipped` is a separate list from `packed` because they are separate decisions:
-  // the kernel is about which classes cost a reader nothing to skip, and this is about
-  // which lines the reader already knows.
-  const inferable = [];
-  const shipped = [];
-  const variantsSelected = [];
-  let enforced = 0;
-  for (const r of packed) {
-    const variantFolded = foldVariants(r.body, r.id ?? '', lockedVariants);
-    const filtered = filterInferable(variantFolded.body, proofs);
-    const folded = foldChecks(filtered.body);
-    enforced += folded.enforced.length;
-    variantsSelected.push(...variantFolded.selected);
-    if (!variantFolded.changed && !filtered.changed && !folded.changed) {
-      shipped.push(r);
-      continue;
-    }
-    for (const x of filtered.removed) inferable.push({ rule: r.id, text: x.text, expr: x.expr });
-    shipped.push({ ...r, body: folded.body });
-  }
-  // A body that points the reader at a profile they cannot reach is a rule-text defect:
-  // the region renders, but the reference dangles. Kept out of `problems` because that
-  // array is the mdc list `sync` already reports, and one fault must not print twice.
-  const crossRefs = [];
-  const selectedIds = new Set(selected.map((r) => r.id));
-  for (const r of shipped) {
-    for (const p of crossRefProblems(r.body, all, selectedIds)) {
-      crossRefs.push(`${r.id}: ${p}`);
-    }
-  }
-  const lockedNonDefault = variantsSelected.filter((v) => v.locked && v.winner !== v.baseline);
-  if (lockedNonDefault.length > 0) {
-    notes.push(
-      `variants: applied ${lockedNonDefault.length} locked variant(s) (${lockedNonDefault.map((v) => `${v.slotId}=${v.winner}`).join(', ')})`,
-    );
-  }
-  if (enforced > 0) {
-    notes.push(
-      `enforced: ${enforced} line(s) left the region because a checker runs them`,
-    );
-  }
-  if (inferable.length > 0) {
-    // Never silent, and never a heading. A line that left with no trace repeats the
-    // mistake ADR-073 rejected for deferred rules, and a `## Dropped` section spends region
-    // bytes on lines the reader is being told not to read. A count they can act on, plus —
-    // with `--explain` — the evidence behind each one, is the third option.
-    notes.push(
-      `inferability: dropped ${inferable.length} line(s) this repository already proves; ${CLI} sync --explain names each one and the evidence behind it`,
-    );
-    if (flags?.explain === true) {
-      for (const x of inferable) {
-        notes.push(`inferable: ${x.rule} dropped "${x.text}" — proved by ${x.expr}`);
-      }
-    }
-  }
-  const folded = foldsRules(resolved) ? bodies.map(({ rule }) => rule.id) : [];
-
-  // The workspace-shared rules this repository declared (ADR-084).
-  //
-  // Read from the manifest and never from the reader's home directory, because this
-  // function is what `sync` and `check` both call: a region that depended on what
-  // somebody had installed would render differently on a machine where they had not,
-  // and CI would report drift on a tree `sync` had just written. The ids travel in the
-  // manifest so the answer to "what leaves this region" is a fact about the repository.
-  const declared = declaredShared(manifest);
-  const carriedIds = new Set(declared.level === null ? [] : [...declared.rules]);
-
-  // Every rule the workspace carries, as the rule objects the index below names. Both
-  // lists, because a surface that folds its rules into the primary document carries the
-  // canonical process bodies in that document too — and a reader who cannot find
-  // `slice-commit` anywhere near their repository will look for it in AGENTS.md.
-  const carried = [
-    ...shipped.filter((r) => carriedIds.has(r.id)).map((rule) => ({ rule, kind: 'profile' })),
-    ...bodies.filter(({ rule }) => carriedIds.has(rule.id)).map(({ rule }) => ({ rule, kind: 'process' })),
-  ];
-
-  // The rules this root would carry in its region, with the bytes it would carry them
-  // in — the input ADR-084's workspace intersection compares.
-  //
-  // Computed from `shipped` rather than from what the region ends up carrying, and that
-  // is the whole reason it is computed at all: a rule already declared shared must still
-  // appear here, or a second `shared install` would intersect against a list that no
-  // longer contained it and shrink the shared file every time anybody ran the command.
-  // The declaration is an input to the region; it is not an input to what is shareable.
-  const shareable = [
-    // Only the rules this package ships. A repository's own profile, or a pack it
-    // installed, is policy somebody chose to write: carrying it into a shared home file
-    // would mean editing that file to change a repository's rules, and the copy would
-    // reach every other repository in the estate that declared the same id. A rule
-    // somebody can override must stay somewhere they own.
-    ...shipped
-      .filter((r) => r.error === null && toolRule(r) && typeof r.id === 'string' && r.id !== '')
-      .map((r) => ({
-        id: r.id,
-        source: r.source,
-        priority: r.priority ?? null,
-        rendered: frameSource(r, stripFrontmatter(r.body).trim(), 'profile'),
-      })),
-    // The folded process bodies, and only while they are folded. A surface that writes
-    // one file per rule expects that file at a path inside the repository, so a
-    // user-level copy cannot stand in for it — but when the surface folds the whole region
-    // into the primary document, those bytes are as repeated across a workspace as the
-    // profiles are, and `tokens --repos` named them as the last duplicate block in a
-    // two-repository measurement.
-    ...bodies
-      .filter(({ rule }) => folded.includes(rule.id) && toolRule(rule))
-      .map(({ rule, body }) => ({
-        id: rule.id,
-        source: rule.source,
-        priority: rule.priority ?? null,
-        rendered: frameSource(rule, body, 'process'),
-      })),
-  ].filter((r) => r.rendered !== '');
-
-  // The selected rules that are not shareable, with the reason. `shared plan` reporting
-  // only what it carries would imply every profile in the workspace had been accounted
-  // for, and a reader whose own house rule is missing from the list would conclude it
-  // moved — so the names it did not take, and why, are data rather than an omission.
-  const shareableIds = new Set(shareable.map((r) => r.id));
-  const excluded = selected
-    .filter((r) => typeof r.id === 'string' && r.id !== '' && !shareableIds.has(r.id))
-    .map((r) => ({
-      id: r.id,
-      why: r.error !== null ? 'error' : toolRule(r) ? 'empty' : 'policy',
-    }));
-
-  // The budget, and the bytes held back for what loads beside the region.
-  //
-  // Read from the manifest rather than from the plan's spelling of it. Plan 0003 R08
-  // wrote `projection.budget.bytes`, and ADR-072 moved the key to the top level because
-  // `projection` is a generated key `upgrade` replaces wholesale - a budget that reset
-  // itself on upgrade would reset the reader's context size without anyone asking. The
-  // plan is not edited: the key it names is wrong, and a ruling that supersedes it is
-  // the record of why.
-  const budget = declaredBudget(manifest);
-  // Names and triggers only. Read once, outside the packer, because a skill does not
-  // change as rules are cut and reading its body here would put the cost back into the
-  // region the index exists to keep it out of (ADR-085).
-  const skills = await installedSkills(root);
-
-  // The digest is needed before the region can be weighed rather than after, because the
-  // provenance header is part of what lands in the file. `provenanceDigest` is a pure
-  // function of the bytes this package ships, so computing it once and passing it down is
-  // the same value the tail of this function was getting on its own.
-  const sha = await provenanceDigest();
-
-  /**
-   * The region, assembled from whatever survived the budget (ADR-083).
-   *
-   * One function, called once for the whole projection and again for each attempt the
-   * packer makes, so a cut region and an uncut one are the same document by construction
-   * rather than by two functions agreeing. The card, the inferability notes, the folded
-   * process bodies and the disclosure index are not candidates for a cut: a budget is a
-   * decision about rules, and dropping the index would hide the rules the cut removed.
-   */
-  const assemble = (cut) => {
-    // A rule the workspace carries once leaves the region, and so does a rule the packer
-    // could not afford. Both are exclusions from the same list, so the section below can
-    // name all three reasons — which is the only reason the section exists: a reader who
-    // opens AGENTS.md and does not find a rule they know is there will look for it.
-    const kept = shipped.filter((r) => !cut.has(r.id) && !carriedIds.has(r.id));
-    // Stable bytes first (ADR-086). Core, then the profiles this package ships, then
-    // everything this repository added — the card, its own profiles, the process
-    // bodies. A line the repository edits then changes only the tail, and the prefix
-    // a reader has cached stays byte-identical. The card used to lead (ADR-077 ruling
-    // 1); it now leads the tail, because a command this repository owns is the thing
-    // an edit is most likely to move.
-    const stable = kept.filter((r) => toolRule(r)).sort(stableOrder);
-    const repoRules = kept.filter((r) => !toolRule(r)).sort((a, b) => String(a.id).localeCompare(String(b.id)));
-    let text = render(stable);
-    if (card.text) text += `${text === '' ? '' : '\n\n'}${card.text}`;
-    // The pointer follows the card: the card says what this repository runs, and the
-    // pointer says how the tool serves a task. Adjacent, they read as one block of
-    // repo-facing advice instead of two facts the reader has to connect.
-    text += `${text === '' ? '' : '\n\n'}${ORIENTATION_POINTER}`;
-    const repoText = render(repoRules);
-    if (repoText) text += `\n\n${repoText}`;
-    const sources = [...stable, ...repoRules].map((r) => r.source);
-
-    // Every reason a rule is missing lands in this one section, and each line says which
-    // it was. A rule deferred by its class, a rule cut to reach a byte count and a rule
-    // the workspace carries once are three different decisions, but they are the same fact
-    // to a reader — it is not in this file — and three headings would spend region bytes
-    // on structure nobody can act on. The line names the command that shows the rule,
-    // because for all three the remedy is the same single read.
-    //
-    // The label is the rule's own frame title, which is why each entry carries the kind it
-    // is rendered as: a canonical rule that the surface folds in is `Process: <id>` in the
-    // shared file, and an index that calls it `Stack:` sends the reader looking for the
-    // wrong thing.
-    const omitted = [
-      ...deferred.map((r) => ({ rule: r, kind: 'profile', why: `${r.priority ?? 'unclassified'}, deferred in kernel mode` })),
-      ...shipped
-        .filter((r) => cut.has(r.id))
-        .map((r) => ({
-          rule: r,
-          kind: 'profile',
-          why: `${r.priority ?? 'unclassified'}, cut to fit the declared budget of ${budget} bytes`,
-        })),
-      ...carried.map(({ rule, kind }) => ({
-        rule,
-        kind,
-        // No path here, deliberately. This text is rendered by `sync` in CI, where the
-        // reader's home directory is somebody else's, and a path is the one thing in a
-        // remedy that cannot be true on both. The remedy is a command that works on the
-        // machine the reader is on.
-        why: `${rule.priority ?? 'unclassified'}, carried once per workspace in your reader's user-level rules file instead; if your reader has no copy, run: ${CLI} shared install`,
-      })),
-    ];
-    if (omitted.length > 0) {
-      // The pointer is the same shape as the scoped one above, and for the same reason:
-      // a reader who opens AGENTS.md and does not find a rule they know is there will
-      // look for it. What it costs to find it has to be one command, named per rule.
-      const lines = omitted
-        .sort((a, b) => byPriorityThenId(a.rule, b.rule))
-        .map(
-          ({ rule, kind, why }) =>
-            `- ${sourceTitle(rule, kind)} — ${why}. Show it with: ${CLI} rules show ${rule.id}`,
-        );
-      // `## Rules not in this region`, not `## Deferred rules`. The heading was written
-      // when there was one reason to be here (ADR-073) and it is region text a reader
-      // reads, so a heading that names one of three reasons misdescribes the two others
-      // (ADR-084).
-      text += `\n\n## Rules not in this region\n\n${lines.join('\n')}`;
-      for (const { rule } of omitted) sources.push(rule.source);
-    }
-
-    if (folded.length > 0) {
-      for (const { rule, body: ruleBody } of bodies) {
-        // A body the workspace carries once is not folded in here either. The heading is
-        // about how the surface loads the region, so it stays; the rule under it does not,
-        // and a region that carried the same bytes twice is the redundancy ADR-084 exists
-        // to remove — reintroduced by the feature that removes it.
-        if (carriedIds.has(rule.id)) continue;
-        // `## Process:`, not `### id`. The body already uses `##`, and a third-level
-        // heading in front of a second-level one is the break a reader cannot repair.
-        text += `\n\n${frameSource(rule, ruleBody, 'process')}`;
-        sources.push(rule.source);
-      }
-    }
-
-    // Last, because this is the index of what the file deliberately does not contain
-    // (ADR-085). A scoped profile keeps the pointer ADR-071 requires — its patterns and
-    // the files it moved to — and a skill keeps its name and the description that says
-    // when to open it. The body of either is the thing that was moved out.
-    const disclosure = [];
-    if (scoped.length > 0 && narrowing) {
-      for (const r of scoped) {
-        disclosure.push(
-          `- ${sourceTitle(r, 'profile')} — loads only when a matching file is in play (${r.scope.join(', ')}): ${scopedPaths(r, resolved).join(', ')}`,
-        );
-        sources.push(r.source);
-      }
-    }
-    const skillNames = new Map();
-    for (const skill of skills) skillNames.set(skill.name, (skillNames.get(skill.name) ?? 0) + 1);
-    for (const skill of skills) {
-      const label = skillNames.get(skill.name) > 1 ? `${skill.name} (${skill.dir})` : skill.name;
-      disclosure.push(
-        skill.trigger === ''
-          ? `- ${label} — no description, so nothing says when to open it. Show it with: ${CLI} skills show ${skill.name}`
-          : `- ${label} — ${skill.trigger}`,
-      );
-    }
-    if (disclosure.length > 0) text += `\n\n## Disclosure\n\n${disclosure.join('\n')}`;
-
-    return { body: text, sources };
-  };
-
-  // What the region will weigh in the file it lands in, measured the way the meter
-  // measures it: the composed region text, markers and provenance header included. One
-  // byte conservative, because the file's own trailing newline falls outside the span —
-  // and conservative in that direction is the only direction a ceiling can afford.
-  const regionBytes = (assembled) =>
-    Buffer.byteLength(compose(assembled.body, { sha, sources: assembled.sources }));
-
-  let assembled = assemble(new Set());
-  let packing = null;
-  if (mode === 'kernel') {
-    const reserve = await budgetReserve(root, resolved, bodies, sha);
-    const result = packToBudget({
-      // Least valuable first: the comparator the deferred section already uses, reversed.
-      // Class decides and the id breaks the tie, so the cut order is a fact about the
-      // repository rather than about the order the filesystem listed files in.
-      //
-      // The workspace-shared rules are not candidates, and that is not a rounding: cutting
-      // one cannot make the region smaller by more than the index line it adds to the
-      // section below, because the rule is carried once per workspace whatever this region
-      // does. A packer that spent its budget on them would report a saving it did not make.
-      candidates: shipped
-        .filter((r) => !carriedIds.has(r.id))
-        .sort((a, b) => -byPriorityThenId(a, b)),
-      ceiling: budget - reserve,
-      costs: (cut) => regionBytes(assemble(cut)),
-    });
-    packing = { ...result, bytes: budget, ceiling: budget - reserve, reserve };
-    if (result.cut.length > 0) assembled = assemble(new Set(result.cut));
-    if (result.cut.length > 0) {
-      notes.push(
-        `budget: cut ${result.cut.length} kernel rule(s) — ${result.cut.join(', ')} — from ${result.before} to ${result.after} bytes against a declared budget of ${budget}, with ${reserve} reserved for the generated files that load beside the region`,
-      );
-    }
-    if (result.floorHeld) {
-      // The one case the packer cannot fix, said where the reader will see it. `hard` is
-      // the floor, so the bytes still over the line are this repository's own hard
-      // constraints and the only levers left are its own: a larger budget, or a rule that
-      // is not as hard as it is declared. ADR-072's kernel finding says both; this says
-      // they were tried first.
-      notes.push(
-        `budget: still ${result.after} bytes after every rule outside the hard class was cut, against a ceiling of ${budget - reserve}; a hard constraint is not cut to reach a byte count, so the kernel itself is over the line`,
-      );
-    }
-    if (result.floorHeld && reserve >= budget) {
-      // A ceiling of zero or less is arithmetically true and useless to read: it says the
-      // region is allowed no bytes, without saying that the files loading beside it have
-      // already spent the whole budget. One number in that manifest is the only lever, and
-      // a reader left to infer it from a subtraction is a reader who will demote a hard
-      // rule to fix a budget that was set below the files it covers.
-      notes.push(
-        `budget: the ${reserve} bytes reserved for the generated files that load beside the region already reach the ${budget} declared, so no cut order meets this budget and the region is cut as far as the hard class allows`,
-      );
-    }
-  }
-
-  const meta = {
-    sha,
-    sources: assembled.sources,
-  };
-  return {
-    stack,
-    facts,
-    manifest,
-    all,
-    profiles: selected.map((r) => r.id),
-    folded,
-    mode,
-    deferred: deferred.map((r) => r.id),
-    // What the workspace carries once per reader instead of here (ADR-084), as ids. The
-    // declaration is what `check` and `sync` both read to decide the region, so the ids
-    // that actually left are reported for the same reason the budget's cuts are: a rule
-    // that disappeared needs a name in the output, or a reader looks for it in vain.
-    carried: carried.map(({ rule }) => rule.id),
-    // What this root could contribute to a workspace's shared file, with the bytes it
-    // would contribute. Read by `simt shared`, never by the projection — which is why
-    // computing it costs a frame per rule and buys nothing on `sync`.
-    shareable,
-    // What it selected and cannot contribute, with the reason. Reported so that a rule
-    // staying in the region is always a decision somebody can see rather than an absence.
-    excluded,
-    // What the budget cost this projection (ADR-083), or null in `full` mode where no
-    // ceiling is applied because nothing is cut. The finding and `simt tokens` both read
-    // this rather than re-deriving it, so a cut cannot be reported one way and measured
-    // another.
-    budget: packing === null
-      ? null
-      : {
-          bytes: packing.bytes,
-          ceiling: packing.ceiling,
-          reserve: packing.reserve,
-          before: packing.before,
-          after: packing.after,
-          floorHeld: packing.floorHeld,
-          cuts: shipped
-            .filter((r) => packing.cut.includes(r.id))
-            .map((r) => ({ id: r.id, priority: r.priority ?? 'unclassified' })),
-        },
-    // The marked lines that left, each with the evidence that dropped it. The region is
-    // written without them; `--explain` is what reads this list, so a removal is reportable
-    // without spending region bytes and without a second computation to find it.
-    inferable,
-    // The profiles that left the region, and the surfaces that accepted them as files.
-    // `plan` writes them and `checkTarget` gates them through this list, so a projected
-    // file and a drifted one are decided by the same computation.
-    scoped,
-    narrowing,
-    surfaces: resolved.ids,
-    surfaceSource: resolved.source,
-    problems,
-    crossRefs,
-    fallback,
-    notes,
-    body: assembled.body,
-    meta,
-  };
-}
-
-/**
- * The bytes held back from the region's own ceiling for the always-on files that load
- * beside it.
- *
- * The budget is one number for a repository, not for one file, so packing the region
- * against the whole number would ship a projection that fits on its own and pushes the
- * total over the line the moment its rule files are written. Both terms below are lower
- * bounds on what that costs, and the larger is taken because the failure each one covers
- * is the one that must not happen: under-reserving reports compliance for a projection
- * that is over budget.
- *
- * The region's own span is deliberately not in either. It is the one number that moves
- * when this projection is packed, and a ceiling that depended on the thing it governs
- * would rewrite the region on the next run and report drift on a tree `sync` had just
- * written - the step-6 defect, rebuilt one layer up.
- *
- * @param {string} root
- * @param {object} resolved the surfaces this projection writes for
- * @param {{rule: object, body: string}[]} bodies the rule bodies being projected
- * @param {string} sha the provenance digest those files will be stamped with
- * @returns {Promise<number>}
- */
-async function budgetReserve(root, resolved, bodies, sha) {
-  // Imported here rather than at the top of the module: `measure/context.mjs` reaches back
-  // into `projection/project.mjs` for the read-limit findings, so a static import from
-  // `rules.mjs` closes a loop through three modules that all have to survive being loaded
-  // in any order. The loop between the other two already exists and is load-bearing in
-  // neither direction; this one is walked only when a kernel is being packed.
-  const { measureRoot } = await import('../measure/context.mjs');
-  const measured = await measureRoot(root);
-  const region = measured.documents.find((d) => d.channel === 'region');
-  const installed = Math.max(0, measured.generatedBytes - (region?.generatedBytes ?? 0));
-
-  // What this projection is about to write, for a repository that has not written it yet.
-  // `ruleTargets` is the one place a rule file is turned into bytes, so the number comes
-  // from there rather than from a second measurement of the same file — and its notes go
-  // nowhere, because `mdcTargets` reports the same ones for the same files in the same run.
-  let planned = 0;
-  for (const { rule, body } of bodies) {
-    for (const target of (await ruleTargets(root, rule, body, sha, resolved, [])).targets) {
-      planned += target.bytes;
-    }
-  }
-  return Math.max(installed, planned);
-}
-
-/**
- * Every per-rule file a scoped profile is written to, as paths a reader can open.
- *
- * Only the surfaces that can scope get one: a Cursor `.mdc` with `globs` and
- * `alwaysApply: false`, an Antigravity file with `trigger: glob`, a Copilot
- * `.instructions.md` with `applyTo`. A surface that reads the region already (opencode)
- * has no file channel at all, and Claude's scoping key is the documented-defect one,
- * so neither appears here.
- */
-function scopedPaths(rule, resolved) {
-  const out = [];
-  for (const s of resolved.surfaces) {
-    if (!canScope(s) || !s.rule) continue;
-    // A folded surface already carries the whole region; it is the reason this profile
-    // is only a file when folding is off, which is the caller's question to answer.
-    if (s.foldRules === true && s.readsPrimary === true && foldsRules(resolved)) continue;
-    out.push(rulePath(s.id, rule.id));
-  }
-  return out;
-}
-
 /**
  * Read every rule file once, with its frontmatter parsed, plus any repo-local
  * profile under `.simt/profiles/`.
@@ -1287,7 +759,7 @@ export function render(selected) {
  * yet says a kernel does not lose compliance (plan 0003 R02), so the mode that changes
  * what a reader gets cannot be the one nobody chose.
  */
-async function projectionMode(root) {
+export async function projectionMode(root) {
   const { manifest } = await readManifest(root);
   return manifest?.mode === 'kernel' ? 'kernel' : 'full';
 }
@@ -1301,7 +773,7 @@ async function projectionMode(root) {
  */
 /** Core, then the remaining shipped profiles by id. Id, not load order: a directory
  *  listing is not a fact about the rules, and two machines must not disagree about it. */
-function stableOrder(a, b) {
+export function stableOrder(a, b) {
   if (a.id === 'core') return b.id === 'core' ? 0 : -1;
   if (b.id === 'core') return 1;
   return String(a.id).localeCompare(String(b.id));
@@ -1325,7 +797,7 @@ export function byPriorityThenId(a, b) {
  * substitutes it, so a rename of the file is a change in one place (MANIFEST_FILE),
  * not a search across every rule body.
  */
-function frameSource(rule, body, kind) {
+export function frameSource(rule, body, kind) {
   const text = demoteHeadings(body.replaceAll('{manifest}', MANIFEST_FILE)).trim();
   if (!text) return '';
   const title = sourceTitle(rule, kind);
@@ -1333,7 +805,7 @@ function frameSource(rule, body, kind) {
   return `## ${title}\n\n${text}`;
 }
 
-function sourceTitle(rule, kind) {
+export function sourceTitle(rule, kind) {
   if (!rule?.id) return null;
   if (kind === 'process') return `Process: ${rule.id}`;
   if (rule.id === 'core') return 'Core';
@@ -1348,7 +820,7 @@ function sourceTitle(rule, kind) {
  * backtick-quoted `<id> profile` in prose, and the `simt rules show <id>`
  * command itself - an id that form names must exist, or the command 404s.
  */
-function crossRefProblems(body, all, selectedIds) {
+export function crossRefProblems(body, all, selectedIds) {
   const problems = [];
   const seen = new Set();
   for (const m of String(body).matchAll(/`([a-z0-9][a-z0-9-]*)`\s+profile|rules show ([a-z0-9][a-z0-9-]*)/g)) {
@@ -1385,10 +857,10 @@ function demoteHeadings(text) {
 }
 
 function parseFrontmatter(text) {
-  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
-  if (!m) return {};
+  const { front } = splitBlock(text);
+  if (front === null) return {};
   const out = {};
-  for (const line of m[1].split('\n')) {
+  for (const line of front.split('\n')) {
     const kv = /^([a-zA-Z-]+):\s*(.*)$/.exec(line);
     if (!kv) continue;
     const [, key, raw] = kv;
@@ -1414,12 +886,10 @@ function parseFrontmatter(text) {
 
 /** Frontmatter and the duplicated H1 are dropped: the region is embedded in a
  *  host document that already has a title, so repeating it wastes context. */
-function stripFrontmatter(text) {
+export function stripFrontmatter(text) {
   // The frontmatter strip must also swallow the blank lines that follow it, or
   // the H1 strip's `^` anchor lands on a newline and silently matches nothing.
-  return text
-    .replace(/^---\n[\s\S]*?\n---\n*/, '')
+  return stripBlock(text)
     .replace(/^#\s+.*\n+/, '')
     .trim();
 }
-