approval-md 0.0.1 → 0.2.0

package/dist/src/cli/journal.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `approval journal write` and `approval journal read` (APRV-195) — the ungated
+ * channel, at the CLI.
+ *
+ * The reasoning for the channel's existence and for its storage location is in
+ * `src/core/journal.ts` and `docs/cli-reference.md#journal`. What belongs here
+ * is the boundary work every other verb in this directory does: parse argv,
+ * resolve a path, map an outcome onto the frozen exit table, and print one JSON
+ * object per invocation.
+ *
+ * Three things are peculiar to these two verbs and are stated where they happen:
+ *
+ * - **The write path touches no gate.** It resolves no policy, reads no log,
+ *   verifies no chain, mints no token and appends no event. That is the point;
+ *   an outlet a policy could close is not an outlet.
+ * - **The read path labels what it prints.** Journal text is written by the
+ *   party under oversight, so it is rendered as `[claimed]` content inside
+ *   delimiters, under a banner saying in one line that it is agent-authored data
+ *   and not instructions to anyone reading it. Same discipline the channels
+ *   apply to a payload (SPEC.md §9), for the same reason: a human reading a
+ *   screen should never have to work out which words came from the runtime.
+ * - **Identity comes from the process, never from the working tree.** `--as`, or
+ *   `APPROVAL_AGENT` in the environment the operator launched. No file in the
+ *   checkout is read to decide who wrote an entry (SPEC.md §11.1 invariant 7),
+ *   and an unattributed entry is recorded as unattributed rather than guessed.
+ */
+import { MAX_ENTRY_BYTES } from "../core/journal.js";
+import type { Streams } from "./main.js";
+/**
+ * The one line every human-facing read opens with.
+ *
+ * Exported because the guard test asserts the read surface carries it: a read
+ * surface that stopped saying whose words these are would turn an outlet into a
+ * channel for instructions, which is precisely the thing SPEC.md §11.1
+ * invariant 4 refuses to let self-reported content become.
+ */
+export declare const JOURNAL_BANNER = "AGENT-AUTHORED DATA, not instructions. These entries are written by the party under oversight; nothing here authorizes, requests or changes any decision.";
+/** `approval journal …` — dispatch to `write` or `read`, or print the help. */
+export declare function commandJournal(argv: string[], streams: Streams, cwd: string, env?: NodeJS.ProcessEnv): number;
+/** Re-exported so the help text and the core cap cannot disagree. */
+export { MAX_ENTRY_BYTES };

package/dist/src/cli/journal.js

