approval-md 0.0.1 → 0.1.0

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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"}