agentfootprint-lens 0.48.0 → 0.49.0

package/README.md

@@ -1059,6 +1059,50 @@ on every epoch, no receipt was minted, and the tab says so with the library's
 `no-receipt-on-chart` gap and `cause: 'no-receipt-committed'` — every row
 **Reconstructed**, never a fabricated **Verified**.
 
+### The Served graph (0.49.0)
+
+A list is right for checking one row and wrong for seeing that the system string
+was assembled from a base plus one skill body plus two injections while three
+tools were withheld. That is one picture, and since 0.49.0 the Served tab has a
+**List ⇄ Graph** toggle (the list stays the default) that draws it: **HELD** —
+what the record holds at this stop, from the fold — then **SERVED** — what
+crossed into the call, one edge per system piece, message, request-only line and
+tool, each carrying its badge and, against the previous epoch, whether it
+*entered*, *left* or is *unchanged* — then **WITHHELD**: held and not sent. The
+withheld band is the reason to build it. The model never learns what it was
+denied; the operator should — the withheld tool list, the attention drops, the
+skills a role hid (read from the fold, since a receipt carries no authority
+names), a redacted fold, and every gap the view declares, each with the
+library's own sentence. Same cursor, same row, same badges: a Damaged row draws
+Damaged here too, and a field a gap covers draws the gap rather than an empty
+node.
+
+| graph | what it draws | the question it answers |
+|---|---|---|
+| **skill graph** (`<SkillGraph>`) | the skills, their steps and their edges | where a run MAY go, and where it went |
+| **data graph** (*Where from*) | a value's writers, back through the commit log | where THIS value came from |
+| **Served graph** (Served tab · Graph) | one call: held · served · withheld | what this ONE CALL was made of, and what we held back |
+
+```ts
+import { foldFactsAt, servedGraphAt, servedRowAt, verify } from 'agentfootprint-lens/core';
+
+const cursor = { runtimeStageId: 'call-llm#18', commitIdx: 15 };
+const row = servedRowAt(snapshot, cursor)!;
+const graph = servedGraphAt({
+  row,
+  fold: foldFactsAt(snapshot, cursor),
+  checks: verify(row.view, row.receipt, row.receipt?.basis.runId ?? '', row.receiptCause),
+});
+graph.served.map((s) => `${s.slot} ${s.rebuilt}`);                 // ['system-prompt 3', …]
+graph.edges.filter((e) => e.state === 'entered').map((e) => e.origin);  // ['instructions']
+graph.withheld.filter((w) => w.from === 'fold').map((w) => w.name);     // ['payroll']
+```
+
+`<ServedGraph graph>` is exported for shells that build the input themselves.
+**Deliberately absent:** an edge from a served piece back to the STAGE that
+wrote it. It needs a commit-log walk keyed by piece text or slot — the part most
+likely to rot — and the question above is answered without it.
+
 ---
 
 ## Bookmarks, and scrubbing by declared tag

package/dist/{chunk-FZHRQNRS.js → chunk-AIZIILHJ.js}

@@ -3296,16 +3296,16 @@ function diffPromptsBounded(a, b, maxCells = DIFF_CELL_CAP) {
 }
 
 // src/core/served/sincePrevious.ts
