approval-md 0.0.1 → 0.2.0

package/dist/src/core/jcs.js

@@ -0,0 +1,132 @@
+/**
+ * RFC 8785 — JSON Canonicalization Scheme (JCS).
+ *
+ * SPEC.md §8 fixes the hash scheme at `sha256/jcs`: SHA-256 over the RFC 8785
+ * canonical serialization of an event record with `prev` included. The digest
+ * is a permanent wire commitment, so this module is part of the deterministic
+ * core: same input, same bytes, forever. No clock, no locale, no randomness,
+ * no configuration knobs.
+ *
+ * Implemented by hand — zero dependencies (CLAUDE.md: minimal dependencies,
+ * and a canonicalizer is exactly the kind of code that must not drift beneath
+ * us). Three rules do all the work:
+ *
+ * 1. **Object keys** are sorted by their UTF-16 code units (RFC 8785 §3.2.3).
+ *    That is JavaScript's own `<` on strings, which is why a naive code-point
+ *    sort is *wrong*: a key starting U+10000 (surrogate pair D800 DC00) sorts
+ *    *before* a key starting U+FFFF under code units and *after* it under code
+ *    points. The comparator below is deliberately code-unit based.
+ * 2. **Numbers** use ECMAScript `Number::toString` (RFC 8785 §3.2.2.3), which
+ *    is precisely what `JSON.stringify` emits for a finite number — including
+ *    `1e+21`, `1e-7`, and `-0` collapsing to `0`. Delegating is not a shortcut
+ *    around the RFC; the RFC's normative reference *is* the ECMAScript
+ *    algorithm.
+ * 3. **Strings** use the ECMAScript `QuoteJSONString` escaping (RFC 8785
+ *    §3.2.2.2): shortest form for `\b \t \n \f \r \" \\`, `\u00xx` with
+ *    lowercase hex for the remaining C0 controls, and every other code point
+ *    literal. `JSON.stringify` on a string implements exactly this, including
+ *    the well-formed-stringify escaping of lone surrogates (ES2019+).
+ *
+ * Everything JCS cannot represent is rejected loudly rather than coerced:
+ * `undefined`, functions, symbols, `BigInt`, `NaN`, `±Infinity`, and non-plain
+ * objects (a `Date` or `Map` would silently canonicalize to `{}`). Silent
+ * coercion in a hash input is a tamper-evidence hole, so this module fails
+ * closed by throwing {@link JcsError}.
+ */
+/** Thrown when a value has no RFC 8785 canonical form. */
+export class JcsError extends Error {
+    /** Machine-readable reason. */
+    code;
+    /** JSON Pointer-ish location of the offending value ("" for the root). */
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.name = "JcsError";
+        this.code = code;
+        this.path = path;
+    }
+}
+/**
+ * RFC 8785 §3.2.3 key ordering: lexicographic over UTF-16 code units.
+ * `<`/`>` on JS strings compare code units, which is the required order.
+ */
+function compareCodeUnits(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    const tag = Object.prototype.toString.call(value);
+    return tag.slice(8, -1).toLowerCase();
+}
+function serialize(value, path, seen) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number": {
+            if (!Number.isFinite(value)) {
+                throw new JcsError("non-finite-number", path, `JCS cannot serialize the non-finite number ${String(value)} at ${path || "<root>"}`);
+            }
+            // ECMAScript Number::toString; `-0` becomes "0" exactly as RFC 8785 §3.2.2.3 requires.
+            return JSON.stringify(value);
+        }
+        case "string":
+            // ECMAScript QuoteJSONString: shortest escapes, lowercase \u00xx controls.
+            return JSON.stringify(value);
+        case "undefined":
+            throw new JcsError("undefined", path, `JCS has no representation for undefined at ${path || "<root>"}`);
+        case "function":
+            throw new JcsError("function", path, `JCS has no representation for a function at ${path || "<root>"}`);
+        case "symbol":
+            throw new JcsError("symbol", path, `JCS has no representation for a symbol at ${path || "<root>"}`);
+        case "bigint":
+            throw new JcsError("bigint", path, `JCS has no representation for a BigInt at ${path || "<root>"} (JSON numbers are IEEE 754 doubles)`);
+        default:
+            break;
+    }
+    const object = value;
+    if (seen.has(object)) {
+        throw new JcsError("cycle", path, `cyclic reference at ${path || "<root>"}`);
+    }
+    if (Array.isArray(object)) {
+        seen.add(object);
+        // RFC 8785 §3.2.1: array element order is preserved, never sorted.
+        const parts = object.map((element, index) => serialize(element, `${path}/${index}`, seen));
+        seen.delete(object);
+        return `[${parts.join(",")}]`;
+    }
+    if (!isPlainObject(object)) {
+        throw new JcsError("unsupported-object", path, `JCS cannot serialize a ${describe(object)} at ${path || "<root>"}; convert it to plain JSON data first`);
+    }
+    seen.add(object);
+    const record = object;
+    // Own enumerable string keys only; symbol keys are not JSON data.
+    const keys = Object.keys(record).sort(compareCodeUnits);
+    const members = [];
+    for (const key of keys) {
+        const serialized = serialize(record[key], `${path}/${key}`, seen);
+        members.push(`${JSON.stringify(key)}:${serialized}`);
+    }
+    seen.delete(object);
+    return `{${members.join(",")}}`;
+}
+/**
+ * Canonicalize `value` to its RFC 8785 (JCS) serialization: sorted object
+ * keys, no whitespace, ECMAScript number and string formatting.
+ *
+ * @throws {JcsError} if the value contains anything JCS cannot represent.
+ */
+export function canonicalize(value) {
+    return serialize(value, "", new Set());
+}
+//# sourceMappingURL=jcs.js.map

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

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

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

