footprintjs 0.2.0 → 0.2.2

package/README.md

@@ -69,17 +69,27 @@ No one wrote those trace sentences. Stage functions just read and write scope &m
 
 ```typescript
 import {
-  FlowChartBuilder, FlowChartExecutor, ScopeFacade,
-  NarrativeRecorder, CombinedNarrativeBuilder,
-} from 'footprint';
+  FlowChartBuilder, FlowChartExecutor, ScopeFacade, toScopeFactory,
+} from 'footprintjs';
+
+// ── The application data ──────────────────────────────────────────────
+
+const app = {
+  applicantName: 'Bob',
+  annualIncome: 42_000,
+  monthlyDebts: 2_100,
+  creditScore: 580,
+  employmentType: 'self-employed',
+  employmentYears: 1,
+};
 
 // ── Stage functions: just do the work, no descriptions needed ──────────
 
-const receiveApplication = async (scope: ScopeFacade) => {
-  scope.setValue('app', app);                         // objects, arrays, nested — all supported
+const receiveApplication = (scope: ScopeFacade) => {
+  scope.setValue('app', app);
 };
 
-const pullCreditReport = async (scope: ScopeFacade) => {
+const pullCreditReport = (scope: ScopeFacade) => {
   const { creditScore } = scope.getValue('app') as any;
   const tier = creditScore >= 740 ? 'excellent' : creditScore >= 670 ? 'good'
              : creditScore >= 580 ? 'fair' : 'poor';
@@ -87,7 +97,7 @@ const pullCreditReport = async (scope: ScopeFacade) => {
   scope.setValue('creditFlags', tier === 'fair' ? ['below-average credit'] : []);
 };
 
-const calculateDTI = async (scope: ScopeFacade) => {
+const calculateDTI = (scope: ScopeFacade) => {
   const { annualIncome, monthlyDebts } = scope.getValue('app') as any;
   const dtiRatio = Math.round((monthlyDebts / (annualIncome / 12)) * 100) / 100;
   scope.setValue('dtiRatio', dtiRatio);
@@ -97,7 +107,15 @@ const calculateDTI = async (scope: ScopeFacade) => {
     dtiRatio > 0.43 ? [`DTI at ${Math.round(dtiRatio * 100)}% exceeds 43%`] : []);
 };
 
-const assessRisk = async (scope: ScopeFacade) => {
+const verifyEmployment = (scope: ScopeFacade) => {
+  const { employmentType, employmentYears } = scope.getValue('app') as any;
+  const verified = employmentType !== 'self-employed' || employmentYears >= 2;
+  scope.setValue('employmentVerified', verified);
+  scope.setValue('employmentFlags',
+    !verified ? [`${employmentType}, ${employmentYears}yr < 2yr minimum`] : []);
+};
+
+const assessRisk = (scope: ScopeFacade) => {
   const creditTier = scope.getValue('creditTier') as string;
   const dtiStatus = scope.getValue('dtiStatus') as string;
   const verified = scope.getValue('employmentVerified') as boolean;
@@ -122,34 +140,22 @@ const chart = new FlowChartBuilder()
   .addFunction('VerifyEmployment', verifyEmployment)
   .addFunction('AssessRisk', assessRisk)
   .addDeciderFunction('LoanDecision', loanDecider as any)
-    .addFunctionBranch('approved', 'ApproveApplication', approveFn)
-    .addFunctionBranch('rejected', 'RejectApplication', rejectFn)
-    .addFunctionBranch('manual-review', 'ManualReview', reviewFn)
+    .addFunctionBranch('approved', 'ApproveApplication', () => {})
+    .addFunctionBranch('rejected', 'RejectApplication', () => {})
+    .addFunctionBranch('manual-review', 'ManualReview', () => {})
     .setDefault('manual-review')
     .end()
   .build();
 
-// ── Instrument scope with NarrativeRecorder ────────────────────────────
-
-const recorder = new NarrativeRecorder({ id: 'loan', detail: 'full' });
-
-const scopeFactory = (ctx: any, stageName: string) => {
-  const scope = new ScopeFacade(ctx, stageName);
-  scope.attachRecorder(recorder);
-  return scope;
-};
-
 // ── Run and get the narrative ──────────────────────────────────────────
 
-const executor = new FlowChartExecutor(chart, scopeFactory);
+const executor = new FlowChartExecutor(chart, toScopeFactory(ScopeFacade));
 await executor.run();
 
-const flowNarrative = executor.getNarrative();     // control flow sentences
-const combined = new CombinedNarrativeBuilder();
-const narrative = combined.build(flowNarrative, recorder);  // ← the trace above
+const narrative = executor.getNarrative();  // ← the trace above
 ```
 
