approval-md 0.1.0 → 0.2.0

package/dist/src/core/advance-cycle.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The vocabulary of a daemon advance cycle, as facts about the log (APRV-204).
+ *
+ * Pure over records: no git, no filesystem, no clock. It lives in `core/`
+ * because three layers ask the same two questions of it — the daemon that
+ * writes the cycles (`daemon/advance.ts`), the doctor row that reports the last
+ * one (`cli/doctor.ts`), and the trigger arithmetic that must not count the
+ * daemon's own bookkeeping — and a CLI module may not import the daemon
+ * (`tests/layering.test.ts`). One home, so the three cannot disagree about
+ * which records are an advance's own.
+ */
+import type { EventRecord } from "./log.js";
+import { type RequestState } from "./state.js";
+/**
+ * Who proposes an advance.
+ *
+ * `agent:daemon`, not the `system:daemon` of `envelope.drift`: the gate's
+ * proposing side is a PRINCIPAL (`human:` or `agent:`), and an advance is a
+ * request to act on the world rather than a fact the runtime observed about
+ * itself. The distinction is load-bearing in the log — a reader tells the
+ * daemon's observations from the daemon's actions by the actor alone.
+ */
+export declare const ADVANCE_ACTOR = "agent:daemon";
+/** The class an advance is gated as. Declared, resolved, and never assumed. */
+export declare const ADVANCE_CLASS = "log.advance";
+/** The task id every advance cycle registers under, plus its head seq. */
+export declare const ADVANCE_TASK_PREFIX = "daemon-advance";
+/** The idempotency key prefix. One key per (published head → working head) span. */
+export declare const ADVANCE_KEY_PREFIX = "daemon-log-advance";
+/** The task id for a cycle that publishes up to `toSeq`. */
+export declare function advanceTaskId(toSeq: number): string;
+/** The idempotency key for the span `fromSeq..toSeq`. */
+export declare function advanceActionKey(fromSeq: number, toSeq: number): string;
+/**
+ * Is this record part of an advance cycle's own bookkeeping?
+ *
+ * Keyed on the task id the daemon registers under, which nothing else writes.
+ * A record whose task merely LOOKS like one of those but was written by another
+ * actor is still excluded, deliberately: the exclusion only ever makes the
+ * cadence advance LESS eagerly, so a false positive costs latency while a false
+ * negative would cost an endless cadence (one cycle appends three records, the
+ * last of them after the commit).
+ */
+export declare function isAdvanceBookkeeping(record: EventRecord): boolean;
+/**
+ * The most recent advance cycle's request, as the log derives it (APRV-211).
+ *
+ * The whole answer a tick needs before it considers asking anything: which key
+ * the last question was opened under, what the human did with it, what bytes it
+ * bound to, and whether anything has spent it yet.
+ */
+export interface OpenAdvanceRequest {
+    actionKey: string;
+    task: string | null;
+    state: RequestState;
+    /** The `payload_hash` the request declared, so an adopting tick binds to it. */
+    payloadHash: string | null;
+    /** True once an `execution.started` has spent this cycle. */
+    spent: boolean;
+}
+/**
+ * The latest advance request in the log, with its derived state, or `null`.
+ *
+ * ## Why the daemon asks this before it asks the gate anything
+ *
+ * A gated advance leaves an `approval.requested` open and its own two records
+ * on the log. Until APRV-211 the next tick recomputed a key from the moving
+ * head, found no request under it, and opened a second question about the same
+ * owed work; the human got one phone buzz per tick for one advance. So the tick
+ * now reads the log for what it already asked, and the answer here is that
+ * reading.
+ *
+ * PURE, and over records the caller verified: the enforcement path never reads
+ * an unverified log (SPEC.md §11.1). The TTL is applied through
+ * {@link requestState}, so a request whose window lapsed reads `expired` here
+ * whether or not the daemon has yet materialised an `approval.expired` record —
+ * an adopting tick must not wait forever on a question nobody can answer.
+ */
+export declare function openAdvanceRequest(records: readonly EventRecord[], ts: string, ttlMs: number | null): OpenAdvanceRequest | null;
+/** What the log says about the most recent advance cycle. */
+export interface LastAdvance {
+    /** The working head the cycle was registered for. */
+    toSeq: number;
+    ts: string;
+    /**
+     * `completed` / `failed` for a cycle that executed, `awaiting` for one the
+     * gate sent to a human and that nobody has answered, `requested` for one
+     * whose question was decided but never executed, `registered` for a cycle
+     * that got no further.
+     */
+    outcome: "completed" | "failed" | "awaiting" | "requested" | "registered";
+    /**
+     * Why it failed, as the verb said it (APRV-211): the refusal code and message
+     * `cli/log-advance.ts` produced, copied onto `execution.failed` at the write
+     * boundary. `null` for every other outcome and for a failure recorded before
+     * the field existed — an exit status with no reason, which is the defect this
+     * carries the fix for and not a shape any reader may assume away.
+     */
+    code: string | null;
+    message: string | null;
+}
+/**
+ * The most recent advance cycle in the log, or `null` when there is none.
+ *
+ * Read from the LOG rather than from a status file, because the log already
+ * carries every fact this answer needs and a second copy could disagree with
+ * it. That is what lets `approval doctor` answer it in a different process from
+ * the daemon that made the attempt, with no shared state between them, and what
+ * makes the answer outlive the daemon's own event stream.
+ */
+export declare function lastAdvance(records: readonly EventRecord[]): LastAdvance | null;
+/**
+ * The one-line repair for a pile of dangling executions, spelled once.
+ *
+ * Every surface that reports an advance nobody closed ends with this command:
+ * the daemon's refusal, its warning line, and the `log-advance-cadence` doctor
+ * row. Spelled here because a repair an operator has to reconstruct from three
+ * slightly different sentences is a repair they retype by hand five times,
+ * which is exactly what was observed on 2026-09-05 and exactly what this task
+ * removes.
+ */
+export declare const RESOLVE_DANGLING_COMMAND = "approval execution resolve --dangling";
+/**
+ * The seq the span named by `daemon-log-advance-<from>-<to>` ends at, or `null`.
+ *
+ * `null` for a key this runtime did not mint the shape of. A key whose tail is
+ * not an integer names no span, so nothing about it can be proved from the
+ * refs, and it is reported as unprovable rather than guessed at.
+ */
+export declare function advanceSpanEnd(actionKey: string): number | null;
+/**
+ * One dangling execution, and what this checkout's git refs can prove about it.
+ *
+ * `provenBy` is the whole point: a ref name, or `null`. A sweep may close only
+ * the first kind, and every surface that reports the second kind reports it as
+ * a human's to establish rather than as a failure — an `execution.failed`
+ * written over an advance that actually published would be worse than the
+ * dangling record it replaced.
+ */
+export interface DanglingAdvance {
+    actionKey: string;
+    task: string | null;
+    /** The `execution.started` record's position. */
+    seq: number;
+    /** The seq the key names, or `null` when the key names no span. */
+    toSeq: number | null;
+    /** The ref that carries `toSeq`, or `null` when nothing in this checkout does. */
+    provenBy: string | null;
+}
+/** Every dangling execution whose key is one this daemon mints, in log order. */
+export declare function danglingAdvances(records: readonly EventRecord[]): DanglingAdvance[];
+/**
+ * The same list, with each entry's proof filled in from a published state.
+ *
+ * PURE, and the published state is an argument rather than something read here:
+ * `publishedState` lives in `cli/log-advance.ts` because it reads git, a CLI
+ * module may not import the daemon, and the daemon, the doctor row and
+ * `execution resolve --dangling` must not disagree about which key counts as
+ * proved. So the git read happens once in each caller and the RULE lives here.
+ *
+ * The rule is one comparison: the ref that carries the highest published seq
+ * carries every seq below it, because `publishedState` only ever counts a copy
+ * of this chain that is a PREFIX of the working log. So a span ending at or
+ * below `publishedSeq` is on that ref, and a span above it is on nothing this
+ * checkout can see.
+ */
+export declare function proveDanglingAdvances(records: readonly EventRecord[], published: {
+    publishedSeq: number;
+    publishedRev: string | null;
+}): DanglingAdvance[];

