approval-md 0.0.1 → 0.2.0

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

@@ -0,0 +1,138 @@
+/**
+ * Write-boundary JSON Schema validation.
+ *
+ * SPEC.md §8: every event and envelope validates against its JSON Schema
+ * before it is written. Validation at the write boundary is itself a control,
+ * so this module fails **closed**: a missing schema directory, an unreadable
+ * or unparseable schema file, an unknown schema id, or an Ajv compile failure
+ * all produce `{ ok: false, errors: [...] }`. Nothing here can return `ok`
+ * for a document it did not actually validate, and nothing throws out to the
+ * caller (a thrown error would be an unhandled write-boundary bypass).
+ *
+ * Determinism: the result is a pure function of (schema files on disk,
+ * document). No network, no clock, no randomness. Every call re-reads every
+ * schema file, so a run never depends on the order or history of previous
+ * calls: edit a schema mid-run and the next call validates against the edit.
+ * Two reuses sit under that rule and neither bends it. {@link prepareValidator}
+ * lets a caller validating many documents against one schema in one pass
+ * compile once and hold the snapshot itself. And since APRV-206 the Ajv
+ * *compile* is reused across calls when the schema bytes just read hash to the
+ * digest the compiled validator was built from — the schema files are still
+ * read every time, so nothing is answered for bytes that were not re-proved;
+ * see {@link compiledValidators} for the argument in full.
+ *
+ * Dialect / import notes (AC #6 — documented, never silently downgraded):
+ *
+ * - Dialect is JSON Schema draft 2020-12 via Ajv's dedicated `Ajv2020` class.
+ *   Ajv 8 ships no `exports` map, so under NodeNext the working ESM import is
+ *   the deep path to the built CJS file:
+ *       import { Ajv2020 } from "ajv/dist/2020.js";
+ *   The named export is used rather than the default because Ajv 8's CJS
+ *   interop default (`module.exports = Ajv2020`) is not typed as a default
+ *   export under `verbatimModuleSyntax` + `esModuleInterop: false`. The named
+ *   binding resolves and type-checks cleanly under NodeNext.
+ * - `ajv-formats` is likewise a deep CJS import: its plugin is exported as
+ *   `module.exports = formatsPlugin`, so the callable value comes from the
+ *   `.default` property of the namespace import under NodeNext.
+ * - Ajv is configured `strict: true`. No strict flag is relaxed. Formats are
+ *   enforced, not annotation-only: `validateFormats: true` plus `ajv-formats`
+ *   registered, so an invalid `date-time` string is a validation error.
+ */
+/** A single validation failure, flattened for logging and CLI output. */
+export interface ValidationError {
+    /** JSON Pointer to the offending location ("" for the document root). */
+    path: string;
+    /** Ajv keyword, or a harness pseudo-keyword such as "schemaLoad". */
+    keyword: string;
+    /** Human-readable reason. */
+    message: string;
+}
+/** Result of a write-boundary validation. Failure always carries a reason. */
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/** Suffix identifying schema files inside the schema directory. */
+export declare const SCHEMA_FILE_SUFFIX = ".schema.json";
+/** Repo `schema/` directory: default source of truth for all schemas. */
+export declare const DEFAULT_SCHEMA_DIR: string;
+/**
+ * Which boundary a validation is speaking for (APRV-121).
+ *
+ * - `write` — the default, and what SPEC.md §8 means by "validate at the write
+ *   boundary". The schemas as written on disk: a monetary amount is a canonical
+ *   decimal string and nothing else.
+ * - `historical` — the read boundary. The log is append-only, so a verifier
+ *   walking records written before APRV-121 meets JSON-number amounts that were
+ *   valid when they were appended and must stay valid forever. This mode makes
+ *   exactly one substitution, described in {@link WIDENED_DEFS}, and no other.
+ *
+ * The asymmetry is the point: a document only ever gets *more* permissive by a
+ * caller explicitly naming the read boundary, and the callers that do are
+ * pinned: `core/verify.ts` (the log walk), the daemon's envelope scan, and the
+ * `set-state` task-file rewrite — paths that read or preserve claims an earlier
+ * write boundary accepted, never ones that author new claims (APRV-121,
+ * APRV-148).
+ */
+export type ValidationMode = "write" | "historical";
+/** Options accepted by {@link validate}. */
+export interface ValidateOptions {
+    /** Directory to load `*.schema.json` from. Injectable for tests. */
+    schemaDir?: string;
+    /** Which boundary this validation speaks for. Defaults to `"write"`. */
+    mode?: ValidationMode;
+}
+/**
+ * The `$defs` a `historical` validation replaces, as `name -> replacement name`.
+ *
+ * Pinned as a list rather than derived from a naming convention, so widening
+ * the read boundary is always a reviewable diff in this file and never a side
+ * effect of adding a definition to a schema. `usd_amount` is the only entry:
+ * the pre-APRV-121 write boundary typed monetary fields as `{"type": "number",
+ * "minimum": 0}`, and `usd_amount_historical` is exactly that union with the
+ * decimal string.
+ */
+export declare const WIDENED_DEFS: Readonly<Record<string, string>>;
+/**
+ * List schema names (file basename minus `.schema.json`) in a directory.
+ * Sorted, so discovery order is stable across platforms and runs.
+ */
+export declare function listSchemaNames(schemaDir?: string): string[];
+/**
+ * Validate `document` against the schema identified by `schemaId` (the schema
+ * filename minus `.schema.json`, or the schema's `$id`).
+ *
+ * Fails closed: every load, parse, and compile problem is reported as a
+ * validation failure rather than thrown.
+ */
+export declare function validate(schemaId: string, document: unknown, options?: ValidateOptions): ValidationResult;
+/**
+ * A validator compiled once and reusable for many documents.
+ *
+ * `check` is {@link validate} with the schema load and Ajv compile already
+ * paid: same results, same error shapes, on every document. This exists for
+ * the one caller that validates thousands of documents against one schema in
+ * one pass — the log chain walk — where a per-document recompile turns a
+ * subsecond verification into minutes of CPU (APRV-186).
+ *
+ * The determinism stance in the module header is unchanged: nothing is cached
+ * across calls to {@link prepareValidator} itself. A prepared validator is a
+ * snapshot of the schema files as they stood when it was prepared; a caller
+ * that wants fresh schemas prepares again.
+ */
+export interface PreparedValidator {
+    ok: true;
+    check(document: unknown): ValidationResult;
+}
+/**
+ * Load and compile `schemaId` once, for reuse across many documents.
+ *
+ * Fails closed exactly as {@link validate} does: every load, parse, and
+ * compile problem is reported as `{ ok: false, errors }`, never thrown.
+ */
+export declare function prepareValidator(schemaId: string, options?: ValidateOptions): PreparedValidator | {
+    ok: false;
+    errors: ValidationError[];
+};

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

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

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

