approval-md 0.0.1 → 0.2.0

package/dist/src/core/money.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Monetary amounts in hashed material (APRV-121).
+ *
+ * ## The representation, and why
+ *
+ * Every USD amount that enters hashed material — an envelope's
+ * `actions[].est_cost_usd` and `budget.max_cost_usd`, the `est_cost_usd` the
+ * gate records on `approval.requested`, `approval.granted`, `execution.started`
+ * and `budget.exceeded`, and the `est_cost_usd` an execution token binds to —
+ * is a **decimal string**: `"0"`, `"0.02"`, `"1200.5"`. Not a JSON number.
+ *
+ * RFC 8785 pins ES6 number serialization, so a single TypeScript runtime is
+ * internally consistent with itself. Cross-language it is not: the fast-path of
+ * SPEC.md §13 and any second implementation must reproduce the same bytes from
+ * the same value, and float formatting is precisely where that breaks. A
+ * decimal string has one spelling, and every language agrees on it because
+ * nobody has to reserialize anything.
+ *
+ * **String decimal, not integer minor units.** Both remove the float; the
+ * choice is about what a human writes and reads. The field is named
+ * `est_cost_usd` and a task author writes it in YAML frontmatter next to a
+ * one-line summary; `est_cost_usd: "0.02"` still says two cents, while
+ * `est_cost_usd: 20000` says nothing without knowing the exponent this project
+ * picked, and picking one commits the format to a currency decision (USD has
+ * two decimal places, other currencies do not) that the field name does not
+ * make. The string also round-trips into and out of a channel message, a CLI
+ * table, and a policy discussion without a conversion anyone can get wrong.
+ *
+ * ## The canonical form
+ *
+ * {@link USD_STRING_PATTERN}: an optional integer part with no leading zeros,
+ * an optional fraction of one to six digits, no sign, no exponent, no trailing
+ * dot, no trailing zeros beyond the last significant digit. One value, one
+ * spelling — `"0.10"` and `"0.1"` cannot both be written, so two records
+ * carrying the same amount always hash the same way.
+ *
+ * Six fractional digits is the resolution, matching the micro-USD unit the
+ * arithmetic below runs in. It is far finer than any real amount and far
+ * coarser than IEEE-754 drift.
+ *
+ * ## The arithmetic
+ *
+ * All budget arithmetic runs in **integer micro-USD**. A decimal string parses
+ * to micros by integer string manipulation, never through a double, so no
+ * rounding happens on the way in and none is possible on the way back out.
+ * Sums, comparisons, and remainders are exact integers: `"0.1" + "0.2"` is
+ * `"0.3"`, and a window of ten thousand two-cent actions is exactly `"200"`
+ * rather than a value that depends on the order they were added in.
+ *
+ * ## Historical compatibility (SPEC.md §8, additive-change precedent)
+ *
+ * The log is append-only, so records written before this change carry JSON
+ * numbers and must keep validating, verifying, and feeding budget math exactly
+ * as before. Every reader here therefore accepts both forms: a decimal string
+ * (the only form the write boundary now admits) and a finite non-negative JSON
+ * number (the historical form). A historical number converts to micros by
+ * `Math.round(value * 1e6)`, which is deterministic for every amount the old
+ * write boundary could have admitted. The write boundary is the only place the
+ * two forms are told apart: `schema/*.schema.json` types the fields as decimal
+ * strings, and `validate(..., { mode: "historical" })` is the one documented
+ * relaxation, used by the verifier and nothing else.
+ */
+/** Micro-USD per USD: the resolution of every amount in this module. */
+export declare const USD_MICROS_SCALE = 1000000;
+/** Fractional digits the canonical form admits (the micro-USD resolution). */
+export declare const USD_FRACTION_DIGITS = 6;
+/**
+ * The canonical decimal-string form, as a JSON Schema `pattern` source.
+ *
+ * Exported so the schemas and the runtime cannot drift: `tests/money.test.ts`
+ * asserts the schema files carry exactly this string.
+ */
+export declare const USD_STRING_PATTERN = "^(0|[1-9][0-9]*)(\\.[0-9]{0,5}[1-9])?$";
+/** Is `value` a canonical decimal USD string? */
+export declare function isUsdString(value: unknown): value is string;
+/**
+ * A canonical decimal string as integer micro-USD, or `null` when the string is
+ * not canonical.
+ *
+ * Parsed by integer arithmetic on the digits: the fraction is padded to six
+ * places and the two halves are combined, so the double never sees the value.
+ */
+export declare function usdStringToMicros(value: string): number | null;
+/**
+ * A historical JSON number as integer micro-USD, or `null` when it is not a
+ * usable amount (non-finite, negative, or beyond the safe-integer range once
+ * scaled).
+ *
+ * `Math.round` is the documented conversion. It is deterministic, and for every
+ * value the pre-APRV-121 write boundary admitted (`minimum: 0`, ES6-serialized)
+ * it lands on the micro the author wrote.
+ */
+export declare function usdNumberToMicros(value: number): number | null;
+/**
+ * Either accepted form as integer micro-USD, or `null` when the value is not a
+ * usable amount.
+ *
+ * This is the reader every enforcement path uses. It accepts the historical
+ * number deliberately: a record already in the log must feed budget math
+ * identically to before this change.
+ */
+export declare function usdToMicros(value: unknown): number | null;
+/** Integer micro-USD as the canonical decimal string. */
+export declare function microsToUsdString(micros: number): string;
+/**
+ * Integer micro-USD as a JSON number, for **display and CLI output only**.
+ *
+ * Never write the result of this function into hashed material: that is the
+ * float this module exists to remove. Budget verdicts report through it because
+ * a verdict is a rendered explanation of a decision the integers already made.
+ */
+export declare function microsToUsdNumber(micros: number): number;
+/**
+ * Either accepted form as a canonical decimal string, or `null` when the value
+ * is not a usable amount.
+ *
+ * The normalizer at every boundary where an amount arrives from outside: a task
+ * envelope, a CLI flag, a historical log record.
+ */
+export declare function normalizeUsd(value: unknown): string | null;
+/**
+ * Either accepted form as a canonical decimal string, defaulting to `"0"`.
+ *
+ * The budgets contract of `core/budgets.ts` requires `est_cost_usd` on every
+ * consuming event, and an action that declared no cost is recorded as `"0"` —
+ * an authorization with no declared cost is still an authorization.
+ */
+export declare function usdOrZero(value: unknown): string;
+/**
+ * Either accepted form as a JSON number, for **display surfaces only**: a
+ * channel card, a CLI table, a `--json` field a human reads.
+ *
+ * `0` for anything unusable, so a renderer never has to decide what to print
+ * for a malformed amount. Same warning as {@link microsToUsdNumber}: the result
+ * of this function must never be written into hashed material.
+ */
+export declare function usdNumber(value: unknown): number;
+/**
+ * Either accepted form as a JSON number, or `null` when there is no amount.
+ *
+ * The display counterpart of {@link normalizeUsd}: it keeps "declared nothing"
+ * distinct from "declared zero", which is a distinction the queue's own columns
+ * make.
+ */
+export declare function usdNumberOrNull(value: unknown): number | null;
+/** An amount as accepted from a caller: canonical string, or historical number. */
+export type UsdInput = string | number;

