agentfootprint-lens 0.47.1 → 0.49.0

package/README.md

@@ -1059,6 +1059,165 @@ 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
+
+**The reader's marks, kept beside the recording — and the author's tags, as a
+ruler.** Since 0.48.0 the Why Lens's right rail has a third tab, **Bookmarks**,
+and the grouped ruler carries a **Tags** strip.
+
+### Why
+
+footprintjs's design page for declared tags names three marks that end in the
+same operation ("keep these stops, fold the rest into them") and differ in who
+puts the mark and when:
+
+| Mark | Who, when | Lives | In the lens |
+|---|---|---|---|
+| **Declared tag** | the author, at build time | the chart's structure → stamped into the commit bundle (`bundle.tags`) | the **Tags** strip: legend and picker |
+| **Derived tag** | the reader, at read time, from the fold | computed by a strategy; never stored | the lens's own grouping (milestones, banded by iteration) — the default axis |
+| **Bookmark** | the reader, at read time, by choice | on the cursor (`mark` / `marks` / `jumpToMark`); persisted beside a recording, never in it | the **Bookmarks** tab |
+
+Only the first two had a place in the lens. footprintjs holds a bookmark on the
+cursor and, by its own law, nowhere else — the log and the snapshot are the
+run's record, not the reader's notes — so a bookmark vanished when the page
+closed. And a run's own tags (agentfootprint 9.90 declares every milestone as
+one) were in the recording with nothing to read them.
+
+### Bookmarks
+
+Stand on a stop and press **Bookmark this stop**. The library names the mark
+(its own `mark()`, seated on the lens's one cursor); the lens writes it to a
+**sidecar** — a small document keyed to the run, in a store you choose. Click a
+bookmark to jump: the port's `jumpToMark`, through the same funnel every other
+mover uses, so the chart, the timeline and the Served tab all follow. Add a
+note inline; remove with one click.
+
+```tsx
+import { Lens } from 'agentfootprint-lens';
+import { memoryBookmarkStore } from 'agentfootprint-lens/core';
+
+<Lens recorder={recorder} runner={agent} granularity="group" />                       // localStorage, by default
+<Lens recorder={recorder} runner={agent} bookmarkStore={memoryBookmarkStore()} />    // this session only
+```
+
+The laws the tab keeps:
+
+- **One cursor.** The tab holds a list, never a position. A jump moves the lens
+  cursor (`onStepChange` fires); a miss never moves.
+- **Never in the record.** Nothing is written into the snapshot or the log.
+- **Omit, never deny.** A bookmark whose stop this recording does not hold —
+  a truncated recording, a sidecar filed under another run — is shown greyed as
+  *not in this recording*, never dropped.
+- **Persistence is a label.** A browser that refuses storage (private mode, a
+  quota, a server render) makes the tab say *bookmarks not saved*; a snapshot
+  with no `runId` says *no run id*. Nothing throws.
+- **No claim sentences.** Every string the tab prints is a label
+  (`BOOKMARK_LABELS`) or computed data; `test/served/no-own-claims.test.ts`
+  walks the file.
+
+The root bookends (*Run · start* / *Run · end*) are not bookmarkable — Home and
+End reach them on every axis, and they share one synthetic address.
+
+Headless, the sidecar is four functions in `/core`: `bookmarkKey(snapshot)`,
+`toSidecar(key, bookmarks)`, `fromSidecar(json, snapshot)` (reports
+`orphaned`), `bookmarksToMarks(bookmarks, positions)` to seed footprintjs's
+`timeTravel(snapshot, { marks })`; stores are `localStorageBookmarkStore()`,
+`memoryBookmarkStore()`, `noBookmarkStore()`, or any `BookmarkStore` of your
+own. See `src/core/bookmarks/README.md`.
+
+### The Tags strip
+
+On the grouped ruler, above the chart: one chip per declared tag, labelled with
+agentfootprint's milestone label when the tag is a milestone (*LLM turn*,
+*Route*) and its raw name otherwise (*audit*), with the number of bundles this
+run stamped it on. The list comes from the recording's **structure** — the
+chart advertises the tags it *can* produce, so the legend is drawn before a
+stop is reached — and the counts from the **log**. A recording that carried no
+structure lists only *tags this run hit* and says *no chart in this recording*.
+A declared tag the run never hit is shown and disabled.
+
+**Pick a chip and the ruler is rebuilt** through footprintjs 9.21's
+`tagStops(names)`: the stops whose bundle carries any picked tag, the untagged
+stages folded into the tagged stop before them, the run's bookends kept. It is
+the same one cursor on a different list — the cursor **keeps its commit**, not
+its step number: it is re-seated at the stop that holds its commit (nearest
+preceding when the new axis has none there — `stepForCommitIdx`, the same rule
+the `granularity` doc gives a host), and the host hears it as an ordinary
+`onStepChange`. `stateAt` at a picked stop equals the default axis's fold at
+the same commit (`src/core/tags/tags.test.ts` pins the equivalence). *Clear*
+restores the lens's own grouping, by the same rule. The strip appears on
+`granularity="group"` at the root level only: the per-step reading's ruler is
+every commit, byte for byte, and a drilled level scrubs its own stops.
+
+A pick scrubs the run's OWN log (`tagStops` reads no other), so a chip is
+pickable only when the tag was hit on the root log; a tag hit only inside
+mounted subflows (the grouped turn's *LLM turn*, the context slots) is shown
+disabled with *in subflows* — real, said, and not a stop on this axis. Counts
+walk each mount's log once (`subflowResults` is dual-keyed; only the `#n`
+entries are read).
+
+```ts
+import { tagLegend, tagAxisPositions, scrubAxisFor } from 'agentfootprint-lens/core';
+
+const legend = tagLegend(runner.getSpec().buildTimeStructure, runner.getLastSnapshot());
+legend.source;                                  // 'structure' | 'log'
+legend.entries.map((e) => [e.label, e.hits]);   // [['Iteration', 2], ['LLM turn', 2], ['audit', 0], …]
+
+const axis = tagAxisPositions(snapshot, ['milestone:llm-turn'], scrubAxisFor(recorder, 'group'));
+axis?.map((p) => p.label);                      // ['Run · start', 'LLM turn 1', 'LLM turn 2', 'Run · end']
+```
+
+**Older peers.** `tagStops` (footprintjs 9.21) and `milestoneFromTags`
+(agentfootprint 9.90) are read off their module namespaces at call time: on a
+peer without them the legend prints raw names, the strip says *tag axis
+unavailable*, and nothing else changes. The peer ranges are untouched.
+
 ---
 
 ## Rendering your own detail pane