@@ -0,0 +1,137 @@
+/**
+ * The values block of `APPROVAL.md` (SPEC.md §5.3), read.
+ *
+ * Everything else in this directory is control: what an agent may do, who
+ * decides, what is sampled. This module reads the other half of the file — the
+ * optional ` ```yaml approval-values ` block in which the operator says what
+ * they value in the work, what they want from the agent, and how they read and
+ * answer. It is the mirror of the journal (SPEC.md §10.1): the journal is the
+ * agent's outlet the gate does not stand in front of, and the values block is
+ * the human's, with the same rule running in both directions, that nothing said
+ * there moves a verdict.
+ *
+ * Three decisions are worth stating here rather than leaving to be inferred.
+ *
+ * **Absence is a declaration, never a default.** A file with no values block is
+ * an operator who has declared no values, which is information. It is not a
+ * missing thing to be repaired, and it is not an invitation to invent a neutral
+ * middle. So the result has three states rather than two: present, absent, and
+ * unreadable, and `ok: true, present: false` is the absent one. Surfaces render
+ * it in the words SPEC.md §5.3 fixes, so a session can tell "nothing was
+ * declared" from "I did not look".
+ *
+ * **Two blocks fail.** One file, at most one values block, exactly as the policy
+ * block is exactly one. Two blocks are two answers to one question, and a reader
+ * that silently took the first would be choosing between two things a human
+ * wrote, on the strength of document order.
+ *
+ * **A values failure never fails the policy.** Enforcement fails closed on the
+ * policy block because an unparseable permission document is one whose author
+ * believes constraints are in force that are not. Nothing about that argument
+ * carries here, because this block is not enforcement: no routing, class match,
+ * sampling draw, budget, token or execution decision reads it (SPEC.md §11.1
+ * invariant 10, pinned by `tests/values-inert.test.ts`). Failing closed on a
+ * malformed values block would convert a typo into an all-manual repository, and
+ * would buy no safety at all in exchange. The two blocks are therefore parsed
+ * and judged independently, on paths that share only the fence splitter, and
+ * this module never calls the policy loader's parse path.
+ *
+ * ## Determinism
+ *
+ * {@link loadValues} is a pure function of the file bytes on disk plus the
+ * schema directory. No clock, no network, no randomness, no cross-call caching,
+ * and no throw: every failure is a result.
+ */
+import { type ValidationError } from "./validate.js";
+/** Info string that marks the OPTIONAL values block (SPEC.md §5.3). */
+export declare const VALUES_INFO_STRING = "yaml approval-values";
+/**
+ * The parsed values block, as `values.schema.json` admits it.
+ *
+ * The key set is closed and small on purpose, and the schema is the authority
+ * on why each key is here and which were rejected. This interface restates the
+ * shape for TypeScript and adds nothing.
+ */
+export interface Values {
+    /** Format version. The only required key; the integer `1` and nothing else. */
+    version: 1;
+    /** What the operator loves, in their own words. */
+    love?: string[];
+    /** What the operator likes. */
+    like?: string[];
+    /** What the operator dislikes. NOT a prohibition: a prohibition is policy. */
+    dislike?: string[];
+    /** What the operator wants FROM the agent, as behaviour rather than taste. */
+    wants?: string[];
+    /** How the operator reads and answers. One sentence or two. */
+    responds?: string;
+}
+/**
+ * Why a values block could not be read.
+ *
+ * Deliberately NOT {@link import("./policy-load.js").PolicyLoadErrorCode}: the
+ * two are different questions with different consequences, and a shared union
+ * would invite a caller to handle one with the other's rules. There is no
+ * `no-block` here, because a file with no values block is not a failure at all.
+ */
+export type ValuesLoadFailureCode = "file-missing" | "multiple-blocks" | "unterminated-fence" | "yaml-error" | "schema-invalid";
+/** Where the values block was read from. */
+export interface ValuesSource {
+    /** Absolute or caller-relative path actually read. */
+    path: string;
+    /** Basename of that path, e.g. `APPROVAL.md`. */
+    filename: string;
+}
+/**
+ * Result of {@link loadValues}: present, absent, or unreadable.
+ *
+ * A not-ok result places no obligation on any enforcement path, because no
+ * enforcement path may be looking. It obligates exactly one thing, of the
+ * surfaces that print it: say the block is there and could not be read, and say
+ * that it grants nothing either way.
+ */
+export type ValuesLoadResult = {
+    ok: true;
+    present: true;
+    values: Values;
+    source: ValuesSource;
+} | {
+    ok: true;
+    present: false;
+    source: ValuesSource;
+} | {
+    ok: false;
+    code: ValuesLoadFailureCode;
+    message: string;
+    errors?: ValidationError[];
+    source?: ValuesSource;
+};
+/** Options accepted by {@link loadValues}. */
+export interface LoadValuesOptions {
+    /** Directory to search for `APPROVAL.md` / `APPROVALS.md`. Default: cwd. */
+    dir?: string;
+    /** Explicit policy file path. Overrides discovery entirely. */
+    file?: string;
+    /** Schema directory passed through to {@link validate}. Injectable for tests. */
+    schemaDir?: string;
+}
+/**
+ * Extract, parse, and validate the values block of an already-read file.
+ *
+ * The bytes-in form of {@link loadValues}, for the caller that has the file in
+ * hand (a doctor run reading it once for several questions) and for the tests
+ * that build a file variant without touching a disk. Nothing here touches the
+ * filesystem, nothing throws, and `path` is used only for messages and for
+ * {@link ValuesSource}.
+ */
+export declare function loadValuesText(path: string, text: string, options?: {
+    schemaDir?: string;
+}): ValuesLoadResult;
+/**
+ * Find `APPROVAL.md`, and read its values block if it has one.
+ *
+ * Discovery plus {@link loadValuesText}. A file that cannot be read at all is
+ * `file-missing`, which is the only failure code here that says nothing about
+ * the block: there was no file to hold one.
+ */
+export declare function loadValues(options?: LoadValuesOptions): ValuesLoadResult;

