@jawache/flow 0.2.1 → 0.3.0

package/dist/types/adapter/product.d.ts

@@ -6,5 +6,10 @@ export interface VerbResult {
 }
 /** `flow init [--empty]` — make this repo drivable, and say exactly what was created. */
 export declare function runInit(cwd: string, args: readonly string[]): VerbResult;
+/**
+ * `flow uninstall [--machine]` — remove what `flow init` wrote in this repo, but the config, and say
+ * exactly what went. `--machine` takes flow's hooks out of the machine-wide settings file too.
+ */
+export declare function runUninstall(cwd: string, args: readonly string[]): VerbResult;
 /** `flow status` — is flow working here, and what will meet me. Green means guarded. */
 export declare function runStatus(cwd: string, args: readonly string[]): Promise<VerbResult>;

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

@@ -1,4 +1,4 @@
-import type { Case, CaseWorld, Check, Ctx, ExecResult, Grammar, LoadedEntry, Moment, Unanswered } from "../language/domain.ts";
+import type { Case, CaseWorld, Check, Ctx, ExecResult, Grammar, LoadedEntry, Moment, ShellCommand, Unanswered } from "../language/domain.ts";
 /** One pattern that matched, and the 1-based line it matched on. */
 export interface PatternHit {
     readonly pattern: string;
@@ -24,57 +24,70 @@ export declare const textBan: (options: {
 /**
  * Ban a dangerous command before it runs.
  *
- * A DETERRENT: the patterns ARE its scope, so matching nothing in a repo is the rule working, not
- * a rule watching the wrong place.
+ * A DETERRENT: the commands it names ARE its scope, so matching nothing in a repo is the rule
+ * working, not a rule watching the wrong place.
  *
- * MATCHED WHOLE, and that is the one difference from `textBan` above. A command is ONE subject
- * however many lines it occupies — `git commit -m "subject\n\nCo-Authored-By: …"` is a single
- * invocation, and the patterns that police it span the newline on purpose. Swept line by line
- * (which is right for a file, where a hit must be able to name its line) every one of those
- * patterns matches nothing, silently: the rule loads, counts, and cannot catch the thing it
- * names.
+ * EACH ENTRY IS A COMMAND IN WORDS — `"git push --force"` — read by the same parse as the line: a
+ * program, then the arguments that make it dangerous. A command in `ctx.commands` matches when its
+ * program, less its path, is the entry's, and its arguments include every one of the entry's, in
+ * any order. Arguments are compared whole, so `"work task"` is not `work task-list` and a quoted
+ * `'we tick later'` is not the word `tick`; a bundle of short flags counts letter by letter on both
+ * sides, so `"rm -rf"` is `rm -fr` and `rm -r -f`. A regex over a command's text could say none of
+ * that: it read `/usr/local/bin/work plan tick` as no tick and `rm -fr` as no `-rf`.
  *
- * WITHOUT ITS HEREDOC BODIES (`elideHeredocs`), by default. A heredoc is text fed to a program,
- * and a python script or a note that names a banned command is not a use of it: matched whole,
- * `python3 - <<'PY'` scripts were refused for naming a recipe in a string. Only the bodies go —
- * the newlines the patterns above span are kept — and a body a shell reads stays, because it is
- * commands.
+ * One command at a time, so `git push origin main; ls -f` is no force push, and a heredoc's body
+ * is text fed to a program, not arguments — unless a shell reads it, when the parse has already
+ * made its lines commands of their own. A line that does not parse is refused when an entry's words
+ * all appear in it as whole words: a deterrent that cannot read a line errs toward refusing it.
  *
- * `matchHeredocs: true` matches the whole command instead. A rule about what a command is FED —
- * the text of a commit message given on stdin, `git commit -F - <<'EOF'` — has to see the body,
- * and would be blind to that message without it.
+ * `wholeLine: true` is the escape hatch for a pattern that spans two commands on purpose
+ * (`curl … | sh`): each entry is then a regex, compiled when the rule loads and tried anywhere in
+ * the line as written, less its heredoc bodies. One that does not compile refuses to load.
+ *
+ * An entry that is not one command in words — a line that does not parse, two commands, a
+ * backslash, the mark of a regex written before words, or a wrapper such as `sudo` or a `FOO=1`
+ * assignment in front — refuses to load, rather than arming a ban that matches nothing, or every
+ * use of its program.
+ *
+ * docs/user/checks/ban-commands.md is the promise, case by case.
  */
 export declare const banCommands: (options: {
     ban: readonly string[];
-    matchHeredocs?: boolean;
+    wholeLine?: boolean;
 }) => Check;
 /**
- * A `banCommands` pattern for: a command that writes permanent prose, with a BACKTICK inside a
- * double-quoted argument.
- *
- * Reads as: <one of `heads`> … <an OPEN double quote> … <a backtick>, where the quote-pair walk
- * skips arguments that are already closed, and both scans refuse to cross a QUOTED heredoc opener
- * — inside one the shell substitutes nothing, so it is the sanctioned way to carry backticks and
- * must not be blocked. An unquoted `<<EOF` is deliberately still caught: there, substitution
- * really does happen. This is the one pattern that has to span a newline, and the reason
- * `banCommands` matches a command whole rather than line by line.
- *
- * A BUILDER over a `heads` list rather than one frozen expression, because the commands that
- * record prose belong to different packs: `git commit` and `gh pr|issue` are `git`'s, which every
- * repo binds, and the `work …` verbs are `work`'s, which only a repo running the work lifecycle
- * binds. One tail, two heads, and neither pack carries a copy of the other's — a second copy of
- * this expression is how the two would drift while both still read as armed.
- *
- * WHY IT IS CORE and not a helper beside the packs: TWO PACKS
- * SHARE IT, and that is the whole rule the fold settled — anything two packs share is a core
- * check. A shared file sitting beside the packs is a library with two users and no owner, and this
- * one proved it by growing four unrelated sections around this pair. Here it sits next to the
- * check it builds a pattern for, and the door that exports one exports both.
- */
-export declare function substitutionInProse(heads: readonly string[]): string;
+ * Refuse a command that records permanent prose when the shell would run a BACKTICK substitution
+ * while building it — a commit message, a PR or issue body, a journal entry.
+ *
+ * `heads` are the commands that record prose, each in words, `"gh pr"`, matched as `banCommands`
+ * matches an entry: the same program, less its path, and every argument of the head among the
+ * command's, compared whole. A head's words are found anywhere among the arguments, so a bare word
+ * passed as an option's value counts too: `"gh pr"` refuses `gh run list --branch pr`. A head that
+ * is not one command in words refuses to load, as an entry does. `gitSubcommands` names git's own,
+ * `commit`, and is read through `gitCommand`: git's options sit between `git` and its subcommand,
+ * so `-C '/a b' commit` is `commit` there, where the containment of `"git commit"` would also take
+ * `git log --grep commit`.
+ *
+ * The verdict reads the parse, never the line: a backtick the shell runs is one the parse lists as
+ * the command's substitution — in a double-quoted or bare argument, or in an unquoted heredoc the
+ * command is fed. A single-quoted argument, an escaped backtick and a QUOTED heredoc run nothing,
+ * so none is refused, and neither is a backtick in another command on the same line. A `$( … )`
+ * substitution is the sanctioned way to feed a heredoc into an argument, so it is not refused
+ * itself; what it runs is, when that holds a backtick — the unquoted `"$(cat <<EOF … EOF)"`
+ * message. A line that does not parse is not judged.
+ *
+ * A CORE CHECK because TWO PACKS SHARE IT: `git` polices `git commit` and the `gh` verbs, which
+ * every repo binds, and `work` the lifecycle verbs, which only a repo running the work lifecycle
+ * binds. Anything two packs share is a core check; a copy in each is how the two would drift
+ * while both still read as armed.
+ */
+export declare const substitutionInProse: (options: {
+    heads: readonly string[];
+    gitSubcommands?: readonly string[];
+}) => Check;
 /**
  * What a blocked prose-writing command is told, and it is the same sentence whichever pack caught
- * it: the mechanism, the absence of an undo, the fix, and the one false positive the rule owns.
+ * it: the mechanism, the absence of an undo, and the fix.
  *
  * ONE constant rather than a message per pack. The sentence never named the verb that was blocked
  * — it names the shape — so two copies would be two places for the same advice to drift, and the
@@ -226,7 +239,12 @@ export declare const jsonInvariant: (options: {
 /** Of some exported names, which are never mentioned in the sibling test's text? */
 export declare function unreferenced(names: readonly string[], siblingText: string): string[];
 /**
- * The names a TypeScript source exports — functions, classes and consts.
+ * The names a TypeScript source exports — functions, classes and consts, in source order.
+ *
+ * An `export const` is read as every name it binds: each declarator of `export const a = 1, b = 2`,
+ * and each name a destructuring pattern binds. A declarator with a type annotation is left out,
+ * destructured or not, and so is an ambient `export declare const`: the declaration sits under an
+ * `ambient_declaration`, not directly under the export, so it is never matched.
  *
  * A real parser rather than a regex, because `export const x = …` inside a string or a comment is
  * exactly the false positive that teaches people to ignore a rule. Parsing is not reaching the
@@ -235,7 +253,11 @@ export declare function unreferenced(names: readonly string[], siblingText: stri
  * milliseconds to load and no other check needs it.
  */
 export declare function exportedNames(content: string): Promise<string[]>;
-/** Every exported symbol is referenced in its sibling test. */
+/**
+ * Every exported symbol is referenced in its sibling test.
+ *
+ * A refusal is one line: the sibling test once, then every export it never mentions.
+ */
 export declare const symbolsInSibling: (options: {
     sibling: string;
 }) => Check;
@@ -270,69 +292,35 @@ export declare const changeTogether: (options: {
  * aimed at a directory called HEAD.
  */
 export declare const GIT_VALUE_OPTS: ReadonlySet<string>;
-/** A heredoc's opener: its delimiter, whether `<<-` strips leading tabs, and where the opener ends. */
-export interface HeredocOpen {
-    readonly delim: string;
-    readonly tabs: boolean;
-    readonly end: number;
-}
-/**
- * The first heredoc opener anywhere in a line, quoted context or not — the one definition of "this
- * line carries a heredoc". A here-string (`<<<`) is stepped over whole, so its tail is not read as
- * one.
- */
-export declare function firstHeredoc(s: string): HeredocOpen | null;
+/** What a command reader is handed: the line, and its parse when the engine made one. */
+type CommandFacts = Pick<Ctx, "command" | "commands">;
 /**
- * Where a `$(` closes, honouring quotes, nesting and any heredoc inside it — a body is text, so an
- * apostrophe or a `)` in it closes nothing. -1 when it never closes.
+ * The command line parsed as bash: `ctx.commands`, or the line parsed here when the ctx carries no
+ * parse at all — which is what an engine older than the parse hands these checks. Null when the
+ * line does not parse, and every reader takes null as "cannot tell".
  */
-export declare function closeParen(s: string, from: number): number;
-/** Where a double-quoted run closes — a `"` inside a `$(…)` in it does not close it. -1 when it never does. */
-export declare function dquoteEnd(s: string, from: number): number;
-/**
- * THE COMMAND LINE WITHOUT ITS HEREDOC BODIES — what a command ban matches unless the rule sets
- * `matchHeredocs`.
- *
- * A heredoc is text fed to a program on its standard input: a python script, a file being written,
- * a note. The words of a banned command inside it are not a use of that command, and matching
- * them refused `python3 - <<'PY'` scripts for naming a recipe in a string. Every body is removed
- * (its terminator line stays, so the opener still ends), whether the delimiter is quoted or not,
- * and wherever the heredoc sits —
- * inside a `$(…)` or a quoted argument too. EVERYTHING ELSE IS LEFT AS WRITTEN — newlines
- * included, because the patterns that police a commit message span them.
- *
- * One exception keeps a body: a heredoc fed to a SHELL (`bash`, `sh`, `zsh`, `eval`, or a pipeline
- * into one), whose body is commands, and a banned one in it will run.
- *
- * Best-effort, and it errs toward matching: from a word whose quote never closes, the line is
- * returned as written, so a ban still sees everything it saw before.
- */
-export declare function elideHeredocs(command: string): string;
-/**
- * A shell-ish tokeniser: quotes respected (so a commit message mentioning `git commit` is not a
- * second command), operators emitted as their own tokens.
- *
- * Null on unparseable input — an unclosed quote — and null means "cannot tell", which every caller
- * must read as "do not judge". A guard that guesses at a line it cannot parse is worse than one
- * that stands aside.
- */
-export declare function tokenizeCommand(command: string): string[] | null;
-/** One `git …` in a command line, split where git stops and its subcommand starts. */
-export interface GitInvocation {
+export declare function shellCommands(facts: CommandFacts): readonly ShellCommand[] | null;
+/** One `git` command in the parse, split where git's own options stop and its subcommand starts. */
+export interface GitCommand {
     /** git's OWN options, before the subcommand — where `-C` counts and only there. */
     readonly globals: readonly string[];
-    /** The subcommand word (`commit`, `status`), or null when the invocation carries none. */
+    /** The subcommand word (`commit`, `status`), or null when the command carries none. */
     readonly subcommand: string | null;
     /** Everything after the subcommand — its own flags and arguments. */
     readonly args: readonly string[];
+    /** Where `args` starts in `command.args`: `args[i]` is `command.args[argsAt + i]`. */
+    readonly argsAt: number;
+    /** The parsed command it was read from: its heredocs are what `git commit -F -` reads. */
+    readonly command: ShellCommand;
 }
 /**
- * Every git invocation in a command line, in order. Null when the line cannot be parsed at all.
- *
- * A token only starts an invocation at a COMMAND position — the start of the line or just after an
- * operator — so a `git` inside a quoted message or as an argument to something else is not one.
+ * One parsed command read as git, or null when its program is not git. The parse has already
+ * found the program, so a `git` inside a quoted message, a heredoc body or another command's
+ * arguments is never one, and a `git` inside `$( … )` or a `bash -c` string is.
  */
-export declare function gitInvocations(command: string): GitInvocation[] | null;
+export declare function gitCommand(command: ShellCommand): GitCommand | null;
+/** Every git command the line runs, in the order the parse lists them; none when it does not parse. */
+export declare function gitCommands(facts: CommandFacts): GitCommand[];
 /**
  * The message a `git commit` in this command line carries, or null when there is no judgeable
  * commit in it at all. Null is the "not our business" answer and every caller passes on it.
@@ -350,7 +338,12 @@ export declare function gitInvocations(command: string): GitInvocation[] | null;
  *
  *   git commit -m MSG · -mMSG · --message MSG · --message=MSG      judged
  *   git commit -m SUBJECT -m BODY   (repeated, any mix of forms)   judged, joined as git joins them
- *   git commit -F - <<'EOF' … EOF   (the commit reads stdin)        judged, via the heredoc body
+ *   git commit -m "$(cat <<'EOF' … EOF)"                            judged, via that heredoc's body,
+ *                                                                  which is what the shell passes
+ *   git commit -F - <<'EOF' … EOF   (the commit reads stdin)        judged, via ITS heredoc's body
+ *   python3 - <<'PY' … PY; git commit -F - <<'EOF' … EOF            judged, via the commit's own
+ *                                                                  heredoc — the first one is the
+ *                                                                  python's script
  *   python3 - <<'PY' … PY; git commit -F msg.txt                    NOT judged — the heredoc is
  *                                                                  another command's script, and
  *                                                                  the message is on disk
@@ -364,7 +357,7 @@ export declare function gitInvocations(command: string): GitInvocation[] | null;
  * The boundary is on the record: this rail polices AGENT-typed commits, which are its audience. A
  * human committing from an editor is not its subject and never was.
  */
-export declare function commitMessage(command: string): string | null;
+export declare function commitMessage(facts: CommandFacts): string | null;
 /** One shell argument, single-quoted so nothing in it can be expanded or re-parsed. */
 export declare function quoteArg(value: string): string;
 /**
@@ -392,15 +385,16 @@ export declare function quoteArg(value: string): string;
  * options exactly as a shell chains directory changes: `cd /a && git -C b status` runs in `/a/b`,
  * and `-C '/a' -C 'b'` says precisely that. Nothing has to decide which of the two wins.
  *
- * ONLY A LEADING `cd`, and only when an operator follows its path. A `cd` in the middle of a chain
- * can be preceded by another that already moved, and a command line that walks two trees is beyond
- * what one answer can honestly describe — the same reason the FIRST git invocation decides below.
+ * ONLY A LEADING `cd`, and only when a command follows it. A `cd` in the middle of a chain can be
+ * preceded by another that already moved, and a command line that walks two trees is beyond what
+ * one answer can honestly describe — the same reason the FIRST git command decides below. Both are
+ * read from the parse, so a `cd` or a `git` inside a quoted argument or a heredoc body is neither.
  *
  * A path the SHELL would have expanded — `~`, a variable — is quoted here and so reaches git
  * literally, which makes the read fail rather than lie. Every caller treats a failed read as "not
  * a repo, git owns that error" and passes: a false negative, which is this pack's stated trade.
  */
-export declare function gitDirPrefix(command: string): string;
+export declare function gitDirPrefix(facts: CommandFacts): string;
 /**
  * Does the message carry the token, on a LINE OF ITS OWN?
  *
@@ -655,7 +649,7 @@ export interface Layer {
     readonly not?: readonly string[];
 }
 export interface Dialect {
-    /** What to cruise. A GLOB, because a bare directory makes depcruise cruise zero modules. */
+    /** What to cruise: a directory or a glob. `src` and `src/**` cruise the same modules. */
     readonly scan: string;
     /** Each layer, as globs — a bare list, or `{ path, not }` when it has holes in it. */
     readonly layers: Readonly<Record<string, readonly string[] | Layer>>;
@@ -667,8 +661,6 @@ export interface Dialect {
     readonly require?: readonly RequireEdge[];
     /** Carve-outs — `type-only` above all, since a type import is erased at compile time. */
     readonly except?: readonly string[];
-    /** Informational rules that never block. `sdp` = the Stable Dependencies Principle. */
-    readonly warn?: readonly string[];
     /** dependency-cruiser's own options, passed through. */
     readonly options?: Readonly<Record<string, unknown>>;
 }
@@ -755,6 +747,15 @@ export declare function nonGlobLayers(layers: Readonly<Record<string, readonly s
  * at load: use plain globs for a layer that an `only` names, or express the exclusion as a `forbid`.
  */
 export declare function holesInAnOnlyList(opts: Dialect): string[];
+/**
+ * A `warn` option — refused, because it is gone and its rule would silently go with it.
+ *
+ * `warn: ["sdp"]` compiled a Stable Dependencies rule that nothing bound, and it is removed with no
+ * replacement. The type no longer has the key, so a literal config fails to compile; but options
+ * built in a variable carry it past the compiler, and dropped quietly the rule would report armed
+ * and fence nothing. It is read off the raw object because the type cannot name it.
+ */
+export declare function removedWarnOption(opts: Dialect): string[];
 /**
  * The generic import-fence runner.
  *
@@ -847,6 +848,10 @@ export declare function readCase(c: Case): {
     readonly dialect: CaseDialect;
     readonly facts: Partial<Ctx>;
     readonly world: CaseWorld;
+    /** commit: the staged paths the last commit does not have, when the case says. */
+    readonly added?: readonly string[] | undefined;
+    /** commit: the staged deletions, by path, with their content as the last commit has it. */
+    readonly deleted?: Readonly<Record<string, string>> | undefined;
 };
 /** Which moment's dialect a case speaks. */
 export declare function caseMoment(c: Case): Moment;

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

@@ -1,4 +1,4 @@
-import { inScope, type Scope, type BreadcrumbMoment, type CaseWorld, type Category, type EntrySpec, type GuardrailMoment, type LoadResult, type LoadedEntry, type Moment, type SessionFacts, type Settings, type TurnAction, type Unanswered, type World } from "../language/domain.ts";
+import { inScope, type Scope, type BreadcrumbMoment, type CaseWorld, type Category, type Ctx, type EntrySpec, type GuardrailMoment, type LoadResult, type LoadedEntry, type Moment, type SessionFacts, type Settings, type TurnAction, type Unanswered, type World } from "../language/domain.ts";
 /**
  * How a category recognises its members from host-written evidence.
  *
@@ -9,7 +9,7 @@ import { inScope, type Scope, type BreadcrumbMoment, type CaseWorld, type Catego
  */
 export interface SpawnRecipe {
     /**
-     * Sidecar agent types that ARE this category, decisively. Brief text is never consulted for a
+     * Host-sent agent types that ARE this category, decisively. Brief text is never consulted for a
      * session whose type is named here — nor for one whose type is named anywhere but `generic`.
      */
     readonly types?: readonly string[];
@@ -21,7 +21,7 @@ export interface SpawnRecipe {
     /** Substrings that recover this category from a generic spawn's brief. */
     readonly brief?: readonly string[];
     /**
-     * True for the top-level session only — no sidecar, no agent type. Structural, and exclusive: a
+     * True for the top-level session only — not spawned, no agent type. Structural, and exclusive: a
      * recipe is either about spawns or about the parent, never both.
      */
     readonly parent?: boolean;
@@ -64,21 +64,33 @@ export declare function categoriesIn(entries: readonly LoadedEntry[]): Category[
  * accident — a transcript since compacted, a brief scrolled away — and a rule that fired for the
  * first half of a session and not the second is worse than either outcome alone. The unit is
  * session × agent because that is what the evidence is about: each subagent has its own transcript
- * and its own sidecar.
+ * and its own agent id.
  */
 export declare function identify(stored: readonly string[] | undefined, facts: SessionFacts, categories: readonly Category[]): Identity;
 /** One event the guardrail rails carry. Facts only — who it happened to is `wearing`. */
 export interface GuardEvent {
     readonly moment: GuardrailMoment;
     /** write/delete: the would-be file, in memory, before disk. */
-    readonly file?: {
-        readonly path: string;
-        readonly content: string;
-    } | undefined;
+    readonly file?: Ctx["file"];
     /** command: the line about to run. */
     readonly command?: string | undefined;
+    /** command: the line's parse, when the caller already made it. Absent, the engine parses the line. */
+    readonly commands?: Ctx["commands"];
     /** commit: the staged paths. */
     readonly staged?: readonly string[] | undefined;
+    /**
+     * commit: the staged paths the last commit does not have, which become each file's `existed`.
+     * Absent when the shell could not ask git, and then `existed` is left unset.
+     */
+    readonly added?: readonly string[] | undefined;
+    /**
+     * commit: the staged deletions an entry will judge (`judgedDeletions`), each with its content as
+     * the last commit has it. A rename is a deletion of its old path plus an add of its new one.
+     */
+    readonly deleted?: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[] | undefined;
     /** turn-end: what the actor did this turn, in order. */
     readonly turn?: readonly TurnAction[] | undefined;
     /** Every category this session × agent wears. Empty means it wears none, not "all of them". */
@@ -123,6 +135,12 @@ export declare function covers(scope: Scope, path: string): boolean;
  * guarded on one page and abandoned on the next.
  */
 export declare function watching(entries: readonly Bound[]): Bound[];
+/**
+ * The staged deletions some entry will judge — the ones whose content is worth reading from the
+ * last commit. A commit that removes a vendored folder is thousands of deletions, and none of them
+ * costs a read unless a rule is about it.
+ */
+export declare function judgedDeletions(entries: readonly LoadedEntry[], deleted: readonly string[]): string[];
 /** A rail refusing. `entry` is null when it is the guard itself that is broken, not a rule. */
 export interface Block {
     readonly do: "block";
@@ -146,6 +164,12 @@ export interface Notice {
     /** The file the prose lives in, when it did not. The shell resolves it; a pure home cannot. */
     readonly file: string | undefined;
     readonly cause: Cause;
+    /**
+     * What the event that showed it was about: the repo-relative path, or the command line, as a
+     * guardrail row's subject is. Absent when the event carries no file or command, such as a
+     * session note or a fault.
+     */
+    readonly subject: string | undefined;
 }
 export type Effect = Block | Notice;
 /**
@@ -359,15 +383,42 @@ export interface SessionMarker {
      * delete. Absent on a marker written before this field existed, which reads as "unknown actor".
      */
     readonly agent?: unknown;
+    /** The type that agent was started as, for the commit gate's log rows. Absent on `main`. */
+    readonly agentType?: unknown;
     readonly ts?: unknown;
 }
+/**
+ * The agent one row, marker or call came from: the key its state is stored under, and its type.
+ *
+ * One value rather than two loose ones, because the type means nothing without the id it belongs to.
+ */
+export interface AgentOf {
+    /** `main` for the session itself, a subagent's `agent_id`, or `commit`: see `UNNAMED_COMMIT`. */
+    readonly agent: string;
+    /** The type the subagent was started as, when the host said. Never beside `main` or `commit`. */
+    readonly agentType?: string;
+}
+/**
+ * The agent a commit-gate run's rows name when no agent can be named: no marker, a stale one, or
+ * one written before markers held the agent. `commit` is also the stream such a commit's rows land
+ * in when no session claims it.
+ */
+export declare const UNNAMED_COMMIT: AgentOf;
+/**
+ * An agent named by an id and, maybe, a type — the one reading of the pair, wherever it is read
+ * from: a hook message's `agent_id` and `agent_type`, or a marker's `agent` and `agentType`.
+ *
+ * Null when the id is not a non-empty string, and the type counts only beside such an id, because a
+ * type means nothing without the agent it belongs to.
+ */
+export declare function namedAgent(id: unknown, type: unknown): AgentOf | null;
 /** A commit long after the last edit is not this session's. */
 export declare const MARKER_MAX_AGE_MS: number;
 /** Who a commit-gate run belongs to: the live session, and which of its agents was working. */
 export interface Attribution {
     readonly session: string;
     /** Null when the marker named no agent — an old marker, or a run with nobody to attribute to. */
-    readonly agent: string | null;
+    readonly who: AgentOf | null;
 }
 /**
  * Which session × agent a commit-gate run belongs to, given the marker it found.
@@ -647,12 +698,11 @@ export declare const RECORDING_VERSION = 1;
 export type RecordedStep = {
     readonly rail: "guard";
     readonly moment: GuardrailMoment;
-    readonly file?: {
-        readonly path: string;
-        readonly content: string;
-    } | undefined;
+    readonly file?: Ctx["file"];
     readonly command?: string | undefined;
     readonly staged?: readonly string[] | undefined;
+    readonly added?: readonly string[] | undefined;
+    readonly deleted?: GuardEvent["deleted"];
     readonly turn?: readonly TurnAction[] | undefined;
     readonly wearing: readonly string[];
     readonly world?: CaseWorld | undefined;
@@ -736,8 +786,8 @@ export interface RowDiff {
  * Only the two MECHANISM rows are compared, and that is not a softening: a replay has no tool
  * calls to record and no session to stamp a meta row for, so `tool`, `run` and `meta` are facts
  * about the live process rather than about the guard's judgement. What the recording claims is
- * that the same rules refuse the same subjects and the same notes show for the same causes, and
- * those are exactly the rows named here.
+ * that the same rules refuse the same subjects and the same notes show for the same causes and
+ * files, and those are exactly the rows named here.
  */
 export declare function diffRows(replayed: readonly Row[], live: readonly Row[]): RowDiff[];
 /**

package/dist/types/engine/state.d.ts

@@ -1,5 +1,5 @@
 import type { Category, SessionFacts } from "../language/domain.ts";
-import { type Attribution, type Identity, type RecordedStep, type Recording, type Row, type SessionRows, type SessionState } from "./domain.ts";
+import { type AgentOf, type Attribution, type Identity, type RecordedStep, type Recording, type Row, type SessionRows, type SessionState } from "./domain.ts";
 /**
  * Create `.flow/`, self-ignored, and answer whether it is there.
  *
@@ -35,11 +35,14 @@ export interface LogContext {
     readonly session: string;
     /** The branch this worktree has out, for the stream's meta row. The adapter knows it; this does not. */
     readonly branch: string | null;
+    /** The agent every row came from, stamped beside the time. */
+    readonly who: AgentOf;
     /** Injected, because a clock inside a decision is a decision nobody can test. */
     readonly now?: () => Date;
 }
 /**
- * Append rows to this session's stream, stamping each with the time and the next event index.
+ * Append rows to this session's stream, stamping each with the time, the next event index and the
+ * agent it came from.
  *
  * The FIRST write creates the file with its meta row, which is the fail-loud "armed" marker — a
  * present-but-quiet log and a missing one are different facts, and a reader that cannot tell them
@@ -99,6 +102,6 @@ export declare function loadRecording(file: string): Recording;
  * marker tracks the session's latest activity and its timestamp is what `attribution` judges
  * freshness by.
  */
-export declare function writeMarker(root: string, session: string, agent: string, branch: string | null, at?: Date): boolean;
-/** Who this worktree's commit belongs to — the fresh marker's session × agent, or `commit`. */
+export declare function writeMarker(root: string, session: string, who: AgentOf, branch: string | null, at?: Date): boolean;
+/** Who this worktree's commit belongs to — the fresh marker's session × agent and its type, or `commit`. */
 export declare function commitAttribution(root: string, branch: string | null, nowMs?: number): Attribution;

package/dist/types/index.d.ts

@@ -1,10 +1,11 @@
 export { guardrail, breadcrumb, type Sentence, type EntrySpec, type GuardrailSpec, type BreadcrumbSpec, type GuardrailSentence, type BreadcrumbSentence, type EntryGroup, type DisabledMark, } from "./language/domain.ts";
 export { definePack, pack, override, defineConfig, type Pack, type PackDefinition, type EntryRef, type RefTarget, type FlowConfig, type Binding, type PackBinding, type OverrideBinding, type ConfigSentence, } from "./language/domain.ts";
-export { defineCheck, withFaults, faultsOf, type Check, type Ctx, type World, type Verdict, type ExecResult, type TurnAction, type Case, type CaseWorld, type Cases, } from "./language/domain.ts";
+export { defineCheck, withFaults, faultsOf, type Check, type Ctx, type World, type Verdict, type ExecResult, type TurnAction, type ShellCommand, type ShellHeredoc, type ShellRedirect, type ShellSubstitution, type Case, type CaseWorld, type Cases, } from "./language/domain.ts";
 export { defineCategory, type Category, type Classifier, type SessionFacts } from "./language/domain.ts";
 export { astGrep, banCommands, canonicalFiles, changeTogether, commitReason, depcruise, execPasses, jsonInvariant, oneWriter, protectedPath, ranSinceEdit, siblingExists, symbolsInSibling, textBan, type CanonOptions, type ChangeGroup, type Dialect, type Layer, type DiffAdds, type ForbidEdge, type JsonAssert, type RequireEdge, } from "./checks/domain.ts";
 export { substitutionInProse, SUBSTITUTION_MESSAGE } from "./checks/domain.ts";
-export { commitMessage, gitDirPrefix, gitInvocations, givesReason, quoteArg, tokenizeCommand, type GitInvocation, } from "./checks/domain.ts";
+export { programName } from "./language/domain.ts";
+export { commitMessage, gitCommand, gitCommands, gitDirPrefix, givesReason, quoteArg, shellCommands, type GitCommand, } from "./checks/domain.ts";
 export { spawnedAs, type SpawnRecipe } from "./engine/domain.ts";
 export { write, command, commit, deletion, turnEnd, session, touch, type Moment, type GuardrailMoment, type BreadcrumbMoment, } from "./language/domain.ts";
 export { loadConfig, refusalText, REFUSAL_CODES, type Refusal, type RefusalCode, type LoadResult, type LoadedEntry, type Settings, } from "./language/domain.ts";