@jawache/flow 0.1.0

package/dist/types/language/domain.d.ts

@@ -0,0 +1,641 @@
+declare const PHASES: {
+    readonly write: readonly ["edit"];
+    readonly command: readonly ["edit", "commit"];
+    readonly commit: readonly ["commit"];
+    readonly delete: readonly ["delete"];
+    readonly "turn-end": readonly ["turn"];
+};
+/** The moments a guardrail may fire at — the keys of the one table above. */
+export type GuardrailMoment = keyof typeof PHASES;
+/** The moments a breadcrumb may show at. A breadcrumb is a note; it has no rail to block. */
+export type BreadcrumbMoment = (typeof BREADCRUMB_MOMENTS)[number];
+/** Either vocabulary. `turn-end` is the one word in both. */
+export type Moment = GuardrailMoment | BreadcrumbMoment;
+export declare const GUARDRAIL_MOMENTS: readonly GuardrailMoment[];
+export declare const BREADCRUMB_MOMENTS: readonly ["session", "touch", "turn-end"];
+export declare const write: "write";
+export declare const command: "command";
+export declare const commit: "commit";
+export declare const deletion: "delete";
+export declare const turnEnd: "turn-end";
+export declare const session: "session";
+export declare const touch: "touch";
+/** The engine phases a moment list fires at — deduped, in declaration order. */
+export declare function phasesOf(at: readonly GuardrailMoment[]): string[];
+/** Is this string one of the guardrail words? The load's backstop, not the editor's job. */
+export declare function isGuardrailMoment(m: string): m is GuardrailMoment;
+/** Is this string one of the breadcrumb words? */
+export declare function isBreadcrumbMoment(m: string): m is BreadcrumbMoment;
+/**
+ * The moments whose events NAME A PATH — and therefore the only ones `.on()` / `.ignore()` narrow.
+ *
+ * A write and a delete carry the would-be file; the commit gate carries the staged set; a touch
+ * carries the file the tool call was about. The other three carry no path at all: a command guard's
+ * patterns ARE its scope, a turn-end is about what the actor did, and a session start is about the
+ * session. The engine expresses the same fact at run time — `subjectsOf` consults `inScope` for
+ * exactly these moments, and `brief` narrows a note only when the event names a path — and stating
+ * it here is what lets a scope that would narrow NOTHING be refused rather than quietly ignored.
+ */
+export declare const PATH_MOMENTS: readonly ["write", "delete", "commit", "touch"];
+export type PathMoment = (typeof PATH_MOMENTS)[number];
+/** Does this moment carry a path for `on` / `ignore` to narrow? */
+export declare function isPathMoment(m: string): m is PathMoment;
+/**
+ * The host-written record of one session × agent, as a classifier sees it.
+ *
+ * Every field is something a HARNESS wrote, not something the session said. `agentType` is the
+ * strongest of them — the sidecar the host writes beside every subagent transcript — and it is
+ * what a classifier should key on when it exists.
+ */
+export interface SessionFacts {
+    /** The head of this session's transcript: the brief it was started with, verbatim. */
+    head: string;
+    /** True when this is a spawned subagent rather than the parent session. */
+    subagent: boolean;
+    /** The host's own agent type for this spawn, from the sidecar it wrote. Absent on a parent. */
+    agentType?: string | undefined;
+    /** The human-readable label the spawning agent gave this subagent. Absent on a parent. */
+    description?: string | undefined;
+}
+/** A category's recognizer: host-written facts in, a yes or no out. */
+export type Classifier = (facts: SessionFacts) => boolean;
+/**
+ * A declared category. Only `defineCategory` makes one — the brand is what lets the load refuse
+ * an entry that scoped itself to something that merely looks like a category.
+ */
+export interface Category {
+    readonly [CATEGORY]: true;
+    readonly name: string;
+    readonly classify: Classifier;
+}
+declare const CATEGORY: unique symbol;
+/** Declare a category: a name, and the recognizer that travels with it. */
+export declare function defineCategory(name: string, classify: Classifier): Category;
+/** Was this made by `defineCategory`? The load's backstop behind `.for()`'s typing. */
+export declare function isCategory(value: unknown): value is Category;
+/** What `ctx.exec` answers. A diagnostic command's whole result, as data. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/** A check's answer. Never an action — the engine turns a fail into an effect. */
+export type Verdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly detail?: string;
+};
+/**
+ * One thing the actor did during a turn: it changed a file, or it ran a command.
+ *
+ * TWO KINDS AND NO MORE, and the narrowness is the contract. A harness records a turn in its own
+ * vocabulary — Claude Code writes JSONL naming tools like `Edit`, `Write` and `Bash` — and which
+ * of those names counts as an edit is exactly the kind of dialect the adapter exists to absorb.
+ * What the engine and a check are handed is the answer, not the transcript: an ordered list of
+ * edits and runs that any harness can produce and a `.test()` case can simply write out.
+ *
+ * The rule this replaces read `$WORK_TURN_TRANSCRIPT` from the environment, opened the file and
+ * parsed it, inside the check — three reads of the world in the one place the design forbids
+ * them, and it made that rule the only core rule no case could drive.
+ */
+export type TurnAction = {
+    readonly did: "edit";
+    readonly path: string;
+} | {
+    readonly did: "run";
+    readonly command: string;
+};
+/**
+ * Everything a check may know and everything it may do.
+ *
+ * The facts are already in memory when the check runs — a write rail sees the file as it WOULD be
+ * written, disk untouched; a command rail sees the line about to run; the commit gate sees the
+ * staged paths. That is what lets a repo's own check name the file at fault instead of
+ * re-deriving the tree, and it makes the work scale with the change rather than with the repo.
+ */
+export interface Ctx {
+    readonly moment: Moment;
+    /** write/touch: the would-be file. */
+    readonly file?: {
+        readonly path: string;
+        readonly content: string;
+    } | undefined;
+    /** command: the line about to run. */
+    readonly command?: string | undefined;
+    /** commit: the staged paths. */
+    readonly staged?: readonly string[] | undefined;
+    /** turn-end: what the actor did this turn, in order. */
+    readonly turn?: readonly TurnAction[] | undefined;
+    exec(cmd: string): Promise<ExecResult>;
+    readonly fs: {
+        read(path: string): Promise<string>;
+        exists(path: string): Promise<boolean>;
+    };
+    readonly git: {
+        diff(path?: string): Promise<string>;
+        stagedFiles(): Promise<string[]>;
+    };
+    ok(): Verdict;
+    /** `detail` rides under the sentence's message, saying which thing broke. */
+    fail(detail?: string): Verdict;
+}
+/** A check: ctx in, a verdict out. Sync or async — the engine awaits either. */
+export type Check = (ctx: Ctx) => Verdict | Promise<Verdict>;
+/**
+ * The two verdict constructors — INTERNAL to flow, and deliberately not part of its public surface.
+ *
+ * A check has exactly one way to answer and it is `ctx.ok()` / `ctx.fail(detail)`. That is the
+ * spelling the fourteen core checks are written in, the spelling a repo's own check is written in,
+ * and the only one flow/index.ts exports. These exist because something has to BUILD the ctx that
+ * carries them — the canned one a `.test()` case runs through, and the live one the adapter makes
+ * — and that is flow's own job, not a config author's. Exporting both would put two spellings of
+ * one answer in front of every check writer, and half of them would pick the wrong one.
+ */
+export declare const verdict: {
+    ok: () => Verdict;
+    fail: (detail?: string) => Verdict;
+};
+/**
+ * Everything a check may reach for beyond the event's own facts — the three capabilities, alone.
+ *
+ * Derived from `Ctx` rather than restated, so there is one description of what flow can reach and
+ * no way to grow a fourth capability that a `.test()` case has no means of recording.
+ */
+export type World = Pick<Ctx, "exec" | "fs" | "git">;
+/**
+ * THE ctx builder — the one place a check's world is assembled, and there must only ever be one.
+ *
+ * Three callers, and the whole promise of this package rests on their agreeing: the engine builds
+ * one from a live event and a real world; `flow test` builds one from a case and a recorded world;
+ * replay builds one from a transcript. If those three assembled a ctx even slightly differently,
+ * a green case would stop being evidence about the live rail — which is the entire value of cases
+ * existing. They were two assemblers for one commit, and that was one commit too many.
+ *
+ * `exec` is wrapped while `fs` and `git` are passed whole, which looks inconsistent and is not: a
+ * method called off `ctx.fs` still has `world.fs` as its receiver, whereas a bare `exec: world.exec`
+ * would be called with `ctx` as its receiver and break any world that closes over itself.
+ */
+export declare function makeCtx(moment: Moment, facts: Partial<Ctx>, world: World): Ctx;
+/**
+ * Declare a CONFIGURED check: a function that takes options and returns a check.
+ *
+ * Its whole job is to give `ctx` its type inside the closure, so the body is written against the
+ * contract with no annotation. The other two forms need nothing at all: an inline check is a
+ * lambda in the sentence, and a named one is `export const x: Check = …`.
+ *
+ * IT DOES ONE THING BESIDES, and it was a plain identity function until it did: the options a
+ * check was configured with are kept ON the returned check, under a symbol nothing enumerates. A
+ * check is a closure, so once it is built the settings inside it are unreachable — and a reader
+ * that cannot see them cannot say what a rule really watches. The generated pack pages printed the
+ * `.check(…)` SOURCE instead, which is how `noGitDiscard({})`, a bare `TESTS` constant and a
+ * helper call reached a page as the whole description of a rule. Read back through `settings` on
+ * the loaded entry they are RESOLVED values: the globs a parameter supplied, the recipe a repo
+ * named. Nothing in the run reads them — the engine calls the check and asks it nothing else — so
+ * this cannot change what any rule decides.
+ */
+export declare function defineCheck<Options, C extends Check>(factory: (options: Options) => C): (options: Options) => C;
+/**
+ * The options a check was configured with, or `undefined` for one that never came through
+ * `defineCheck` — an inline lambda in a sentence, or a bespoke `const x: Check = …`.
+ */
+export declare function checkSettings(check: Check | undefined): unknown;
+/**
+ * The answers a case records for whatever its check reaches for beyond the event's own facts.
+ *
+ * Everything is optional and an absent answer is not a silent zero: the runner reports a reach it
+ * cannot answer as a FAILED case, naming the command or path to add here. A case that passed
+ * because the world happened to answer "" is the thing this design exists to prevent.
+ */
+export interface CaseWorld {
+    /**
+     * Recorded `ctx.exec` answers, by command. Matched exactly first, then by CONTAINMENT — a key
+     * of `"depcruise"` answers the multi-line invocation the depcruise check builds, which is not a
+     * string anybody would want to retype into a case.
+     */
+    readonly exec?: Readonly<Record<string, {
+        stdout?: string;
+        stderr?: string;
+        code?: number;
+    }>>;
+    /** Files `ctx.fs` can see, by path. A path not here does not exist. */
+    readonly fs?: Readonly<Record<string, string>>;
+    /** What `ctx.git.diff()` answers. */
+    readonly gitDiff?: string;
+    /** What `ctx.git.stagedFiles()` answers when the moment carried no staged set of its own. */
+    readonly staged?: readonly string[];
+}
+/** One canned event, in the dialect its moment speaks. */
+export type Case = 
+/** A command rail, shorthand — by far the commonest case, and it should read as one line. */
+string | {
+    readonly command: string;
+    readonly world?: CaseWorld;
+} | {
+    readonly path: string;
+    readonly content: string;
+    readonly world?: CaseWorld;
+} | {
+    readonly staged: readonly string[];
+    readonly world?: CaseWorld;
+} | {
+    readonly actions: readonly TurnAction[];
+    readonly world?: CaseWorld;
+};
+/** The cases an entry carries: what must pass it, and what must be blocked by it. */
+export interface Cases {
+    readonly pass?: readonly Case[];
+    readonly block?: readonly Case[];
+}
+/** Does this cases block prove anything? An entry whose answer is no does not load. */
+export declare function hasCases(cases: Cases | undefined): boolean;
+/** What a recorded world was reached for and could not answer. */
+export interface Unanswered {
+    readonly kind: "exec" | "read";
+    readonly asked: string;
+}
+/**
+ * THE recorded world — a `CaseWorld` as the three capabilities, and there must only ever be one.
+ *
+ * It sits beside `makeCtx` for the same reason and it is the same sentence: `flow test` drives a
+ * check through this, the engine's own suite drives a whole rail through this, and F5's replay will
+ * drive a recorded session through this. The moment there are two of them they disagree about
+ * silence — which is precisely what happened for one commit, where a second copy answered an
+ * unrecorded file read with `""` while this one recorded the reach. One of those makes a case pass
+ * on a fiction, and telling which is which afterwards is impossible.
+ *
+ * Recorded exec answers are matched by exact command first and then by CONTAINMENT, which is not
+ * laziness: the commands a check builds are not always things a person would want to retype — the
+ * depcruise runner's is a multi-line heredoc carrying a compiled config — so a case says
+ * `{ "depcruise": … }` and means "when it shells out to that". Exact wins when both could match, so
+ * a case can still pin one specific invocation out of three.
+ *
+ * An unanswered reach is RECORDED rather than guessed at or thrown on. Guessing would let a case
+ * pass on a fiction; throwing from here would be a throw in a pure home. The caller turns the
+ * record into a failure naming exactly what was asked for.
+ */
+export declare function cannedWorld(recorded: CaseWorld, staged: readonly string[] | undefined, unanswered: Unanswered[]): World;
+/** An entry turned off, and why. The reason is the sentence `flow status` prints beside it. */
+export interface DisabledMark {
+    readonly reason?: string | undefined;
+}
+interface SpecCommon {
+    readonly for?: readonly Category[];
+    readonly on?: readonly string[];
+    readonly ignore?: readonly string[];
+    readonly disabled?: DisabledMark;
+    readonly description?: string;
+}
+/** A guardrail, as its sentence stated it. Every key explicit; nothing derived. */
+export interface GuardrailSpec extends SpecCommon {
+    readonly kind: "guardrail";
+    readonly at?: readonly GuardrailMoment[];
+    readonly check?: Check;
+    readonly message?: string;
+    readonly test?: Cases;
+}
+/** A breadcrumb: a note, and the moments it shows at — all of them, not just the first. */
+export interface BreadcrumbSpec extends SpecCommon {
+    readonly kind: "breadcrumb";
+    readonly at?: readonly BreadcrumbMoment[];
+    readonly text?: string;
+    readonly file?: string;
+}
+export type EntrySpec = GuardrailSpec | BreadcrumbSpec;
+/**
+ * A path scope, as anything that has one states it — an entry's spec, or the universe row the
+ * facts layer reads. Two readers of `on` / `ignore` is how the guard and the report come to
+ * disagree about what a rule watches, so there is one and everything that has a scope wears it.
+ */
+export interface Scope {
+    readonly on?: readonly string[] | undefined;
+    readonly ignore?: readonly string[] | undefined;
+}
+/**
+ * Is this path inside the entry's `on` / `ignore` scope? No `on` at all is every path.
+ *
+ * It lives HERE, with the two keys it reads, rather than with the engine that was its first
+ * caller. Three things now ask it and they must agree exactly: the engine, deciding which staged
+ * files an entry is run against; the case runner, driving that same fan-out from a recorded world;
+ * and the facts layer, reporting what a rule watches. A commit rule whose case exercised a
+ * different scope test than its live rail would be a green case that is not evidence.
+ */
+export declare function inScope(scope: Scope, path: string): boolean;
+/**
+ * The grammar's keys, per entry type — the closed sets the load re-checks.
+ *
+ * They are listed here rather than derived from the interfaces because a type is gone at run time
+ * and the load happens at run time. Adding a verb below without adding it here would build an
+ * entry the load then refuses, which is a loud failure and the right one.
+ */
+export declare const GUARDRAIL_KEYS: readonly ["at", "for", "on", "ignore", "check", "message", "disabled", "test", "description"];
+export declare const BREADCRUMB_KEYS: readonly ["at", "for", "on", "ignore", "text", "file", "disabled", "description"];
+export type GuardrailKey = (typeof GUARDRAIL_KEYS)[number];
+export type BreadcrumbKey = (typeof BREADCRUMB_KEYS)[number];
+/**
+ * A verb, until it is spoken.
+ *
+ * Exported because the override chain in packs.ts is the same trick over the same grammar, and a
+ * second copy of these fifty characters is a second place for "may be said once" to stop being
+ * true.
+ */
+export type Once<Spoken extends string, Key extends string, Verb> = Key extends Spoken ? never : Verb;
+/** What `.on()` becomes once `.at(…)` has ruled every path out. The TEXT is the diagnostic. */
+type DeadScope = "flow: every moment this entry fires at carries no path, so .on()/.ignore() would narrow nothing";
+/**
+ * `.on()` / `.ignore()`, or the refusal — the compile-time half of the dead-scope rule.
+ *
+ * A path scope is consulted only when the event names a path (`PATH_MOMENTS`), so an entry whose
+ * every moment is `command`, `turn-end` or `session` and which nonetheless speaks `.on(…)` reads as
+ * armed and narrows nothing — config that looks like a fence and is one line of decoration. The
+ * engine's silence about it was the old engine's behaviour, kept deliberately until now.
+ *
+ * It is a WRONG-ARGUMENT refusal rather than a `never`, and that is the whole design: `never` gives
+ * "this expression is not callable", which says nothing about why. A parameter typed as the message
+ * puts the sentence itself in the diagnostic, where a reader is already looking.
+ *
+ * It can only fire when `.at(…)` was spoken FIRST — before that, `At` is the whole vocabulary and
+ * every scope is live. Saying `.on(…)` above `.at(command)` is the same mistake with the words in
+ * the other order, and the load's `dead-scope` refusal is what catches it. Both halves, always.
+ */
+type Scoping<At extends Moment, Verb> = [Extract<At, PathMoment>] extends [never] ? (dead: DeadScope) => never : Verb;
+/** Anything a pack may file under an entry name. The one shape `definePack` walks. */
+export interface Sentence<S extends EntrySpec = EntrySpec> {
+    readonly spec: S;
+}
+/** A group of entries, or of groups — a pack may nest, and `git.node.versionIsSemver` is why. */
+export interface EntryGroup {
+    readonly [key: string]: Sentence | EntryGroup;
+}
+export interface GuardrailSentence<Spoken extends GuardrailKey = never, At extends GuardrailMoment = GuardrailMoment> extends Sentence<GuardrailSpec> {
+    readonly at: Once<Spoken, "at", <M extends GuardrailMoment[]>(...moments: M) => GuardrailSentence<Spoken | "at", M[number]>>;
+    readonly for: Once<Spoken, "for", (...categories: Category[]) => GuardrailSentence<Spoken | "for", At>>;
+    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => GuardrailSentence<Spoken | "on", At>>>;
+    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => GuardrailSentence<Spoken | "ignore", At>>>;
+    readonly check: Once<Spoken, "check", (check: Check) => GuardrailSentence<Spoken | "check", At>>;
+    readonly message: Once<Spoken, "message", (message: string) => GuardrailSentence<Spoken | "message", At>>;
+    readonly disabled: Once<Spoken, "disabled", (reason?: string) => GuardrailSentence<Spoken | "disabled", At>>;
+    readonly test: Once<Spoken, "test", (cases: Cases) => GuardrailSentence<Spoken | "test", At>>;
+    readonly description: Once<Spoken, "description", (description: string) => GuardrailSentence<Spoken | "description", At>>;
+}
+export interface BreadcrumbSentence<Spoken extends BreadcrumbKey = never, At extends BreadcrumbMoment = BreadcrumbMoment> extends Sentence<BreadcrumbSpec> {
+    readonly at: Once<Spoken, "at", <M extends BreadcrumbMoment[]>(...moments: M) => BreadcrumbSentence<Spoken | "at", M[number]>>;
+    readonly for: Once<Spoken, "for", (...categories: Category[]) => BreadcrumbSentence<Spoken | "for", At>>;
+    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "on", At>>>;
+    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "ignore", At>>>;
+    readonly text: Once<Spoken, "text", (text: string) => BreadcrumbSentence<Spoken | "text", At>>;
+    readonly file: Once<Spoken, "file", (path: string) => BreadcrumbSentence<Spoken | "file", At>>;
+    readonly disabled: Once<Spoken, "disabled", (reason?: string) => BreadcrumbSentence<Spoken | "disabled", At>>;
+    readonly description: Once<Spoken, "description", (description: string) => BreadcrumbSentence<Spoken | "description", At>>;
+}
+type Missing<Spoken extends string, Required extends string> = Exclude<Required, Spoken>;
+type NeverSaid<What extends string, Verb extends string> = Verb extends string ? `flow: this ${What} never said .${Verb}() — nothing defaults, so it is not an entry` : never;
+/** A guardrail must say when it fires, what it asks, what it tells you, and what proves it. */
+type GuardrailRequired = "at" | "check" | "message" | "test";
+/** A breadcrumb must say when it shows, and carry its prose one of the two ways. */
+type BreadcrumbProse = "flow: this breadcrumb has no prose — say .text(…) or .file(…)";
+export type CompleteEntry<B> = B extends GuardrailSentence<infer S, infer _GuardrailAt> ? "disabled" extends S ? B : [Missing<S, GuardrailRequired>] extends [never] ? B : NeverSaid<"guardrail", Missing<S, GuardrailRequired>> : B extends BreadcrumbSentence<infer S, infer _BreadcrumbAt> ? "disabled" extends S ? B : [Missing<S, "at">] extends [never] ? "text" extends S ? B : "file" extends S ? B : BreadcrumbProse : NeverSaid<"breadcrumb", Missing<S, "at">> : B extends EntryGroup ? {
+    readonly [K in keyof B]: CompleteEntry<B[K]>;
+} : never;
+/**
+ * THE chain builder — every chain in this grammar, and there are three of them: a guardrail, a
+ * breadcrumb, and an override.
+ *
+ * The three differ in only two ways, and both are arguments here: which keys they START from, and
+ * how the accumulated keys are EXPOSED (a sentence shows them as `.spec`, an override wraps them
+ * in its binding). What they must never differ in is the verbs themselves — that a second `.on()`
+ * replaces nothing, that `.disabled()` records an empty reason rather than dropping it, that every
+ * step returns a NEW object so a pack can build a family off a shared prefix. Each of those was
+ * written twice for one commit, which is one commit longer than "one of the two copies is now
+ * subtly different" needs.
+ *
+ * Which verbs a given caller may reach is a TYPE question and is answered entirely by the
+ * interfaces above and in packs.ts — an override has no `.check` because its chain type does not
+ * declare one, not because a different builder withheld it. That is the same reason this works
+ * over an untyped record: the chain types are a PROJECTION of this one object, a shrinking subset
+ * of eleven verbs, and no signature can describe that from the inside. The casts at each entry
+ * point are the seam.
+ */
+export declare function chain<Exposed extends object>(spoken: Readonly<Record<string, unknown>>, expose: (spoken: Readonly<Record<string, unknown>>) => Exposed): Exposed;
+/** Open a guardrail sentence. It blocks; it must therefore say what it asks and what it proves. */
+export declare function guardrail(): GuardrailSentence;
+/** Open a breadcrumb sentence. Breadcrumbs are data — no check, ever, and no rail to block. */
+export declare function breadcrumb(): BreadcrumbSentence;
+/** Is this an entry rather than a group of them? What `definePack` walks a pack's tree with. */
+export declare function isSentence(value: unknown): value is Sentence;
+declare const PACK: unique symbol;
+declare const REF: unique symbol;
+/** Phantoms: typed, never present at run time. They exist so a call site can be refused. */
+declare const PARAMS: unique symbol;
+declare const KIND: unique symbol;
+/** A pack's definition — its name, and how to build its entries. */
+export interface PackDefinition {
+    readonly name: string;
+    /** Build the entry tree. A pack that takes no parameters ignores the argument. */
+    readonly build: (params: unknown) => EntryGroup;
+    /**
+     * Does this pack REQUIRE parameters? Measured from the factory's arity, so a factory whose
+     * parameter has a default — `(repo: Doors = {}) => …`, every field optional — is a pack
+     * `pack(docs)` may bind, exactly as the compiler already allows.
+     */
+    readonly takesParams: boolean;
+}
+/** Where a reference points. Flat: the pack's name, and the entry's dotted path within it. */
+export interface RefTarget {
+    readonly pack: string;
+    readonly id: string;
+}
+/**
+ * A typed reference to one entry.
+ *
+ * `Kind` is a phantom — nothing carries it at run time, because a parameterised pack's tree does
+ * not exist until it is bound and a reference has to be writable before that. What it buys is the
+ * whole point of references being typed: `override()` knows whether it is looking at a guardrail
+ * or a breadcrumb, so `.message()` on a breadcrumb and `.text()` on a guardrail are refused where
+ * you type them rather than at a load nobody watches.
+ */
+export interface EntryRef<Kind extends EntrySpec["kind"] = EntrySpec["kind"]> {
+    readonly [REF]: RefTarget;
+    readonly [KIND]?: Kind;
+}
+/** The reference tree a pack presents — the same shape as the entries, refs at the leaves. */
+export type Refs<T> = {
+    readonly [K in keyof T]: T[K] extends Sentence<GuardrailSpec> ? EntryRef<"guardrail"> : T[K] extends Sentence<BreadcrumbSpec> ? EntryRef<"breadcrumb"> : T[K] extends EntryGroup ? Refs<T[K]> : never;
+};
+interface PackHandle<Params> {
+    readonly [PACK]: PackDefinition;
+    /** Phantom. It exists so `pack(tdd)` without parameters is not a call the compiler will make. */
+    readonly [PARAMS]?: Params;
+}
+/** What `definePack` hands back: the reference tree, with the definition riding underneath it. */
+export type Pack<T extends EntryGroup, Params = undefined> = Refs<T> & PackHandle<Params>;
+export interface PackBinding {
+    readonly kind: "pack";
+    /** `undefined` when the bound value was never a pack — what the load's `not-a-pack` reads. */
+    readonly pack: PackDefinition | undefined;
+    readonly params: unknown;
+    /** Were parameters supplied at all? The load's coarse backstop behind the compiler's fine one. */
+    readonly hasParams: boolean;
+}
+export interface OverrideBinding {
+    readonly kind: "override";
+    readonly ref: RefTarget;
+    /** ONLY the keys the chain spoke. An absent key here is one that flows through from the pack. */
+    readonly spoken: Readonly<Record<string, unknown>>;
+}
+export type Binding = PackBinding | OverrideBinding;
+/**
+ * The engine's dials — the few numbers that are about the RUN rather than about any one entry.
+ *
+ * It is deliberately not part of the sentence grammar, and `defineConfig`'s second argument is
+ * where it goes. `driftTokens` is the clearest example of why: how far a session may drift before
+ * a breadcrumb shows again is one answer for the whole repo, and putting it on entries would make
+ * every breadcrumb restate it or inherit it silently. The grammar stays closed; this is a knob.
+ */
+export interface Settings {
+    /** Context tokens between re-showings of a breadcrumb. Absent = the engine's own default. */
+    readonly driftTokens?: number;
+}
+/** A whole guard, as its config file states it: bindings, in the order they were spoken. */
+export interface FlowConfig {
+    readonly bindings: readonly Binding[];
+    readonly settings: Settings;
+}
+/**
+ * Declare a pack: a name, and its entries.
+ *
+ * The entries argument is `T & CompleteEntry<T>` — the first half infers the tree, the second
+ * checks every sentence in it. An incomplete one lands on a string literal whose text names the
+ * verb it never said, so the editor's error is the instruction.
+ */
+export declare function definePack<T extends EntryGroup>(name: string, entries: T & CompleteEntry<T>): Pack<T>;
+export declare function definePack<Params, T extends EntryGroup>(name: string, factory: (params: Params) => T & CompleteEntry<T>): Pack<T, Params>;
+/** The definition riding under a pack value, or undefined if this was never made by definePack. */
+export declare function packDefinition(value: unknown): PackDefinition | undefined;
+/** Where a reference points, or undefined if this was never a reference. */
+export declare function refTarget(value: unknown): RefTarget | undefined;
+/**
+ * Bind a pack — all its entries, opt-out.
+ *
+ * ONE signature, not two overloads, and the reason is the error message. A pack that declares no
+ * parameters carries `Params = undefined`, and the rest-tuple below then resolves to `[]` — so
+ * `pack(node)` is a complete call. A pack that DOES declare them infers its own parameter type,
+ * the tuple gains a required member, and `pack(tdd)` is short an argument: "Expected 2 arguments,
+ * but got 1", at the line you typed. Two overloads produced the same refusal wearing a diagnostic
+ * about a phantom property, which was true and unreadable.
+ */
+export declare function pack<T extends EntryGroup, Params>(definition: Pack<T, Params>, ...params: undefined extends Params ? [params?: Params] : [params: Params]): PackBinding;
+/**
+ * What an override may speak: BOTH entry grammars, minus the two verbs it must never reach.
+ *
+ * Derived rather than listed, and the subtraction is the whole statement — "an override moves an
+ * entry, rewords it or switches it off, and can never touch what the entry ASKS" is said once,
+ * here, in a form that cannot drift from the key sets it is subtracting from. A third hand-typed
+ * listing of the grammar would be a third place to forget a verb.
+ */
+type OverrideKey = Exclude<GuardrailKey | BreadcrumbKey, "check" | "test">;
+interface OverrideChain<Kind extends EntrySpec["kind"], Spoken extends OverrideKey> {
+    readonly binding: OverrideBinding;
+    readonly at: Once<Spoken, "at", (...moments: (Kind extends "guardrail" ? GuardrailMoment : BreadcrumbMoment)[]) => OverrideChain<Kind, Spoken | "at">>;
+    readonly for: Once<Spoken, "for", (...categories: Category[]) => OverrideChain<Kind, Spoken | "for">>;
+    readonly on: Once<Spoken, "on", (...globs: string[]) => OverrideChain<Kind, Spoken | "on">>;
+    readonly ignore: Once<Spoken, "ignore", (...globs: string[]) => OverrideChain<Kind, Spoken | "ignore">>;
+    readonly message: Kind extends "guardrail" ? Once<Spoken, "message", (message: string) => OverrideChain<Kind, Spoken | "message">> : never;
+    readonly text: Kind extends "breadcrumb" ? Once<Spoken, "text", (text: string) => OverrideChain<Kind, Spoken | "text">> : never;
+    readonly file: Kind extends "breadcrumb" ? Once<Spoken, "file", (path: string) => OverrideChain<Kind, Spoken | "file">> : never;
+    readonly disabled: Once<Spoken, "disabled", (reason?: string) => OverrideChain<Kind, Spoken | "disabled">>;
+    readonly description: Once<Spoken, "description", (description: string) => OverrideChain<Kind, Spoken | "description">>;
+}
+/**
+ * Override one entry, speaking only what changes.
+ *
+ * There is no `.check()` and no `.test()` here, and their absence is the design: an override can
+ * move an entry, reword it or switch it off, but it can never reach inside what the entry ASKS.
+ */
+export declare function override<Kind extends EntrySpec["kind"]>(ref: EntryRef<Kind>): OverrideChain<Kind, never>;
+/** Anything a config line may be: a pack binding, or an override chain at any point in its chain. */
+export type ConfigSentence = PackBinding | {
+    readonly binding: OverrideBinding;
+};
+/**
+ * The config: the sentences, in order, and the engine's dials.
+ *
+ * It records and does not judge. Every refusal lives in `loadConfig` instead, for one reason —
+ * a config with three mistakes should report three, and a function that threw on the first would
+ * report one and hide the rest behind a fix.
+ *
+ * The settings argument is OPTIONAL and trailing, which is the shape F1 promised it: `driftTokens`
+ * is an engine number and the engine did not exist yet, so the grammar was closed without it and
+ * left room for exactly this. A config that sets nothing writes `defineConfig([…])` as before.
+ */
+export declare function defineConfig(sentences: readonly ConfigSentence[], settings?: Settings): FlowConfig;
+/** An effective entry, and where each of its keys came from. */
+export interface Overlaid {
+    readonly spec: EntrySpec;
+    readonly source: Readonly<Record<string, "pack" | "override">>;
+}
+/**
+ * Lay an override's spoken keys over a definition, and record where every key came from.
+ *
+ * A named key replaces the WHOLE key — lists never merge, so an override that narrows one glob
+ * restates the others. That is deliberate: two merge semantics is two bugs, and it is the same
+ * replacement rule the YAML shadows had, kept.
+ *
+ * THE ONLY place a source map is built, including the first one: an entry with no override at all
+ * is `overlay(spec, {})`, not a second loop somewhere else that agrees with this one until it
+ * doesn't. `prior` is what makes that true for the second override onto one entry as well —
+ * without it, laying anything over an already-overridden entry would relabel the earlier
+ * override's keys as the pack's.
+ */
+export declare function overlay(base: EntrySpec, spoken: Readonly<Record<string, unknown>>, prior?: Readonly<Record<string, "pack" | "override">>): Overlaid;
+/** The closed vocabulary of refusals. Every load failure is exactly one of these. */
+export declare const REFUSAL_CODES: readonly ["not-a-pack", "missing-parameter", "unknown-entry", "unknown-key", "unknown-moment", "missing-mandatory", "undeclared-category", "no-cases", "duplicate-id", "dead-scope"];
+export type RefusalCode = (typeof REFUSAL_CODES)[number];
+/** One reason the config will not load. */
+export interface Refusal {
+    readonly code: RefusalCode;
+    /** What it is about: `pack.entry`, or the pack alone when no entry is named. */
+    readonly entry: string;
+    /** The sentence a reader acts on. It always names the entry, because a hook shows one line. */
+    readonly detail: string;
+}
+/** One entry as the engine will run it: the pack's sentence, with every override laid over it. */
+export interface LoadedEntry {
+    /** `pack.id` — one spelling from definition to log line. */
+    readonly id: string;
+    readonly pack: string;
+    /** The entry's dotted path within its pack. */
+    readonly key: string;
+    readonly spec: EntrySpec;
+    /** Where each key came from — what `flow status` prints when it explains an entry. */
+    readonly source: Readonly<Record<string, "pack" | "override">>;
+    /** The categories this entry is scoped to. Empty means every category. */
+    readonly categories: readonly string[];
+    /** The engine phases this entry fires at. Empty for a breadcrumb, which has no rail. */
+    readonly phases: readonly string[];
+    /**
+     * The options this entry's check was configured with, RESOLVED — what a parameter supplied, not
+     * what the source typed. `undefined` for a breadcrumb, and for a check that never came through
+     * `defineCheck`. Nothing in the run reads it; it is how a reader is told what a rule watches.
+     */
+    readonly settings?: unknown;
+}
+export type LoadResult = {
+    readonly ok: true;
+    readonly entries: readonly LoadedEntry[];
+} | {
+    readonly ok: false;
+    readonly refusals: readonly Refusal[];
+};
+/**
+ * Every refusal as ONE block of text — the sentence a person reads when the config will not load.
+ *
+ * There is exactly one wording, here, because there are three places it surfaces and they must not
+ * drift: the `flow test` exception (errors.ts), the block a gated moment refuses with, and the
+ * notice a breadcrumb moment degrades to. A guard that describes its own breakage differently
+ * depending on which rail you hit is a guard nobody learns to read.
+ */
+export declare function refusalText(refusals: readonly Refusal[]): string;
+/** Turn a config's bindings into the effective regime, or into every reason it cannot be one. */
+export declare function loadConfig(config: FlowConfig): LoadResult;
+export {};