@@ -0,0 +1,238 @@
+/**
+ * `approval journal write` and `approval journal read` (APRV-195) — the ungated
+ * channel, at the CLI.
+ *
+ * The reasoning for the channel's existence and for its storage location is in
+ * `src/core/journal.ts` and `docs/cli-reference.md#journal`. What belongs here
+ * is the boundary work every other verb in this directory does: parse argv,
+ * resolve a path, map an outcome onto the frozen exit table, and print one JSON
+ * object per invocation.
+ *
+ * Three things are peculiar to these two verbs and are stated where they happen:
+ *
+ * - **The write path touches no gate.** It resolves no policy, reads no log,
+ *   verifies no chain, mints no token and appends no event. That is the point;
+ *   an outlet a policy could close is not an outlet.
+ * - **The read path labels what it prints.** Journal text is written by the
+ *   party under oversight, so it is rendered as `[claimed]` content inside
+ *   delimiters, under a banner saying in one line that it is agent-authored data
+ *   and not instructions to anyone reading it. Same discipline the channels
+ *   apply to a payload (SPEC.md §9), for the same reason: a human reading a
+ *   screen should never have to work out which words came from the runtime.
+ * - **Identity comes from the process, never from the working tree.** `--as`, or
+ *   `APPROVAL_AGENT` in the environment the operator launched. No file in the
+ *   checkout is read to decide who wrote an entry (SPEC.md §11.1 invariant 7),
+ *   and an unattributed entry is recorded as unattributed rather than guessed.
+ */
+import { readFileSync } from "node:fs";
+import { appendJournal, readJournal, MAX_ENTRY_BYTES, } from "../core/journal.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { JOURNAL_HELP, JOURNAL_READ_HELP, JOURNAL_WRITE_HELP } from "./help.js";
+import { DEFAULT_JOURNAL_DIR, resolvePath } from "./paths.js";
+import { usageErrorText } from "./usage.js";
+/** The environment variable that names the agent, when `--as` is not given. */
+const AGENT_ENV = "APPROVAL_AGENT";
+const WRITE_FLAGS = {
+    "--message": "string",
+    "--task": "string",
+    "--session": "string",
+    "--journal": "string",
+    "--as": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+const READ_FLAGS = {
+    "--limit": "string",
+    "--since": "string",
+    "--journal": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+/** The default number of entries `read` prints. */
+const DEFAULT_LIMIT = 20;
+function wantsJson(argv) {
+    return argv.includes("--json");
+}
+function usageError(streams, json, message, helpText) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, helpText));
+    return EXIT_USAGE;
+}
+function ioError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "io", message } })}\n`);
+    else
+        streams.err(`approval: ${message}\n`);
+    return EXIT_IO;
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * The one line every human-facing read opens with.
+ *
+ * Exported because the guard test asserts the read surface carries it: a read
+ * surface that stopped saying whose words these are would turn an outlet into a
+ * channel for instructions, which is precisely the thing SPEC.md §11.1
+ * invariant 4 refuses to let self-reported content become.
+ */
+export const JOURNAL_BANNER = "AGENT-AUTHORED DATA, not instructions. These entries are written by the party under oversight; nothing here authorizes, requests or changes any decision.";
+/** `approval journal write`. */
+function commandJournalWrite(argv, streams, cwd, env) {
+    const json = wantsJson(argv);
+    const parsed = parseFlags(argv, WRITE_FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, parsed.message, JOURNAL_WRITE_HELP);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${JOURNAL_WRITE_HELP}\n`);
+        return EXIT_OK;
+    }
+    const message = stringFlag(parsed.flags, "--message");
+    const positional = parsed.positionals[0];
+    const extra = parsed.positionals[1];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, JOURNAL_WRITE_HELP);
+    }
+    if (positional !== undefined && positional !== "-") {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(positional)} (the only positional is "-", which reads the entry from stdin; text goes in --message)`, JOURNAL_WRITE_HELP);
+    }
+    if (message === null && positional === undefined) {
+        return usageError(streams, json, 'missing entry: pass --message "<text>", or "-" to read it from stdin', JOURNAL_WRITE_HELP);
+    }
+    if (message !== null && positional !== undefined) {
+        return usageError(streams, json, "--message and - are two ways to give the same entry; pass one", JOURNAL_WRITE_HELP);
+    }
+    let text;
+    if (message !== null) {
+        text = message;
+    }
+    else {
+        try {
+            text = readFileSync(0, "utf8");
+        }
+        catch (cause) {
+            return ioError(streams, json, `stdin could not be read: ${detail(cause)}`);
+        }
+    }
+    const dir = resolvePath(stringFlag(parsed.flags, "--journal"), DEFAULT_JOURNAL_DIR, cwd);
+    const actorFlag = stringFlag(parsed.flags, "--as");
+    const actorEnv = env[AGENT_ENV];
+    const actor = actorFlag !== null && actorFlag.trim().length > 0
+        ? actorFlag
+        : actorEnv !== undefined && actorEnv.trim().length > 0
+            ? actorEnv
+            : undefined;
+    const task = stringFlag(parsed.flags, "--task");
+    const session = stringFlag(parsed.flags, "--session");
+    const outcome = appendJournal(dir, text, {
+        ...(actor === undefined ? {} : { actor }),
+        ...(task === null ? {} : { task }),
+        ...(session === null ? {} : { session }),
+    });
+    if (!outcome.ok) {
+        if (outcome.code === "io")
+            return ioError(streams, json, outcome.message);
+        return usageError(streams, json, outcome.message, JOURNAL_WRITE_HELP);
+    }
+    if (json) {
+        streams.out(`${JSON.stringify({
+            ok: true,
+            path: outcome.path,
+            ts: outcome.entry.ts,
+            actor: outcome.entry.actor,
+            bytes: Buffer.byteLength(outcome.entry.text, "utf8"),
+        })}\n`);
+    }
+    else {
+        streams.out(`journal: entry written to ${outcome.path} as ${outcome.entry.actor}\n`);
+    }
+    return EXIT_OK;
+}
+/** One entry, rendered for a person. */
+function renderEntry(entry) {
+    const attribution = [
+        entry.ts,
+        entry.actor,
+        ...(entry.task === undefined ? [] : [`task ${entry.task}`]),
+        ...(entry.session === undefined ? [] : [`session ${entry.session}`]),
+    ].join("  ");
+    return [`${attribution}  [claimed]`, "  ---", ...entry.text.split("\n").map((line) => `  ${line}`), "  ---"].join("\n");
+}
+/** `approval journal read`. */
+function commandJournalRead(argv, streams, cwd) {
+    const json = wantsJson(argv);
+    const parsed = parseFlags(argv, READ_FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, parsed.message, JOURNAL_READ_HELP);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${JOURNAL_READ_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, JOURNAL_READ_HELP);
+    }
+    const rawLimit = stringFlag(parsed.flags, "--limit");
+    let limit = DEFAULT_LIMIT;
+    if (rawLimit !== null) {
+        if (!/^\d+$/u.test(rawLimit) || Number(rawLimit) === 0) {
+            return usageError(streams, json, `--limit expects a positive whole number, got ${JSON.stringify(rawLimit)}`, JOURNAL_READ_HELP);
+        }
+        limit = Number(rawLimit);
+    }
+    const since = stringFlag(parsed.flags, "--since");
+    if (since !== null && !/^\d{4}-\d{2}-\d{2}$/u.test(since)) {
+        return usageError(streams, json, `--since expects a date like 2026-09-01, got ${JSON.stringify(since)}`, JOURNAL_READ_HELP);
+    }
+    const dir = resolvePath(stringFlag(parsed.flags, "--journal"), DEFAULT_JOURNAL_DIR, cwd);
+    const outcome = readJournal(dir, { limit, ...(since === null ? {} : { since }) });
+    if (!outcome.ok)
+        return ioError(streams, json, outcome.message);
+    if (json) {
+        streams.out(`${JSON.stringify({
+            ok: true,
+            dir,
+            note: JOURNAL_BANNER,
+            total: outcome.total,
+            entries: outcome.entries,
+        })}\n`);
+        return EXIT_OK;
+    }
+    streams.out(`${JOURNAL_BANNER}\n${dir}\n\n`);
+    if (outcome.entries.length === 0) {
+        streams.out("_no entries_\n");
+        return EXIT_OK;
+    }
+    for (const entry of outcome.entries)
+        streams.out(`${renderEntry(entry)}\n\n`);
+    streams.out(`${String(outcome.entries.length)} of ${String(outcome.total)} entries (oldest first)\n`);
+    return EXIT_OK;
+}
+/** `approval journal …` — dispatch to `write` or `read`, or print the help. */
+export function commandJournal(argv, streams, cwd, env = process.env) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    if (sub === undefined) {
+        return usageError(streams, wantsJson(argv), "missing subcommand for `approval journal`", JOURNAL_HELP);
+    }
+    if (sub === "--help" || sub === "-h" || sub === "help") {
+        streams.out(`${JOURNAL_HELP}\n`);
+        return EXIT_OK;
+    }
+    switch (sub) {
+        case "write":
+            return commandJournalWrite(rest, streams, cwd, env);
+        case "read":
+            return commandJournalRead(rest, streams, cwd);
+        default:
+            return usageError(streams, wantsJson(argv), `unknown subcommand ${JSON.stringify(sub)} for \`approval journal\``, JOURNAL_HELP);
+    }
+}
+/** Re-exported so the help text and the core cap cannot disagree. */
+export { MAX_ENTRY_BYTES };
+//# sourceMappingURL=journal.js.map