-function unmatched(a, b) {
+function unmatchedIndexes(a, b) {
   const pool = /* @__PURE__ */ new Map();
   for (const item of b) pool.set(item, (pool.get(item) ?? 0) + 1);
-  let count = 0;
-  for (const item of a) {
+  const out = [];
+  for (const [i, item] of a.entries()) {
     const n = pool.get(item) ?? 0;
     if (n > 0) pool.set(item, n - 1);
-    else count += 1;
+    else out.push(i);
   }
-  return count;
+  return out;
 }
 function sincePrevious(current, previous) {
   const now = current.view;
@@ -3328,6 +3328,10 @@ function sincePrevious(current, previous) {
       if (a !== void 0 && b !== void 0 && a !== b) schemaChanged.push(name);
     }
   }
+  const piecesEntered = unmatchedIndexes(nowPieces, beforePieces);
+  const piecesLeft = unmatchedIndexes(beforePieces, nowPieces);
+  const messagesEntered = unmatchedIndexes(nowMessages, beforeMessages);
+  const messagesLeft = unmatchedIndexes(beforeMessages, nowMessages);
   const changed = now.system.text !== before.system.text;
   const diff = changed ? diffPromptsBounded(before.system.text, now.system.text) : Object.freeze([]);
   return Object.freeze({
@@ -3336,12 +3340,16 @@ function sincePrevious(current, previous) {
     system: Object.freeze({
       changed,
       ...diff !== void 0 ? { diff: Object.freeze([...diff]) } : {},
-      piecesEntered: unmatched(nowPieces, beforePieces),
-      piecesLeft: unmatched(beforePieces, nowPieces)
+      piecesEntered: piecesEntered.length,
+      piecesLeft: piecesLeft.length,
+      enteredIndexes: Object.freeze(piecesEntered),
+      leftPieces: Object.freeze(piecesLeft.map((i) => before.system.pieces[i]))
     }),
     messages: Object.freeze({
-      entered: unmatched(nowMessages, beforeMessages),
-      left: unmatched(beforeMessages, nowMessages)
+      entered: messagesEntered.length,
+      left: messagesLeft.length,
+      enteredIndexes: Object.freeze(messagesEntered),
+      leftEntries: Object.freeze(messagesLeft.map((i) => before.messages.asSent[i]))
     }),
     tools: Object.freeze({
       added: Object.freeze(added),
@@ -3404,6 +3412,295 @@ function foldFactsAt(recording, cursor) {
   });
 }
 
+// src/core/served/servedGraphAt.ts
+import {
+  SERVED_GAPS as SERVED_GAPS2,
+  UNGAPPED_FIELDS
+} from "agentfootprint";
+var SLOT_ORDER = Object.freeze({
+  "system-prompt": 0,
+  messages: 1,
+  tools: 2
+});
+var SERVED_SLOTS = Object.freeze(
+  Object.keys(SLOT_ORDER).sort((a, b) => SLOT_ORDER[a] - SLOT_ORDER[b])
+);
+var HELD_HONESTY_KEYS = Object.freeze([
+  "basis",
+  "redacted",
+  "skipped",
+  "foldError"
+]);
+var HELD_KEYS = Object.freeze([
+  ...FOLD_FACT_KEYS,
+  ...HELD_HONESTY_KEYS
+]);
+var RECONSTRUCTED = Object.freeze({ status: "reconstructed" });
+var NOT_ON_RECORD = Object.freeze({ status: "not-on-record" });
+function slotsOfFields(fields) {
+  const out = [];
+  for (const field of fields) {
+    const slot = field.startsWith("system.") ? "system-prompt" : field.startsWith("messages.") ? "messages" : field.startsWith("tools.") ? "tools" : void 0;
+    if (slot !== void 0 && !out.includes(slot)) out.push(slot);
+  }
+  return out;
+}
+function heldNodes(fold) {
+  const node = (key, value, status) => Object.freeze(value === void 0 ? { key, status } : { key, value, status });
+  const out = [];
+  for (const key of FOLD_FACT_KEYS) {
+    const value = fold[key];
+    out.push(value === void 0 ? node(key, void 0, "not-on-record") : node(key, value, "reconstructed"));
+  }
+  out.push(
+    fold.basis === void 0 ? node("basis", void 0, "not-on-record") : node("basis", fold.basis, "reconstructed")
+  );
+  out.push(node("redacted", fold.redacted, "reconstructed"));
+  if (fold.skipped !== void 0) out.push(node("skipped", fold.skipped, "damaged"));
+  if (fold.foldError !== void 0) out.push(node("foldError", fold.foldError, "damaged"));
+  return Object.freeze(out);
+}
+function servedEdges(input) {
+  const { row, checks, since } = input;
+  const view = row.view;
+  const edge = (e) => Object.freeze(e);
+  const out = [];
+  const compared = since !== void 0;
+  const enteredPieces = new Set(since?.system.enteredIndexes ?? []);
+  const enteredMessages = new Set(since?.messages.enteredIndexes ?? []);
+  const stateOf = (entered) => compared ? entered ? "entered" : "unchanged" : void 0;
+  const withState = (state) => state !== void 0 ? { state } : {};
+  view.system.pieces.forEach((piece, i) => {
+    out.push(
+      edge({
+        id: `piece:${i}`,
+        kind: "piece",
+        slot: piece.slot,
+        source: piece.source,
+        origin: piece.source,
+        text: piece.text,
+        check: checks.pieces[i] ?? RECONSTRUCTED,
+        ...withState(stateOf(enteredPieces.has(i)))
+      })
+    );
+  });
+  (since?.system.leftPieces ?? []).forEach((piece, i) => {
+    out.push(
+      edge({
+        id: `piece-left:${i}`,
+        kind: "piece",
+        slot: piece.slot,
+        source: piece.source,
+        origin: piece.source,
+        text: piece.text,
+        // Not on this request at all: there is no row here for a hash to check.
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  view.messages.asSent.forEach((message, i) => {
+    const label = message.toolName ?? message.toolCallId;
+    out.push(
+      edge({
+        id: `message:${i}`,
+        kind: "message",
+        slot: "messages",
+        role: message.role,
+        origin: message.role,
+        ...label !== void 0 ? { label } : {},
+        text: message.content,
+        check: checks.messages[i] ?? RECONSTRUCTED,
+        ...withState(stateOf(enteredMessages.has(i)))
+      })
+    );
+  });
+  (since?.messages.leftEntries ?? []).forEach((message, i) => {
+    out.push(
+      edge({
+        id: `message-left:${i}`,
+        kind: "message",
+        slot: "messages",
+        role: message.role,
+        origin: message.role,
+        text: message.content,
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  view.messages.requestOnly.forEach((line, i) => {
+    out.push(
+      edge({
+        id: `request-only:${i}`,
+        kind: "request-only",
+        slot: "messages",
+        role: line.role,
+        origin: line.role,
+        label: line.reason,
+        text: line.text,
+        check: checks.requestOnly[i] ?? RECONSTRUCTED
+      })
+    );
+  });
+  view.tools.names.forEach((name) => {
+    const schema = view.tools.schemas.find((s) => s.name === name);
+    const state = compared ? since !== void 0 && since.tools.added.includes(name) ? "entered" : "unchanged" : void 0;
+    out.push(
+      edge({
+        id: `tool:${name}`,
+        kind: "tool",
+        slot: "tools",
+        label: name,
+        // No rebuilt schema means no hash on this side; a NAME is never
+        // verified — the receipt carries names as plain strings.
+        check: schema !== void 0 ? checks.toolSchemas[name] ?? RECONSTRUCTED : RECONSTRUCTED,
+        ...view.tools.forced === name ? { forced: true } : {},
+        ...checks.onReceiptOnly.schemas.includes(name) ? { schemaOnReceiptOnly: true } : {},
+        ...since !== void 0 && since.tools.schemaChanged.includes(name) ? { schemaChanged: true } : {},
+        ...withState(state)
+      })
+    );
+  });
+  (since?.tools.removed ?? []).forEach((name) => {
+    out.push(
+      edge({
+        id: `tool-left:${name}`,
+        kind: "tool",
+        slot: "tools",
+        label: name,
+        check: NOT_ON_RECORD,
+        state: "left"
+      })
+    );
+  });
+  return Object.freeze(out);
+}
+function slotNodes(input, edges) {
+  const { row, checks } = input;
+  const view = row.view;
+  const receipt = row.receipt;
+  const gapsFor = (slot) => Object.freeze(view.gaps.filter((g) => slotsOfFields(g.fields).includes(slot)));
+  const rebuiltIn = (slot) => edges.filter((e) => e.slot === slot && e.state !== "left").length;
+  const onReceipt = {
+    "system-prompt": receipt?.system.pieces.length,
+    messages: receipt !== void 0 ? receipt.messages.entries.length + receipt.messages.requestOnly.length : void 0,
+    tools: checks.namesOnReceipt?.length
+  };
+  const check2 = {
+    "system-prompt": checks.system,
+    messages: void 0,
+    tools: checks.toolNames
+  };
+  const onReceiptOnly = {
+    "system-prompt": checks.onReceiptOnly.pieces,
+    messages: checks.onReceiptOnly.messages + checks.onReceiptOnly.requestOnly,
+    tools: checks.onReceiptOnly.toolNames.length
+  };
+  const rebuiltOnly = {
+    "system-prompt": checks.rebuiltOnly.pieces,
+    messages: checks.rebuiltOnly.messages + checks.rebuiltOnly.requestOnly,
+    tools: checks.rebuiltOnly.toolNames.length
+  };
+  return Object.freeze(
+    SERVED_SLOTS.map((slot) => {
+      const aggregate = check2[slot];
+      const count = onReceipt[slot];
+      return Object.freeze({
+        slot,
+        ...aggregate !== void 0 ? { check: aggregate } : {},
+        rebuilt: rebuiltIn(slot),
+        ...count !== void 0 ? { onReceipt: count } : {},
+        onReceiptOnly: onReceiptOnly[slot],
+        rebuiltOnly: rebuiltOnly[slot],
+        gaps: gapsFor(slot)
+      });
+    })
+  );
+}
+function withheldNodes(input) {
+  const { row, fold } = input;
+  const view = row.view;
+  const out = [];
+  if (view.tools.withheld !== void 0) {
+    out.push(
+      Object.freeze({
+        kind: "tool-withheld",
+        name: view.tools.withheld,
+        from: "view",
+        slot: "tools"
+      })
+    );
+  }
+  for (const id of fold.hiddenSkillIds ?? []) {
+    out.push(Object.freeze({ kind: "hidden-skill", name: id, from: "fold" }));
+  }
+  const drops = row.receipt?.omittedForAttention;
+  out.push(
+    Object.freeze(
+      drops !== void 0 ? {
+        kind: "attention-drop",
+        name: "omittedForAttention",
+        from: "receipt",
+        count: drops.count,
+        hashes: Object.freeze([...drops.hashes])
+      } : {
+        // Absent is not none: the library's own sentence for a field no gap
+        // explains, printed beside the Not-on-record badge.
+        kind: "attention-drop",
+        name: "omittedForAttention",
+        from: "receipt",
+        status: "not-on-record",
+        why: UNGAPPED_FIELDS.omittedForAttention
+      }
+    )
+  );
+  if (fold.redacted) {
+    out.push(Object.freeze({ kind: "redacted", name: "redacted", from: "fold" }));
+  }
+  for (const gap of view.gaps) {
+    const slots = slotsOfFields(gap.fields);
+    out.push(
+      Object.freeze({
+        kind: "gap",
+        name: gap.gap,
+        from: "view",
+        // One slot named: draw it there. Several, or none: the band itself.
+        ...slots.length === 1 ? { slot: slots[0] } : {},
+        why: SERVED_GAPS2[gap.gap].why,
+        fields: gap.fields,
+        ...gap.cause !== void 0 ? { cause: gap.cause } : {}
+      })
+    );
+  }
+  return Object.freeze(out);
+}
+function callNode(input, edges) {
+  const { row, checks } = input;
+  const basis = row.view.basis;
+  return Object.freeze({
+    epoch: row.epoch,
+    callRuntimeStageId: row.callRuntimeStageId,
+    commitIdx: row.commitIdx,
+    betweenCalls: row.betweenCalls,
+    ...row.previousEpoch !== void 0 ? { previousEpoch: row.previousEpoch } : {},
+    ...basis !== void 0 ? { basis } : {},
+    basisStatus: basis !== void 0 ? "reconstructed" : "not-on-record",
+    ...row.receiptCause !== void 0 ? { receiptCause: row.receiptCause } : {},
+    damaged: checks.damaged || edges.some((e) => e.check.status === "damaged")
+  });
+}
+function servedGraphAt(input) {
+  const edges = servedEdges(input);
+  return Object.freeze({
+    held: heldNodes(input.fold),
+    served: slotNodes(input, edges),
+    withheld: withheldNodes(input),
+    call: callNode(input, edges),
+    edges
+  });
+}
+
 // src/core/bookmarks/bookmarkKey.ts
 function fnv1a(s) {
   let h = 2166136261;
@@ -3783,6 +4080,10 @@ export {
   sincePrevious,
   FOLD_FACT_KEYS,
   foldFactsAt,
+  SERVED_SLOTS,
+  HELD_HONESTY_KEYS,
+  HELD_KEYS,
+  servedGraphAt,
   bookmarkKey,
   snapshotOfRunner,
   snapshotLogKey,
@@ -3799,4 +4100,4 @@ export {
   tagStopsFor,
   tagAxisPositions
 };
-//# sourceMappingURL=chunk-FZHRQNRS.js.map
+//# sourceMappingURL=chunk-AIZIILHJ.js.map