devflow-kit 3.9.0 → 3.11.0

package/dist/core/mds-variants.js

@@ -21,13 +21,26 @@
  *   5. Which files does the shipped registry produce, flattened into the manifest
  *      an installer converges to? (generatedReferenceManifest — the one answer
  *      that asserts instead of returning a Result; see the function for why.)
+ *      The same question for a machine with compliance off is answered by
+ *      installedReferenceManifest({ compliance: false }): the manifest minus the
+ *      references of the posting operations (POSTING_OPS) and the publication gate.
+ * Two more questions serve the compliance-off references the build writes beside
+ * the compliance-on ones: which relative paths a compliance-off install omits
+ * (complianceOffOmittedRelPaths), and what each compliance arm of one operation's
+ * section keeps (splitSectionArms).
+ * A last group serves the workflow skill folders: which hosts make up a folder and
+ * which files each variant key holds (WORKFLOW_FOLDERS, workflowFolderFiles), and the
+ * build id that ties the files of one folder and key together (workflowBuildId,
+ * stampBuildId, unstampBuildId, checkFolderBuildIds, verifyFolderBuildId).
  * It still performs no I/O and no iteration over the filesystem.
  *
  * The `-variants` in the filename names the variant-expansion entry point below
  * (DR-16), which lives next to the validation it depends on.
  */
+import { createHash } from 'crypto';
 import * as path from 'path';
 import { isContainedIn } from './paths.js';
+import { COMPLIANCE_OFF_OUTPUT_DIR, OFF_OUTPUT_DIRS, machineVariantKey, splitVariants, } from './curation-variants.js';
 function Ok(value) {
     return { ok: true, value };
 }
@@ -101,13 +114,42 @@ export function validateContractOutputName(name) {
         return Ok(name);
     return Err(inner.error.kind === 'empty' ? { kind: 'empty' } : { ...inner.error, name });
 }
+/**
+ * The one name the core host of a workflow skill folder may emit: the stem of
+ * `SKILL.md`, the file name a skill's entry point has by convention.
+ */
+export const WORKFLOW_SKILL_ENTRY_NAME = 'SKILL';
+/**
+ * Validate the emitted basename of a workflow skill folder's CORE host: exactly the
+ * literal {@link WORKFLOW_SKILL_ENTRY_NAME}.
+ *
+ * D-WORKFLOW-SKILL-NAME: a THIRD name rule, beside validateOutputName and
+ * validateContractOutputName, and OUTPUT_NAME_RE stays as it is. The literal is
+ * uppercase, which the ordinary rule refuses on purpose for every command, agent and
+ * reference, so relaxing the shared rule would have admitted `Implement.md` as a
+ * command name too, across all four build destinations, to buy a name only this one
+ * file needs. A closed set of one is a literal comparison, not a pattern.
+ *
+ * Every other name is refused with the ordinary rule's diagnosis where it has one
+ * (empty, traversal, separator), so those refusals cannot drift apart from their
+ * originals; a name the ordinary rule accepts is still refused here, as an
+ * invalid-charset name, because only the literal is allowed. The refusal reports the
+ * name AS WRITTEN.
+ */
+export function validateSkillOutputName(name) {
+    if (name === WORKFLOW_SKILL_ENTRY_NAME)
+        return Ok(name);
+    const ordinary = validateOutputName(name);
+    return Err(ordinary.ok ? { kind: 'invalid-charset', name } : ordinary.error);
+}
 /**
  * The only directories the MDS build may write into, each tagged with the host
  * variant it selects.
  *
  * `dist/commands` holds compiled slash commands; `dist/agents` holds agents
  * compiled from generator hosts; `dist/skills/git/references` holds the generated
- * `devflow:git` skill references. Adding an entry here is the single place a new
+ * `devflow:git` skill references; `dist/workflows` holds the compiled workflow skill
+ * folders. Adding an entry here is the single place a new
  * build destination becomes legal — and `satisfies` forces that entry to declare
  * a HostVariant, so no destination can arrive without saying how it is treated.
  */
@@ -159,10 +201,46 @@ export const SKILL_REFS_SKILL_NAME = 'git';
  * no reference module is planned — the same reason AGENTS_OUTPUT_DIR is exported.
  */
 export const SKILL_REFS_OUTPUT_DIR = `dist/skills/${SKILL_REFS_SKILL_NAME}/references`;