package/dist/src/core/money.js

@@ -0,0 +1,195 @@
+/**
+ * Monetary amounts in hashed material (APRV-121).
+ *
+ * ## The representation, and why
+ *
+ * Every USD amount that enters hashed material — an envelope's
+ * `actions[].est_cost_usd` and `budget.max_cost_usd`, the `est_cost_usd` the
+ * gate records on `approval.requested`, `approval.granted`, `execution.started`
+ * and `budget.exceeded`, and the `est_cost_usd` an execution token binds to —
+ * is a **decimal string**: `"0"`, `"0.02"`, `"1200.5"`. Not a JSON number.
+ *
+ * RFC 8785 pins ES6 number serialization, so a single TypeScript runtime is
+ * internally consistent with itself. Cross-language it is not: the fast-path of
+ * SPEC.md §13 and any second implementation must reproduce the same bytes from
+ * the same value, and float formatting is precisely where that breaks. A
+ * decimal string has one spelling, and every language agrees on it because
+ * nobody has to reserialize anything.
+ *
+ * **String decimal, not integer minor units.** Both remove the float; the
+ * choice is about what a human writes and reads. The field is named
+ * `est_cost_usd` and a task author writes it in YAML frontmatter next to a
+ * one-line summary; `est_cost_usd: "0.02"` still says two cents, while
+ * `est_cost_usd: 20000` says nothing without knowing the exponent this project
+ * picked, and picking one commits the format to a currency decision (USD has
+ * two decimal places, other currencies do not) that the field name does not
+ * make. The string also round-trips into and out of a channel message, a CLI
+ * table, and a policy discussion without a conversion anyone can get wrong.
+ *
+ * ## The canonical form
+ *
+ * {@link USD_STRING_PATTERN}: an optional integer part with no leading zeros,
+ * an optional fraction of one to six digits, no sign, no exponent, no trailing
+ * dot, no trailing zeros beyond the last significant digit. One value, one
+ * spelling — `"0.10"` and `"0.1"` cannot both be written, so two records
+ * carrying the same amount always hash the same way.
+ *
+ * Six fractional digits is the resolution, matching the micro-USD unit the
+ * arithmetic below runs in. It is far finer than any real amount and far
+ * coarser than IEEE-754 drift.
+ *
+ * ## The arithmetic
+ *
+ * All budget arithmetic runs in **integer micro-USD**. A decimal string parses
+ * to micros by integer string manipulation, never through a double, so no
+ * rounding happens on the way in and none is possible on the way back out.
+ * Sums, comparisons, and remainders are exact integers: `"0.1" + "0.2"` is
+ * `"0.3"`, and a window of ten thousand two-cent actions is exactly `"200"`
+ * rather than a value that depends on the order they were added in.
+ *
+ * ## Historical compatibility (SPEC.md §8, additive-change precedent)
+ *
+ * The log is append-only, so records written before this change carry JSON
+ * numbers and must keep validating, verifying, and feeding budget math exactly
+ * as before. Every reader here therefore accepts both forms: a decimal string
+ * (the only form the write boundary now admits) and a finite non-negative JSON
+ * number (the historical form). A historical number converts to micros by
+ * `Math.round(value * 1e6)`, which is deterministic for every amount the old
+ * write boundary could have admitted. The write boundary is the only place the
+ * two forms are told apart: `schema/*.schema.json` types the fields as decimal
+ * strings, and `validate(..., { mode: "historical" })` is the one documented
+ * relaxation, used by the verifier and nothing else.
+ */
+/** Micro-USD per USD: the resolution of every amount in this module. */
+export const USD_MICROS_SCALE = 1_000_000;
+/** Fractional digits the canonical form admits (the micro-USD resolution). */
+export const USD_FRACTION_DIGITS = 6;
+/**
+ * The canonical decimal-string form, as a JSON Schema `pattern` source.
+ *
+ * Exported so the schemas and the runtime cannot drift: `tests/money.test.ts`
+ * asserts the schema files carry exactly this string.
+ */
+export const USD_STRING_PATTERN = "^(0|[1-9][0-9]*)(\\.[0-9]{0,5}[1-9])?$";
+const CANONICAL = /^(0|[1-9][0-9]*)(\.([0-9]{0,5}[1-9]))?$/u;
+/** Is `value` a canonical decimal USD string? */
+export function isUsdString(value) {
+    return typeof value === "string" && CANONICAL.test(value);
+}
+/**
+ * A canonical decimal string as integer micro-USD, or `null` when the string is
+ * not canonical.
+ *
+ * Parsed by integer arithmetic on the digits: the fraction is padded to six
+ * places and the two halves are combined, so the double never sees the value.
+ */
+export function usdStringToMicros(value) {
+    const match = CANONICAL.exec(value);
+    if (match === null)
+        return null;
+    const whole = match[1] ?? "0";
+    const fraction = (match[3] ?? "").padEnd(USD_FRACTION_DIGITS, "0");
+    const micros = Number(whole) * USD_MICROS_SCALE + Number(fraction);
+    return Number.isSafeInteger(micros) ? micros : null;
+}
+/**
+ * A historical JSON number as integer micro-USD, or `null` when it is not a
+ * usable amount (non-finite, negative, or beyond the safe-integer range once
+ * scaled).
+ *
+ * `Math.round` is the documented conversion. It is deterministic, and for every
+ * value the pre-APRV-121 write boundary admitted (`minimum: 0`, ES6-serialized)
+ * it lands on the micro the author wrote.
+ */
+export function usdNumberToMicros(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return null;
+    const micros = Math.round(value * USD_MICROS_SCALE);
+    return Number.isSafeInteger(micros) ? micros : null;
+}
+/**
+ * Either accepted form as integer micro-USD, or `null` when the value is not a
+ * usable amount.
+ *
+ * This is the reader every enforcement path uses. It accepts the historical
+ * number deliberately: a record already in the log must feed budget math
+ * identically to before this change.
+ */
+export function usdToMicros(value) {
+    if (typeof value === "string")
+        return usdStringToMicros(value);
+    if (typeof value === "number")
+        return usdNumberToMicros(value);
+    return null;
+}
+/** Integer micro-USD as the canonical decimal string. */
+export function microsToUsdString(micros) {
+    if (!Number.isFinite(micros))
+        return "0";
+    const rounded = Math.round(micros);
+    const negative = rounded < 0;
+    const magnitude = Math.abs(rounded);
+    const whole = Math.floor(magnitude / USD_MICROS_SCALE);
+    const fraction = String(magnitude % USD_MICROS_SCALE)
+        .padStart(USD_FRACTION_DIGITS, "0")
+        .replace(/0+$/u, "");
+    const text = fraction === "" ? String(whole) : `${String(whole)}.${fraction}`;
+    // A negative amount is not a canonical value and never enters hashed
+    // material; it exists only as budget headroom already spent, which the
+    // verdict reports as a number rather than through this function.
+    return negative ? `-${text}` : text;
+}
+/**
+ * Integer micro-USD as a JSON number, for **display and CLI output only**.
+ *
+ * Never write the result of this function into hashed material: that is the
+ * float this module exists to remove. Budget verdicts report through it because
+ * a verdict is a rendered explanation of a decision the integers already made.
+ */
+export function microsToUsdNumber(micros) {
+    return Math.round(micros) / USD_MICROS_SCALE;
+}
+/**
+ * Either accepted form as a canonical decimal string, or `null` when the value
+ * is not a usable amount.
+ *
+ * The normalizer at every boundary where an amount arrives from outside: a task
+ * envelope, a CLI flag, a historical log record.
+ */
+export function normalizeUsd(value) {
+    const micros = usdToMicros(value);
+    return micros === null ? null : microsToUsdString(micros);
+}
+/**
+ * Either accepted form as a canonical decimal string, defaulting to `"0"`.
+ *
+ * The budgets contract of `core/budgets.ts` requires `est_cost_usd` on every
+ * consuming event, and an action that declared no cost is recorded as `"0"` —
+ * an authorization with no declared cost is still an authorization.
+ */
+export function usdOrZero(value) {
+    return normalizeUsd(value) ?? "0";
+}
+/**
+ * Either accepted form as a JSON number, for **display surfaces only**: a
+ * channel card, a CLI table, a `--json` field a human reads.
+ *
+ * `0` for anything unusable, so a renderer never has to decide what to print
+ * for a malformed amount. Same warning as {@link microsToUsdNumber}: the result
+ * of this function must never be written into hashed material.
+ */
+export function usdNumber(value) {
+    return microsToUsdNumber(usdToMicros(value) ?? 0);
+}
+/**
+ * Either accepted form as a JSON number, or `null` when there is no amount.
+ *
+ * The display counterpart of {@link normalizeUsd}: it keeps "declared nothing"
+ * distinct from "declared zero", which is a distinction the queue's own columns
+ * make.
+ */
+export function usdNumberOrNull(value) {
+    const micros = usdToMicros(value);
+    return micros === null ? null : microsToUsdNumber(micros);
+}
+//# sourceMappingURL=money.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../../src/core/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,wCAAwC,CAAC;AAE3E,MAAM,SAAS,GAAG,0CAA0C,CAAC;AAE7D,iDAAiD;AACjD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9B,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,gBAAgB,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,gBAAgB,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,GAAG,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,OAAO,GAAG,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,gBAAgB,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,GAAG,gBAAgB,CAAC;SAClD,QAAQ,CAAC,mBAAmB,EAAE,GAAG,CAAC;SAClC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;IAC9E,qEAAqE;IACrE,uEAAuE;IACvE,iEAAiE;IACjE,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,iBAAiB,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC"}