package/dist/src/core/agents-md.d.ts

@@ -0,0 +1,276 @@
+/**
+ * AGENTS.md permissions import (SPEC.md §2, §12) — turn permissions PROSE into
+ * a DRAFT policy block a human can read, correct, and confirm.
+ *
+ * SPEC.md §2 names the gap this closes: AGENTS.md files "routinely contain
+ * permissions sections splitting actions into 'allowed without prompting' and
+ * 'require approval first'", and "nothing checks". SPEC.md §12 gives the verb:
+ * `approval import agents-md` "parses ... permissions sections into draft
+ * policy classes for human confirmation".
+ *
+ * ## This module is deterministic, and there is no model in it
+ *
+ * Per CLAUDE.md's engineering invariants, routing and policy are pure
+ * deterministic code; LLMs are confined to language tasks. Reading a bullet
+ * list is a language task in appearance only — its OUTPUT is a permission
+ * document, so the mapping is a fixed, ordered, documented keyword table
+ * ({@link CLASS_TABLE}), not a judgement. The same bytes always produce the
+ * same draft, on any machine, with no network and no clock. An LLM-assisted
+ * `--suggest` (proposing classes for bullets this table cannot place) is a
+ * separate, opt-in, out-of-scope idea: it would be allowed to propose, never
+ * to decide.
+ *
+ * ## The grammar
+ *
+ * Input is CommonMark-ish markdown. The scanner is line-based:
+ *
+ * - **Fenced code blocks** (``` or ~~~, 3+ markers, indented at most 3 spaces)
+ *   are skipped entirely. A bullet inside an example block is an example.
+ * - **Headings** are ATX only: `^ {0,3}#{1,6}\s+text`, trailing `#`s stripped.
+ *   Setext headings are not recognised; the convention in the wild is ATX.
+ * - A heading whose text contains `permissions` (case-insensitive, at any
+ *   level) opens the **permissions region**. The region closes at the next
+ *   non-canonical heading whose level is less than or equal to the permissions
+ *   heading's level.
+ * - Three **canonical sub-headings** open a section, matched case-insensitively
+ *   against {@link SECTION_PHRASES} after normalisation (lowercased, markdown
+ *   emphasis and backticks stripped, whitespace collapsed, trailing `:`
+ *   dropped). They are recognised at ANY level and, deliberately, whether or
+ *   not a parent `Permissions` heading exists: the bare three-heading layout is
+ *   common in AGENTS.md files.
+ * - **Bullets** are `-` or `*` list items (`^\s*[-*]\s+`) appearing while a
+ *   section is open. A following line that is not blank, not a heading, not a
+ *   list item and not a fence is a **continuation** and is joined to the
+ *   previous bullet with a single space. Any heading closes the open section.
+ * - Every other line is ignored.
+ *
+ * Non-canonical headings seen inside the permissions region, and non-canonical
+ * headings that interrupt an open section, are reported in `ignored` rather
+ * than silently dropped: a heading the importer did not understand may be
+ * carrying permissions prose, and the human confirming the draft is the one who
+ * should decide.
+ *
+ * ## Fail closed
+ *
+ * A bullet the table cannot place is NOT guessed at and NOT dropped. It becomes
+ * an `unmapped` entry, is preserved verbatim as a comment in the draft, and is
+ * covered by `defaults.autonomy: manual` — the strictest outcome available.
+ * Likewise a source with no permissions section produces an empty draft (all
+ * classes manual by default) plus a warning, never a permissive one.
+ *
+ * ## The values draft
+ *
+ * Since APRV-240 the same file is scanned a second time for four optional
+ * headings ("what I value", "what good looks like", "how I like to work",
+ * "what I want from you") and their bullets are drafted into a
+ * ` ```yaml approval-values ` block (SPEC.md §5.3). Every bullet lands in
+ * `wants:`, and nothing is ever placed in `love:`, `like:` or `dislike:`.
+ * Grading is the human's act. This importer can see that a line was written
+ * down; it cannot see how much its author meant it, and a guessed grade would
+ * put words in their mouth inside the one block of `APPROVAL.md` that exists to
+ * carry their own.
+ *
+ * ## Namespaces
+ *
+ * SPEC.md §7 reserves top-level namespaces to the spec and lets implementations
+ * add sub-classes freely. The developer-workstation vocabulary this table emits
+ * (`vcs.*`, `deps.*`, `release.*`, `exec.*`, `network.*`, `policy.edit`) is not
+ * in the §7 table, which was written for life-admin side effects. That is a
+ * deliberate, visible property of a DRAFT: the classes are proposals a human
+ * renames or upstreams before confirming, and the draft says so in its header.
+ */
+/** Which prose section a bullet came from. */
+export type AgentsMdSection = "allowed" | "approval-first" | "never";
+/** SPEC.md §5.2 autonomy levels, strictest first. */
+export type Autonomy = "manual" | "supervised" | "autonomous";
+/** One list item of a permissions section. */
+export interface Bullet {
+    /** The bullet's text, continuation lines joined, marker stripped. */
+    text: string;
+    /** 1-based line number of the bullet's first line, for diagnostics. */
+    line: number;
+}
+/** The three recognised sections, each in source order. */
+export interface AgentsMdSections {
+    allowed: Bullet[];
+    approvalFirst: Bullet[];
+    never: Bullet[];
+}
+/** Result of {@link parseAgentsMd}. Pure function of the input bytes. */
+export interface AgentsMdParse {
+    sections: AgentsMdSections;
+    /** Headings the scanner met inside the permissions area and did not use. */
+    ignored: string[];
+    /** Human-facing notes; never a reason to relax anything. */
+    warnings: string[];
+}
+/**
+ * The class heuristic: an ORDERED, STABLE table. First match wins, and the
+ * order of this array IS the precedence. Each entry lists alternative keyword
+ * conjunctions; an alternative matches when every one of its keywords appears
+ * as a substring of the normalised bullet text.
+ *
+ * Ordering rules, so future edits stay principled:
+ *
+ * 1. The most consequential and most specific classes come first, because a
+ *    bullet naming several actions ("git push, merges to main, tag creation")
+ *    is placed by its first match and the safer placement is the broader,
+ *    more consequential class.
+ * 2. `network.call` precedes `deps.add` on purpose: "any network call beyond
+ *    package installs" contains "install" and is not a dependency bullet.
+ * 3. `vcs.push` precedes `vcs.push.main`: a bullet naming pushes generally
+ *    should govern all pushes, not only pushes to the default branch.
+ * 4. Generic verbs (`edit`, `read`) come last, since almost every bullet
+ *    contains one.
+ *
+ * Adding a keyword here changes what a draft proposes for existing files, so
+ * the table is pinned byte-for-byte by `tests/agents-md.test.ts` fixtures.
+ */
+export declare const CLASS_TABLE: ReadonlyArray<{
+    readonly cls: string;
+    readonly any: ReadonlyArray<readonly string[]>;
+}>;
+/** Text used for keyword matching: lowercased with whitespace collapsed. */
+export declare function normaliseBullet(text: string): string;
+/**
+ * The class this bullet proposes, or `null` when the table cannot place it.
+ *
+ * Deterministic, total, and side-effect free: the first entry of
+ * {@link CLASS_TABLE} with a satisfied keyword conjunction wins.
+ */
+export declare function classifyBullet(text: string): string | null;
+/**
+ * Parse the permissions region of an AGENTS.md-style document.
+ *
+ * Never throws. Pure function of `markdown`; see the module header for the
+ * grammar it accepts.
+ */
+export declare function parseAgentsMd(markdown: string): AgentsMdParse;
+/** Result of {@link parseValuesHeadings}. Pure function of the input bytes. */
+export interface ValuesDraft {
+    /** The recognised headings, normalised, in source order. */
+    headings: string[];
+    /** Bullets destined for `wants:`: truncated, deduped, capped. */
+    wants: string[];
+    /** Bullets past {@link VALUES_MAX_ITEMS}, kept so none is dropped silently. */
+    overflow: string[];
+    /** Human-facing notes; never a reason to relax anything. */
+    warnings: string[];
+}
+/**
+ * Collect the bullets under the optional values headings of an AGENTS.md-style
+ * document (SPEC.md §5.3).
+ *
+ * ## Everything goes to `wants`, and nothing is graded
+ *
+ * The values block has three standing grades (`love`, `like`, `dislike`) and
+ * one behavioural list (`wants`). This function fills `wants` and leaves the
+ * three grades empty, always. A grade is a statement of taste, and it is the
+ * human's to make: the source shows that a line was written under a heading, it
+ * does not show how strongly it was meant, and an importer that inferred
+ * "love" from an exclamation mark or a heading's wording would be putting words
+ * in its reader's mouth in the one block of `APPROVAL.md` that exists to carry
+ * theirs. `wants` is the honest destination for a bullet whose grade is
+ * unknown: it says the operator asked for something, which is exactly what a
+ * bullet under "what I want from you" demonstrates.
+ *
+ * ## The scan
+ *
+ * A second line-based pass over the same primitives {@link parseAgentsMd} uses,
+ * with the same rules: fenced code blocks are skipped whole (a bullet in an
+ * example block is an example), headings are ATX at any level, a values heading
+ * opens a section, any other heading closes one, and a non-blank line that is
+ * not a bullet, heading or fence is a continuation joined to the previous
+ * bullet with a single space.
+ *
+ * Never throws. No clock, no filesystem, no network.
+ */
+export declare function parseValuesHeadings(markdown: string): ValuesDraft;
+/** One proposed class rule, with the bullets that produced it. */
+export interface DraftClass {
+    cls: string;
+    autonomy: Autonomy;
+    /** Every bullet that mapped here, in source order. */
+    bullets: Array<{
+        text: string;
+        section: AgentsMdSection;
+    }>;
+    /** The bullet that decided the autonomy (strictest, earliest on ties). */
+    from: {
+        text: string;
+        section: AgentsMdSection;
+    };
+}
+/** A bullet the table could not place. Covered by `defaults.autonomy`. */
+export interface UnmappedBullet {
+    text: string;
+    section: AgentsMdSection;
+}
+/** Result of {@link importAgentsMd}: the draft, and everything it could not use. */
+export interface AgentsMdImport {
+    classes: DraftClass[];
+    unmapped: UnmappedBullet[];
+    ignored: string[];
+    warnings: string[];
+    /**
+     * The values headings the same source declared (APRV-240). Empty `headings`
+     * means the source declared none, and no values fence is rendered at all: an
+     * absent values block is a declaration in its own right (SPEC.md §5.3), and a
+     * draft of one would be this importer inventing the declaration.
+     */
+    values: ValuesDraft;
+}
+/**
+ * Parse and classify: the whole deterministic half of `approval import
+ * agents-md`. Emitting bytes is {@link renderDraftPolicy}'s job.
+ *
+ * Conflicts follow SPEC.md §5.2 "deny beats allow": when bullets from different
+ * sections claim the same class, the strictest autonomy wins and a warning
+ * names both bullets, because a class that appears in both an allow list and an
+ * approval list is a contradiction in the SOURCE that a human must resolve.
+ */
+export declare function importAgentsMd(markdown: string): AgentsMdImport;
+/** Info string of the machine-readable policy block (SPEC.md §5). */
+export declare const POLICY_INFO_STRING = "yaml approval-policy";
+/**
+ * Render the values draft, fenced (APRV-240).
+ *
+ * The argument is the whole {@link ValuesDraft} rather than its bullets alone,
+ * because the entries past the cap have to appear in the output as comments:
+ * the renderer needs to see what was left out in order to say so.
+ *
+ * Deterministic, like everything else here. Entries are emitted as
+ * double-quoted scalars via `JSON.stringify`, whose escapes are all valid YAML
+ * double-quoted escapes, so a bullet full of backticks, colons and `#` survives
+ * the round trip without the renderer having to reason about YAML quoting.
+ */
+export declare function renderFencedValuesDraft(draft: ValuesDraft, source: string): string;
+/**
+ * The fenced values draft for an import, or `null` when the source declared no
+ * values headings. The `--json` surface's `values_draft` field, verbatim.
+ */
+export declare function valuesDraftOf(result: AgentsMdImport, source: string): string | null;
+/**
+ * Render the draft policy YAML. Deterministic: no clock, no cwd, no
+ * randomness — the only inputs are the import result and the source label, so
+ * the same file always produces the same bytes.
+ *
+ * With `values` omitted (or from a source that declared no values headings) the
+ * output is bare YAML with no fence, a valid policy under
+ * `schema/policy.schema.json` that loads through `loadPolicy` once wrapped in a
+ * ` ```yaml approval-policy ` fence.
+ *
+ * With a values draft the shape changes, and it has to. A values fence appended
+ * to bare YAML could not be pasted into a policy fence, because the values
+ * block's own closing fence would close the policy block and leave a file that
+ * loads as neither. So a two-block draft is emitted already fenced: the policy
+ * inside its ` ```yaml approval-policy ` fence, then the values fence after it,
+ * which is the shape `APPROVAL.md` itself has and which the policy loader and
+ * the values reader each read straight off disk.
+ */
+export declare function renderDraftPolicy(result: AgentsMdImport, source: string, values?: ValuesDraft | null): string;
+/**
+ * The draft wrapped in its ` ```yaml approval-policy ` fence, for stdout, with
+ * the values fence printed after it when the source declared values headings.
+ */
+export declare function renderFencedDraft(result: AgentsMdImport, source: string, values?: ValuesDraft | null): string;