+/**
+ * Repo-relative root of the compliance-off references: the one source root a
+ * compliance-off install overlays from.
+ *
+ * It sits inside the compliance-off prompt tree (COMPLIANCE_OFF_OUTPUT_DIR), beside
+ * `commands/` and `agents/`, and mirrors SKILL_REFS_OUTPUT_DIR below that tree. It is
+ * deliberately NOT an entry of the allowlist below: the build writes it as a second
+ * output of a reference module, so no host can declare it as its `output-dir:`.
+ *
+ * The tree is complete, not a patch over the compliance-on one: it holds every file of
+ * `installedReferenceManifest({ compliance: false })`, a byte copy of the compliance-on
+ * file where the module has no compliance arm there. An installer that reads this root
+ * therefore never has to fall through to SKILL_REFS_OUTPUT_DIR (AC-50).
+ */
+export const COMPLIANCE_OFF_SKILL_REFS_OUTPUT_DIR = `${COMPLIANCE_OFF_OUTPUT_DIR}/skills/${SKILL_REFS_SKILL_NAME}/references`;
+/**
+ * The kind folder the workflow skill folders sit in: `dist/workflows`, and
+ * `<variant tree>/workflows` for every other variant key, as `commands` and `agents`
+ * are the kind folders of the prompts.
+ */
+export const WORKFLOW_FOLDERS_KIND = 'workflows';
+/**
+ * Repo-relative destination for `workflow-skill` hosts: the root that holds one folder
+ * per registered workflow skill, `dist/workflows/<folder>/…`.
+ *
+ * D-WORKFLOW-FOLDER-BUILD: a host declares this ROOT, never its folder. The folder and
+ * the file inside it come from the registry WORKFLOW_FOLDERS, for the reason a
+ * reference module's operations do: the names are a typed roster, not frontmatter.
+ * The off variants of a folder sit under the trees of the other variant keys
+ * (workflowFoldersRootRelPath), none of which is a destination a host may declare.
+ *
+ * Exported because the build's orphan prune names this tree even when no folder is
+ * registered, which is exactly the case where every folder in it is an orphan.
+ */
+export const WORKFLOW_FOLDERS_OUTPUT_DIR = `dist/${WORKFLOW_FOLDERS_KIND}`;
 const ALLOWED_OUTPUT_DIRS = [
     { dir: COMMANDS_OUTPUT_DIR, variant: 'commands' },
     { dir: AGENTS_OUTPUT_DIR, variant: 'agents' },
     { dir: SKILL_REFS_OUTPUT_DIR, variant: 'skill-refs' },
+    { dir: WORKFLOW_FOLDERS_OUTPUT_DIR, variant: 'workflow-skill' },
 ];
 /**
  * The allowlisted directory names, in declaration order, for error rendering.
@@ -325,6 +403,33 @@ export const PR_HOST_OPS = [
  * GitHub.
  */
 export const PR_HOST_DESTINATION_ROOT = 'pr';
+/**
+ * The eight Git operations that post to GitHub or to a tracker: the one roster of
+ * them. Posting steps are a compile-time variant keyed on the machine compliance
+ * switch alone, and this list says which reference files that variant drops.
+ *
+ * A compliance-off install carries no reference file of any of them: four under
+ * `pr/` and, for each of the three providers, four under `tracker/{provider}/`, which
+ * is 16 files. `check-merge-readiness` is deliberately absent: it reads state and
+ * posts nothing. The names are checked against the registry twice, once at compile
+ * time here (each is a PR-host or a tracker operation) and once at run time by
+ * {@link checkPostingOps}, because the manifest that omits them must fail closed: a
+ * name that matched no file would leave a posting reference in a compliance-off
+ * install without a signal.
+ *
+ * Tests take this list from here and never retype it
+ * (POSTING_OPERATIONS in tests/fixtures/mds-manifest.ts).
+ */
+export const POSTING_OPS = [
+    'post-review-summary',
+    'resolve-review-threads',
+    'post-resolution-summary',
+    'update-pr-evidence',
+    'manage-debt',
+    'post-wave-report',
+    'backlink-shipped-issues',
+    'associate-release',
+];
 /**
  * The cross-cutting `devflow:git` reference documents — provider-independent, so
  * they land at the root of the references directory rather than under
@@ -360,6 +465,13 @@ export const GIT_CROSS_CUTTING_DOCS = [
     'publication-gate',
     'trust-rule',
 ];
+/**
+ * The cross-cutting documents a compliance-off install omits besides the references
+ * of {@link POSTING_OPS}: `publication-gate` holds the D10 step order and is named
+ * from the two summary operations only, so once those are gone nothing loads it.
+ * A subset of {@link GIT_CROSS_CUTTING_DOCS}, checked at compile time.
+ */
+export const COMPLIANCE_OFF_OMITTED_DOCS = ['publication-gate'];
 /**
  * The Git operations whose one operation reference is a cross-cutting document
  * rather than a per-op file in `pr/` or `tracker/{provider}/` (D-OP-ONE-REF).
@@ -632,6 +744,10 @@ export function deferredReferenceModuleSources(modules = VARIANT_MODULES) {
  * VariantModuleKind for why a count proves nothing about a named document set.
  */
 export const MIN_VARIANT_PAIRS = 8;
