approval-md 0.4.0 → 0.4.2

package/dist/src/core/identity.js

@@ -0,0 +1,122 @@
+/**
+ * Identity strings by role (APRV-500, amended SPEC.md §5.2 proposed).
+ *
+ * The runtime has always written three actor kinds, `human:`, `agent:` and
+ * `system:`, and every human-only verb (grant, reject, revoke, attest, review,
+ * checkpoint, gate window, channel decisions) checked its own `^human:.+`; they
+ * now all read {@link isHumanActor} below.
+ * APRV-500 RESERVES a fourth kind for the judge, `model:<name>@<version>`, and
+ * this module is where that reservation is stated: the one parser that names
+ * the kind, and the one place that says which role may carry it.
+ *
+ * In 0.4.2 that is the `reviewer` role of `delegation.reviewers` and nothing
+ * else, and even there it only PARSES: a policy whose block lists any reviewer
+ * fails to load with `delegation-not-supported` (`core/delegation.ts`). Every
+ * human-only verb checks {@link isHumanActor} (`^human:.+`, and the id does not
+ * begin with a reserved kind), so a `model:` actor, and a `human:model:…` one,
+ * is refused `actor-not-human` by every verb; the event schema's actor patterns
+ * are unchanged, so no record can carry a `model:` actor. A later core that
+ * admits the judge widens a role here and a verb there, each as its own change.
+ *
+ * Pure: no I/O, no clock.
+ */
+/**
+ * `model:<name>@<major>.<minor>.<patch>`, the judge's identity.
+ *
+ * `<name>` is the judge service, lowercase alphanumerics and `-`, at most 64
+ * characters. The version pins one judge release (prompt, rubric and underlying
+ * model snapshot), so a provider change is a new version. The same pattern is
+ * `schema/policy.schema.json`'s `modelIdentity`; `tests/policy-delegation.test.ts`
+ * holds the two equal.
+ */
+export const MODEL_IDENTITY_PATTERN = /^model:[a-z0-9][a-z0-9-]{0,63}@[0-9]+\.[0-9]+\.[0-9]+$/u;
+/** `human:<id>`, the shape every human-only verb already requires. */
+const HUMAN_IDENTITY = /^human:(.+)$/u;
+/**
+ * Identity kinds that are reserved and are not a person's name (APRV-500
+ * refutation S3). THE one list: every human-only verb reads it through
+ * {@link isHumanActor}, so reserving a further kind is one entry here.
+ *
+ * Why it exists. `^human:.+` admits any id, and a policy that names no approver
+ * roster restricts nothing further, so `human:model:judge@0.3.0` used to pass
+ * every human-only verb and a channel decision under it was recorded as
+ * `approval.granted`: the judge written down as a person, which is the one
+ * thing the `model:` reservation exists to prevent. A human id that begins with
+ * a reserved kind prefix is therefore not a human identity anywhere. The
+ * comparison ignores case and leading whitespace, so `human:Model:judge` and
+ * `human: model:judge` are refused too.
+ */
+export const RESERVED_IDENTITY_KINDS = ["model"];
+/** Does this `human:` id begin with a reserved kind prefix (`model:`)? */
+export function wearsReservedKind(id) {
+    const folded = id.trimStart().toLowerCase();
+    return RESERVED_IDENTITY_KINDS.some((kind) => folded.startsWith(`${kind}:`));
+}
+/**
+ * Is `actor` a human identity a human-only verb may record (grant, reject,
+ * revoke, attest, review, checkpoint, gate window, channel decisions, and the
+ * CLI's `--as` / `APPROVAL_HUMAN` resolution)?
+ *
+ * `^human:.+`, as every verb always required, and the id does not begin with a
+ * reserved kind (see {@link RESERVED_IDENTITY_KINDS}). A refusal keeps each
+ * verb's existing code, `actor-not-human`: the identity names a judge, not a
+ * person, and no refusal code is added.
+ */
+export function isHumanActor(actor) {
+    if (typeof actor !== "string")
+        return false;
+    const human = HUMAN_IDENTITY.exec(actor);
+    return human !== null && !wearsReservedKind(human[1] ?? "");
+}
+/**
+ * The clause a refusal message appends when `actor` is a `human:` id wearing a
+ * reserved kind, so the person reading it learns why a `human:` actor was
+ * refused as not human. Empty for every other actor.
+ */
+export function reservedKindNote(actor) {
+    if (typeof actor !== "string")
+        return "";
+    const human = HUMAN_IDENTITY.exec(actor);
+    if (human === null || !wearsReservedKind(human[1] ?? ""))
+        return "";
+    return ` (a human: id may not begin with a reserved identity kind, ${RESERVED_IDENTITY_KINDS.map((kind) => `${kind}:`).join(", ")}: that names a judge, not a person)`;
+}
+/** The roles a `model:` identity may hold. One, and it is reserved. */
+const MODEL_ROLES = new Set(["reviewer"]);
+/**
+ * Parse `text` as an identity for `role`, or `null` when it is not one that
+ * role admits.
+ *
+ * `human:<id>` is admitted for every role, unless the id begins with a reserved
+ * kind (`human:model:…`, see {@link RESERVED_IDENTITY_KINDS}), which is `null`
+ * for every role. `model:<name>@<version>` is admitted for `reviewer` alone;
+ * for any other role it is `null`, exactly as an `agent:` or `system:` actor
+ * is. Anything else, a bare id or a malformed model string included, is
+ * `null`.
+ */
+export function parseIdentity(text, role) {
+    if (typeof text !== "string")
+        return null;
+    if (MODEL_IDENTITY_PATTERN.test(text)) {
+        if (!MODEL_ROLES.has(role))
+            return null;
+        // The pattern admits exactly one `@`, after the name.
+        const at = text.indexOf("@");
+        return { kind: "model", name: text.slice("model:".length, at), version: text.slice(at + 1) };
+    }
+    const human = HUMAN_IDENTITY.exec(text);
+    // APRV-500 refutation S3: `human:model:judge@0.3.0` is the judge wearing a
+    // person's prefix, and it is no identity for any role.
+    if (human !== null && !wearsReservedKind(human[1] ?? ""))
+        return { kind: "human", id: human[1] ?? "" };
+    return null;
+}
+/**
+ * {@link isHumanActor} in the shape of the `/^human:.+/u` constants it replaced
+ * (APRV-500 refutation S3), so every human-only verb's existing
+ * `HUMAN_ACTOR.test(actor)` reads this one rule rather than its own copy.
+ */
+export const HUMAN_ACTOR_RULE = {
+    test: isHumanActor,
+};
+//# sourceMappingURL=identity.js.map

