footPrint copilot-instructions.md

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/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
├── 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

Entry points: footprintjs (public) and footprintjs/advanced (internals).

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);
await executor.run();
executor.getNarrative();  // causal trace with decision evidence