Design lineage
The numbered design documents that decided the library's load-bearing shapes — what each locked in, and where to read the full reasoning.
The library's shape was decided in numbered design documents, kept in the repo under
docs/design/. Each doc
records the constraint that forced the design, not just the winner — read them when you want
to know why a surface is the way it is.
The shared record — migrating from 2.x
The session writes its record with RecordFrame, SharedMemory and EventLog
from foottrace/write. Trace readers such as causalChain and sliceForKey
come from foottrace. They read the same record bytes as before extraction.
Session.commitLog() still returns CommitBundle[], but hcifootprint no longer
re-exports CommitBundle. Add foottrace ^1.0.0 to your application's dependencies
and import this type from its owner, foottrace:
import { } from 'hcifootprint';
import type { CommitBundle } from 'foottrace';
const = ('shop', { : { : {} } });
const = .();
const : CommitBundle[] = .();The removed type export is a breaking change from 2.x. The session methods and
record bytes are unchanged. HCI depends on foottrace ^1.0.0 and accepts
footprintjs ^9.47.0 || ^10.0.0; guard evaluation and schema normalization stay
in footprintjs.
D18 — the navigation graph
The canonical authoring surface: pages → areas / tabs / modals → tools, one does sentence
with two readers, typed node paths, mount-time action declaration, the presence sensor, and
Mode B (serveToAgent). Everything on The navigation graph,
Presence and Journeys as fixed tools traces here.
Read D18.
D21 — confirm receipts
The needs-confirm ask carries receipts — willDo, the guard evidence, the position,
the recent trail — and both answers land in an auditable ask→decision→fire journal, separate
from the gap ledger. The reasoning behind Confirms & receipts.
Read D21.
D22 — materialized fires
An agent fire that would execute nothing is refused (NOT_MATERIALIZED) instead of settling
a success-shaped no-op; tours opt in and get honest no-ops. The 0.3.0 behavior change that
the adoption ladder leans on.
Read D22.
D23 — graph sources
The graph grows from what the app already has: fromRoutes / fromJourneys /
fromLiveStore, ONE documented merge order, typed actuation on the edge (url / click / tab /
programmatic), the navigate session option, and the never-trap invariant with its three
gates. The reasoning behind Graph sources,
Actuation and Live bindings, including the tab-semantics
decision and the tree-shake geometry with the measured probe numbers.
Read D23.