footPrint AGENTS.md

footprint.js — AI Coding Instructions

This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.

Core Principle

Collect during traversal, never post-process. All data collection (narrative, metrics, manifest, identity) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.

Architecture — Library of Libraries

src/lib/
├── capture/   → Value-capture/retention primitives (RetentionPolicy 'full'|'summary'|'off', read/write summary markers) — shared by the readTracking (#14) + writeTracking (#13c-A) dials; RFC-001 builds on it
├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer, EventLog)
├── schema/    → Validation abstraction (Zod optional, duck-typed detection)
├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), DeciderList, SelectorFnList)
├── scope/     → Per-stage facades + recorders + providers
├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods, cycle-safe)
├── decide/    → decide()/select() decision evidence capture (filter + function)
├── recorder/  → CompositeRecorder, KeyedStore<T>, SequenceStore<T>, BoundaryStateStore<TState>, composition primitives
├── pause/     → Pause/Resume (PauseSignal, FlowchartCheckpoint, PausableHandler)
├── engine/    → DFS traversal + narrative + 13 handlers
├── runner/    → High-level executor (FlowChartExecutor)
└── contract/  → I/O schema + OpenAPI generation

Dependency DAG: capture (standalone leaf) <- memory <- scope <- reactive <- engine <- runner, schema <- engine, builder (standalone) -> engine, contract <- schema, decide -> scope

Three entry points:

• import { ... } from 'footprintjs' — public API
• import { ... } from 'footprintjs/trace' — execution tracing: runtimeStageId, commitLog queries, storage primitives (KeyedStore, SequenceStore, BoundaryStateStore)
• import { ... } from 'footprintjs/advanced' — engine internals (also re-exports trace)