hacifootprint
Reference

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.

On this page