@@ -1290,6 +1449,27 @@ field, the library's gap sentences verbatim, the fold's hidden skill ids, and a
 since-previous diff. Headless: `servedRowAt` · `verify` · `sincePrevious` ·
 `foldFactsAt` in `/core`. See "The Served tab" above.
 
+### `<BookmarksTab>` — the reader's marks, riding the one cursor
+
+`<BookmarksTab bookmarks orphaned persistence positions step port moveTo onAdd
+onRemove onNote>`. The Why Lens mounts it as the right rail's third tab
+(`<Lens bookmarkStore?>` picks the store; default `localStorageBookmarkStore()`);
+exported for consumer-built shells, with `useBookmarkSidecar({ snapshot, store })`
+as the list and `openLensCursor(positions, { marks })` as the port. A jump is
+the port's `toMark` through `moveTo`; orphans are greyed and labelled; the
+store's availability is a label. Headless: `bookmarkKey` · `toSidecar` ·
+`fromSidecar` · `bookmarksToMarks` and the three stores in `/core`. See
+"Bookmarks, and scrubbing by declared tag" above.
+
+### `<TagPicker>` — the declared-tag legend and picker
+
+`<TagPicker legend picked onPick available>`. The engineer view mounts it above
+the chart on `granularity="group"` at the root level; `legend` is
+`tagLegend(structure, snapshot)` (`source: 'structure' | 'log'`), a pick is a
+list of tag names the lens hands to `tagAxisPositions(snapshot, picked, base)`
+(footprintjs 9.21's `tagStops`). Picking never moves the cursor; it changes the
+list the one cursor is a step into.
+
 ### `<BugReportButton>` — report a bug with the run attached, consent first
 
 A small button for a debug UI. The dialog it opens shows every selectable unit

package/dist/{Lens-Ccs8UUDQ.d.cts → Lens-_IjGLEGt.d.cts}

@@ -4,7 +4,7 @@ import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
 import { d as NavigationResult, C as CursorPosition, L as LensRecorder } from './resolveNavigation-Ckr2nXHY.cjs';
-import { C as ChartGroupHighlight, a as LensCursorPort, H as Humanizer } from './lensStops-DfNxsaH0.cjs';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-B598GxMJ.cjs';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -523,8 +523,22 @@ interface LensProps {
      * granularities carries it by `commitIdx`: build the target axis with
      * `scrubAxisFor(recorder, granularity)` and resolve it with
      * `stepForCommitIdx(positions, at.commitIdx)`.
+     *
+     * (0.48.0) The TAGS strip — the declared-tag legend and the picker that
+     * rebuilds the ruler through `tagStops` — appears on `'group'` at the root
+     * level only; `'step'` scrubs every commit and carries no strip. A pick
+     * re-seats the cursor by the same `stepForCommitIdx` rule.
      */
     readonly granularity?: 'step' | 'group';
+    /**
+     * Where the reader's BOOKMARKS persist (0.48.0). A bookmark is the reader's
+     * mark — never written into the recording — kept in a sidecar keyed to the
+     * run and seeded onto the cursor when the recording is opened. Default:
+     * `localStorageBookmarkStore()`; a browser that refuses storage makes the
+     * Bookmarks tab say "bookmarks not saved" rather than throw. Pass
+     * `memoryBookmarkStore()` for a session-only reading, or your own store.
+     */
+    readonly bookmarkStore?: BookmarkStore;
     /**
      * Controlled cursor (omit for uncontrolled). Omit it and the lens is
      * self-driving exactly as it has always been: it holds the position itself,

package/dist/{Lens-9wZ84e70.d.ts → Lens-_hExvOXu.d.ts}

@@ -4,7 +4,7 @@ import * as agentfootprint from 'agentfootprint';
 import { CommentaryTemplates } from 'agentfootprint';
 import React__default, { Ref } from 'react';
 import { d as NavigationResult, C as CursorPosition, L as LensRecorder } from './resolveNavigation-Ckr2nXHY.js';
-import { C as ChartGroupHighlight, a as LensCursorPort, H as Humanizer } from './lensStops-Di41Rg3f.js';
+import { C as ChartGroupHighlight, c as LensCursorPort, H as Humanizer, b as BookmarkStore } from './tagAxis-C__DMHiD.js';
 import { NodeTypes } from '@xyflow/react';
 import { TraceGraph, TraceFlowLayout, RuntimeOverlay } from 'footprint-explainable-ui/flowchart';
 
@@ -523,8 +523,22 @@ interface LensProps {
      * granularities carries it by `commitIdx`: build the target axis with
      * `scrubAxisFor(recorder, granularity)` and resolve it with
      * `stepForCommitIdx(positions, at.commitIdx)`.
+     *
+     * (0.48.0) The TAGS strip — the declared-tag legend and the picker that
+     * rebuilds the ruler through `tagStops` — appears on `'group'` at the root
+     * level only; `'step'` scrubs every commit and carries no strip. A pick
+     * re-seats the cursor by the same `stepForCommitIdx` rule.
      */
     readonly granularity?: 'step' | 'group';
+    /**
+     * Where the reader's BOOKMARKS persist (0.48.0). A bookmark is the reader's
+     * mark — never written into the recording — kept in a sidecar keyed to the
+     * run and seeded onto the cursor when the recording is opened. Default:
+     * `localStorageBookmarkStore()`; a browser that refuses storage makes the
+     * Bookmarks tab say "bookmarks not saved" rather than throw. Pass
+     * `memoryBookmarkStore()` for a session-only reading, or your own store.
+     */
+    readonly bookmarkStore?: BookmarkStore;
     /**
      * Controlled cursor (omit for uncontrolled). Omit it and the lens is
      * self-driving exactly as it has always been: it holds the position itself,