@dreamforgestudiollc/emet 0.2.4 → 0.2.6

package/src/session-graph.js

@@ -1,10 +1,11 @@
 /**
- * EMET - the session graph: the monorail under the guardrails (2026-09-29;
- * the practice is docs/GUARDRAILS-AND-MONORAILS.md).
+ * EMET - the session graph: the monorail under the guardrails (2026-09-29,
+ * board board 120, design staging/emet-session-graph.md; the practice is
+ * docs/GUARDRAILS-AND-MONORAILS.md).
  *
- * The owner: "guardrails give a field of movement and execution to allow an AI to do
+ * Alex: "guardrails give a field of movement and execution to allow an AI to do
  * processes where rails guide the AI through a process flow without it
- * processing" (a recorded lesson). The floor, the character and the served
+ * processing" (semantic ref 297). The floor, the character and the served
  * instructions are the guardrails. This file is the monorail - the car cannot
  * leave the beam; where a flow forks, a small switch owned by the track (never
  * the model) picks the branch (designed 2026-09-29, not yet built): the next step of a
@@ -68,18 +69,19 @@ export const HANDOFF_DOC = 'HANDOFF.md';
 export const BOARD_DOC = 'STATE.md';
 
 /**
- * Per-bot close records (C1, 2026-10-01; the owner's decisions 1-7). The rule, stated once: a session written
+ * Per-bot close records (C1, 2026-10-01; review note "C1: per-bot close
+ * records", the owner's decisions 1-7). The rule, stated once: a session written
  * under a bot's source tag closes against that bot's own records
  * (bots/<tag>/HANDOFF.md); only that tag's own revisions in the session window
  * count; a bot tag never writes or cites the main HANDOFF.md or STATE.md.
  *
  * A tag T is a BOT TAG when bots/T/HANDOFF.md is listed in EMET_RECORD_DOCS,
  * the list that already marks ids as supersede-only records (tools.js
- * recordDocIds). No new setting: the owner adds one id per bot, and removing it
+ * recordDocIds). No new setting: Alex adds one id per bot, and removing it
  * puts that tag back on the host rules. Bot records are named by the source
  * tag itself (decision 1), so no tag-to-name mapping exists. These are pure
  * reads of settings - no database - so the graph can key its bot-handoff gate
- * on a write's `source` without an extra read.
+ * on a write's `source` without an extra read (review note section 5).
  */
 export function botRecordDir(tag) { return `bots/${tag}/`; }
 export function botHandoffDoc(tag) { return `bots/${tag}/HANDOFF.md`; }