package/dist/src/core/apply-patch.d.ts

@@ -0,0 +1,49 @@
+/** Strict parsing and path classification for Codex `apply_patch` (APRV-312). */
+import { type ProtectedPathEntry } from "./command-class.js";
+export type ApplyPatchOperation = {
+    kind: "add";
+    path: string;
+    lines: string[];
+} | {
+    kind: "delete";
+    path: string;
+} | {
+    kind: "update";
+    path: string;
+    moveTo?: string;
+    hunks: ApplyPatchHunk[];
+    eof: boolean;
+};
+export interface ApplyPatchHunk {
+    header: string;
+    lines: string[];
+}
+export type ApplyPatchParseResult = {
+    ok: true;
+    operations: ApplyPatchOperation[];
+} | {
+    ok: false;
+    detail: string;
+};
+/** Parse one exact apply_patch envelope. No filesystem reads occur here. */
+export declare function parseApplyPatch(raw: string): ApplyPatchParseResult;
+export interface ApplyPatchTarget {
+    role: "add" | "delete" | "update" | "move-destination";
+    path: string;
+    absolute: string;
+    resolved: string;
+    classes: string[];
+}
+export type ApplyPatchClassification = {
+    ok: true;
+    operations: ApplyPatchOperation[];
+    targets: ApplyPatchTarget[];
+    classes: string[];
+} | {
+    ok: false;
+    detail: string;
+};
+/** Resolve and classify every source and destination of a parsed patch. */
+export declare function classifyApplyPatch(parsed: {
+    operations: ApplyPatchOperation[];
+}, cwd: string, protectedPaths?: readonly ProtectedPathEntry[]): ApplyPatchClassification;