package/dist/src/core/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/core/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,yDAAyD,CAAC;AAEhG,sEAAsE;AACtE,MAAM,cAAc,GAAG,eAAe,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAO,CAAU,CAAC;AAE1D,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,MAAM,MAAM,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,KAAK,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IACpE,OAAO,8DAA8D,uBAAuB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC,CAAC;AACzK,CAAC;AAkBD,uEAAuE;AACvE,MAAM,WAAW,GAA8B,IAAI,GAAG,CAAe,CAAC,UAAU,CAAC,CAAC,CAAC;AAEnF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAkB;IAC5D,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,sDAAsD;QACtD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IAC/F,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,2EAA2E;IAC3E,uDAAuD;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IACvG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmD;IAC9E,IAAI,EAAE,YAAY;CACnB,CAAC"}

package/dist/src/core/log-lock.d.ts

@@ -0,0 +1,435 @@
+/**
+ * The holder of `<log>.lock`, and the one way a lock left by a writer that died
+ * holding it is taken back (APRV-479).
+ *
+ * ## The defect this exists for
+ *
+ * `core/log.ts` serializes every append with a lockfile created `wx` and never
+ * stolen, because silently breaking somebody else's lock is how two writers
+ * come to share a `seq`. A writer that dies while it holds the lock never
+ * removes it: a harness hook killed by SIGTERM with no listener registered (the
+ * default disposition), any verb killed by SIGKILL, a Hermes gateway restart in
+ * the middle of an append. Every later writer, the daemon included, then waits
+ * its two seconds and refuses `lock-timeout`, and the tenant's gate stays
+ * wedged until a human removes the file.
+ *
+ * ## The rule every decision here follows
+ *
+ * A wrong reclaim (two writers under one lock, a forked chain) is far worse than
+ * a missed one (a wedge a human clears with one command). So a holder is LIVE
+ * unless this process can prove it gone, and a lock is taken back only by a
+ * writer that has already waited out its whole lock timeout.
+ *
+ * ## What this module does
+ *
+ * 1. **The lockfile names its holder.** {@link createLockFile} writes one JSON
+ *    line into the file it creates: pid, host, boot, on Linux the pid and time
+ *    namespaces and the process start time, when the lock was taken, which kind
+ *    of holder (`append` | `hold`), and a nonce. An older writer's lockfile is
+ *    empty.
+ * 2. **Only a regular file that parses strictly is judged.** Every read opens
+ *    without blocking and without following links, and reads only a regular
+ *    file of at most 4 KiB. Anything else at the lock's path (a FIFO, a link, a
+ *    directory, an oversized or malformed file, a record of another version) is
+ *    not this writer's to judge: it is LIVE.
+ * 3. **The judgement ({@link judgeHolder}).** Gone only when the holder is in
+ *    this process's own pid namespace and boot, and provably not running:
+ *    - Linux: `/proc` is this namespace's (`/proc/self` names this pid), the
+ *      record's boot id and pid-namespace inode equal this process's, and then
+ *      `kill(pid, 0)` answers ESRCH with `/proc/<pid>` absent or a zombie, or
+ *      `/proc/<pid>/stat` names a process whose start time (read in the same
+ *      time namespace) is not the holder's;
+ *    - elsewhere (macOS): the same hostname, boot readings within
+ *      {@link BOOT_SLACK_S} seconds, and `kill(pid, 0)` answering ESRCH.
+ *
+ *    Everything else is LIVE: EPERM, another namespace or boot or host, a
+ *    `/proc` entry that cannot be read.
+ * 4. **A lockfile with no holder record** (empty: an older version's, or a
+ *    writer killed between the create and the write) is gone only once its
+ *    mtime is {@link LEGACY_LOCK_RECLAIM_AGE_MS} old AND this writer watched
+ *    that very file (inode, mtime, size) unchanged through its own wait.
+ * 5. **The reclaim ({@link reclaimStaleLock}) is two atomic steps, and nothing
+ *    else is written.** The taker's own complete lockfile is written first,
+ *    under `<lock>.take.<pid>.<nonce>`, so whoever finds a claim beside the
+ *    lock also finds its taker and can judge it (`approval log unlock` refuses
+ *    while one is seen running). Then the claim: `link(2)` of the lock's path to a name
+ *    derived from the judged record, `<lock>.stale.<pid>.<created ms>`, which
+ *    fails EEXIST for every other reclaimer of the same lockfile, and which is
+ *    then read back to prove it names the very file that was judged (inode,
+ *    mtime, bytes). Then the take: this writer's own lockfile is `rename(2)`d
+ *    over the lock's path, once the claim and the lock's path are read again
+ *    and are still the judged file. The lock's
+ *    path is never empty, so no ordinary `wx` create slips in, and between the
+ *    claim and the take nothing in the protocol can change it: the holder is
+ *    dead, every other writer's create fails EEXIST, and every other
+ *    reclaimer's claim fails EEXIST. (A bare `rename` of the lockfile aside
+ *    cannot be made safe: a reclaimer that judged the dead lock and stalled
+ *    would later move whatever live lock had replaced it.)
+ * 6. **The reclaim is in the log first.** The reclaimer appends
+ *    `audit.lock_reclaimed` as the first record under the lock it took
+ *    (`core/log.ts`), carrying the strictly parsed pid, op and `created` and
+ *    nothing else from the file, and only then unlinks the stale name.
+ * 7. **A termination signal does not leave a lock behind.**
+ *    {@link guardTerminationWhileLocked} is installed before a lockfile is
+ *    created, and before a reclaim's claim, and held until the lock is removed: for SIGTERM, SIGINT and SIGHUP with
+ *    no listener, a listener that re-raises the signal with its default
+ *    disposition once the lock is released, so the process still dies of it.
+ *    SIGKILL cannot be caught, which is what 1 to 6 are for.
+ *
+ * Never reclaimed automatically, whatever the holder: a lock beside a
+ * `log sync` snapshot (a sync killed part way may have left the working log at
+ * its committed bytes), and a lock beside a log that does not exist. A lock from
+ * another container or boot is never reclaimed automatically either; the
+ * refusal names the pid and the human verb, `approval log unlock --pid <n>`
+ * ({@link takeLockForUnlock}).
+ */
+/** The holder record's format version. A reader treats any other as not its to judge. */
+export declare const LOCK_HOLDER_VERSION = 1;
+/**
+ * How old an empty lockfile (no holder record) must be before it is reclaimed.
+ * An append holds the lock for milliseconds, and the longest holder in this
+ * runtime (`approval log sync`) for seconds.
+ */
+export declare const LEGACY_LOCK_RECLAIM_AGE_MS: number;
+/**
+ * How long a writer must have watched an empty lockfile unchanged (the same
+ * inode, mtime and size since the first refusal of its wait) before it may take
+ * it as `legacy-aged`. A writer of this version fills its record within
+ * microseconds of its create, so an empty file that stays empty across a retry
+ * interval is not one; an mtime alone can read old through a stepped clock or
+ * a file server's lagging one (APRV-479 R3-8).
+ */
+export declare const LEGACY_LOCK_WATCH_MS = 20;
+/**
+ * Off Linux, how far apart two boot readings (`now - uptime`, in seconds) may
+ * be and still count as one boot. A wall-clock step moves the reading, so a
+ * larger gap is "another boot, or a stepped clock": live, never gone.
+ */
+export declare const BOOT_SLACK_S = 60;
+/**
+ * `created` exactly as `Date#toISOString` writes it AND a real instant: the
+ * string must survive a round trip, which `2026-02-30T00:00:00.000Z` (a shape
+ * match that V8 rolls over to March 2nd) does not.
+ */
+export declare function isCanonicalTimestamp(value: string): boolean;
+/** `append`: one record. `hold`: a whole operation under `withAppendLock`. */
+export type LockOp = "append" | "hold";
+/** Who a process is, as far as a liveness judgement can use it. */
+export interface HolderIdentity {
+    pid: number;
+    host: string;
+    /** Linux: `/proc/sys/kernel/random/boot_id`. Elsewhere: `~<boot epoch seconds>`. */
+    boot: string;
+    /** Linux only: `/proc/self/ns/pid`. */
+    pidns?: string;
+    /** Linux only: field 22 of `/proc/self/stat` (clock ticks after boot, in this time namespace). */
+    start?: string;
+    /** Linux only, where the kernel has time namespaces: `/proc/self/ns/time`. */
+    timens?: string;
+}
+/** What a lockfile written by this version holds, one JSON line. */
+export interface LockHolder extends HolderIdentity {
+    v: typeof LOCK_HOLDER_VERSION;
+    /** When the lock was taken, as `Date#toISOString` writes it. */
+    created: string;
+    op: LockOp;
+    /** Random, so two lockfiles are never byte-identical. */
+    nonce: string;
+}
+/**
+ * Why a lock was taken over: the `audit.lock_reclaimed` payload's closed
+ * `reason` set. `holder-dead` and `legacy-aged` are a writer's proof;
+ * `operator-cleared` is a person's assertion (`approval log unlock`), never a
+ * proof, and only a `human:` actor carries it.
+ */
+export type LockReclaimReason = "holder-dead" | "legacy-aged" | "operator-cleared";
+/**
+ * The judgement on one holder record. `running` (on a live verdict): this
+ * process saw the holder itself running (Linux: its start time; elsewhere: its
+ * pid, on this host, in this boot). A live verdict without it is a holder this
+ * process cannot check, which a human may clear with `approval log unlock`.
+ */
+export type HolderVerdict = {
+    state: "gone";
+    why: string;
+} | {
+    state: "live";
+    why: string;
+    running: boolean;
+};
+/** This process, as a holder record describes it. */
+export interface SelfIdentity {
+    pid: number;
+    host: string;
+    boot: string | undefined;
+    pidns: string | undefined;
+    start: string | undefined;
+    timens?: string | undefined;
+    linux: boolean;
+    /**
+     * Linux: whether `/proc` is this process's own pid namespace's procfs
+     * (`/proc/self` names `process.pid`). `false` means no pid read from it can be
+     * trusted, and every holder is live. Absent is taken as `true` (tests).
+     */
+    procIsOwn?: boolean;
+}
+/** What `/proc/<pid>/stat` said. */
+export type ProcStatRead = {
+    kind: "stat";
+    state: string;
+    start: string;
+}
+/** ENOENT or ESRCH: no entry this process can see. */
+ | {
+    kind: "absent";
+}
+/** Anything else (EACCES, EPERM, an unparseable line): nothing can be concluded. */
+ | {
+    kind: "unreadable";
+    why: string;
+};
+/** `kill(pid, 0)`: `ok` (exists), `ESRCH` (no such process), `EPERM` (exists, another user's), `other`. */
+export type SignalZero = "ok" | "ESRCH" | "EPERM" | "other";
+/** What a liveness judgement may ask of the operating system. Injected by tests. */
+export interface LivenessProbe {
+    /** Linux: `/proc/<pid>/stat`, as read by this process. */
+    linuxStat(pid: number): ProcStatRead;
+    signalZero(pid: number): SignalZero;
+}
+/**
+ * Parse `/proc/<pid>/stat`: the command name is parenthesized and may contain
+ * spaces and parentheses, so the fields are counted from the LAST `)`. After it,
+ * index 0 is field 3 (state) and index 19 is field 22 (starttime).
+ */
+export declare function parseProcStat(text: string): {
+    state: string;
+    start: string;
+} | null;
+/** The real probe: `/proc` and `kill(pid, 0)`. */
+export declare const NODE_LIVENESS_PROBE: LivenessProbe;
+/**
+ * Is `/proc` this process's own pid namespace's procfs? `/proc/self` resolves
+ * to the reader's pid as THAT procfs numbers it, so it names `process.pid` only
+ * when the procfs belongs to the namespace `process.pid` was issued in, or when
+ * the pid happens to be the same number in both (APRV-479 R3-9). So the
+ * `NSpid:` line of `/proc/self/status` must also hold exactly one field, this
+ * pid: it lists the pid in every namespace from the procfs's own down to the
+ * reader's, and one field means they are the same namespace. A kernel without
+ * the line (before 4.1) proves nothing, and every holder is then live.
+ */
+export declare function procIsOwnNamespace(read?: (path: string) => string, pid?: number, status?: (path: string) => string): boolean;
+/** This process's identity, read once: none of it changes while the process lives. */
+export declare function selfIdentity(): SelfIdentity;
+/** The record this process writes into a lockfile it creates now. */
+export declare function holderRecord(op: LockOp, now?: Date): LockHolder;
+/**
+ * What a lockfile's bytes say: a strictly parsed v1 record, `legacy` (empty or
+ * whitespace only: no holder record at all), or `unknown` (anything else: a
+ * malformed record, another version, text that is not JSON), which is never
+ * judged.
+ */
+export declare function parseHolder(bytes: Buffer | string): {
+    kind: "v1";
+    holder: LockHolder;
+} | {
+    kind: "legacy";
+} | {
+    kind: "unknown";
+};
+/**
+ * Is the process that wrote `holder` provably gone? Pure: the identity of the
+ * reader and the operating system's answers are parameters. "Live" means "not
+ * provably gone". The holder's boot and pid namespace are established before
+ * any pid is looked up, because a pid means nothing outside the namespace it
+ * was issued in.
+ */
+export declare function judgeHolder(holder: HolderIdentity, self: SelfIdentity, probe: LivenessProbe): HolderVerdict;
+/**
+ * Replace the liveness judgement (tests only: the pin that a live holder's
+ * lock survives only because of the check). `null` restores the real one.
+ */
+export declare function setLockLivenessForTests(judge: ((holder: HolderIdentity) => HolderVerdict) | null): void;
+/** Where a test may act inside the lock's protocol. Nothing in `src/` sets one. */
+export type LockStep = "after-open" | "judged" | "claimed" | "before-take";
+/** Run `seam` at each named step (tests only: a stall, a signal, a planted file). `null` removes it. */
+export declare function setLockSeamForTests(seam: ((step: LockStep) => void) | null): void;
+/** The lock this process created or took: enough to release only that one. */
+export interface OwnLock {
+    path: string;
+    ino: bigint;
+    bytes: Buffer;
+}
+/**
+ * Create `path` with `wx` and write this process's holder record into it.
+ * Throws what `openSync` throws, so `EEXIST` means another writer holds it. A
+ * record that cannot be written leaves an empty lockfile, which is still a lock.
+ * The caller installs the signal guard BEFORE calling this.
+ */
+export declare function createLockFile(path: string, op: LockOp): OwnLock;
+/**
+ * Remove the lock this process holds, and only it: anything else at the path
+ * (another inode, other bytes) is left where it is.
+ */
+export declare function releaseLockFile(own: OwnLock): void;
+/** What an `audit.lock_reclaimed` record says, and the stale name to unlink once it is in the log. */
+export interface ReclaimNote {
+    /** The lockfile's base name. */
+    lockfile: string;
+    reason: LockReclaimReason;
+    /**
+     * From a v1 record only: the strictly parsed pid, op and `created`. `created`
+     * is `null` when it is not plausible ({@link plausibleCreated}).
+     */
+    holder?: {
+        pid: number;
+        op: LockOp;
+        created: string | null;
+    };
+    /**
+     * How long the lock had been held, from `created` (or an empty lockfile's
+     * mtime), by this process's clock. Absent exactly when `created` is `null`.
+     */
+    age_ms?: number;
+    /** The claim name, removed after the record lands. Never recorded. */
+    stale: string;
+    /** One line for a person. Never recorded. */
+    why: string;
+}
+/** How far before the log's last record a holder's `created` may lie and still be recorded. */
+export declare const CREATED_BEFORE_LAST_RECORD_MS: number;
+/** How far past this process's clock a holder's `created` may lie and still be recorded. */
+export declare const CREATED_AFTER_NOW_MS: number;
+/**
+ * The record of a reclaim carries a holder's `created` (and the age derived
+ * from it) only when it is plausible: no earlier than the log's last record's
+ * `ts` minus {@link CREATED_BEFORE_LAST_RECORD_MS}, and no later than now plus
+ * {@link CREATED_AFTER_NOW_MS}. Anything else is a value the file chose (any
+ * canonical instant parses, year 0000 and 9999 included), so the record says
+ * `created: null` and carries no age. With no last record to measure from, no
+ * `created` is plausible. (APRV-479 R3-7, the stricter rule.)
+ */
+export declare function plausibleCreated(note: ReclaimNote, lastTs: number | null, now: number): ReclaimNote;
+/** What the writer knows about the log before it claims: whether it could record a reclaim at all, and its last record's time. */
+export type RecordContext = {
+    ok: true;
+    lastTs: number | null;
+} | {
+    ok: false;
+    why: string;
+};
+/** What {@link reclaimStaleLock} found and did. */
+export type ReclaimOutcome = 
+/** This process now holds the lock and must record `note` first. */
+{
+    kind: "taken";
+    own: OwnLock;
+    releaseGuard: () => void;
+    note: ReclaimNote;
+}
+/** The lock moved, or another writer is reclaiming it: wait again. */
+ | {
+    kind: "retry";
+    why: string;
+}
+/** The lock stays where it is; `why` names its holder and the human command. */
+ | {
+    kind: "kept";
+    why: string;
+};
+/** The human verb, as a refusal names it. */
+export declare function unlockCommand(pid: number | null): string;
+/** A lockfile as a writer saw it at the first refusal of its wait (R3-8). */
+export interface LockObservation {
+    ino: bigint;
+    mtimeNs: bigint;
+    size: bigint;
+    /** When it was seen, by this process's clock. */
+    at: number;
+}
+/** What is at `<logPath>.lock` now, without opening it: a regular file's identity, or `null`. */
+export declare function observeLock(logPath: string, now?: number): LockObservation | null;
+/** Options for {@link reclaimStaleLock}. */
+export interface ReclaimOptions {
+    now?: number;
+    /** The writer's own write-boundary check of the record it would append: a reclaim it would refuse is not made. */
+    recordValid?: (note: ReclaimNote) => boolean;
+    /**
+     * The lockfile as this writer saw it at the first refusal of this wait
+     * ({@link observeLock}). An empty lockfile is taken only when it is that
+     * same file, watched for at least {@link LEGACY_LOCK_WATCH_MS}.
+     */
+    watched?: LockObservation | null;
+    /**
+     * Can this writer append at all right now (its daemon stamp, the log's
+     * tail), and when was the log's last record? Asked before the claim, so a
+     * reclaim whose record would be refused is never made; the last record's
+     * time bounds the `created` the record may carry ({@link plausibleCreated}).
+     * Absent: appendable, with no last record to measure from.
+     */
+    recordContext?: () => RecordContext;
+}
+/**
+ * Judge `<logPath>.lock` once and, when its holder is provably gone, take it:
+ * claim, prove the claim, take. Called by a writer only after its whole lock
+ * timeout has passed. Nothing is written but the stale name (the claim) and
+ * this writer's own lockfile.
+ */
+export declare function reclaimStaleLock(logPath: string, op: LockOp, options?: ReclaimOptions): ReclaimOutcome;
+/** The stale name of a reclaim whose record is now in the log. */
+export declare function finishReclaim(note: ReclaimNote): void;
+/** What {@link takeLockForUnlock} found and did. */
+export type UnlockOutcome = {
+    kind: "taken";
+    own: OwnLock;
+    releaseGuard: () => void;
+    note: ReclaimNote;
+} | {
+    kind: "none";
+} | {
+    kind: "refused";
+    why: string;
+};
+/**
+ * `approval log unlock --pid <n|none>`: a human's take of a lock no writer
+ * reclaims (another container, another boot, a pid that cannot be checked, a
+ * claim whose reclaimer died, a planted stale name). The human asserts that no
+ * writer is running; this refuses only what it can see is wrong: a `--pid`
+ * that is not the record's, a holder it sees running, a lock beside a sync
+ * snapshot, and anything at the lock's path that is not a lockfile (which `rm`
+ * removes). It takes the lock with the same claim and take as a writer's
+ * reclaim, so the record of it (reason `operator-cleared`) is the first under
+ * the lock it takes.
+ */
+export declare function takeLockForUnlock(logPath: string, expected: number | null, lastTs?: number | null, now?: number): UnlockOutcome;
+/**
+ * Hold SIGTERM, SIGINT and SIGHUP from just before a lockfile is created until
+ * just after it is removed, for each signal nobody listens for (the default
+ * disposition would kill the process with the lockfile in place). Returns the
+ * release.
+ *
+ * Node shows a caught signal to JavaScript only when the event loop turns, and
+ * removing the last listener before that turn drops it. So after the release:
+ * a verb that returns or awaits dies of the signal at its next turn;
+ * `approval run` awaits {@link yieldToTerminationSignals} before it spawns, so
+ * a stop request during its append ends it first; and a synchronous wait calls
+ * {@link settleTerminationGuards} before it blocks, so the wait runs under the
+ * default disposition, at the price of losing a signal that landed in the
+ * append's own milliseconds. A create that fails EEXIST releases and settles at
+ * once, so a lock wait runs unguarded (a signal there kills at once, holding
+ * nothing).
+ *
+ * Windows has no such signals to hold; there this is a no-op.
+ */
+export declare function guardTerminationWhileLocked(): () => void;
+/**
+ * Synchronous code about to block (an `Atomics.wait` poll, a `spawnSync`) calls
+ * this first: when no lock is held, the guard is removed now, so the block is
+ * not run with termination signals held. No-op while a lock is held.
+ */
+export declare function settleTerminationGuards(): void;
+/**
+ * Turn the event loop past a poll phase, so a termination signal a released
+ * lock's guard caught is dispatched now and the process dies of it here,
+ * before the caller starts whatever it was about to start.
+ */
+export declare function yieldToTerminationSignals(): Promise<void>;