@@ -101,7 +103,7 @@ export function mainRecordIds() {
  * The source tag a write names, read as dispatch.js sourceOf reads it
  * (`source`, then the older aliases). Repeated here because dispatch imports
  * this module. No default: a write with no source takes the host path in the
- * graph.
+ * graph (review note section 5).
  */
 export function writeSourceOf(args = {}) {
   const v = args.source ?? args.updated_by ?? args.retired_by ?? args.accepted_by ?? args.channel ?? null;
@@ -136,7 +138,7 @@ export function echoId(id) {
  * Every session base an id could belong to, the way the close check groups a
  * session's documents (session.js inspectSession: ^base(_.*)?$). An id like
  * `<base>_extra` is counted by the close as part of `<base>`, so the closed-
- * session guard must treat it as `<base>` too (2026-10-01, the reviewer's gate
+ * session guard must treat it as `<base>` too (2026-10-01, the tester's gate
  * (a)). Longest first: the id itself, then each prefix ending before a `_`.
  */
 export function candidateBases(sessionId) {
@@ -163,13 +165,13 @@ export function groupedUnder(sessionId, base) {
 /**
  * The session a call names: `session_id`, else the transcript span in
  * `metadata.derived_from` (revise_memory refuses metadata.session_id and names
- * its session there - live-caught 2026-09-29, a recorded lesson), else - for
+ * its session there - live-caught 2026-09-29, semantic ref 295), else - for
  * emet_session_close, the only tool that takes `receipts` -
  * `receipts.transcript_session_id`. The close tool's description documents
  * that shape ("receipts.transcript_session_id is used when this is omitted")
  * and sessionClose checks that session; until 2026-10-01 the graph read only
  * `session_id`, so a close naming its session only in the receipts was never
- * recorded and the session stayed open (the second reader's nit 3 on an earlier draft, the reviewer's
+ * recorded and the session stayed open (the reviewer's nit 3 on commit-df21117, the tester's
  * condition 1). Receipts sent as JSON text are read as sessionClose reads
  * them (session.js parseReceipts).
  */
@@ -193,8 +195,8 @@ function receiptsOf(value) {
 }
 
 /**
- * An exchange number as sent, normalized ONCE (2026-10-01, the second reader's re-check of
- * an earlier draft). Hosts send numbers as numbers or as text ("4"). The guard read "4"
+ * An exchange number as sent, normalized ONCE (2026-10-01, the reviewer's re-check of
+ * commit-2a361fd). Hosts send numbers as numbers or as text ("4"). The guard read "4"
  * as 4 while emet_transcript_append only took real numbers, so a text "4" was a
  * "retry" to the guard and "the next exchange" to the tool. dispatch now runs
  * every exchange_index through this before the graph, the guard and the tool,
@@ -351,8 +353,8 @@ export async function isSessionClosed(base, dbManager) {
  * once the window passes, the session is locked. A retry of that same
  * exchange number is answered as already saved, never as a second write:
  * the guard answers it itself and the tool is not called, at any time after
- * the close, so a retry can write nothing anywhere (2026-10-01, the second reader's blocker
- * and the reviewer's gate on an earlier draft). The closing exchange itself is written
+ * the close, so a retry can write nothing anywhere (2026-10-01, the reviewer's blocker
+ * and the tester's gate on commit-2a361fd). The closing exchange itself is written
  * into the session's last live part, whatever part or base id the caller sent.
  *
  * graceDecision is pure: state is the session row, declared the exchange the
@@ -368,7 +370,7 @@ export const DEFAULT_CLOSE_GRACE_MINUTES = 5;
 export const MAX_CLOSE_GRACE_MINUTES = 60;
 
 /**
- * The window setting, checked (2026-10-01, the second reader's nit 4). Unset or blank: the
+ * The window setting, checked (2026-10-01, the reviewer's nit 4). Unset or blank: the
  * default, 5. A number from 0 to 60: that many minutes (0 turns the window
  * off). Anything else is NOT silently accepted: a negative or non-numeric value
  * falls back to the default 5, and a value over 60 is capped at 60; both come
@@ -390,7 +392,7 @@ function closeGraceName() {
 export function closeGraceSetting(raw = setting('CLOSE_GRACE_MINUTES'), name = closeGraceName()) {
   if (raw === undefined || raw === null || String(raw).trim() === '') return { minutes: DEFAULT_CLOSE_GRACE_MINUTES, note: null };
   // Decimal only: Number() also reads hex, octal and binary ("0x10" is 16),
-  // which no one means for minutes (the second reader's nit 5 on an earlier draft).
+  // which no one means for minutes (the reviewer's nit 5 on commit-df21117).
   const text = String(raw).trim();
   const n = /^[+-]?(\d+(\.\d*)?|\.\d+)(e[+-]?\d+)?$/i.test(text) ? Number(text) : NaN;
   if (!Number.isFinite(n) || n < 0) {
@@ -517,7 +519,7 @@ export async function closedSessionGuard(tool, args = {}, dbManager, now = new D
     } catch (e) { throw await unreadable(tool, base, 'the transcript part to be revised', e); }
     if (!part) return null; // the tool itself refuses a revision of a part that does not exist
     // A correction of a closed session keeps EXACTLY the exchange numbers the
-    // part holds (2026-10-01, the second reader's nit 2): none added, none dropped, none
+    // part holds (2026-10-01, the reviewer's nit 2): none added, none dropped, none
     // duplicated. Numbers sent as text are stored as numbers; the corrected
     // part is stored in exchange order.
     const held = [...new Set((part.exchanges || []).map((e) => Number(e && e.exchange_index)))].sort((a, b) => a - b);
@@ -563,8 +565,8 @@ export async function closedSessionGuard(tool, args = {}, dbManager, now = new D
   const d = graceDecision(row, declared, highest, now, minutes);
 
   if (d === 'retry') {
-    // Answered HERE, and the tool is never called (2026-10-01, the second reader's blocker on
-    // an earlier draft): a retry handed to the tool with the caller's arguments could
+    // Answered HERE, and the tool is never called (2026-10-01, the reviewer's blocker on
+    // commit-2a361fd): a retry handed to the tool with the caller's arguments could
     // land in another part id, the base id, or - with the number sent as text -
     // as a new exchange, while the reply said nothing was written.
     return { retry: true, base, index: row.grace_index,
@@ -572,7 +574,7 @@ export async function closedSessionGuard(tool, args = {}, dbManager, now = new D
   }
   if (d === 'grace') {
     const index = highest + 1;
-    // Pinned to the session's last live part (2026-10-01, the second reader's nit 3), never
+    // Pinned to the session's last live part (2026-10-01, the reviewer's nit 3), never
     // the part or base id the caller named. If that part is full, the append
     // rolls to the next part number exactly as a live append does.
     let part = typeof pos.last_part === 'string' && pos.last_part ? pos.last_part : null;
@@ -767,7 +769,7 @@ export async function graphBefore(tool, args, dbManager, now = new Date()) {
 }
 
 // ---------------------------------------------------------------------------
-// Lab results (2026-09-29, the owner: "a 'lab results' location for storing the
+// Lab results (2026-09-29, Alex: "a 'lab results' location for storing the
 // results in real time with time stamps so we can have a resource to look at
 // after the probationary period"). Every check the monorail makes - ok,
 // refuse, unknown (would_refuse in rows from before enforce-only) - is one timestamped row in
@@ -901,7 +903,7 @@ export function graphBlock(g) {
 /**
  * After a successful call: record the step. Never throws - a failed record is
  * logged, not fatal. Returns what happened, so the close can say so
- * (2026-10-01, the second reader's nit 2 on an earlier draft, the reviewer's condition 2):
+ * (2026-10-01, the reviewer's nit 2 on commit-df21117, the tester's condition 2):
  *   null                          nothing to record (no session, or no step)
  *   {recorded: true, base}        the step was written
  *   {recorded: false, base, error} the write failed (logged as a warning)

package/src/session.js

@@ -322,7 +322,7 @@ export async function corroborateCoverage(db, baseId) {
       // correction makes the check permanently worse, and the flag can never
       // clear because superseded entries cannot be edited. Found live at the
       // 2026-09-11 close: nine entries superseded with correct spans, and the
-      // check still read the old record's 31-33 against a 27-exchange session.
+      // check still read the old ref 314's 31-33 against a 27-exchange session.
       // Every other read in EMET hides superseded entries by default; this one
       // now does too - and says how many it set aside, because dropping
       // evidence silently is the other half of the same mistake.
@@ -354,7 +354,7 @@ export async function corroborateCoverage(db, baseId) {
  * The store check above answers "do the artifacts exist". It could not answer
  * "did the host actually do each step", and a host that skipped a step, or
  * never read the transcript back, could still walk away with `complete`
- * because the store happened to look fine. The owner's requirement (a decision record,
+ * because the store happened to look fine. the owner's requirement (procedural ref 388,
  * 389, 391): the wrap steps HAVE TO BE FOLLOWED, whichever model is hosting,
  * and a skipped step blocks the close the same way a skipped opening is caught
  * at initialize.
@@ -387,7 +387,7 @@ export const RECEIPT_FIELDS = Object.freeze({
 });
 
 /**
- * A bot session's receipts (C1, 2026-10-01).
+ * A bot session's receipts (C1, 2026-10-01; review note section 3.3).
  * Seven: no board is required - a bot that keeps one lists it under
  * bots/<tag>/ as board_doc (checked when given) or as a working document - and
  * handoff_doc names the bot's own handoff. Host receipts stay at the eight
@@ -403,7 +403,7 @@ export const BOT_RECEIPT_FIELDS = Object.freeze({
   handoff_version: RECEIPT_FIELDS.handoff_version
 });
 
-/** The message every bot-records refusal carries. */
+/** The message every bot-records refusal carries (review note section 3.5). */
 export function hubRecordsMessage(tag) {
   return `a bot session closes against ${botRecordDir(tag)} records; the main handoff and board are the hub's`;
 }
@@ -429,7 +429,7 @@ export function sessionTagOf(rows = []) {
  * Hosts do not all pass an object argument the same way. A client working from
  * a cached tool list that predates `receipts` - or a host that serialises every
  * nested argument - sends the receipts as JSON TEXT. Found live at the first
- * close under the new rule (2026-09-26, cloud-host): every artifact present,
+ * close under the new rule (2026-09-26, cowork-cloud): every artifact present,
  * receipts sent, and the server saw none. Consistent execution across hosts
  * means accepting both forms. Text that does not parse is treated as absent,
  * so it still blocks - it is never guessed at.
@@ -485,7 +485,7 @@ export function checkReceipts(receipts, observed) {
 
   const docs = new Map((observed.documents || []).map((d) => [d.doc_id, d]));
 
-  // A bot session never names the main records: any
+  // A bot session never names the main records (review note section 3.5): any
   // receipt that does is refused here, and those ids get no other check.
   const mainIds = bot ? (bot.main_records || []) : [];
   const isMain = (id) => mainIds.includes(id);
@@ -852,7 +852,7 @@ export async function sessionClose(options = {}) {
       if (row && ms !== null && ms >= startMs) {
         receiptEpisodicSource = parseMetadata(row.metadata).source || null;
         if (bot) {
-          // A bot's session record is its own and cites this session.
+          // A bot's session record is its own and cites this session (review note 3.2).
           const cited = typeof row.source_session_id === 'string' && row.source_session_id ? row.source_session_id : null;
           if (receiptEpisodicSource !== bot.tag) {
             episodicRejected = `its metadata.source is ${receiptEpisodicSource || '(none)'}, not ${bot.tag}`;
@@ -968,8 +968,8 @@ export async function sessionClose(options = {}) {
     }
 
     // Store-level gaps make the session incomplete. Receipt problems, and a
-    // transcript nothing independently corroborates, BLOCK it (the owner 2026-09-26,
-    // A decision record: receipts required from the first deploy; the former
+    // transcript nothing independently corroborates, BLOCK it (Alex 2026-09-26,
+    // procedural ref 391: receipts required from the first deploy; the former
     // `unconfirmed` state is blocked, not passed).
     const storeMissing = [...missing];
     const receiptCheck = checkReceipts(receipts, {