footprintjs 1.0.0 → 1.0.1

package/AGENTS.md

@@ -1,125 +1,119 @@
-# footprint.js — AI Agent Instructions
+# footprint.js — Agent Instructions
 
-> The flowchart pattern for backend code — self-explainable systems that AI can reason about.
-
-## What This Library Does
-
-footprint.js structures backend logic as a graph of named functions with transactional state. Every run auto-generates a causal trace showing what happened and why. An LLM reads the trace and explains decisions accurately — no hallucination.
+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) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+**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 detection)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), typedFlowChart())
 ├── 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/    → High-level executor (FlowChartExecutor)
-└── contract/  → I/O schema + OpenAPI generation
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
 ```
 
-Two entry points:
-- `import { ... } from 'footprintjs'` — public API
-- `import { ... } from 'footprintjs/advanced'` — internals
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
 
-## Quick Start
+## Key API — TypedScope (Recommended)
 
 ```typescript
-import { flowChart, FlowChartExecutor } from 'footprintjs';
-
-const chart = flowChart('ReceiveOrder', (scope) => {
-    scope.setValue('orderId', 'ORD-123');
-    scope.setValue('amount', 49.99);
-  }, 'receive-order', undefined, 'Receive the incoming order')
-  .addFunction('ProcessPayment', (scope) => {
-    const amount = scope.getValue('amount');
-    scope.setValue('paymentStatus', amount < 100 ? 'approved' : 'review');
-  }, 'process-payment', 'Charge customer')
+import { typedFlowChart, createTypedScopeFactory, FlowChartExecutor, decide } from 'footprintjs';
+
+interface State {
+  creditScore: number;
+  riskTier: string;
+  decision?: string;
+}
+
+const chart = typedFlowChart<State>('Intake', async (scope) => {
+  scope.creditScore = 750;          // typed write (no setValue needed)
+  scope.riskTier = 'low';           // typed write
+}, 'intake')
   .setEnableNarrative()
+  .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({ input: { orderId: 'ORD-123' } });
-console.log(executor.getNarrative());
-```
-
-## Builder API
-
-```typescript
-flowChart(name, fn, id, extractor?, description?)  // start chain
-  .addFunction(name, fn, id, description?)          // linear stage
-  .addDeciderFunction(name, fn, id, description?)   // single-choice branch
-    .addFunctionBranch(branchId, name, fn)           //   branch option
-    .addSubFlowChartBranch(branchId, subflow)        //   subflow branch
-    .setDefault(branchId)                             //   fallback
-    .end()                                            //   close decider
-  .addSelectorFunction(name, fn, id, description?)  // multi-choice fan-out
-  .addListOfFunction([...], { failFast? })           // parallel fork
-  .addSubFlowChartNext(id, subflow, mount, opts?)   // mount subflow inline
-  .loopTo(stageId)                                   // back-edge loop
-  .setEnableNarrative()                              // enable narrative
-  .setInputSchema(schema)                            // Zod or JSON Schema
-  .build()                                           // compile
-  .toSpec()                                          // JSON structure
-  .toMermaid()                                       // diagram
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<State>());
+await executor.run();
+executor.getNarrative();  // causal trace with decision evidence
 ```
 
-## Stage Function Signature
+### TypedScope $-methods (escape hatches)
 
 ```typescript
-(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+scope.$getArgs<T>()        // frozen readonly input
+scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
+scope.$break()             // stop pipeline
+scope.$debug(key, value)   // debug info
+scope.$metric(name, value) // metrics
 ```
 
-## ScopeFacade (per-stage state access)
+### decide() / select()
 
 ```typescript
-scope.getValue('key')              // tracked read → appears in narrative
-scope.setValue('key', value)        // tracked write → appears in narrative
-scope.updateValue('key', partial)  // deep merge (tracked)
-scope.deleteValue('key')           // tracked delete
-scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+// Filter syntax — captures operators + thresholds
+decide(scope, [
+  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
+], 'rejected');
+
+// Function syntax — captures which keys were read
+decide(scope, [
+  { when: (s) => s.creditScore > 700, then: 'approved' },
+], 'rejected');
+
+// select() — all matching branches (not first-match)
+select(scope, [
+  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
+  { when: { bmi: { gt: 30 } }, then: 'obesity' },
+]);
 ```
 
-## Executor
+### Executor
 
 ```typescript
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input, timeoutMs?, signal? });
-
-executor.getNarrative()         // string[] — combined flow + data
-executor.getNarrativeEntries()  // CombinedNarrativeEntry[] — structured
-executor.getSnapshot()          // full memory state
-executor.attachFlowRecorder(r)  // plug observer before run()
-executor.setRedactionPolicy({   // PII protection
-  keys: ['ssn'], patterns: [/password/i]
-})
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<State>());
+await executor.run({ input, env: { traceId: 'req-123' } });
+executor.getNarrative()            // string[]
+executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
+executor.getSnapshot()             // memory state
+executor.attachRecorder(recorder)  // scope observer
+executor.attachFlowRecorder(r)     // flow observer
+executor.setRedactionPolicy({ keys, patterns, fields })
 ```
 
-## Two Observer Systems
+## Observer Systems
 
-**Scope Recorder** — fires DURING stage: `onRead`, `onWrite`, `onCommit`, `onStageStart/End`
-**FlowRecorder** — fires AFTER stage: `onStageExecuted`, `onDecision`, `onFork`, `onNext`, `onLoop`, `onError`
+- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
+- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
+- 8 built-in FlowRecorder strategies
+- `setEnableNarrative()` auto-attaches `CombinedNarrativeRecorder`
 
-8 built-in FlowRecorder strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent.
-
-`CombinedNarrativeRecorder` implements BOTH — auto-attached by `setEnableNarrative()`.
-
-## Anti-Patterns
+## Rules
 
+- Use `typedFlowChart<T>()` + `createTypedScopeFactory<T>()` (not flowChart + ScopeFacade)
+- Use `decide()` / `select()` in decider/selector functions
+- Use typed property access (not getValue/setValue)
+- Use `$getArgs()` for input, `$getEnv()` for environment
 - Never post-process the tree — use recorders
-- Never use deprecated `CombinedNarrativeBuilder`
-- Don't use `getArgs()` for tracked data — use `getValue()`/`setValue()`
-- Don't manually create `CombinedNarrativeRecorder` — `setEnableNarrative()` handles it
-
-## Build
-
-```bash
-npm install footprintjs
-npm run build    # CJS + ESM dual output
-npm test
-```
+- `setEnableNarrative()` is all you need for narrative setup