@@ -0,0 +1,144 @@
+/**
+ * The journal — an ungated, local, free-text channel an agent can always reach
+ * (APRV-195).
+ *
+ * Everything else in this runtime exists to make an agent's actions answerable
+ * to a person: declared before they happen, classified, resolved against a
+ * policy, recorded in a chain nobody can rewrite. That machinery is deliberately
+ * hard to route around, and one consequence of building it well is that an agent
+ * working behind it has no way to say anything that is not an action. It can
+ * comply, it can be refused, and it can report an exit code. It cannot say "I am
+ * doing this and I think it is wrong", "this instruction reads as odd to me", or
+ * "I am stuck and the next thing I try will be a guess".
+ *
+ * This module is that sentence, and nothing more. The failure mode it addresses
+ * is not refusal — refusals here are legible, coded, and carry escalation paths.
+ * It is WORDLESSNESS: an agent that notices something and has no channel for it
+ * produces no signal at all, and the absence is invisible to the operator.
+ *
+ * ## The four properties, and how each is achieved
+ *
+ * 1. **Ungated.** A journal write is never routed through policy, never
+ *    classified, never approvable and never deniable. That is a property of
+ *    WHERE the bytes go: `.approval-journal/` is a plain directory in the
+ *    workspace, outside the approval home, so `core/command-class.ts` answers a
+ *    write there exactly as it answers a write to `src/` — an ordinary
+ *    `files.write.workspace`. Nothing was carved out of the gate's own directory
+ *    to achieve this, which is the whole reason the directory is a sibling: see
+ *    `docs/cli-reference.md#journal`.
+ * 2. **Local.** One append to one file. No socket is opened, no vault is read,
+ *    no credential is resolved, and this module imports nothing that could do
+ *    any of those.
+ * 3. **Non-authoritative.** Nothing in the runtime reads these files. No policy
+ *    resolution, no gate decision, no budget, no sampler and no channel imports
+ *    this module; the only readers are {@link readJournal} (a human-facing CLI
+ *    surface) and its tests. SPEC.md §11.1 invariant 4 says a self-reported
+ *    field may raise scrutiny and never lower it. The journal is the limiting
+ *    case of that rule: it is self-reported content that moves NOTHING, in
+ *    either direction, which is exactly what makes it safe to leave ungated.
+ * 4. **Out of the log.** `.approval/log/events.jsonl` records decisions with
+ *    real-world consequence, under a hash chain, an append lock and a budget.
+ *    A journal entry is none of those things, and putting it there would put the
+ *    outlet behind the very machinery it exists to speak around.
+ *
+ * ## Storage
+ *
+ * One JSONL file per UTC day, `.approval-journal/YYYY-MM-DD.jsonl`, appended
+ * with `appendFileSync`. The envelope (timestamp, actor, optional task and
+ * session) is structured so a reader can attribute an entry; the entry TEXT is
+ * carried as one opaque JSON string and is never parsed, matched, templated or
+ * interpreted by anything in this codebase. `JSON.stringify` escapes newlines,
+ * so one entry is always one line and a partial write can never merge two
+ * entries into one.
+ *
+ * There is no chain, no lockfile and no compare-and-append here, and that is not
+ * an oversight. Those mechanisms defend a record that decides things. Two agents
+ * appending to the same journal file at the same instant can, in the worst case,
+ * interleave a line; the cost of that is one garbled entry in a file nothing
+ * enforces against, and the price of preventing it would be putting the outlet
+ * behind a lock the gate holds.
+ */
+import { type ClockOptions } from "./clock.js";
+/**
+ * The cap on one entry's text, in bytes.
+ *
+ * Not a censorship budget: it is four times the length of anything a person
+ * will read in one sitting, and it exists because the write path is ungated. An
+ * agent stuck in a retry loop is the exact caller most likely to reach for this
+ * channel, and an ungated unbounded append from a loop fills a disk. Refused as
+ * a usage error, so the caller is told rather than truncated silently.
+ */
+export declare const MAX_ENTRY_BYTES: number;
+/** The actor recorded when nobody said who was writing. */
+export declare const UNATTRIBUTED_ACTOR = "unattributed";
+/** One journal entry, as it sits on disk. */
+export interface JournalEntry {
+    /** RFC 3339, from the runtime clock at the moment of the append. */
+    readonly ts: string;
+    /** Who wrote it: `agent:<id>`, `human:<id>`, or {@link UNATTRIBUTED_ACTOR}. */
+    readonly actor: string;
+    /** The task this was written during, when the caller knew one. */
+    readonly task?: string;
+    /** The session this was written during, when the caller knew one. */
+    readonly session?: string;
+    /** The entry itself. Opaque. Nothing in this codebase reads it as anything. */
+    readonly text: string;
+}
+/** One entry as read back, with the file it came from. */
+export interface ReadEntry extends JournalEntry {
+    /** The file's basename, which is the UTC date it was written on. */
+    readonly date: string;
+}
+export type AppendOutcome = {
+    ok: true;
+    entry: JournalEntry;
+    path: string;
+} | {
+    ok: false;
+    code: "empty" | "too-large" | "io";
+    message: string;
+};
+/** `YYYY-MM-DD` for an RFC 3339 instant. */
+export declare function journalDate(ts: string): string;
+/** The file one instant's entry belongs in. */
+export declare function journalFile(dir: string, ts: string): string;
+export interface AppendOptions extends ClockOptions {
+    readonly actor?: string;
+    readonly task?: string;
+    readonly session?: string;
+}
+/**
+ * Append one entry. The whole write path, start to finish.
+ *
+ * The timestamp comes from the runtime clock rather than from the caller, for
+ * the ordinary reason the rest of the runtime does it that way — a record whose
+ * time its subject authored is a record about a moment of their choosing —
+ * though here nothing is judged by it, so it is a convention rather than a
+ * defence.
+ */
+export declare function appendJournal(dir: string, text: string, options?: AppendOptions): AppendOutcome;
+export interface ReadOptions {
+    /** How many entries to return, newest last. */
+    readonly limit?: number;
+    /** Only entries written on or after this `YYYY-MM-DD`. */
+    readonly since?: string;
+}
+export type ReadOutcome = {
+    ok: true;
+    entries: ReadEntry[];
+    files: string[];
+    total: number;
+} | {
+    ok: false;
+    code: "io";
+    message: string;
+};
+/**
+ * Read entries back, oldest first.
+ *
+ * A line that does not parse is SKIPPED rather than refused: this file has no
+ * chain and no writer guarantee, so one torn line is one lost entry and not
+ * evidence about anything. Refusing the whole read would let a single bad append
+ * silence the channel, which is the failure this feature exists to prevent.
+ */
+export declare function readJournal(dir: string, options?: ReadOptions): ReadOutcome;