package/dist/src/core/payload-census.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What the payload store holds, read against what the log says about it
+ * (APRV-41's counts, APRV-59's home for them).
+ *
+ * The census is a *reporting* question, asked by `approval doctor` and by
+ * `approval status`, and answered from two sources that can disagree: the files
+ * under `.approval/payloads/` and the records of `events.jsonl`. It decides
+ * nothing and deletes nothing. The daemon's pruner (`daemon/prune.ts`) is the
+ * only caller allowed to act on the same facts, and it derives its plan through
+ * the two helpers exported here so that the counts a reader is shown and the
+ * files the daemon would remove are computed by one piece of code.
+ *
+ * ## Why this lives in `core/` and not beside the pruner
+ *
+ * The CLI reports these numbers, and a CLI verb reaching into `daemon/` to do it
+ * is the wrong direction: `daemon/` is a caller of the core, never a dependency
+ * of the surfaces. This module is that shared core. Nothing here reads a clock,
+ * loads a policy, appends an event, or unlinks a file.
+ *
+ * ## Why not in `core/payload-store.ts`
+ *
+ * The store module is deliberately ignorant of the log ("Nothing here opens
+ * `events.jsonl`"): it addresses bytes by hash and verifies them, and that
+ * narrowness is what makes it safe to call from every channel. The census is the
+ * opposite kind of thing, a comparison between the log and the store, so it gets
+ * its own module rather than teaching the store to read events.
+ */
+import type { EventRecord } from "./log.js";
+/** Hashes a `payload.pruned` record already names. */
+export declare function prunedHashes(records: EventRecord[]): Set<string>;
+export interface Binding {
+    /** Action keys that declared this hash. */
+    actionKeys: Set<string>;
+    /** A record named the hash without an action key: bound, but unattributable. */
+    unattributed: boolean;
+}
+/**
+ * Every hash any record binds to, mapped to the actions that declared it.
+ *
+ * Two attributions are understood, because they are the two the runtime writes:
+ * a `payload_hash` beside a record's own `action_key` (`approval.requested` and
+ * `approval.granted` carry it there), and the `payload_hash` of each action
+ * inside a `task.registered` envelope, attributed to that action's
+ * `idempotency_key` — which is where a *registered but not yet requested* action
+ * declares its bytes. Without the second, a payload stored at registration time
+ * would look like residue nothing bound and be pruned out from under the request
+ * about to be made for it.
+ *
+ * Everything else is caught by a deep scan and deliberately treated as a
+ * binding this module cannot attribute: an unattributable binding is never
+ * prunable, so an event shape nobody here anticipated makes a payload immortal
+ * rather than making it disposable. The only event exempt from the scan is
+ * `payload.pruned`, whose whole job is to name bytes that are going.
+ */
+export declare function bindingsOf(records: EventRecord[]): Map<string, Binding>;
+export interface PayloadStoreCensus {
+    /** Files the store currently holds, by hash. */
+    files: number;
+    /** Distinct hashes a `payload.pruned` event names — evidence that outlived bytes. */
+    pruned: number;
+    /** Files present that no record binds: head-moved residue, prunable when enabled. */
+    orphans: number;
+    /** Files present whose prune event is already logged (a crash mid-prune). */
+    awaitingRemoval: number;
+}
+/**
+ * Count what the store holds against what the log says about it.
+ *
+ * Honest in both directions and about both failure modes: `pruned` is a fact of
+ * the log (it stays true forever, whatever the store does), `orphans` and
+ * `awaitingRemoval` are facts about the disagreement between the two. None of
+ * them is a health verdict; a reader is being told what is there.
+ */
+export declare function payloadStoreCensus(records: EventRecord[], storeDir: string): PayloadStoreCensus;

package/dist/src/core/payload-census.js

@@ -0,0 +1,146 @@
+/**
+ * What the payload store holds, read against what the log says about it
+ * (APRV-41's counts, APRV-59's home for them).
+ *
+ * The census is a *reporting* question, asked by `approval doctor` and by
+ * `approval status`, and answered from two sources that can disagree: the files
+ * under `.approval/payloads/` and the records of `events.jsonl`. It decides
+ * nothing and deletes nothing. The daemon's pruner (`daemon/prune.ts`) is the
+ * only caller allowed to act on the same facts, and it derives its plan through
+ * the two helpers exported here so that the counts a reader is shown and the
+ * files the daemon would remove are computed by one piece of code.
+ *
+ * ## Why this lives in `core/` and not beside the pruner
+ *
+ * The CLI reports these numbers, and a CLI verb reaching into `daemon/` to do it
+ * is the wrong direction: `daemon/` is a caller of the core, never a dependency
+ * of the surfaces. This module is that shared core. Nothing here reads a clock,
+ * loads a policy, appends an event, or unlinks a file.
+ *
+ * ## Why not in `core/payload-store.ts`
+ *
+ * The store module is deliberately ignorant of the log ("Nothing here opens
+ * `events.jsonl`"): it addresses bytes by hash and verifies them, and that
+ * narrowness is what makes it safe to call from every channel. The census is the
+ * opposite kind of thing, a comparison between the log and the store, so it gets
+ * its own module rather than teaching the store to read events.
+ */
+import { isPayloadHash } from "./payload.js";
+import { listStoredPayloadHashes } from "./payload-store.js";
+import { payloadOf } from "./state.js";
+/** Hashes a `payload.pruned` record already names. */
+export function prunedHashes(records) {
+    const pruned = new Set();
+    for (const record of records) {
+        if (record.event !== "payload.pruned")
+            continue;
+        const hash = payloadOf(record)["payload_hash"];
+        if (isPayloadHash(hash))
+            pruned.add(hash);
+    }
+    return pruned;
+}
+/** Every payload-hash-shaped string anywhere inside a value. */
+function hashesWithin(value, found) {
+    if (isPayloadHash(value)) {
+        found.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            hashesWithin(item, found);
+        return;
+    }
+    if (typeof value === "object" && value !== null) {
+        for (const item of Object.values(value))
+            hashesWithin(item, found);
+    }
+}
+/**
+ * Every hash any record binds to, mapped to the actions that declared it.
+ *
+ * Two attributions are understood, because they are the two the runtime writes:
+ * a `payload_hash` beside a record's own `action_key` (`approval.requested` and
+ * `approval.granted` carry it there), and the `payload_hash` of each action
+ * inside a `task.registered` envelope, attributed to that action's
+ * `idempotency_key` — which is where a *registered but not yet requested* action
+ * declares its bytes. Without the second, a payload stored at registration time
+ * would look like residue nothing bound and be pruned out from under the request
+ * about to be made for it.
+ *
+ * Everything else is caught by a deep scan and deliberately treated as a
+ * binding this module cannot attribute: an unattributable binding is never
+ * prunable, so an event shape nobody here anticipated makes a payload immortal
+ * rather than making it disposable. The only event exempt from the scan is
+ * `payload.pruned`, whose whole job is to name bytes that are going.
+ */
+export function bindingsOf(records) {
+    const bindings = new Map();
+    const bindingFor = (hash) => {
+        let binding = bindings.get(hash);
+        if (binding === undefined) {
+            binding = { actionKeys: new Set(), unattributed: false };
+            bindings.set(hash, binding);
+        }
+        return binding;
+    };
+    for (const record of records) {
+        if (record.event === "payload.pruned")
+            continue;
+        const payload = payloadOf(record);
+        const attributed = new Set();
+        const own = payload["payload_hash"];
+        const key = record.action_key;
+        if (isPayloadHash(own) && typeof key === "string" && key.length > 0) {
+            bindingFor(own).actionKeys.add(key);
+            attributed.add(own);
+        }
+        const actions = payload["actions"];
+        if (Array.isArray(actions)) {
+            for (const action of actions) {
+                if (typeof action !== "object" || action === null)
+                    continue;
+                const item = action;
+                const hash = item["payload_hash"];
+                const declaredKey = item["idempotency_key"];
+                if (!isPayloadHash(hash))
+                    continue;
+                if (typeof declaredKey === "string" && declaredKey.length > 0) {
+                    bindingFor(hash).actionKeys.add(declaredKey);
+                    attributed.add(hash);
+                }
+            }
+        }
+        const mentioned = new Set();
+        hashesWithin(payload, mentioned);
+        for (const hash of mentioned) {
+            if (attributed.has(hash))
+                continue;
+            bindingFor(hash).unattributed = true;
+        }
+    }
+    return bindings;
+}
+/**
+ * Count what the store holds against what the log says about it.
+ *
+ * Honest in both directions and about both failure modes: `pruned` is a fact of
+ * the log (it stays true forever, whatever the store does), `orphans` and
+ * `awaitingRemoval` are facts about the disagreement between the two. None of
+ * them is a health verdict; a reader is being told what is there.
+ */
+export function payloadStoreCensus(records, storeDir) {
+    const present = listStoredPayloadHashes(storeDir);
+    const pruned = prunedHashes(records);
+    const bindings = bindingsOf(records);
+    let orphans = 0;
+    let awaitingRemoval = 0;
+    for (const hash of present) {
+        if (pruned.has(hash))
+            awaitingRemoval += 1;
+        else if (!bindings.has(hash))
+            orphans += 1;
+    }
+    return { files: present.length, pruned: pruned.size, orphans, awaitingRemoval };
+}
+//# sourceMappingURL=payload-census.js.map

package/dist/src/core/payload-census.js.map

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