@nikovirtala/adr 0.2.0 → 0.3.0

package/dist/types/commit-actions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `{action}` of a commit that writes one event of each type (design §4.3), and what the title slot
+ * names: the decision's title for the events that change whether it is decided, else its display.
+ */
+export declare const ACTIONS: {
+    readonly proposed: {
+        readonly action: "propose to";
+        readonly names: "title";
+    };
+    readonly accepted: {
+        readonly action: "decide to";
+        readonly names: "title";
+    };
+    readonly rejected: {
+        readonly action: "decide not to";
+        readonly names: "title";
+    };
+    readonly withdrawn: {
+        readonly action: "withdraw the proposal to";
+        readonly names: "title";
+    };
+    readonly deprecated: {
+        readonly action: "deprecate";
+        readonly names: "display";
+    };
+    readonly superseded: {
+        readonly action: "supersede";
+        readonly names: "display";
+    };
+    readonly noted: {
+        readonly action: "add a note to";
+        readonly names: "display";
+    };
+    readonly linked: {
+        readonly action: "link";
+        readonly names: "display";
+    };
+    readonly scoped: {
+        readonly action: "set the scope of";
+        readonly names: "display";
+    };
+};
+/** `{action}` of `adr index --commit`, whose title slot holds `the decision index`. */
+export declare const INDEX_ACTION = "regenerate";
+/** What `adr index --commit`'s title slot holds. */
+export declare const INDEX_TITLE = "the decision index";
+/** The longest `{action}`, which `[commit] subject` must leave room for. */
+export declare const LONGEST_ACTION: number;
+/** The longest display: `ADR-` and up to 9 digits (`formatDecisionNumber`, kind/project.ts). */
+export declare const DISPLAY_LENGTH = 13;
+/** What a link's title slot names after the display when the target is in another log. */
+export declare const CROSS_LOG_LINK = "to a decision in another log";
+/** adr's commit-subject placeholders, each with its longest value (design §4.2). */
+export declare const COMMIT_VARS: Readonly<{
+    action: number;
+    id: 8;
+    display: 13;
+    command: 9;
+}>;
+/**
+ * The names the title placeholder holds instead of a title, which are never shortened, each with
+ * its action: supersede's `<display> with <display>` and a link's `<display> to <display>` or
+ * `<display> to a decision in another log` (`planLink` in write.ts), and `adr index`'s
+ * `the decision index`. The shorter names (a display, at most 13 characters) always fit in the
+ * room a title gets.
+ */
+export declare const COMMIT_NAMES: readonly {
+    length: number;
+    vars: {
+        action: number;
+    };
+}[];

package/dist/types/config.d.ts