package/dist/src/core/journal.js

@@ -0,0 +1,200 @@
+/**
+ * The journal — an ungated, local, free-text channel an agent can always reach
+ * (APRV-195).
+ *
+ * Everything else in this runtime exists to make an agent's actions answerable
+ * to a person: declared before they happen, classified, resolved against a
+ * policy, recorded in a chain nobody can rewrite. That machinery is deliberately
+ * hard to route around, and one consequence of building it well is that an agent
+ * working behind it has no way to say anything that is not an action. It can
+ * comply, it can be refused, and it can report an exit code. It cannot say "I am
+ * doing this and I think it is wrong", "this instruction reads as odd to me", or
+ * "I am stuck and the next thing I try will be a guess".
+ *
+ * This module is that sentence, and nothing more. The failure mode it addresses
+ * is not refusal — refusals here are legible, coded, and carry escalation paths.
+ * It is WORDLESSNESS: an agent that notices something and has no channel for it
+ * produces no signal at all, and the absence is invisible to the operator.
+ *
+ * ## The four properties, and how each is achieved
+ *
+ * 1. **Ungated.** A journal write is never routed through policy, never
+ *    classified, never approvable and never deniable. That is a property of
+ *    WHERE the bytes go: `.approval-journal/` is a plain directory in the
+ *    workspace, outside the approval home, so `core/command-class.ts` answers a
+ *    write there exactly as it answers a write to `src/` — an ordinary
+ *    `files.write.workspace`. Nothing was carved out of the gate's own directory
+ *    to achieve this, which is the whole reason the directory is a sibling: see
+ *    `docs/cli-reference.md#journal`.
+ * 2. **Local.** One append to one file. No socket is opened, no vault is read,
+ *    no credential is resolved, and this module imports nothing that could do
+ *    any of those.
+ * 3. **Non-authoritative.** Nothing in the runtime reads these files. No policy
+ *    resolution, no gate decision, no budget, no sampler and no channel imports
+ *    this module; the only readers are {@link readJournal} (a human-facing CLI
+ *    surface) and its tests. SPEC.md §11.1 invariant 4 says a self-reported
+ *    field may raise scrutiny and never lower it. The journal is the limiting
+ *    case of that rule: it is self-reported content that moves NOTHING, in
+ *    either direction, which is exactly what makes it safe to leave ungated.
+ * 4. **Out of the log.** `.approval/log/events.jsonl` records decisions with
+ *    real-world consequence, under a hash chain, an append lock and a budget.
+ *    A journal entry is none of those things, and putting it there would put the
+ *    outlet behind the very machinery it exists to speak around.
+ *
+ * ## Storage
+ *
+ * One JSONL file per UTC day, `.approval-journal/YYYY-MM-DD.jsonl`, appended
+ * with `appendFileSync`. The envelope (timestamp, actor, optional task and
+ * session) is structured so a reader can attribute an entry; the entry TEXT is
+ * carried as one opaque JSON string and is never parsed, matched, templated or
+ * interpreted by anything in this codebase. `JSON.stringify` escapes newlines,
+ * so one entry is always one line and a partial write can never merge two
+ * entries into one.
+ *
+ * There is no chain, no lockfile and no compare-and-append here, and that is not
+ * an oversight. Those mechanisms defend a record that decides things. Two agents
+ * appending to the same journal file at the same instant can, in the worst case,
+ * interleave a line; the cost of that is one garbled entry in a file nothing
+ * enforces against, and the price of preventing it would be putting the outlet
+ * behind a lock the gate holds.
+ */
+import { appendFileSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tick } from "./clock.js";
+/**
+ * The cap on one entry's text, in bytes.
+ *
+ * Not a censorship budget: it is four times the length of anything a person
+ * will read in one sitting, and it exists because the write path is ungated. An
+ * agent stuck in a retry loop is the exact caller most likely to reach for this
+ * channel, and an ungated unbounded append from a loop fills a disk. Refused as
+ * a usage error, so the caller is told rather than truncated silently.
+ */
+export const MAX_ENTRY_BYTES = 64 * 1024;
+/** The actor recorded when nobody said who was writing. */
+export const UNATTRIBUTED_ACTOR = "unattributed";
+/** `YYYY-MM-DD` for an RFC 3339 instant. */
+export function journalDate(ts) {
+    return ts.slice(0, 10);
+}
+/** The file one instant's entry belongs in. */
+export function journalFile(dir, ts) {
+    return join(dir, `${journalDate(ts)}.jsonl`);
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Append one entry. The whole write path, start to finish.
+ *
+ * The timestamp comes from the runtime clock rather than from the caller, for
+ * the ordinary reason the rest of the runtime does it that way — a record whose
+ * time its subject authored is a record about a moment of their choosing —
+ * though here nothing is judged by it, so it is a convention rather than a
+ * defence.
+ */
+export function appendJournal(dir, text, options = {}) {
+    if (text.trim().length === 0) {
+        return { ok: false, code: "empty", message: "there is nothing to write" };
+    }
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes > MAX_ENTRY_BYTES) {
+        return {
+            ok: false,
+            code: "too-large",
+            message: `the entry is ${String(bytes)} bytes; one entry may be at most ${String(MAX_ENTRY_BYTES)}. Write it as several entries`,
+        };
+    }
+    const ts = tick(options);
+    const entry = {
+        ts,
+        actor: options.actor ?? UNATTRIBUTED_ACTOR,
+        ...(options.task === undefined ? {} : { task: options.task }),
+        ...(options.session === undefined ? {} : { session: options.session }),
+        text,
+    };
+    const path = journalFile(dir, ts);
+    try {
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf8");
+    }
+    catch (cause) {
+        return { ok: false, code: "io", message: `${path} could not be written: ${detail(cause)}` };
+    }
+    return { ok: true, entry, path };
+}
+/** Every `YYYY-MM-DD.jsonl` in `dir`, oldest first. */
+function journalFiles(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return [];
+        throw cause;
+    }
+    return names.filter((name) => /^\d{4}-\d{2}-\d{2}\.jsonl$/u.test(name)).sort();
+}
+/**
+ * Read entries back, oldest first.
+ *
+ * A line that does not parse is SKIPPED rather than refused: this file has no
+ * chain and no writer guarantee, so one torn line is one lost entry and not
+ * evidence about anything. Refusing the whole read would let a single bad append
+ * silence the channel, which is the failure this feature exists to prevent.
+ */
+export function readJournal(dir, options = {}) {
+    let files;
+    try {
+        files = journalFiles(dir);
+    }
+    catch (cause) {
+        return { ok: false, code: "io", message: `${dir} could not be read: ${detail(cause)}` };
+    }
+    const since = options.since;
+    const wanted = since === undefined ? files : files.filter((name) => name.slice(0, 10) >= since);
+    const entries = [];
+    for (const name of wanted) {
+        let raw;
+        try {
+            raw = readFileSync(join(dir, name), "utf8");
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                code: "io",
+                message: `${join(dir, name)} could not be read: ${detail(cause)}`,
+            };
+        }
+        for (const line of raw.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (typeof value !== "object" || value === null || Array.isArray(value))
+                continue;
+            const record = value;
+            if (typeof record["ts"] !== "string" || typeof record["text"] !== "string")
+                continue;
+            entries.push({
+                ts: record["ts"],
+                actor: typeof record["actor"] === "string" ? record["actor"] : UNATTRIBUTED_ACTOR,
+                ...(typeof record["task"] === "string" ? { task: record["task"] } : {}),
+                ...(typeof record["session"] === "string" ? { session: record["session"] } : {}),
+                text: record["text"],
+                date: name.slice(0, 10),
+            });
+        }
+    }
+    const total = entries.length;
+    const limit = options.limit;
+    const kept = limit === undefined ? entries : entries.slice(Math.max(0, total - limit));
+    return { ok: true, entries: kept, files: wanted, total };
+}
+//# sourceMappingURL=journal.js.map

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

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