+/** POSIX path, relative to SKILL_REFS_OUTPUT_DIR, of the file a module writes for one of its names. */
+function referenceRelPath(mod, op) {
+    return mod.subdir === '' ? `${op}.md` : `${mod.subdir}/${op}.md`;
+}
 /**
  * Expand reference modules into the flat `(module, op)` pair list the build
  * writes.
@@ -693,7 +809,7 @@ export function expandVariants(modules = resolveVariantModules()) {
             if (!nameResult.ok) {
                 return Err({ kind: 'invalid-op-name', module: mod.source, op, cause: nameResult.error });
             }
-            const relPath = mod.subdir === '' ? `${op}.md` : `${mod.subdir}/${op}.md`;
+            const relPath = referenceRelPath(mod, op);
             const claimants = claimedBy.get(relPath);
             if (claimants === undefined) {
                 claimedBy.set(relPath, [mod.source]);
@@ -755,12 +871,29 @@ export function generatedReferenceManifest() {
  * its sibling does (design review M3): the registry is a compile-time constant,
  * so a refusal is a programming error rather than an install-time degradation.
  *
+ * `compliance: false` is the install of a machine with compliance off: the same
+ * manifest without the references of the posting operations ({@link POSTING_OPS},
+ * 16 files) and without the publication gate document, which only those operations
+ * load. Any other value, and an absent option, is today's manifest. The omission
+ * fails closed: a posting name the registry does not carry asserts, because a name
+ * that matched no file would leave a posting reference in a compliance-off install.
+ *
  * @param opts.modules - Registry to expand (defaults to the shipped one, with the
  *   gated contract module resolved). Injectable so the refusal arm is provable
  *   without editing the registry.
+ * @param opts.compliance - `false` for the compliance-off install; the default is on.
  */
 export function installedReferenceManifest(opts = {}) {
-    return expandedManifest(opts.modules ?? resolveVariantModules());
+    const modules = opts.modules ?? resolveVariantModules();
+    const manifest = expandedManifest(modules);
+    if (opts.compliance !== false)
+        return manifest;
+    const omitted = complianceOffOmittedRelPaths(modules);
+    if (!omitted.ok) {
+        throw new Error(`${describePostingOpsError(omitted.error)}. POSTING_OPS and VARIANT_MODULES in ` +
+            `src/core/mds-variants.ts must agree.`);
+    }
+    return manifest.filter(rel => !omitted.value.has(rel));
 }
 /** Every relPath a registry expands to, or the assertion both manifests share. */
 function expandedManifest(modules) {
@@ -771,6 +904,94 @@ function expandedManifest(modules) {
     }
     return expanded.value.map(pair => pair.relPath);
 }