-The NarrativeRecorder observes every `getValue`/`setValue` call. The ControlFlowNarrativeGenerator captures stage transitions and decisions. CombinedNarrativeBuilder merges both into the trace. No descriptions were written by hand.
+`enableNarrative()` auto-instruments every scope. The executor captures stage transitions, decisions, reads, and writes &mdash; then merges them into the combined trace. No descriptions were written by hand.
 
 ---
 
@@ -238,7 +244,7 @@ FootPrint has three moving parts:
 ### Linear
 
 ```typescript
-import { flowChart } from 'footprint';
+import { flowChart } from 'footprintjs';
 
 flowChart('A', fnA)
   .addFunction('B', fnB)
@@ -365,7 +371,7 @@ Each stage receives a **scope** &mdash; a transactional interface to shared stat
 Extend `ScopeFacade` with domain-specific getters for type-safe reads:
 
 ```typescript
-import { ScopeFacade } from 'footprint';
+import { ScopeFacade } from 'footprintjs';
 
 class LoanScope extends ScopeFacade {
   get creditScore(): number {
@@ -403,7 +409,7 @@ const total = scope.getValue('total');       // read
 
 ```typescript
 import { z } from 'zod';
-import { defineScopeFromZod } from 'footprint';
+import { defineScopeFromZod } from 'footprintjs';
 
 const schema = z.object({
   creditScore: z.number(),
@@ -424,18 +430,19 @@ Recorders observe scope operations without modifying them. Attach multiple for d
 
 ```typescript
 import {
-  ScopeFacade, DebugRecorder, MetricRecorder, NarrativeRecorder,
-} from 'footprint';
+  ScopeFacade, DebugRecorder, MetricRecorder,
+} from 'footprintjs';
 
 const scopeFactory = (ctx: any, stageName: string) => {
   const scope = new ScopeFacade(ctx, stageName);
   scope.attachRecorder(new DebugRecorder({ verbosity: 'verbose' }));
   scope.attachRecorder(new MetricRecorder());
-  scope.attachRecorder(new NarrativeRecorder({ id: 'trace', detail: 'full' }));
   return scope;
 };
 ```
 
+> **Note:** `NarrativeRecorder` is attached automatically when narrative is enabled via `setEnableNarrative()` or `executor.enableNarrative()`. You only need to attach it manually if you need custom options.
+
 Error isolation is built in: if a recorder throws, the error is routed to `onError` hooks of other recorders, and the scope operation continues normally.
 
 ### Custom Recorders
@@ -443,7 +450,7 @@ Error isolation is built in: if a recorder throws, the error is routed to `onErr
 Implement any subset of six hooks: `onRead`, `onWrite`, `onCommit`, `onError`, `onStageStart`, `onStageEnd`.
 
 ```typescript
-import { Recorder, WriteEvent } from 'footprint';
+import { Recorder, WriteEvent } from 'footprintjs';
 
 class AuditRecorder implements Recorder {
   readonly id = 'audit';
@@ -591,7 +598,9 @@ An LLM reading this trace can immediately explain: *"The validation failed becau
 | Method | Description |
 |--------|-------------|
 | `run(options?)` | Execute the flowchart. Options: `{ signal?, timeoutMs? }` |
-| `getNarrative()` | Control-flow narrative sentences |
+| `getNarrative()` | Combined narrative (flow + data) with ScopeFacade; flow-only otherwise |
+| `getFlowNarrative()` | Flow-only narrative sentences |
+| `getNarrativeEntries()` | Structured `CombinedNarrativeEntry[]` for programmatic use |
 | `getSnapshot()` | Full execution tree + state |
 | `getExtractedResults()` | Extractor results map |
 | `getEnrichedResults()` | Enriched snapshots (scope state, debug info, output) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Turn your whiteboard flowchart into running code — with automatic causal traces for LLM reasoning",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",