src/conventions-read.ts

Functions

Imports

It imports src/log.ts, src/store-probe.ts. Imported by src/tools/docs-read.ts.

Source

1// Whether sessions read the portfolio rules. Every repo's CLAUDE.md says to read
2// capsid/conventions.md first; audit_log recorded writes only, so there was no evidence
3// either way. A read of that document, through `capsid_read_doc` or `capsid_start_session`, now leaves one
4// `conventions-read` row, at most one per caller per hour so it cannot become noise.
5//
6// The row is NOT addressed to capsid/conventions.md. `lastActor` and the Portal read the
7// newest audit row for a document's path as its last writer, so a reader's row there
8// would make every reader the document's last_actor. It sits in the capsid namespace
9// with no path, and params say how the document was reached.
10
11import { HEALTH_PROBE_NS, HEALTH_PROBE_PATH } from "./store-probe";
12import { logEvent } from "./log";
13
14const CONVENTIONS_READ_ACTION = "conventions-read";
15const WINDOW = "-1 hour";
16
17/** Whether a read of this document is a read of the portfolio rules. */
18export function isConventionsDoc(namespace: string, path: string): boolean {
19  return namespace === HEALTH_PROBE_NS && path === HEALTH_PROBE_PATH;
20}
21
22/** Record that `actor` read the rules, unless it already did inside the last hour. One
23 *  statement, so the check and the insert cannot be separated by another request's row
24 *  for the same caller. A failure is reported and never fails the read: this is a
25 *  measurement, and the caller asked for a document. */
26export async function recordConventionsRead(
27  db: D1Database,
28  actor: string,
29  via: "read" | "brief",
30  forNamespace: string
31): Promise<void> {
32  try {
33    await db
34      .prepare(
35        `INSERT INTO audit_log (actor, action, namespace, path, params)
36         SELECT ?1, ?2, ?3, NULL, ?4
37         WHERE NOT EXISTS (
38           SELECT 1 FROM audit_log WHERE action = ?2 AND actor = ?1 AND at >= datetime('now', ?5)
39         )`
40      )
41      .bind(actor, CONVENTIONS_READ_ACTION, HEALTH_PROBE_NS, JSON.stringify({ via, for_namespace: forNamespace }), WINDOW)
42      .run();
43  } catch (err) {
44    logEvent("error", "CONVENTIONS_READ", { message: `CONVENTIONS_READ could not record the read by ${actor}: ${err instanceof Error ? err.message : String(err)}` });
45  }
46}