footPrint: Instructions file for GitHub Copilot

footprint.js — Copilot 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 happens as side effects of the single DFS traversal. Never walk the tree after execution.

Architecture

src/lib/
├── memory/    → Engine state and policy (StageContext composes foottrace RecordFrame)
├── schema/    → Validation (Zod optional, duck-typed)
├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
├── scope/     → Per-stage facades + recorders + providers
├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
├── decide/    → decide()/select() decision evidence capture
├── engine/    → DFS traversal + narrative + handlers
├── runner/    → FlowChartExecutor
└── contract/  → I/O schema + OpenAPI

FootPrint has six engine doors: footprintjs (main API) · footprintjs/recorders (recorder factories) · footprintjs/trace (engine recorders, stores and structure walkers) · footprintjs/advanced (engine internals) · footprintjs/detach (fire-and-forget children) · footprintjs/zod (opt-in zod bridge).

The separate record package has three doors: foottrace (record shapes, readers and runtime IDs), foottrace/write (SharedMemory, EventLog, RecordFrame) and foottrace/paths (record-path rules and safe nested access). Import directly from the owner: FootPrint does not re-export record declarations or keep local copies of record rules.

Key API — TypedScope (Recommended)

import { flowChart, FlowChartExecutor, decide } from 'footprintjs';

interface State {
  creditScore: number;
  riskTier: string;
  decision?: string;
}

const chart = flowChart<State>('Intake', async (scope) => {
  scope.creditScore = 750;          // typed write (no setValue needed)
  scope.riskTier = 'low';           // typed write
}, 'intake')
  .addDeciderFunction('Route', (scope) => {
    return decide(scope, [
      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
    ], 'rejected');
  }, 'route', 'Route based on risk')
    .addFunctionBranch('approved', 'Approve', async (scope) => {
      scope.decision = 'Approved';
    })
    .addFunctionBranch('rejected', 'Reject', async (scope) => {
      scope.decision = 'Rejected';
    })
    .setDefault('rejected')
    .end()
  .build();

const executor = new FlowChartExecutor(chart);
executor.enableNarrative();      // the narrative is OFF until enabled
await executor.run();
executor.getNarrativeEntries();  // CombinedNarrativeEntry[] — causal trace with decision evidence