package/dist/src/core/values.js

@@ -0,0 +1,153 @@
+/**
+ * The values block of `APPROVAL.md` (SPEC.md §5.3), read.
+ *
+ * Everything else in this directory is control: what an agent may do, who
+ * decides, what is sampled. This module reads the other half of the file — the
+ * optional ` ```yaml approval-values ` block in which the operator says what
+ * they value in the work, what they want from the agent, and how they read and
+ * answer. It is the mirror of the journal (SPEC.md §10.1): the journal is the
+ * agent's outlet the gate does not stand in front of, and the values block is
+ * the human's, with the same rule running in both directions, that nothing said
+ * there moves a verdict.
+ *
+ * Three decisions are worth stating here rather than leaving to be inferred.
+ *
+ * **Absence is a declaration, never a default.** A file with no values block is
+ * an operator who has declared no values, which is information. It is not a
+ * missing thing to be repaired, and it is not an invitation to invent a neutral
+ * middle. So the result has three states rather than two: present, absent, and
+ * unreadable, and `ok: true, present: false` is the absent one. Surfaces render
+ * it in the words SPEC.md §5.3 fixes, so a session can tell "nothing was
+ * declared" from "I did not look".
+ *
+ * **Two blocks fail.** One file, at most one values block, exactly as the policy
+ * block is exactly one. Two blocks are two answers to one question, and a reader
+ * that silently took the first would be choosing between two things a human
+ * wrote, on the strength of document order.
+ *
+ * **A values failure never fails the policy.** Enforcement fails closed on the
+ * policy block because an unparseable permission document is one whose author
+ * believes constraints are in force that are not. Nothing about that argument
+ * carries here, because this block is not enforcement: no routing, class match,
+ * sampling draw, budget, token or execution decision reads it (SPEC.md §11.1
+ * invariant 10, pinned by `tests/values-inert.test.ts`). Failing closed on a
+ * malformed values block would convert a typo into an all-manual repository, and
+ * would buy no safety at all in exchange. The two blocks are therefore parsed
+ * and judged independently, on paths that share only the fence splitter, and
+ * this module never calls the policy loader's parse path.
+ *
+ * ## Determinism
+ *
+ * {@link loadValues} is a pure function of the file bytes on disk plus the
+ * schema directory. No clock, no network, no randomness, no cross-call caching,
+ * and no throw: every failure is a result.
+ */
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { scanFences } from "./md-fence.js";
+// `POLICY_FILENAMES` is the SPEC.md §5 filename precedence and `parseHardenedYaml`
+// is the ONE hardened YAML parse in this codebase (see its own doc comment). The
+// values block lives inside the same file and deserves the same parser stance,
+// so both are borrowed rather than replicated. Nothing else is: the policy
+// loader's own parse path is untouched from here, in either direction.
+import { POLICY_FILENAMES, parseHardenedYaml } from "./policy-load.js";
+import { validate } from "./validate.js";
+/** Info string that marks the OPTIONAL values block (SPEC.md §5.3). */
+export const VALUES_INFO_STRING = "yaml approval-values";
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function sourceOf(path) {
+    return { path, filename: basename(path) };
+}
+function failure(code, message, source, errors) {
+    const base = { ok: false, code, message };
+    const withSource = source === undefined ? base : { ...base, source };
+    return errors === undefined ? withSource : { ...withSource, errors };
+}
+/**
+ * Find the file the values block would live in.
+ *
+ * The SAME discovery `loadPolicy` performs, and the same precedence
+ * ({@link POLICY_FILENAMES}: `APPROVAL.md`, then `APPROVALS.md`), because it is
+ * the same file. It is written out here rather than imported because the policy
+ * loader's is private to it, and a values reader that reached into the policy
+ * loader for anything but a shared constant is the coupling this module exists
+ * without.
+ */
+function resolveFile(options) {
+    if (options.file !== undefined) {
+        try {
+            return { path: options.file, text: readFileSync(options.file, "utf8") };
+        }
+        catch (cause) {
+            return failure("file-missing", `policy file ${options.file} could not be read: ${errorMessage(cause)}`, sourceOf(options.file));
+        }
+    }
+    const dir = options.dir ?? process.cwd();
+    for (const filename of POLICY_FILENAMES) {
+        const candidate = join(dir, filename);
+        try {
+            return { path: candidate, text: readFileSync(candidate, "utf8") };
+        }
+        catch {
+            continue;
+        }
+    }
+    return failure("file-missing", `no policy file found in ${dir} (looked for ${POLICY_FILENAMES.join(", ")})`);
+}
+/**
+ * Extract, parse, and validate the values block of an already-read file.
+ *
+ * The bytes-in form of {@link loadValues}, for the caller that has the file in
+ * hand (a doctor run reading it once for several questions) and for the tests
+ * that build a file variant without touching a disk. Nothing here touches the
+ * filesystem, nothing throws, and `path` is used only for messages and for
+ * {@link ValuesSource}.
+ */
+export function loadValuesText(path, text, options = {}) {
+    const source = sourceOf(path);
+    const scan = scanFences(text, VALUES_INFO_STRING);
+    if (scan.unterminated) {
+        // CommonMark would close an unterminated fence at EOF. This does not, for
+        // the reason the policy loader does not: the truncated tail of a block is
+        // indistinguishable from a complete one, and a values block that says half
+        // of what a human wrote is worse than one that says it could not be read.
+        return failure("unterminated-fence", `${path}: unterminated \`\`\`${VALUES_INFO_STRING} fence (no closing fence before end of file)`, source);
+    }
+    if (scan.blocks.length === 0) {
+        // The declaration of absence. Not a failure, and not a default.
+        return { ok: true, present: false, source };
+    }
+    if (scan.blocks.length > 1) {
+        return failure("multiple-blocks", `${path}: found ${String(scan.blocks.length)} \`\`\`${VALUES_INFO_STRING} fenced blocks; SPEC.md §5.3 allows at most one`, source);
+    }
+    const parsed = parseHardenedYaml(scan.blocks[0] ?? "", {
+        subject: "values YAML",
+        tagContext: "a values block",
+    });
+    if (!parsed.ok)
+        return failure("yaml-error", `${path}: ${parsed.message}`, source);
+    // `exactOptionalPropertyTypes` is on, so the key is omitted rather than
+    // passed as `undefined`: the validator's own default is not the same thing as
+    // an explicit `undefined` schema directory.
+    const validated = validate("values", parsed.value, options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir });
+    if (!validated.ok) {
+        return failure("schema-invalid", `${path}: the values block does not match values.schema.json`, source, validated.errors);
+    }
+    return { ok: true, present: true, values: parsed.value, source };
+}
+/**
+ * Find `APPROVAL.md`, and read its values block if it has one.
+ *
+ * Discovery plus {@link loadValuesText}. A file that cannot be read at all is
+ * `file-missing`, which is the only failure code here that says nothing about
+ * the block: there was no file to hold one.
+ */
+export function loadValues(options = {}) {
+    const resolved = resolveFile(options);
+    if ("ok" in resolved)
+        return resolved;
+    return loadValuesText(resolved.path, resolved.text, options.schemaDir === undefined ? {} : { schemaDir: options.schemaDir });
+}
+//# sourceMappingURL=values.js.map

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

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