@@ -7,7 +7,7 @@ export interface AdrConfig {
     readonly defaultTemplate: string;
     /** `[log] main_branch`: the ref numbers come from; `null` resolves it automatically. */
     readonly mainBranch: string | null;
-    /** `[log] index`: validated now, used in phase 2. */
+    /** `[log] index`: `committed` keeps a generated `<root>/index.md` fresh and verified. */
     readonly index: "committed" | "none";
     /** `[policy] accept_requires_human`. */
     readonly acceptRequiresHuman: boolean;
@@ -17,6 +17,12 @@ export interface AdrConfig {
     readonly mcpCanDecide: boolean;
     /** `[verify] fail_on`. */
     readonly failOn: Severity;
+    /** `[verify] governed_by_inactive`: the severity of `decision/governed-by-inactive`. */
+    readonly governedByInactive: Severity;
+    /** `[hooks] scope_follow_renames`: what the pre-commit hook does with renames of covered files. */
+    readonly scopeFollowRenames: "stage" | "warn" | "off";
+    /** `[hooks] index`: whether the pre-commit hook only checks `index.md` or regenerates it. */
+    readonly hookIndex: "check" | "stage";
     /** `[commit] subject`: the template of `--commit` subjects. */
     readonly commitSubject: CommitTemplate;
     /** `[scope] anchor_keyword`: the code-anchor keyword, `adr` in `// adr:<id>`. */

package/dist/types/hooks.d.ts

@@ -0,0 +1,59 @@
+import { type Finding, type HookManager, type HookName, type Severity } from "@nikovirtala/ledger";
+import type { DecisionLog } from "./log.js";
+/** `adr hooks … --json` (design 2b §4.3); `hooks run` prints `ledger-findings/v1` instead. */
+export interface HooksResultJson {
+    readonly format: "adr-hooks/v1";
+    readonly action: "install" | "uninstall" | "print" | "trailers";
+    /** Repo-relative shim paths written or removed. */
+    readonly written: readonly string[];
+    readonly unchanged: readonly string[];
+    readonly registrations: readonly {
+        readonly hook: HookName;
+        readonly argv: readonly string[];
+    }[];
+    /** `print` only. */
+    readonly snippet: string | null;
+    /** `trailers` only: the trailers added, in order. */
+    readonly trailers: readonly (readonly [string, string])[];
+}
+/**
+ * adr's command per hook (design 2b D4), after `adr`. `--root <root>` comes first only when the
+ * root can't be found without it: no `<repo>/adr.toml` names it and it isn't `docs/adr`. So the
+ * hooks see the same config as a plain `adr` run, and never print the root-override note.
+ */
+export declare function decisionHookCommands(log: DecisionLog): Partial<Record<HookName, readonly string[]>>;
+/**
+ * Registers adr's four commands in ledger's shims, one per hook and shared with other ark tools
+ * (design 2b D4). With `core.hooksPath` set or a foreign hook file present, it writes the rest and
+ * then throws `HookConflictError` (exit 2), naming each conflict and the `print` command.
+ */
+export declare function installDecisionHooks(log: DecisionLog): Promise<HooksResultJson>;
+/** Removes adr from every shim; a shim left with no tool is deleted. */
+export declare function uninstallDecisionHooks(log: DecisionLog): Promise<HooksResultJson>;
+/** The config to paste into a hook manager instead of installing shims. */
+export declare function printDecisionHooks(log: DecisionLog, manager: HookManager): HooksResultJson;
+/**
+ * The `commit-msg` step (P1 §7.1): appends one `ADR`/`ADR-Event` pair per staged added event file
+ * of the log, by path, keeping repeats (`ifExists: "add"`). It does nothing for a message that
+ * already has an `ADR-Event:` trailer (an `adr … --commit` message), or during a merge, whose
+ * events came with their own commits' trailers. Throws `UsageError` when the file is missing.
+ */
+export declare function addHookTrailers(log: DecisionLog, messageFile: string): Promise<HooksResultJson>;
+/**
+ * `adr hooks run pre-commit` (design 2b D8): rename following, then the index, then `verify
+ * --staged`, stopping at the first step that fails. `worktree` must be opened with the work-tree
+ * reader, because rename following writes through `write()`; `index` with the index reader, for
+ * the config as staged, the index render and verify. Only the index step stages `index.md`, and
+ * only with `[hooks] index = "stage"`; rename following passes `index: "skip"`. Neither stages
+ * into a temporary index (`stagingSafe`). A step that can't run throws (exit 2).
+ */
+export declare function runPreCommitHook(o: {
+    readonly worktree: DecisionLog;
+    readonly index: DecisionLog;
+    readonly env: NodeJS.ProcessEnv;
+}): Promise<{
+    readonly exit: 0 | 1;
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+    readonly failOn: Severity;
+}>;

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
 export { type AdrConfig, DEFAULT_ADR_CONFIG, parseAdrConfig } from "./config.js";
+export { addHookTrailers, decisionHookCommands, type HooksResultJson, installDecisionHooks, printDecisionHooks, runPreCommitHook, uninstallDecisionHooks, } from "./hooks.js";
 export { type InitResultJson, initDecisionLog } from "./init.js";
 export { type AdrOptions, adrKind, DECISION_STATUSES, type DecisionEvents, type DecisionState, type DecisionStatus, type DecisionView, formatDecisionNumber, type LinkRel, parseDecisionNumber, REF, } from "./kind.js";
-export { type DecisionLog, type DecisionsRead, openDecisionLog, readDecisions, readDecisionsFrom, resolveDecision, } from "./log.js";
+export { type ChangedSince, changedSince, type DecisionLog, type DecisionsRead, openDecisionLog, readDecisions, readDecisionsFrom, resolveDecision, } from "./log.js";
+export { type IndexResultJson, indexDecisionLog, renderDecisionIndex } from "./log-index.js";
 export { type DecisionForJson, type DecisionsForJson, decisionsFor, type UnresolvedAnchorJson, } from "./scope.js";
 export { adrChecks, verifyDecisions } from "./verify.js";
 export { type DecisionListJson, type DecisionShowJson, listDecisions, type NumberingJson, showDecision, stateHeader, } from "./views.js";

package/dist/types/init.d.ts

@@ -12,12 +12,18 @@ export interface InitResultJson {
     readonly commit: string | null;
     readonly notes: readonly string[];
 }
+/**
+ * What the recovery hint says about rerunning `adr init` after `git commit` failed (design 2b D5):
+ * init keeps existing files, so it would commit nothing.
+ */
+export declare const INIT_RERUN = "Running adr init again won't commit them: the files exist now, so it keeps them and commits nothing.";
 /**
  * `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
  * template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
  * A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
  * the log without `--root`; when that file exists for another log, the config goes in the root.
- * With `commit` (default `[policy] auto_commit`) the written files are committed on their own;
+ * With `[log] index = "committed"` it also writes `<root>/index.md` unless one exists. With
+ * `commit` (default `[policy] auto_commit`) the written files are committed on their own;
  * nothing written means nothing committed. No events are written.
  */
 export declare function initDecisionLog(log: DecisionLog, o?: {

package/dist/types/log-index.d.ts

@@ -0,0 +1,117 @@
+import { type Check, type Finding, type Git, type IndexSpec, type LogLayout, type TreeReader } from "@nikovirtala/ledger";
+import type { AdrConfig } from "./config.js";
+import { type DecisionView } from "./kind.js";
+import { type DecisionLog } from "./log.js";
+import type { WriteOptions } from "./write.js";
+/** `adr index --json` (design 2b §4.5). */
+export interface IndexResultJson {
+    readonly format: "adr-index/v1";
+    /** The index file, repo-relative: `<root>/index.md`. */
+    readonly path: string;
+    readonly check: boolean;
+    /**
+     * `--check`: no finding. Otherwise: the copies the command compares (the work tree and the
+     * index, or HEAD's when committing) already held the render.
+     */
+    readonly fresh: boolean;
+    /** Repo-relative paths this command wrote. */
+    readonly written: readonly string[];
+    readonly commit: string | null;
+    /** `--check`'s findings; `[]` otherwise. */
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+}
+/**
+ * What the recovery hint says about rerunning `adr index --commit` after `git commit` failed
+ * (design 2b D5). It names the file, not the path, which the hint lists above it.
+ */
+export declare const INDEX_RERUN = "You can also run adr index --commit again once git accepts the commit; it commits index.md while it differs from HEAD's.";
+/**
+ * The step before the manual commit when a write's second index render failed after staging
+ * (design 2b §4.5 step 4).
+ */
+export declare const INDEX_BEFORE: (root: string) => string;
+/**
+ * The step after the manual commit when the commit carried the index: the commit's render leaves
+ * out other decisions' uncommitted entries (design 2b D5, §4.5 step 5).
+ */
+export declare const INDEX_AFTER: (root: string) => string;
+/** The repo-relative path of a log's generated index. */
+export declare const indexPath: (layout: LogLayout) => string;
+/**
+ * adr's index spec (01:209: active decisions first), built per render so that a superseded
+ * decision's status can name its successor's display from `views`.
+ */
+export declare const DECISION_INDEX: (root: string, views: ReadonlyMap<string, DecisionView>) => IndexSpec<DecisionView>;
+/**
+ * The index `tree` must hold: its decisions, numbered as they will be once the commit holding
+ * `tree` (which builds on `history`: HEAD, a commit, or null on an unborn HEAD) is on main
+ * (design 2b D2), with `[log] main_branch`'s numbers first. A tree that isn't a commit's (the work
+ * tree, the index) also merges `MERGE_HEAD` while a merge is in progress. In a shallow clone the
+ * numbers continue from those `history`'s index recorded; `null` when there are none, so the
+ * numbers can't be projected.
+ */
+export declare function renderDecisionIndex(git: Git, o: {
+    readonly layout: LogLayout;
+    readonly adr: AdrConfig;
+    readonly tree: TreeReader;
+    readonly history: string | null;
+}): Promise<string | null>;
+/**
+ * What the unstaged-files `index/stale` finding and the matching write note both start with:
+ * `path` lists `files` (some of them), which aren't staged.
+ */
+export declare function unstagedIndexText(path: string, files: readonly string[]): string;
+/**
+ * The log's event and body files whose work-tree content isn't staged (untracked or modified),
+ * sorted: the cause of a staged `index.md` that only the work tree's render matches.
+ */
+export declare function unstagedLogFiles(git: Git, layout: LogLayout): Promise<string[]>;
+/**
+ * The verify check that `<root>/index.md` is current (design 2b §4.5, "Freshness in verify"). In
+ * staged mode (the pre-commit hook), a stale staged copy that equals the work tree's render
+ * means another decision's files aren't staged: writes stage the work tree's render (D2), and
+ * `adr index` would change nothing. The finding then names those files and says to stage them.
+ */
+export declare function decisionIndexCheck(log: DecisionLog): Check;
+/** Whether `bytes` (null: absent) hold exactly `text`. */
+export declare function holdsText(bytes: Uint8Array | null, text: string): boolean;
+/** HEAD's copy of `path`; `null` when it is absent or HEAD is unborn. */
+export declare function headBytes(git: Git, path: string): Promise<Uint8Array | null>;
+/** HEAD's tree, or an empty tree on an unborn HEAD. */
+export declare function headTree(git: Git, head: string | null): Promise<TreeReader>;
+/**
+ * Brings the work-tree copy of `path` to `text` (atomically, when it differs) and reports whether
+ * the staged copy differs, so the caller stages it. `old` is the work-tree copy before the write
+ * (`null` when absent), for rollback.
+ */
+export declare function writeIndexCopy(git: Git, path: string, text: string): Promise<{
+    readonly wrote: boolean;
+    readonly old: Uint8Array | null;
+    readonly stage: boolean;
+}>;
+/** The first line of an error's message, for notes and headlines. */
+export declare const firstLine: (err: unknown) => string;
+/** `adr index`'s result and whether the work-tree refresh after a commit changed a copy. */
+export interface IndexRun {
+    readonly doc: IndexResultJson;
+    /** With a commit requested: step 5 wrote or staged the work tree's render. */
+    readonly refreshed: boolean;
+}
+/**
+ * `adr index` (design 2b §4.5) with what the text output needs; `indexDecisionLog` is the
+ * library entry.
+ */
+export declare function runDecisionIndex(log: DecisionLog, o?: WriteOptions & {
+    readonly check?: boolean;
+}): Promise<IndexRun>;
+/**
+ * `adr index [--check] [--commit | --no-commit] [-m <message>]` (design 2b §4.5): renders
+ * `<root>/index.md` and writes and stages it where the work tree or the index differ. With
+ * `commit` (default `[policy] auto_commit`) it renders HEAD's tree and commits the file alone when
+ * HEAD's copy differs, then refreshes the work tree's copy, which may include other decisions'
+ * uncommitted entries. `check` writes nothing and reports `index/*` findings.
+ */
+export declare function indexDecisionLog(log: DecisionLog, o?: WriteOptions & {
+    readonly check?: boolean;
+}): Promise<IndexResultJson>;

package/dist/types/log.d.ts

@@ -33,8 +33,15 @@ export interface DecisionsRead {
     /** How the log was located (`ToolLog.notes`); `[]` for a MemoryTree read. */
     readonly notes: readonly string[];
 }
-/** `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. */
+/**
+ * `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. In a shallow clone of a
+ * log with `[log] index = "committed"`, the numbers come from `<root>/index.md` in the commit
+ * being read (`--ref`, else HEAD, resolved when the numbers are needed), never from the work tree's
+ * copy, which may number acceptances that exist only there (design 2b D1, §4.6).
+ */
 export declare function readDecisions(log: DecisionLog): Promise<DecisionsRead>;
+/** The display numbers `readDecisions` uses, with its shallow-clone fallback to `index.md`. */
+export declare function numberDecisions(log: DecisionLog): Promise<Numbering>;
 /** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
 export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly layout: LogLayout;
@@ -44,6 +51,13 @@ export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly commit?: string | null;
     readonly notes?: readonly string[];
 }): Promise<DecisionsRead>;
+/**
+ * The note a read command adds about where numbers come from: the shallow-clone index, or why
+ * they are unavailable (`unavailable: false` leaves that one out); `null` for none.
+ */
+export declare function numberingNote(read: DecisionsRead, o: {
+    readonly unavailable: boolean;
+}): string | null;
 /** Why numbers are unavailable, in words: `shallow clone` or `no main branch`. */
 export declare function unavailableReason(n: Numbering): string;
 /**
@@ -51,3 +65,22 @@ export declare function unavailableReason(n: Numbering): string;
  * Throws `UsageError` (exit 2) naming the reason when it names nothing.
  */
 export declare function resolveDecision(read: DecisionsRead, input: string): string;
+/** The `since` key of `adr list --since <rev>` (design 2b D7). */
+export interface ChangedSince {
+    /** The revision as given, such as `ORIG_HEAD`. */
+    readonly rev: string;
+    readonly commit: string;
+    /** Event files added since `rev`, sorted by path. */
+    readonly events: readonly {
+        readonly subject: string;
+        readonly type: string;
+        readonly path: string;
+    }[];
+}
+/**
+ * The event files in `--ref`'s tree (else HEAD's) that `rev`'s tree lacks (design 2b D7). Diffing
+ * trees answers "what did this pull bring" for fast-forwards and merges (`ORIG_HEAD` is the tip
+ * before them), and lists nothing for a rebase of your own work, whose events are in both trees.
+ * Throws `RefNotFoundError` when either revision doesn't resolve.
+ */
+export declare function changedSince(log: DecisionLog, rev: string): Promise<ChangedSince>;

package/dist/types/verify.d.ts

@@ -1,9 +1,11 @@
 import { type Check, type Finding, type VerifyMode } from "@nikovirtala/ledger";
-import type { DecisionLog } from "./log.js";
+import { type DecisionLog } from "./log.js";
 /**
- * Every phase-1 check for the log: ledger's mechanical and fold checks with adr's actor policy,
- * and template lint against the templates in the head tree and, for older versions, the history
- * of `historyRef`.
+ * Every check for the log: ledger's mechanical and fold checks with adr's actor policy, template
+ * lint against the templates in the head tree and, for older versions, the history of
+ * `historyRef`, the scope-glob and anchor checks, and the decision checks over code
+ * (`decision/governed-by-inactive`, `decision/scope-narrowed`). With `[log] index = "committed"`,
+ * also the freshness of `<root>/index.md`.
  */
 export declare function adrChecks(log: DecisionLog, historyRef: string | null): readonly Check[];
 /** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */

package/dist/types/views.d.ts

@@ -1,10 +1,10 @@
 import { type EventEnvelope, type Finding, type StateHeader } from "@nikovirtala/ledger";
 import type { DecisionStatus, DecisionView } from "./kind.js";
-import type { DecisionsRead } from "./log.js";
+import type { ChangedSince, DecisionsRead } from "./log.js";
 /** The `numbering` key of the read documents. */
 export interface NumberingJson {
     readonly available: boolean;
-    readonly reason: "shallow" | "no-main-ref" | null;
+    readonly reason: "shallow" | "no-main-ref" | "index" | null;
     readonly ref: string | null;
 }
 /** `adr list --json` (design §5.5). */
@@ -15,6 +15,8 @@ export interface DecisionListJson {
     readonly commit: string | null;
     readonly numbering: NumberingJson;
     readonly decisions: readonly DecisionView[];
+    /** With `--since <rev>`: the event files added since `rev`; `null` without it. */
+    readonly since: ChangedSince | null;
     /** Newer envelope or schema versions; upgrade adr. */
     readonly unreadable: readonly string[];
     /** First event not `proposed`, or a body with no events; run adr verify. */
@@ -40,11 +42,13 @@ export interface DecisionShowJson {
 /** The `numbering` key of `adr-list/v1`, `adr-show/v1` and `adr-for/v1`. */
 export declare const numberingJson: (read: DecisionsRead) => NumberingJson;
 /**
- * The `adr-list/v1` document: decisions in list order, filtered by `status` and truncated to
+ * The `adr-list/v1` document: decisions in list order, filtered by `status` and by `since` (only
+ * the decisions with event files added since its revision, from `changedSince`), and truncated to
  * `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.
  */
 export declare function listDecisions(read: DecisionsRead, o?: {
     readonly status?: readonly DecisionStatus[];
+    readonly since?: ChangedSince | null;
     readonly limit?: number;
 }): DecisionListJson;
 /**

package/dist/types/write.d.ts

@@ -1,4 +1,4 @@
-import { type Actor, type EventEnvelope, type Finding, type SetOp, type Template, type TemplateSource, type Trailer } from "@nikovirtala/ledger";
+import { type Actor, type EventEnvelope, type Finding, type SetOp, type Template, type TemplateSource, type Trailer, type TreeReader } from "@nikovirtala/ledger";
 import { type DecisionView } from "./kind.js";
 import { type DecisionLog, type DecisionsRead } from "./log.js";
 /** `adr <write command> --json` (design §5.5, §6.1). */
@@ -9,7 +9,9 @@ export interface WriteResultJson {
     /**
      * The decision after the write; before it when `ok` is false (`null` for a refused `new`).
      * After a commit it is read again from the log, so an acceptance committed on the main ref
-     * carries its number; otherwise `number` is `null` until the acceptance lands on main.
+     * carries its number; otherwise `number` is `null` until the acceptance lands on main. In a
+     * shallow clone with a committed index, the number comes from HEAD's `index.md`, which on a
+     * branch is the number the decision will get once the branch merges.
      */
     readonly decision: DecisionView | null;
     /** Each decision superseded by this write, after it (read again after a commit, like `decision`). */
@@ -33,6 +35,11 @@ export interface WriteOptions {
     readonly message?: string | null;
     /** Notes to report before the write's own, such as the attribution notes. */
     readonly notes?: readonly string[];
+    /**
+     * With `[log] index = "committed"`: `"refresh"` (the default) keeps `<root>/index.md` fresh;
+     * `"skip"` leaves it alone (the pre-commit hook's rename following, design 2b D8).
+     */
+    readonly index?: "refresh" | "skip";
 }
 export interface ProposeInput {
     readonly title: string;
@@ -229,11 +236,20 @@ export interface AfterStage {
     /** `false` skips the commit: the files stay written and staged, and `commit` is `null`. */
     readonly commit: boolean;
 }
+/** What `applyPlan` did. */
+export interface AppliedPlan {
+    /** Repo-relative paths written: the plan's files, then `<root>/index.md` when it was written. */
+    readonly written: string[];
+    readonly commit: string | null;
+    readonly findings: readonly Finding[];
+    /** Notes about the index ("not updated", "may be stale"); `[]` when none. */
+    readonly notes: readonly string[];
+}
 /**
- * Applies a plan (§5.4): refuses a commit whose scope has unstaged or needed untracked paths,
- * writes the files (removing them again if a write fails), stages them, runs `afterStage`, and
- * commits `plan.stage` plus the involved subjects' already-staged files with exact trailers.
+ * What the recovery hint says about rerunning a write command after `git commit` failed (design
+ * 2b D5): the batch is already in the log, so a rerun is refused, writes nothing or duplicates it.
  */
+export declare const WRITE_RERUN = "Don't run the command again: the log already holds the change, so a rerun would be refused, do nothing, or write it a second time.";
 export declare function applyPlan(log: DecisionLog, plan: WritePlan, o: {
     readonly commit: boolean;
     /** The commit message, without trailers; required when committing. */
@@ -241,11 +257,13 @@ export declare function applyPlan(log: DecisionLog, plan: WritePlan, o: {
     /** `message` is the user's own: append the trailers to its own trailer block, if it ends in one. */
     readonly mergeTrailers?: boolean;
     readonly afterStage?: () => Promise<AfterStage>;
-}): Promise<{
-    written: string[];
-    commit: string | null;
-    findings: readonly Finding[];
-}>;
+    /**
+     * Renders the log's index for `tree`, which builds on `history` (HEAD, the new commit, or
+     * null on an unborn HEAD); `null` when the numbers can't be projected. Given only when the log
+     * keeps a committed index (design 2b D2, §4.5).
+     */
+    readonly index?: (tree: TreeReader, history: string | null) => Promise<string | null>;
+}): Promise<AppliedPlan>;
 /**
  * The clock, the randomness and `applyPlan` the write functions use. Only tests pass their own
  * (for example an `apply` that fails once); the default is the real ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikovirtala/adr",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Architecture decision records kept as event logs in git: frozen bodies, computed status and supersession chains. CLI and library.",
   "keywords": [
     "adr",
@@ -45,7 +45,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@nikovirtala/ledger": "^0.4.0"
+    "@nikovirtala/ledger": "^0.5.0"
   },
   "scripts": {
     "build": "tsdown",