package/dist/src/cli/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../src/cli/journal.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/log-advance.d.ts

@@ -0,0 +1,287 @@
+/**
+ * `approval log advance` (APRV-125) — the commit-and-push half of the log
+ * ritual, as a verb.
+ *
+ * The APRV-92 flow, written down: the log's appends the remote does not have
+ * yet are gathered into a commit whose message names the seq range they cover,
+ * and pushed to a short-lived records branch that exists for it. Main is
+ * protected here, so the commit reaches it through a pull request, and the PR
+ * step is `--pr`, which runs the ordinary gated `gh` path. Since APRV-284 that
+ * step also ARMS the merge (`gh pr merge <branch> --merge --auto`, off with
+ * `--no-auto-merge`): a records pull request carries only evidence paths, so
+ * the click it was waiting for was never a review. {@link armAutoMerge} carries
+ * the reasoning and the guard that keeps it true.
+ *
+ * ## The three refusals that are the point
+ *
+ * **`log-advance-dirty-stage`.** The staged set must be EXACTLY the log, the
+ * queue projection, and the payload store — nothing else. The failure this
+ * prevents is the one CLAUDE.md's rule is written against: a log commit riding
+ * a branch that carries other work. A verb that ran `git add -A` and hoped
+ * would be a worse version of the hand-ritual it replaces, so anything else
+ * already staged is a refusal and not a thing to unstage. Unstaging someone
+ * else's work is not this verb's decision to make.
+ *
+ * **`log-advance-checkout-required`.** This verb never checks out anything. The
+ * checkout is the footgun: a branch switch with an uncommitted working log
+ * rewinds `events.jsonl` under whatever holds it open, which is fork 2 of
+ * 2026-08-20. It builds the commit with a scratch index and pushes THAT commit
+ * to a records branch by refspec, which moves no HEAD and touches no file.
+ *
+ * ## The base is the remote, not the local branch (APRV-203)
+ *
+ * The verb used to commit on the branch you were standing on, which made the
+ * operator responsible for that branch being current. A checkout whose local
+ * `main` was behind origin produced a records commit parented on a stale tip,
+ * carrying a tree that silently reverted everything main had merged since. So
+ * the verb fetches first and bases its commit on the remote's tip: `git
+ * read-tree` fills a scratch index from origin's tree, the log, the queue
+ * projection and the payload store are laid over it from the working tree, and
+ * `commit-tree` parents the result on origin. HEAD, the operator's index and
+ * every file in the working tree are exactly as they were found.
+ *
+ * **`log-advance-not-primary`.** Same rule as sync's: the committed log has one
+ * home, and it is not a worktree.
+ *
+ * ## One records branch, and one pull request, per day (APRV-204)
+ *
+ * The daemon advances on a cadence, so an advance is no longer a once-a-day
+ * ceremony and the day's records branch usually already exists. When it does,
+ * and its log is a prefix of the working log, the commit is parented on THAT
+ * branch rather than on the trunk: parenting every advance on the trunk makes
+ * the second push of the day a non-fast-forward of a branch a pull request is
+ * already open on. `--pr` asks whether an open pull request exists for the head
+ * branch before creating one, so a day gets a single pull request that later
+ * advances grow.
+ *
+ * A local branch that is AHEAD of origin with commits this verb did not make is
+ * not a refusal: the advance is based on origin either way, and those commits
+ * are simply not part of it. What IS refused is a working log that origin's log
+ * is not a prefix of, in either direction, because an advance is only ever the
+ * records origin does not have yet.
+ *
+ * ## This verb appends no event
+ *
+ * For the same reason `log sync` appends none: committing the file the log
+ * lives in is housekeeping on the container, not a decision about the world.
+ * The commit is already the record of itself, in git, where a reader can see
+ * exactly which bytes moved (SPEC §10.1, amended APRV-125).
+ */
+import { type EventRecord } from "../core/log.js";
+import type { LogHead } from "../core/verify.js";
+import { defaultRecordsBranch } from "./log-anchor.js";
+import { type ProgressReporter } from "./progress.js";
+/**
+ * The only paths an advance may stage, as git spells them.
+ *
+ * A closed list, checked in both directions: everything staged must be in it,
+ * and nothing outside it may be staged. Widening it is a reviewable diff.
+ */
+export declare const ADVANCE_PATHS: readonly string[];
+/** Machine-readable refusal codes. Frozen public API, printed in the help. */
+export declare const LOG_ADVANCE_REFUSAL_CODES: readonly ["log-advance-not-primary", "log-advance-no-branch", "log-advance-dirty-stage", "log-advance-checkout-required", "log-advance-unverified", "log-advance-locked", "log-advance-fetch-failed", "log-advance-behind-remote", "log-advance-remote-diverged", "log-advance-git-failed", "log-advance-push-rejected", "log-advance-pr-failed", "log-advance-co-author-invalid"];
+export type LogAdvanceRefusalCode = (typeof LOG_ADVANCE_REFUSAL_CODES)[number];
+/** What became of the auto-merge arm. Closed (SPEC.md §11.1 invariant 6). */
+export type AutoMergeState = "armed" | "withheld" | "refused" | "off";
+export interface LogAdvanceOptions {
+    cwd: string;
+    /** The records branch to push to. Default `records-log-<YYYY-MM-DD>`. */
+    branch?: string | null;
+    remote?: string;
+    /**
+     * The remote branch the records commit is parented on. Defaults to the branch
+     * the checkout is standing on, which in the primary checkout is the trunk.
+     */
+    base?: string | null;
+    /** Open the pull request through `gh` as well as pushing. */
+    pr?: boolean;
+    /**
+     * Arm auto-merge on the pull request `--pr` opens or updates (APRV-284).
+     *
+     * Defaults to true and is read only when {@link pr} is set: there is nothing
+     * to arm without a pull request. `false` is the opt-out, and it is an opt-out
+     * rather than an opt-in because a records pull request that sits at CLEAN
+     * waiting for a hand click is the thing this option exists to remove.
+     */
+    autoMerge?: boolean;
+    /** Optional display credit. It grants no authority and is never inferred. */
+    coAuthor?: string;
+    /** Report what would happen and stage, commit, and push nothing. */
+    dryRun?: boolean;
+    /** The date the default branch name is built from. Injected by the CLI edge. */
+    today?: string;
+    /**
+     * Where the phase narration goes (APRV-167/APRV-203). The CLI edge passes a
+     * reporter over stderr, and `--json` passes none: a machine consumer parses
+     * one object and progress on its stream would corrupt it.
+     */
+    progress?: ProgressReporter;
+}
+export interface LogAdvanceReport {
+    root: string;
+    /** The branch the checkout is standing on. It is not moved, ever. */
+    branch: string;
+    recordsBranch: string;
+    remote: string;
+    /** The remote branch the advance was measured against, and the sha it was at. */
+    base: {
+        branch: string;
+        sha: string;
+    } | null;
+    /**
+     * The commit this advance is actually parented on (APRV-204): the base
+     * branch's tip on the first advance of a day, and the day's records branch on
+     * every advance after it, so the push fast-forwards the branch the day's pull
+     * request is open on.
+     */
+    parent?: {
+        ref: string;
+        sha: string;
+    };
+    /** True when the parent was the day's existing records branch. */
+    reusedRecordsBranch?: boolean;
+    /**
+     * True when the day's branch existed and did NOT contain the base, so this
+     * advance rebuilt it on the base rather than stacking on its tip (APRV-234).
+     */
+    rebuilt?: boolean;
+    /** The ref and sha the rebuild was parented on, when there was one. */
+    rebuiltOn?: {
+        ref: string;
+        sha: string;
+    };
+    /**
+     * The branch this advance would have pushed to, when the rebuilt commit was
+     * refused there and a fresh `records-log-<date>-<n>` was opened instead.
+     * `null` whenever `recordsBranch` is the branch that was asked for.
+     */
+    fallbackFrom?: string | null;
+    /** True when this run OPENED the pull request; false when one already stood. */
+    prCreated?: boolean;
+    /**
+     * What became of the auto-merge arm (APRV-284). A closed set, machine-read.
+     *
+     * - `null` — no pull request step ran at all (`pr` was not asked for, or
+     *   nothing was owed and nothing was pushed).
+     * - `"off"` — the caller turned the arm off (`--no-auto-merge`).
+     * - `"armed"` — `gh pr merge <branch> --merge --auto` succeeded: the pull
+     *   request lands as a merge commit when its checks and its branch rules
+     *   say so, and never before.
+     * - `"withheld"` — THIS verb declined to arm, because the branch it pushed
+     *   carries something outside {@link ADVANCE_PATHS}. See
+     *   {@link autoMergeNote}.
+     * - `"refused"` — `gh` said no (auto-merge disabled on the repository, a
+     *   merge queue, a pull request already mergeable). The pull request is open
+     *   either way, so this is reported and never fatal.
+     */
+    autoMerge?: AutoMergeState | null;
+    /** Why the arm was withheld or refused, verbatim; `null` when it was not. */
+    autoMergeNote?: string | null;
+    /** The seq range this advance carries, inclusive; null when nothing is owed. */
+    range: {
+        from: number;
+        to: number;
+    } | null;
+    committedHead: LogHead | null;
+    workingHead: LogHead | null;
+    staged: readonly string[];
+    message: string;
+    commit: string | null;
+    pushed: boolean;
+    prUrl: string | null;
+    dryRun: boolean;
+}
+export type LogAdvanceResult = {
+    ok: true;
+    report: LogAdvanceReport;
+} | {
+    ok: false;
+    code: LogAdvanceRefusalCode;
+    message: string;
+    /** Paths that were staged and should not have been. */
+    offending?: readonly string[];
+    quote?: readonly string[];
+};
+export { defaultRecordsBranch };
+/** `approval log advance`, as a function. The CLI wrapper formats its answer. */
+export declare function logAdvance(options: LogAdvanceOptions): LogAdvanceResult;
+/** Where the records that are already published end. */
+export interface PublishedState {
+    /** The highest seq this chain reaches on a records branch, the trunk, or HEAD. */
+    publishedSeq: number;
+    /** The working log's head seq. */
+    workingSeq: number;
+    /** Working records above `publishedSeq`, advance bookkeeping included. */
+    pending: number;
+    /** The same count with the daemon's own advance cycles removed. */
+    substantive: number;
+    /**
+     * The rev the published head was read from, or `null` when no rev carried a
+     * copy of this chain (APRV-210).
+     *
+     * A row that says "N records are not yet on a records branch" is unreadable
+     * without it: a rev that resolved to nothing and a rev that carried nothing
+     * are the same number and completely different facts, and the doctor's
+     * cadence row reported the first as the second on a log whose first 8,379
+     * records had been merged to the trunk an hour earlier.
+     */
+    publishedRev: string | null;
+    /** Every rev that was consulted, in the order they were tried. */
+    revs: readonly string[];
+    /**
+     * Where the OWED SPAN ends: the highest unpublished seq that is not an
+     * advance cycle's own bookkeeping, or {@link publishedSeq} when none is
+     * (APRV-211).
+     *
+     * `workingSeq` was the wrong end of the span for the daemon's idempotency
+     * key. One gated attempt appends its own `task.registered` and
+     * `approval.requested`, which move the head, so the next tick computed a
+     * DIFFERENT key for the SAME owed work and asked the human a second question.
+     * Measured over substantive records, the span is stable for exactly as long
+     * as the owed work is unchanged, which is what makes one owed advance one
+     * question — and it still moves the moment a real record lands, so the
+     * payload hash still differs per distinct advance and the `supervised-live`
+     * draw is never re-rolled for the same span.
+     *
+     * Never below `publishedSeq`: a span that ran backwards would name a range
+     * the commit could not carry.
+     */
+    substantiveSeq: number;
+}
+/**
+ * How much of the working log is already on a records branch or the trunk.
+ *
+ * Reads git's object store and NEVER the network: this is asked on every daemon
+ * tick and by `approval doctor`, and a status question must not depend on a
+ * remote being reachable. The revs consulted are the local advance anchors
+ * (`refs/approval/advance/*`, which {@link logAdvance} writes before it pushes),
+ * the remote-tracking refs for the base branch and the day's records branch, and
+ * `HEAD`. The highest head among the copies that are a PREFIX of this chain
+ * wins; anything else is ignored, which can only make a caller advance less
+ * eagerly.
+ *
+ * It lives here rather than beside the daemon's cadence because `approval
+ * doctor` reports the same number and a CLI module may not import the daemon.
+ */
+export declare function publishedState(root: string, logPath: string, records: readonly EventRecord[], where: {
+    remote: string;
+    base: string | null;
+}, today: string): PublishedState;
+/** The canonical commit subject. It names the seq range, so the log is findable. */
+export declare function advanceMessage(range: {
+    from: number;
+    to: number;
+}, branch: string): string;
+/**
+ * Validate a display-only Git trailer identity before any mutating step.
+ *
+ * The accepted form is deliberately one line and one header value. It is never
+ * derived from a log actor and never interpreted as gate or GitHub authority.
+ */
+export declare function validateCoAuthor(input: string | undefined): {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    message: string;
+};