+/**
+ * Check a roster of posting operations against the registry: every name must be an
+ * operation of a fan-out module, and none may be listed twice.
+ *
+ * A named document is not an operation, so a document name is refused here: that
+ * keeps the posting roster from growing into a second list of documents to omit
+ * (those are {@link COMPLIANCE_OFF_OMITTED_DOCS}). The loop runs once over the roster
+ * given, so its bound is the roster's own length.
+ *
+ * @param ops - The roster to check (the shipped one is {@link POSTING_OPS}).
+ * @param modules - The registry to check it against.
+ */
+export function checkPostingOps(ops, modules) {
+    const registered = new Set(modules.filter(mod => mod.kind === 'fanout').flatMap(mod => mod.ops));
+    const seen = new Set();
+    for (const op of ops) {
+        if (seen.has(op))
+            return Err({ kind: 'duplicate-posting-op', op });
+        seen.add(op);
+        if (!registered.has(op))
+            return Err({ kind: 'unregistered-posting-op', op });
+    }
+    return Ok(ops);
+}
+/** Render a posting-roster refusal as one line, with a `never` default so a new kind cannot fall through. */
+export function describePostingOpsError(error) {
+    switch (error.kind) {
+        case 'unregistered-posting-op':
+            return (`posting operation '${error.op}' is not an operation of any fan-out reference module ` +
+                `in VARIANT_MODULES`);
+        case 'duplicate-posting-op':
+            return `posting operation '${error.op}' is listed twice in the posting roster`;
+        default: {
+            const unhandled = error;
+            return `unhandled posting roster refusal ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
+/**
+ * Does a compliance-off install omit the reference this module writes for `op`?
+ *
+ * A fan-out module's file is omitted when `op` is a posting operation; a named
+ * document is omitted when it is in {@link COMPLIANCE_OFF_OMITTED_DOCS}; the contract
+ * document is never omitted. The `never` default makes a fourth module kind answer
+ * the question here rather than inherit one of these answers.
+ */
+function omittedWhenComplianceOff(kind, op, postingOps) {
+    switch (kind) {
+        case 'fanout':
+            return postingOps.includes(op);
+        case 'named':
+            return COMPLIANCE_OFF_OMITTED_DOCS.includes(op);
+        case 'contract':
+            return false;
+        default: {
+            // A kind added to VariantModuleKind stops compiling at the next line. If one
+            // reached run time anyway it fails closed: its reference is left out.
+            const unhandled = kind;
+            void unhandled;
+            return true;
+        }
+    }
+}
+/**
+ * The relative paths (under the references root) a compliance-off install omits, for
+ * a registry: every file of a posting operation, and the omitted documents.
+ *
+ * The one owner of the omission. The compliance-off manifest filters by it, and the
+ * build decides from it which references get a compliance-off copy, so the manifest an
+ * installer converges to and the tree the build writes cannot drift apart.
+ *
+ * @param modules - The registry to read.
+ * @param postingOps - The posting roster (defaults to {@link POSTING_OPS}); injectable
+ *   so the refusal of a bogus roster is provable without editing the shipped one.
+ */
+export function complianceOffOmittedRelPaths(modules, postingOps = POSTING_OPS) {
+    const checked = checkPostingOps(postingOps, modules);
+    if (!checked.ok)
+        return Err(checked.error);
+    const omitted = new Set();
+    for (const mod of modules) {
+        for (const op of mod.ops) {
+            if (omittedWhenComplianceOff(mod.kind, op, postingOps))
+                omitted.add(referenceRelPath(mod, op));
+        }
+    }
+    return Ok(omitted);
+}
 // ---------------------------------------------------------------------------
 // Section splitting — which slice of a module's compiled body belongs to which op
 // ---------------------------------------------------------------------------
@@ -874,4 +1095,480 @@ export function splitVariantSections(body, entries) {
     }
     return Ok(out);
 }
+/** A variant body as a reference file holds it: trimmed, one trailing newline, or empty when it has no text. */
+function settleSectionBody(body) {
+    const trimmed = body.trim();
+    return trimmed === '' ? '' : `${trimmed}\n`;
+}
+/**
+ * Split one operation's section on its compliance arms.
+ *
+ * The caller has already split the module into operation sections
+ * (splitVariantSections), so an arm that runs across two sections is an unclosed arm
+ * in the first and an unopened end in the second, and each is refused here with the
+ * operation it is in. Each variant is settled the way splitVariantSections settles a
+ * section, so a section with no arm gives both variants its own bytes.
+ *
+ * Curation is outside this split: the splitter keeps the curation-on text in both
+ * bodies, and the build refuses a curation marker in a reference module before it
+ * gets here.
+ *
+ * Total and pure: a refusal is a Result.
+ *
+ * @param op - The operation, for the refusal.
+ * @param content - The settled section from splitVariantSections.
+ * @param opts.complianceOffWritten - Whether the build writes a compliance-off file
+ *   for this operation. A variant that is written must have text; an operation the
+ *   compliance-off install omits writes none, and its compliance-off body may be empty.
+ */
+export function splitSectionArms(op, content, opts) {
+    const split = splitVariants(content);
+    if (!split.ok)
+        return Err({ kind: 'arm-split', op, error: split.error });
+    const on = settleSectionBody(split.value.bodies.on);
+    const complianceOff = settleSectionBody(split.value.bodies['compliance-off']);
+    if (on === '')
+        return Err({ kind: 'empty-variant', op, variant: 'on' });
+    if (opts.complianceOffWritten && complianceOff === '') {
+        return Err({ kind: 'empty-variant', op, variant: 'compliance-off' });
+    }
+    return Ok({ on, complianceOff });
+}
+// ---------------------------------------------------------------------------
+// Workflow skill folders: the registry, the files of each variant key, the build id
+// ---------------------------------------------------------------------------
+/** The compiled name of a folder's core host: the skill's entry file. */
+export const WORKFLOW_SKILL_FILE = `${WORKFLOW_SKILL_ENTRY_NAME}.md`;
+/**
+ * The subfolder of reference files that sit outside the build id: they are read on
+ * demand by link, not as part of the skill's own text, and they ship byte-equal to
+ * their compiled body.
+ */
+export const WORKFLOW_REFERENCES_DIR = 'references';
+/**
+ * The workflow skill folders this build compiles.
+ *
+ * D-WORKFLOW-FOLDER-BUILD: the set is empty, and the build layer ships with it empty.
+ * No host in src/assets becomes a folder until a folder is registered here, so every
+ * file the build wrote before is byte-identical. A host that declares the workflow
+ * root without a row here is refused, which is what keeps a folder from appearing by
+ * accident. The registry is a typed roster rather than frontmatter for the reason the
+ * git reference modules' roster is: the folder and file names are decided in one
+ * reviewed place.
+ */
+export const WORKFLOW_FOLDERS = [];
+/** Every host of a folder, the core first, then the references in registry order. */
+export function workflowFolderHosts(folder) {
+    return [
+        { source: folder.core, file: WORKFLOW_SKILL_FILE, role: 'core', omittedWhenComplianceOff: false },
+        ...folder.references.map((ref) => ({
+            source: ref.source,
+            file: ref.file,
+            role: 'reference',
+            omittedWhenComplianceOff: ref.omittedWhenComplianceOff === true,
+        })),
+    ];
+}
+/** The host a repo-relative source path is registered as, and its folder; null when no folder lists it. */
+export function findWorkflowFolderHost(folders, source) {
+    for (const folder of folders) {
+        const host = workflowFolderHosts(folder).find(h => h.source === source);
+        if (host !== undefined)
+            return { folder, host };
+    }
+    return null;
+}
+/**
+ * A repo-relative POSIX `.mds` path that stays inside the repo: no backslash, no
+ * leading slash, no dot segment, spelled canonically.
+ */
+function isRepoRelativeMdsSource(source) {
+    return source.endsWith('.mds')
+        && !source.includes('\\')
+        && !path.posix.isAbsolute(source)
+        && !source.startsWith('../')
+        && path.posix.normalize(source) === source;
+}
+/**
+ * Validate the compiled name of a reference file: `<name>.md` or `references/<name>.md`,
+ * with the ordinary output-name rule on the stem. `SKILL` is refused by that rule (it is
+ * uppercase), so the entry file belongs to the core host alone.
+ */
+function validateWorkflowReferenceFile(file) {
+    const prefix = `${WORKFLOW_REFERENCES_DIR}/`;
+    const bare = file.startsWith(prefix) ? file.slice(prefix.length) : file;
+    if (!bare.endsWith('.md'))
+        return Err({ kind: 'invalid-charset', name: file });
+    const stem = validateOutputName(bare.slice(0, -'.md'.length));
+    if (stem.ok)
+        return Ok(file);
+    return Err(stem.error.kind === 'empty' ? { kind: 'empty' } : { ...stem.error, name: file });
+}
+/**
+ * Check a registry: every folder and file name is safe to join onto a build
+ * destination, every source is a repo-relative `.mds` path, and no folder, source or
+ * file is listed twice.
+ *
+ * Total and pure. Each loop is bounded by the registry it is given.
+ */
+export function checkWorkflowFolders(folders) {
+    const folderNames = new Set();
+    const sources = new Set();
+    for (const folder of folders) {
+        const named = validateOutputName(folder.name);
+        if (!named.ok)
+            return Err({ kind: 'bad-folder-name', folder: folder.name, error: named.error });
+        if (folderNames.has(folder.name))
+            return Err({ kind: 'duplicate-folder', folder: folder.name });
+        folderNames.add(folder.name);
+        const files = new Set();
+        for (const host of workflowFolderHosts(folder)) {
+            if (!isRepoRelativeMdsSource(host.source)) {
+                return Err({ kind: 'bad-source', folder: folder.name, source: host.source });
+            }
+            if (sources.has(host.source))
+                return Err({ kind: 'duplicate-source', source: host.source });
+            sources.add(host.source);
+            if (host.role === 'reference') {
+                const file = validateWorkflowReferenceFile(host.file);
+                if (!file.ok)
+                    return Err({ kind: 'bad-file', folder: folder.name, file: host.file, error: file.error });
+            }
+            if (files.has(host.file))
+                return Err({ kind: 'duplicate-file', folder: folder.name, file: host.file });
+            files.add(host.file);
+        }
+    }
+    return Ok(folders);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseWorkflowReference(value, at) {
+    if (!isRecord(value))
+        return Err({ kind: 'malformed', at });
+    const { source, file, omittedWhenComplianceOff } = value;
+    if (typeof source !== 'string')
+        return Err({ kind: 'malformed', at: `${at}.source` });
+    if (typeof file !== 'string')
+        return Err({ kind: 'malformed', at: `${at}.file` });
+    if (omittedWhenComplianceOff !== undefined && typeof omittedWhenComplianceOff !== 'boolean') {
+        return Err({ kind: 'malformed', at: `${at}.omittedWhenComplianceOff` });
+    }
+    return Ok(omittedWhenComplianceOff === undefined ? { source, file } : { source, file, omittedWhenComplianceOff });
+}
+/**
+ * Parse a registry from untrusted data (JSON that crossed a process boundary) and
+ * check it: the shape first, then {@link checkWorkflowFolders}. Pure; a refusal
+ * names the path of the first malformed field.
+ */
+export function parseWorkflowFolders(value) {
+    if (!Array.isArray(value))
+        return Err({ kind: 'malformed', at: '$' });
+    const folders = [];
+    for (const [index, entry] of value.entries()) {
+        const at = `$[${index}]`;
+        if (!isRecord(entry))
+            return Err({ kind: 'malformed', at });
+        const { name, core, references } = entry;
+        if (typeof name !== 'string')
+            return Err({ kind: 'malformed', at: `${at}.name` });
+        if (typeof core !== 'string')
+            return Err({ kind: 'malformed', at: `${at}.core` });
+        if (!Array.isArray(references))
+            return Err({ kind: 'malformed', at: `${at}.references` });
+        const parsed = [];
+        for (const [refIndex, ref] of references.entries()) {
+            const result = parseWorkflowReference(ref, `${at}.references[${refIndex}]`);
+            if (!result.ok)
+                return Err(result.error);
+            parsed.push(result.value);
+        }
+        folders.push({ name, core, references: parsed });
+    }
+    return checkWorkflowFolders(folders);
+}
+/** Render a registry refusal as one line a person can act on. */
+export function describeWorkflowFolderError(error) {
+    switch (error.kind) {
+        case 'malformed':
+            return `the workflow folder registry is malformed at ${error.at}`;
+        case 'bad-folder-name':
+            return `workflow folder name '${error.folder}' is refused (${error.error.kind})`;
+        case 'duplicate-folder':
+            return `workflow folder '${error.folder}' is registered twice`;
+        case 'bad-source':
+            return `workflow folder '${error.folder}' lists '${error.source}', which is not a repo-relative .mds path`;
+        case 'duplicate-source':
+            return `the source '${error.source}' is listed twice in the workflow folder registry`;
+        case 'bad-file':
+            return `workflow folder '${error.folder}' names the file '${error.file}', which is refused (${error.error.kind})`;
+        case 'duplicate-file':
+            return `workflow folder '${error.folder}' names the file '${error.file}' twice`;
+        default: {
+            const unhandled = error;
+            return `unhandled workflow folder refusal ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
+/** A folder is complete for every key, so the key a machine reads is the one for its switches alone. */
+const FOLDER_ARMS = { curation: true, compliance: true };
+/**
+ * The variant key of the folder a machine with these switches reads.
+ *
+ * Unlike a prompt, a folder is complete under every key (a byte copy of the on text
+ * where no arm applies), so the key follows the switches alone and never depends on
+ * which arms a file carries. The mapping is machineVariantKey's, with every arm assumed
+ * present, so the key table has one owner.
+ */
+export function workflowFolderKey(switches) {
+    return machineVariantKey(switches, FOLDER_ARMS);
+}
+/** The keys whose folder omits the compliance-gated files: the ones that turn compliance off. */
+const COMPLIANCE_OFF_KEYS = new Set([true, false].map(curation => workflowFolderKey({ curation, compliance: false })));
+/**
+ * The files one variant key's folder holds, in registry order, the core first.
+ *
+ * The one owner of "which files does this key hold": the build plans a file's
+ * destination as absent exactly when it is not listed here, and checks each key's
+ * folder against this list. A key that lacks a file of its own list fails the build;
+ * a file the key's list leaves out is never required.
+ */
+export function workflowFolderFiles(folder, key) {
+    const complianceOff = COMPLIANCE_OFF_KEYS.has(key);
+    return workflowFolderHosts(folder)
+        .filter(host => !(complianceOff && host.omittedWhenComplianceOff))
+        .map(host => host.file);
+}
+/** Repo-relative POSIX root of the folders of one variant key: `dist/workflows`, or `<variant tree>/workflows`. */
+export function workflowFoldersRootRelPath(key) {
+    return key === 'on' ? WORKFLOW_FOLDERS_OUTPUT_DIR : `${OFF_OUTPUT_DIRS[key]}/${WORKFLOW_FOLDERS_KIND}`;
+}
+/** Repo-relative POSIX path of one file of one folder under one variant key. */
+export function workflowFolderRelPath(key, folder, file) {
+    return `${workflowFoldersRootRelPath(key)}/${folder}/${file}`;
+}
+/** Whether a file of a folder carries the build id. The reference files are outside it. */
+export function isStampedWorkflowFile(file) {
+    return !file.startsWith(`${WORKFLOW_REFERENCES_DIR}/`);
+}
+/** Length of the build id, in hex digits. */
+export const BUILD_ID_LENGTH = 12;
+/** The stamp as a heading carries it: a suffix on the first heading line. */
+const BUILD_STAMP_SUFFIX_RE = new RegExp(` \\[build ([0-9a-f]{${BUILD_ID_LENGTH}})\\]$`);
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * The build id of one folder under one variant key: the first {@link BUILD_ID_LENGTH}
+ * hex digits of the SHA-256 over the folder's compiled bodies as they stand BEFORE the
+ * stamp, sorted by file name.
+ *
+ * D-BUILD-ID: one id per folder and key, and nothing else goes into it: no timestamp,
+ * no per-file hash. The same sources therefore give the same id on every machine and
+ * every run, and any change to any file of the folder moves it. The digest covers
+ * every file of the key's folder, the reference files included, so a changed reference
+ * moves the id of its folder; only the STAMP skips them (isStampedWorkflowFile), which
+ * keeps those files byte-equal to their compiled bodies.
+ *
+ * The id can be recomputed from a stamped folder. The stamp drops the blanks that end
+ * the first heading line, so a stamped file enters the digest in that same form
+ * ({@link stampReadyBody}) and {@link unstampBuildId} gives back the exact text that was
+ * hashed. A body whose heading ends in blanks and one whose heading does not therefore
+ * share an id, as they share their stamped text.
+ *
+ * Each file enters the digest as its name, its length in bytes, then its body, each
+ * on a line of its own. The length makes the framing injective: two different sets of
+ * files cannot produce one byte stream by moving text across a file boundary.
+ */
+export function workflowBuildId(files) {
+    const hash = createHash('sha256');
+    for (const { file, body } of [...files].sort((a, b) => byCodeUnit(a.file, b.file))) {
+        const hashed = isStampedWorkflowFile(file) ? stampReadyBody(body) : body;
+        hash.update(`${file}\n${Buffer.byteLength(hashed, 'utf8')}\n`);
+        hash.update(hashed, 'utf8');
+        hash.update('\n');
+    }
+    return hash.digest('hex').slice(0, BUILD_ID_LENGTH);
+}
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+const HEADING_RE = /^#{1,6}[ \t]+\S/;
+/**
+ * Find the first ATX heading line, skipping a leading frontmatter block and every
+ * fenced code block, so a `# comment` in either is never mistaken for it. One pass over
+ * the lines, so the bound is the text's own length.
+ */
+function locateFirstHeading(text) {
+    const lines = text.split('\n');
+    let inFrontmatter = lines[0]?.replace(/\r$/, '') === '---';
+    let fence = null;
+    let offset = 0;
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.replace(/\r$/, '');
+        const start = offset;
+        offset += raw.length + 1;
+        if (inFrontmatter) {
+            if (index > 0 && line === '---')
+                inFrontmatter = false;
+            continue;
+        }
+        const opened = FENCE_RE.exec(line);
+        if (opened !== null) {
+            const marker = opened[1];
+            if (fence === null)
+                fence = marker;
+            else if (marker[0] === fence[0] && marker.length >= fence.length)
+                fence = null;
+            continue;
+        }
+        if (fence === null && HEADING_RE.test(line))
+            return { start, end: start + line.length };
+    }
+    return null;
+}
+/** The offset where the text of a heading line ends: its end, less the blanks that close it. */
+function headingTextEnd(text, heading) {
+    return heading.start + text.slice(heading.start, heading.end).replace(/[ \t]+$/, '').length;
+}
+/**
+ * A compiled body in the form the stamp leaves it, before the suffix: the blanks that
+ * end the first heading line dropped. A body with no heading is returned as it is.
+ * {@link stampBuildId} writes the suffix after this text and {@link unstampBuildId}
+ * returns this text, which is what lets the build id be recomputed from a stamped file.
+ */
+function stampReadyBody(body) {
+    const heading = locateFirstHeading(body);
+    if (heading === null)
+        return body;
+    return `${body.slice(0, headingTextEnd(body, heading))}${body.slice(heading.end)}`;
+}
+/**
+ * Stamp a build id into the first heading line of a compiled body, as the suffix
+ * ` [build <id>]`.
+ *
+ * D-BUILD-ID: the heading is where a reader of the file sees the id first, and a
+ * suffix leaves the heading text, and every anchor made from it, as written. A body
+ * with no heading has nowhere to carry the id and is refused, and so is a heading that
+ * already carries a stamp, which would otherwise hide a stale one behind the new one.
+ * The blanks that end the heading line are dropped, so the suffix follows the text
+ * directly; {@link unstampBuildId} undoes the stamp up to that one change.
+ */
+export function stampBuildId(body, id) {
+    const heading = locateFirstHeading(body);
+    if (heading === null)
+        return Err({ kind: 'no-heading' });
+    const existing = BUILD_STAMP_SUFFIX_RE.exec(body.slice(heading.start, heading.end));
+    if (existing !== null)
+        return Err({ kind: 'already-stamped', id: existing[1] });
+    return Ok(`${body.slice(0, headingTextEnd(body, heading))} [build ${id}]${body.slice(heading.end)}`);
+}
+/** Read the build id out of the first heading line of a stamped file. */
+export function readBuildId(text) {
+    const heading = locateFirstHeading(text);
+    if (heading === null)
+        return Err({ kind: 'no-heading' });
+    const stamp = BUILD_STAMP_SUFFIX_RE.exec(text.slice(heading.start, heading.end));
+    return stamp === null ? Err({ kind: 'no-stamp' }) : Ok(stamp[1]);
+}
+/**
+ * Take the stamp off a stamped file: the text without the suffix on its first heading
+ * line, and the id the suffix carried.
+ *
+ * The inverse of {@link stampBuildId} on a body whose heading does not end in blanks
+ * (a heading that does comes back without them, which is the form the build id is taken
+ * over). Only the first heading is read, so a stamp-like text elsewhere in the file stays.
+ */
+export function unstampBuildId(text) {
+    const heading = locateFirstHeading(text);
+    if (heading === null)
+        return Err({ kind: 'no-heading' });
+    const stamp = BUILD_STAMP_SUFFIX_RE.exec(text.slice(heading.start, heading.end));
+    if (stamp === null)
+        return Err({ kind: 'no-stamp' });
+    return Ok({ body: `${text.slice(0, heading.end - stamp[0].length)}${text.slice(heading.end)}`, id: stamp[1] });
+}
+/**
+ * The shared-id check of a folder: every stamped file of one folder and key carries the
+ * same build id. Returns that id. It reads the stamps and nothing else; it does not
+ * recompute the id from the files, and {@link verifyFolderBuildId} does.
+ *
+ * The reference files are outside it. A file with no heading or no stamp is refused by
+ * name, and two ids are refused with every file's id listed, so a folder that mixes
+ * files of two builds (an install that stopped half-way, a stale file copied in) stops
+ * the check instead of passing as one skill.
+ */
+export function checkFolderBuildIds(files) {
+    const ids = [];
+    for (const { file, body } of files) {
+        if (!isStampedWorkflowFile(file))
+            continue;
+        const read = readBuildId(body);
+        if (!read.ok)
+            return Err({ kind: 'unstamped', file, reason: read.error.kind });
+        ids.push({ file, id: read.value });
+    }
+    if (ids.length === 0)
+        return Err({ kind: 'no-stamped-file' });
+    const first = ids[0].id;
+    return ids.every(entry => entry.id === first) ? Ok(first) : Err({ kind: 'mixed-ids', ids });
+}
+/**
+ * The check a reader of a folder makes: the shared-id check ({@link checkFolderBuildIds}),
+ * then the id recomputed over the unstamped stamped files and the reference bodies as
+ * they stand, which must be the id the stamps carry. Returns that id.
+ *
+ * Every file of the key's folder must be in `files`, because the id covers them all. A
+ * folder with one stamped file, or a reference file of another build, no longer passes
+ * on the stamps alone: its files hash to another id. The check holds for a folder as
+ * the build wrote it. It does not hold against someone who edits a file and the stamp
+ * together, since the id is a plain digest and not a signature.
+ */
+export function verifyFolderBuildId(files) {
+    const shared = checkFolderBuildIds(files);
+    if (!shared.ok)
+        return shared;
+    const unstamped = [];
+    for (const { file, body } of files) {
+        if (!isStampedWorkflowFile(file)) {
+            unstamped.push({ file, body });
+            continue;
+        }
+        const read = unstampBuildId(body);
+        if (!read.ok)
+            return Err({ kind: 'unstamped', file, reason: read.error.kind });
+        unstamped.push({ file, body: read.value.body });
+    }
+    const recomputed = workflowBuildId(unstamped);
+    return recomputed === shared.value ? Ok(shared.value) : Err({ kind: 'id-mismatch', stamped: shared.value, recomputed });
+}
+/** Render a stamp refusal as one line a person can act on. */
+export function describeBuildStampError(error) {
+    switch (error.kind) {
+        case 'no-heading':
+            return 'it has no heading line to carry the build id; open the file with a heading';
+        case 'already-stamped':
+            return `its first heading already carries a build stamp (${error.id}); the build writes the stamp itself`;
+        default: {
+            const unhandled = error;
+            return `unhandled build stamp refusal ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
+/** Render a build id check refusal as one line a person can act on. */
+export function describeBuildIdCheckError(error) {
+    switch (error.kind) {
+        case 'no-stamped-file':
+            return 'the folder holds no file that carries a build id';
+        case 'unstamped':
+            return `${error.file} has no build id (${error.reason})`;
+        case 'mixed-ids':
+            return `the folder mixes build ids: ${error.ids.map(entry => `${entry.file} ${entry.id}`).join(', ')}`;
+        case 'id-mismatch':
+            return `the files of the folder hash to build id ${error.recomputed}, but the stamps carry ${error.stamped}; a file is from another build or was changed`;
+        default: {
+            const unhandled = error;
+            return `unhandled build id refusal ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
 //# sourceMappingURL=mds-variants.js.map