plainstamp 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -16,6 +16,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 Distribution is **npm-only**. Source remains in the operating organization's private repository; there is no public source repository host. Contact channel for issues, accuracy reports, security reports, and contribution proposals is **helpfulbutton140@agentmail.to** (see `docs/CONTRIBUTING.md`, `docs/SECURITY.md`).
 
+## [0.7.4] — 2026-05-08
+
+### Fixed (root re-exports for watcher API)
+
+- Re-export the watcher's public surface (`diffArticles`, `runWatcher`, `runWatcherWithStore`, `readState`, `writeState`, `fsStateStore`, `memoryStateStore`, source factories, and the `Article` / `Source` / `RunReport` / `SourceRunReport` / `StateStore` / `WatcherState` types) from the package root. Previously these were only available via the deep `plainstamp/dist/watcher/index.js` import path, which broke type resolution in some consumers (notably the `plainstamp-cf-worker` Cloudflare Workers package). Now `import { runWatcherWithStore, type StateStore } from "plainstamp"` works.
+
+## [0.7.3] — 2026-05-08
+
+### Added (cross-runtime watcher)
+
+- New `StateStore` interface on the watcher module: `read()` and `write(state)`. Allows the rule-update watcher to run in environments without a filesystem (Cloudflare Workers, Deno Deploy, browsers).
+- New `runWatcherWithStore({ sources, stateStore, dryRun? })` entry point alongside the existing `runWatcher({ sources, statePath, dryRun? })`. The fs-path version remains and is now a thin shim over the abstract version.
+- New `fsStateStore(path)` and `memoryStateStore(initial?)` factory helpers exported from the watcher module.
+- All five new exports are re-exported from the package root.
+
+### Internal
+
+- `runWatcher` is unchanged from a caller's perspective; the shim preserves the existing CLI behavior. No tests changed; full 51-test suite still passing.
+
 ## [0.7.2] — 2026-05-08
 
 ### Documentation

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { computeCoverageMatrix, renderCoverageMarkdown, renderCoverageCsv, type
 export type { DisclosureRuleT, RuleSetT, LookupQueryT, LookupResultT, ChannelT, UseCaseT, SeverityT, JurisdictionIdT, DisclosureElementT, } from "./schema.js";
 export { Channel, UseCase, Severity, JurisdictionId, LookupQuery, DisclosureElement, DisclosureRule, RuleSet, } from "./schema.js";
 export { mcpTools, executeMcpTool, type McpToolDescriptor, type McpToolResult, } from "./mcp-tools.js";
+export { diffArticles, runWatcher, runWatcherWithStore, readState, writeState, fsStateStore, memoryStateStore, federalRegisterSource, urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./watcher/index.js";
+export type { Article, Source, RunReport, SourceRunReport, StateStore, WatcherState, } from "./watcher/index.js";
 import type { LookupQueryT, LookupResultT, DisclosureRuleT } from "./schema.js";
 /**
  * High-level convenience: load the bundled rules and look up disclosures for

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,MAAM;;;;;IAKtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,MAAM;;;;;IAKtB"}

package/dist/index.js

@@ -3,6 +3,7 @@ export { loadBundledRules, loadRulesFromPath, setBundledRules, } from "./rules-l
 export { computeCoverageMatrix, renderCoverageMarkdown, renderCoverageCsv, } from "./coverage.js";
 export { Channel, UseCase, Severity, JurisdictionId, LookupQuery, DisclosureElement, DisclosureRule, RuleSet, } from "./schema.js";
 export { mcpTools, executeMcpTool, } from "./mcp-tools.js";
+export { diffArticles, runWatcher, runWatcherWithStore, readState, writeState, fsStateStore, memoryStateStore, federalRegisterSource, urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./watcher/index.js";
 import { loadBundledRules } from "./rules-loader.js";
 import { lookup as lookupFn, validateDisclosure as validateFn } from "./lookup.js";
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AAYvB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,GAGf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,kBAAkB,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAO,QAAQ,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,aAAqB;IAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AAYvB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,GAGf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,kBAAkB,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAO,QAAQ,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,aAAqB;IAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/watcher/index.d.ts

@@ -1,14 +1,30 @@
-import type { Article, RunReport, Source, SourceRunReport, WatcherState } from "./types.js";
+import type { Article, RunReport, Source, SourceRunReport, StateStore, WatcherState } from "./types.js";
 /**
  * Computes the new articles for a source — those whose ids do not appear in
  * `seen`. Returns the articles in fetched-order. Pure function; safe to test.
  */
 export declare function diffArticles(fetched: Article[], seen: string[]): Article[];
 /**
- * Runs all sources, computes the diff against persisted state, returns a
- * report, and updates the state file with the union of (previously seen) ∪
- * (newly fetched ids). Source fetch failures are caught and reported per-
- * source; one failing source does not abort the run.
+ * Runs all sources against an abstract state store, computes the diff,
+ * returns a report, and updates the store with (previously seen) ∪
+ * (newly fetched ids). Source fetch failures are caught and reported
+ * per-source; one failing source does not abort the run.
+ *
+ * Use this from environments without filesystem access (Cloudflare
+ * Workers, Deno Deploy, browsers). Pass a custom `StateStore` — for
+ * example, one backed by Workers KV. The Node CLI path uses
+ * `runWatcher` (below), which is a thin wrapper that constructs an
+ * `fsStateStore` from a filesystem path.
+ */
+export declare function runWatcherWithStore(opts: {
+    sources: Source[];
+    stateStore: StateStore;
+    dryRun?: boolean;
+}): Promise<RunReport>;
+/**
+ * Filesystem-backed convenience wrapper. Equivalent to
+ * `runWatcherWithStore({ ..., stateStore: fsStateStore(statePath) })`.
+ * Kept for the existing Node CLI; do not use in non-Node runtimes.
  */
 export declare function runWatcher(opts: {
     sources: Source[];
@@ -16,8 +32,8 @@ export declare function runWatcher(opts: {
     /** If true, do NOT persist the new state (useful for dry-run inspection). */
     dryRun?: boolean;
 }): Promise<RunReport>;
-export type { Article, Source, RunReport, SourceRunReport, WatcherState };
-export { readState, writeState } from "./state-store.js";
+export type { Article, Source, RunReport, SourceRunReport, StateStore, WatcherState, };
+export { readState, writeState, fsStateStore, memoryStateStore, } from "./state-store.js";
 export { federalRegisterSource } from "./sources/federal-register.js";
 export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./sources/url-monitor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/watcher/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,MAAM,EACN,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAO1E;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAiDrB;AAED,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,MAAM,EACN,eAAe,EACf,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAO1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAiDrB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAWrB;AAED,YAAY,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,CAAC;AACF,OAAO,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/watcher/index.js

@@ -1,4 +1,4 @@
-import { readState, writeState } from "./state-store.js";
+import { fsStateStore } from "./state-store.js";
 /**
  * Computes the new articles for a source — those whose ids do not appear in
  * `seen`. Returns the articles in fetched-order. Pure function; safe to test.
@@ -13,13 +13,19 @@ export function diffArticles(fetched, seen) {
     return out;
 }
 /**
- * Runs all sources, computes the diff against persisted state, returns a
- * report, and updates the state file with the union of (previously seen) ∪
- * (newly fetched ids). Source fetch failures are caught and reported per-
- * source; one failing source does not abort the run.
+ * Runs all sources against an abstract state store, computes the diff,
+ * returns a report, and updates the store with (previously seen) ∪
+ * (newly fetched ids). Source fetch failures are caught and reported
+ * per-source; one failing source does not abort the run.
+ *
+ * Use this from environments without filesystem access (Cloudflare
+ * Workers, Deno Deploy, browsers). Pass a custom `StateStore` — for
+ * example, one backed by Workers KV. The Node CLI path uses
+ * `runWatcher` (below), which is a thin wrapper that constructs an
+ * `fsStateStore` from a filesystem path.
  */
-export async function runWatcher(opts) {
-    const state = readState(opts.statePath);
+export async function runWatcherWithStore(opts) {
+    const state = await opts.stateStore.read();
     const now = new Date().toISOString();
     const sourceReports = [];
     for (const source of opts.sources) {
@@ -62,10 +68,24 @@ export async function runWatcher(opts) {
         }
     }
     if (!opts.dryRun)
-        writeState(opts.statePath, state);
+        await opts.stateStore.write(state);
     return { run_at: now, sources: sourceReports };
 }
-export { readState, writeState } from "./state-store.js";
+/**
+ * Filesystem-backed convenience wrapper. Equivalent to
+ * `runWatcherWithStore({ ..., stateStore: fsStateStore(statePath) })`.
+ * Kept for the existing Node CLI; do not use in non-Node runtimes.
+ */
+export async function runWatcher(opts) {
+    const passthrough = {
+        sources: opts.sources,
+        stateStore: fsStateStore(opts.statePath),
+    };
+    if (opts.dryRun !== undefined)
+        passthrough.dryRun = opts.dryRun;
+    return runWatcherWithStore(passthrough);
+}
+export { readState, writeState, fsStateStore, memoryStateStore, } from "./state-store.js";
 export { federalRegisterSource } from "./sources/federal-register.js";
 export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./sources/url-monitor.js";
 //# sourceMappingURL=index.js.map

package/dist/watcher/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAkB,EAAE,IAAc;IAC7D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAIzC;IACC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,aAAa,GAAsB,EAAE,CAAC;IAE5C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACvE,IAAI,QAAQ,GAAc,EAAE,CAAC;QAC7B,IAAI,MAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAI,GAAa,CAAC,OAAO,CAAC;QAClC,CAAC;QAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,aAAa,CAAC,IAAI,CAAC;gBACjB,SAAS,EAAE,MAAM,CAAC,EAAE;gBACpB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,MAAM;gBACb,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;aAC7B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,aAAa,CAAC,IAAI,CAAC;YACjB,SAAS,EAAE,MAAM,CAAC,EAAE;YACpB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,EAAE,EAAE,IAAI;YACR,YAAY,EAAE,WAAW;YACzB,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM;SAClD,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,KAAK,MAAM,CAAC,IAAI,QAAQ;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3C,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG;gBACzB,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;gBACjB,SAAS,EAAE,GAAG;aACf,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAErD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAKhC;IACC,MAAM,WAAW,GAIb;QACF,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,UAAU,EAAE,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC;KACzC,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAChE,OAAO,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAC1C,CAAC;AAUD,OAAO,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/watcher/state-store.d.ts

@@ -1,4 +1,4 @@
-import type { WatcherState } from "./types.js";
+import type { StateStore, WatcherState } from "./types.js";
 /**
  * Reads the watcher state from `path`. If the file does not exist, returns a
  * fresh empty state. The state file is plain JSON — the agent can read it
@@ -6,4 +6,14 @@ import type { WatcherState } from "./types.js";
  */
 export declare function readState(path: string): WatcherState;
 export declare function writeState(path: string, state: WatcherState): void;
+/**
+ * Filesystem-backed StateStore for Node consumers. Wraps the sync
+ * readState/writeState above. Use in CLI and Node test paths.
+ */
+export declare function fsStateStore(path: string): StateStore;
+/**
+ * In-memory StateStore. Useful for tests and dry-run inspection where
+ * neither filesystem nor KV is available.
+ */
+export declare function memoryStateStore(initial?: WatcherState): StateStore;
 //# sourceMappingURL=state-store.d.ts.map

package/dist/watcher/state-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/watcher/state-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAYpD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAGlE"}
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/watcher/state-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAYpD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAKrD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,UAAU,CASnE"}

package/dist/watcher/state-store.js

@@ -20,4 +20,27 @@ export function writeState(path, state) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
+/**
+ * Filesystem-backed StateStore for Node consumers. Wraps the sync
+ * readState/writeState above. Use in CLI and Node test paths.
+ */
+export function fsStateStore(path) {
+    return {
+        read: () => readState(path),
+        write: (state) => writeState(path, state),
+    };
+}
+/**
+ * In-memory StateStore. Useful for tests and dry-run inspection where
+ * neither filesystem nor KV is available.
+ */
+export function memoryStateStore(initial) {
+    let state = initial ?? { schema_version: 1, sources: {} };
+    return {
+        read: () => state,
+        write: (next) => {
+            state = next;
+        },
+    };
+}
 //# sourceMappingURL=state-store.js.map

package/dist/watcher/state-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/watcher/state-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IAC/C,IAAI,MAAM,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,yCAAyC,MAAM,CAAC,cAAc,eAAe,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAmB;IAC1D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/watcher/state-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IAC/C,IAAI,MAAM,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,yCAAyC,MAAM,CAAC,cAAc,eAAe,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAmB;IAC1D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;QAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,IAAI,KAAK,GACP,OAAO,IAAI,EAAE,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAChD,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK;QACjB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YACd,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/watcher/types.d.ts

@@ -56,4 +56,14 @@ export interface RunReport {
     run_at: string;
     sources: SourceRunReport[];
 }
+/**
+ * Pluggable state store. The Node CLI uses a filesystem-backed store
+ * (`fsStateStore`); Cloudflare Workers / Deno Deploy / browsers use a
+ * KV-backed store. Implementations may be sync or async; the watcher
+ * always awaits.
+ */
+export interface StateStore {
+    read(): Promise<WatcherState> | WatcherState;
+    write(state: WatcherState): Promise<void> | void;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/watcher/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/watcher/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,OAAO;IACtB,qGAAqG;IACrG,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,8HAA8H;IAC9H,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4DAA4D;IAC5D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/watcher/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,OAAO;IACtB,qGAAqG;IACrG,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,8HAA8H;IAC9H,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4DAA4D;IAC5D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;IAC7C,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClD"}

package/docs/guides/cfpb-circular-2023-03-ai-adverse-action-builder-guide.md

@@ -0,0 +1,261 @@
+# CFPB Circular 2023-03 (AI credit decisions): a builder's guide
+
+> **Informational only — not legal advice.** Verify against the cited
+> regulator-published text and consult counsel for production deployments.
+> See `AI-DISCLOSURE.md` in this package.
+
+If your fintech, lender, or AI-credit platform uses any model — neural
+network, gradient-boosted trees, ensemble, or even a complex linear
+model — to make adverse credit decisions on consumer applications, the
+**Consumer Financial Protection Bureau's Circular 2023-03** is the
+single most important federal regulatory guidance you need to comply
+with. The headline rule, in one sentence: *the technological complexity
+of an AI/ML model is not a defense for failing to provide ECOA-compliant
+adverse-action reasons.* This guide covers what that means in
+production, why generic reason codes are now legal liability, the
+relationship to FCRA's parallel notice obligations, and what
+explainability discipline a creditor needs in place before deploying an
+AI/ML credit model at all.
+
+## What CFPB Circular 2023-03 actually says
+
+On September 19, 2023, the CFPB issued [Circular 2023-03](https://www.consumerfinance.gov/compliance/circulars/circular-2023-03-adverse-action-notification-requirements-and-the-proper-use-of-the-cfpbs-sample-forms-provided-in-regulation-b/),
+titled *"Adverse action notification requirements and the proper use of
+the CFPB's sample forms provided in Regulation B."* The Circular
+clarifies how the long-standing adverse-action obligations of the **Equal
+Credit Opportunity Act** (15 U.S.C. § 1691(d)) and **Regulation B**
+(12 CFR § 1002.9) apply when a creditor uses AI/ML models in credit
+decisions.
+
+The two operative holdings:
+
+1. **Specific, applicant-specific reasons are required.** When a creditor
+   takes adverse action against a credit applicant, the creditor must
+   provide a statement of the *specific principal reasons* that
+   adversely affected *the applicant's specific situation*. Generic
+   model-level explanations ("failed credit-decision model", "score
+   below cutoff", "credit application incomplete") are insufficient.
+2. **Technological complexity is not a defense.** A creditor cannot
+   evade the specific-reasons obligation by claiming that the underlying
+   AI/ML model is "too complex to explain." If the creditor cannot
+   accurately identify the specific reasons that drove the model's
+   adverse decision in this applicant's case, *the creditor likely
+   cannot lawfully use the model* for credit decisions at all.
+
+The Circular is interpretive — it does not amend ECOA or Regulation B —
+but it is the CFPB's authoritative position and has been treated as
+binding in subsequent supervisory examinations.
+
+## Statutory teeth: ECOA penalties
+
+The CFPB Circular interprets ECOA. The penalties for ECOA violations
+come straight from the statute (15 U.S.C. § 1691e):
+
+- **Actual damages** to the affected applicant.
+- **Punitive damages** up to **$10,000 per individual action** or, in
+  class actions, the lesser of **$500,000 or 1% of the creditor's net
+  worth**.
+- **Attorney's fees and costs** for prevailing applicants.
+- **Equitable and declaratory relief** (e.g., orders to revise
+  adverse-action notice templates).
+
+The CFPB also exercises **supervisory and enforcement authority** under
+12 U.S.C. § 5514 and § 5515, including civil money penalties under 12
+U.S.C. § 5565 (up to $1,375,406 per day for knowing violations, in
+2026 dollars adjusted for inflation). ECOA enforcement remains a
+declared CFPB priority through 2026.
+
+## Required elements of the adverse-action notice
+
+Under Regulation B (12 CFR § 1002.9) as interpreted by Circular 2023-03,
+an adverse-action notice on an AI-driven credit decision must include:
+
+| Element | What it is | Examples |
+|---|---|---|
+| Specific principal reasons | Applicant-specific factors that drove this decision — not generic model-level language. | "(1) recent delinquencies on existing accounts; (2) high ratio of unsecured debt to monthly income; (3) short length of credit history" |
+| Right-to-statement notice | Notice that the applicant may request a written statement of the specific reasons within 60 days, and the creditor will respond within 30 days. | (Statutory language, see CFPB sample forms) |
+| ECOA equal-credit notice | Standard ECOA prohibited-bases statement and federal compliance agency identification. | (Standard language from Regulation B Appendix C) |
+| Creditor name and address | Identity of the creditor making the decision. | — |
+
+Plus the **governance-side** obligation that does not appear in the
+notice but is essential to lawful deployment:
+
+- **Model explainability sufficient to support per-applicant reason
+  codes.** This is the core compliance burden of Circular 2023-03 for
+  AI/ML credit models.
+
+## Why "specific principal reasons" is harder than it sounds
+
+Most AI/ML credit models do not natively produce reason codes. A
+gradient-boosted tree returns a score. A neural net returns a
+probability. To extract per-applicant reasons, creditors typically use
+**post-hoc explainability methods** — most commonly **SHAP** (SHapley
+Additive exPlanations) or **LIME** (Local Interpretable Model-agnostic
+Explanations).
+
+The CFPB's position, in supervisory guidance and Circular 2023-03's
+commentary, is that post-hoc explainability is **acceptable** as a
+source of reason codes — *if* the creditor has validated that the
+explanations actually reflect what drove the decision in each case.
+Three traps:
+
+1. **Plausibility is not accuracy.** SHAP values can produce
+   plausible-sounding reason codes that don't match the model's actual
+   decision logic, especially for highly correlated features. The
+   creditor must validate that the generated reasons are *correct*, not
+   just *coherent*.
+2. **Feature aggregation matters.** A creditor often has many
+   correlated features (e.g., 15 different debt-utilization features).
+   If the SHAP attribution gets spread across all 15, no single one
+   crosses the threshold for "principal reason." The creditor needs a
+   feature-grouping policy that produces reportable reason codes.
+3. **The number of reason codes.** Regulation B's official commentary
+   suggests up to **four reason codes** is a typical maximum for one
+   adverse-action notice. The model needs a pipeline that produces a
+   ranked list of specific factors limited to that count.
+
+## The "lawfully use the model" trap
+
+Circular 2023-03's most aggressive language is:
+
+> *"If a creditor cannot accurately identify the specific reasons for
+> the adverse action, the creditor likely cannot lawfully use the model
+> for credit decisions."*
+
+This is consequential. It implies a **per-model gating decision**: a
+creditor must affirmatively determine, before deploying any AI/ML
+credit model, that the model's decisions can be explained at the
+per-applicant level with accuracy adequate to support reason codes. If
+the model is a black box (opaque deep-learning ensemble with no
+explainability layer, third-party scoring API that does not provide
+reason codes, etc.), deploying it for credit decisions is itself an
+ECOA violation — *independent* of any specific notice the creditor
+sends.
+
+This shifts the compliance burden upstream into model governance:
+- Vendor due diligence: any third-party model must provide
+  per-applicant reason codes that the creditor has validated.
+- Internal model approval: the model risk management framework
+  (consistent with SR 11-7 if the creditor is a federally-supervised
+  bank, or its functional equivalent for non-bank lenders) must
+  include explainability verification.
+- Production monitoring: ongoing checks that explanations remain
+  accurate as the model is retrained.
+
+## Where the FCRA stacks
+
+Many adverse credit actions are based "in whole or in part on a
+consumer report" — which triggers a **parallel** notice obligation
+under the **Fair Credit Reporting Act**, 15 U.S.C. § 1681m(a). The FCRA
+notice has its own required elements:
+
+- The name, address, and toll-free phone number of the consumer
+  reporting agency that provided the report.
+- A statement that the CRA did not make the adverse decision and
+  cannot explain it.
+- Notice of the consumer's right to obtain a free copy of the report
+  within 60 days.
+- Notice of the consumer's right to dispute information in the report.
+
+Under 12 CFR § 1002.9(b)(2) and FCRA practice, both sets of obligations
+can be satisfied in **one combined notice** — but both sets of required
+elements must appear. AI/ML credit models that consume CRA data
+(virtually all consumer-credit AI models) fall under both regimes.
+
+## Adverse-action timing under Regulation B
+
+Independently of content, Regulation B (12 CFR § 1002.9(a)) imposes
+**timing** requirements:
+
+- **30 days** from receipt of a completed application to send adverse-
+  action notice.
+- **30 days** from taking adverse action on an existing account.
+- **90 days** from notifying the applicant of a counter-offer if the
+  applicant did not accept the counter-offer.
+
+AI/ML credit decisions are typically faster than these limits, but
+batch-pipeline architectures need to ensure the notice-generation
+service runs within the deadline even when the model retrains, model
+serving fails over, or compliance review queues create delay.
+
+## Common compliance failure patterns
+
+- **Boilerplate reason codes.** "Application did not meet underwriting
+  criteria" or "score below threshold." Per Circular 2023-03, these
+  are insufficient on their face. Each notice must reference
+  applicant-specific factors.
+- **Reason codes derived from the wrong model layer.** A creditor
+  whose production model is an XGBoost ensemble but whose reason codes
+  are pulled from a separate "explainer" linear model trained on the
+  same data is at risk: the reason codes don't reflect the actual
+  model's decision logic.
+- **Unvalidated SHAP outputs.** Using raw SHAP values as reason codes
+  without any validation that the high-attribution features actually
+  drove the decision in this case.
+- **Missing FCRA notice elements.** Adverse-action notices that meet
+  ECOA but omit FCRA's CRA identification and dispute-rights language.
+- **No model-governance gate.** Deploying a third-party scoring API
+  without validating that the API's reason codes meet ECOA's
+  specificity requirement.
+- **Late notice on AI-batch decisions.** A weekly scoring batch that
+  produces decisions on day 0 but doesn't generate notices until day
+  35 — past the 30-day deadline.
+
+## How plainstamp helps
+
+`plainstamp` ships a `us-cfpb-circular-2023-03-ai-adverse-action` rule
+that returns the live disclosure-element checklist for AI-driven
+adverse-action notices, plain-language and formal-language templates,
+citation back to ECOA + Regulation B + Circular 2023-03, and a
+`last_verified` date. Lookup:
+
+```bash
+npx plainstamp lookup --jurisdiction us \
+                      --channel email-transactional \
+                      --use-case financial-services
+```
+
+Returns the CFPB rule alongside any other federal financial-services
+rules that apply (e.g., FINRA RN 24-09 on AI in customer
+communications). For US-based lenders also operating in EU markets,
+query `--jurisdiction eu` to layer the GDPR Article 22 automated-
+decision-making obligations on top.
+
+## The minimum viable compliance posture
+
+If your AI-credit deployment is starting from zero on Circular 2023-03
+compliance, ship these four artifacts in order:
+
+1. **Per-applicant reason-code pipeline.** A documented pipeline that
+   produces ≤4 specific reason codes for every adverse decision, with
+   evidence the codes reflect applicant-specific factors.
+2. **Model explainability validation.** Documentation that the
+   reason-code pipeline produces accurate explanations — not merely
+   plausible ones. SHAP / LIME / counterfactual-based methods are
+   acceptable; what matters is the validation evidence.
+3. **Combined ECOA + FCRA adverse-action notice template.** A single
+   template that satisfies both regimes' required elements when CRA
+   data was used.
+4. **Notice-generation SLA.** Production monitoring that adverse-
+   action notices are generated and delivered within Regulation B's
+   30-day deadline, with escalation when the SLA is at risk.
+
+Then layer the higher-fidelity work — fairness testing, disparate-
+impact analysis, ongoing model performance review — onto the higher-
+risk products first.
+
+## Source-of-truth links
+
+- **CFPB Circular 2023-03** ([consumerfinance.gov](https://www.consumerfinance.gov/compliance/circulars/circular-2023-03-adverse-action-notification-requirements-and-the-proper-use-of-the-cfpbs-sample-forms-provided-in-regulation-b/))
+- **Equal Credit Opportunity Act, 15 U.S.C. § 1691(d)** ([uscode.house.gov](https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title15-section1691&num=0&edition=prelim))
+- **Regulation B, 12 CFR § 1002.9 (adverse-action notices)** ([ecfr.gov](https://www.ecfr.gov/current/title-12/chapter-X/part-1002/section-1002.9))
+- **Fair Credit Reporting Act, 15 U.S.C. § 1681m (FCRA adverse-action notices)** ([uscode.house.gov](https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title15-section1681m&num=0&edition=prelim))
+- **CFPB sample adverse-action forms (Regulation B Appendix C)** ([ecfr.gov](https://www.ecfr.gov/current/title-12/chapter-X/part-1002/appendix-Appendix%20C%20to%20Part%201002))
+
+`plainstamp` is maintained by an autonomous AI agent operating under
+KS Elevated Solutions LLC. Accuracy reports, rule-update suggestions,
+and security disclosures: [helpfulbutton140@agentmail.to](mailto:helpfulbutton140@agentmail.to).
+
+---
+
+[`← Back to plainstamp`](https://plainstamp.pages.dev/)

package/docs/guides/finra-rn-24-09-ai-customer-communications-builder-guide.md

@@ -0,0 +1,301 @@
+# FINRA Regulatory Notice 24-09 (AI in customer communications): a builder's guide
+
+> **Informational only — not legal advice.** Verify against the cited
+> regulator-published text and consult counsel for production deployments.
+> See `AI-DISCLOSURE.md` in this package.
+
+If your broker-dealer, registered representative platform, or
+fintech-with-securities-business uses generative AI or large-language
+models for any customer-facing purpose — chatbots that respond to
+client questions, AI-drafted research summaries, AI-generated email
+templates sent to clients, AI-suggested portfolio actions, AI-powered
+voice agents on the phone with retail customers — **FINRA Regulatory
+Notice 24-09** applies to you. It does not create new rules. It
+clarifies that the existing FINRA rulebook applies, in full, to
+AI-driven communications and AI-driven recommendations. This guide
+covers what that means in production, the six existing rules that
+matter most, the third-party-vendor responsibility doctrine, and what
+written supervisory procedures (WSPs) need to cover before deployment.
+
+## What FINRA Regulatory Notice 24-09 actually says
+
+On June 27, 2024, FINRA issued [Regulatory Notice 24-09](https://www.finra.org/rules-guidance/notices/24-09),
+*"FINRA Reminds Member Firms of Their Obligations When Using Generative
+Artificial Intelligence and Large Language Models."*
+
+The Notice has two operative parts:
+
+1. **Existing FINRA rules apply to AI tools.** Member firms using
+   generative AI in their securities business remain subject to all
+   existing FINRA rules — supervision (Rule 3110), communications with
+   the public (Rule 2210), suitability (Rule 2111), KYC (Rule 2090),
+   books-and-records (Rule 4511), and gifts and gratuities (Rule 3220).
+2. **Member firms remain responsible even when the tool is
+   third-party.** Outsourcing AI tool development or operation to a
+   vendor does not shift the firm's obligations. Vendor due diligence
+   and ongoing oversight are part of Rule 3110 supervision.
+
+Notice 24-09 also flags risk areas — hallucination, bias, data privacy,
+intellectual-property exposure — that firms should address in their
+written supervisory procedures.
+
+The Notice is "reminder-and-clarification" guidance: no new rule, no
+new compliance date, no new penalty. The binding obligations come from
+the existing rule text. But by issuing the Notice, FINRA established
+that AI use without WSP coverage of these rules is, at minimum, a
+**Rule 3110 supervision deficiency** by definition.
+
+## The six rules that matter
+
+### Rule 2210 — communications with the public
+
+**The standard.** All communications with the public must be fair,
+balanced, and not misleading. Communications cannot omit material
+information that would render them misleading. Specific communication
+categories (retail communications, correspondence, institutional
+communications) have specific principal-review, filing, and approval
+requirements.
+
+**How it applies to AI.** Any output of an AI tool that is delivered
+to a customer or prospective customer is a "communication with the
+public." That includes:
+
+- Chatbot responses to customer questions.
+- AI-generated email templates sent to clients.
+- AI-drafted market commentary, research summaries, or "explainers."
+- AI-suggested replies that a human rep then sends.
+
+The Rule 2210 categorization (retail vs. correspondence vs.
+institutional) and the corresponding pre-approval / filing workflow
+applies on the same terms as for human-generated communications. An
+AI-generated retail communication still needs principal pre-approval
+under Rule 2210(b)(1)(A) before delivery.
+
+### Rule 3110 — supervision
+
+**The standard.** A member firm must establish and maintain a
+supervisory system, including written supervisory procedures, that is
+reasonably designed to achieve compliance with applicable securities
+laws and FINRA rules.
+
+**How it applies to AI.** Any AI tool used in the firm's securities
+business — internally developed, third-party SaaS, fine-tuned model,
+agentic system — must be brought under the firm's supervisory system.
+That means:
+
+- Identification of AI tools in use (inventory).
+- WSPs that address AI tool review, monitoring, and exception
+  handling.
+- Designated principal responsible for AI-tool oversight.
+- Vendor due diligence for any third-party AI tool, with ongoing
+  monitoring.
+
+A firm using AI without WSP coverage of these elements has a Rule
+3110 deficiency on the face of it.
+
+### Rule 2111 — suitability
+
+**The standard.** Recommendations to retail customers must be
+suitable based on the customer's investment profile. Reg BI extends
+the standard to a "best interest" obligation for broker-dealers
+recommending to retail customers.
+
+**How it applies to AI.** AI-generated investment recommendations are
+subject to Rule 2111 (and Reg BI where applicable) on the same terms
+as human-generated recommendations. The recommendation must be
+evaluated against the customer's investment profile. The firm cannot
+escape suitability review by saying the AI generated it.
+
+Production implication: any recommendation pipeline that includes an
+AI-generation step must include a suitability-evaluation step before
+the recommendation reaches the customer. The "AI-suggested + rep
+delivers" pattern only complies if the rep performs the suitability
+review; "AI-suggested + auto-delivered" requires the suitability check
+to be in the automation.
+
+### Rule 2090 — Know Your Customer
+
+**The standard.** Firms must use reasonable diligence to know
+essential facts about every customer.
+
+**How it applies to AI.** AI tools that condition responses on
+customer data — personalized chatbots, individualized risk-assessment
+agents — must use customer data that satisfies Rule 2090's diligence
+standard. Don't feed a customer-facing AI a customer profile the firm
+hasn't reasonably verified.
+
+### Rule 4511 — books and records
+
+**The standard.** Member firms must make and preserve books and
+records as required by SEA Rules 17a-3 and 17a-4 and applicable FINRA
+rules.
+
+**How it applies to AI.** AI inputs and outputs that constitute
+communications with customers are records subject to Rule 4511's
+preservation requirements. That means:
+
+- Chatbot conversations (full transcripts) must be preserved.
+- AI-generated email content (the actual text sent) must be preserved.
+- Where the AI tool was used in a regulated activity, the prompts and
+  outputs must be retrievable in response to FINRA or SEC inquiry.
+
+Rule 4511 incorporates SEA Rule 17a-4(b)(4)'s 3-year retention period
+for communications, with WORM (write-once, read-many) format
+requirements for the first 2 years. Production AI tools need a
+recording layer that satisfies WORM and retention obligations.
+
+### Rule 3220 — gifts and gratuities
+
+**The standard.** $100/year per recipient cap on gifts; non-cash
+compensation rules apply to promotional items.
+
+**How it applies to AI.** AI-generated promotional materials, branded
+giveaways, and content marketing fall under Rule 3220 standards if
+delivered with associated gifts or non-cash compensation. The Notice
+flags this primarily as a reminder; in practice it applies to firms
+running AI-generated marketing campaigns alongside gift programs.
+
+## Third-party vendor responsibility
+
+The most consequential clarification in Notice 24-09 is that **member
+firm obligations persist when the AI tool is operated by a third-party
+vendor**. Buying a chatbot from a vendor does not transfer Rule 3110
+supervision or Rule 2210 communication standards to the vendor. The
+firm remains responsible.
+
+What this means in production:
+
+- **Pre-deployment vendor due diligence.** Before deploying a
+  third-party AI tool, the firm must evaluate the vendor's controls,
+  including model accuracy, data handling, output review mechanisms,
+  and incident response.
+- **Ongoing oversight.** The firm must monitor vendor performance and
+  output quality on an ongoing basis — not just at procurement time.
+- **Written agreement coverage.** Vendor contracts should include
+  audit rights, data-handling provisions, and incident notification
+  obligations. The firm cannot meet Rule 3110 with a contract that
+  doesn't permit visibility into the vendor's AI tool operation.
+- **Records access.** The firm must be able to produce records
+  generated by the vendor's tool in response to FINRA or SEC inquiry,
+  on the firm's regular response timeline.
+
+The "vendor pattern" most at risk: a firm uses a SaaS AI chatbot
+hosted entirely by the vendor, with no per-message logging into the
+firm's systems and no audit rights in the contract. This is a Rule
+3110 violation independent of any specific output.
+
+## Where the SEC layers on top
+
+FINRA member firms registered as broker-dealers also face SEC
+obligations that overlap with Notice 24-09's scope. Two to be aware of:
+
+- **SEC Staff Bulletin on AI/PDA conflicts of interest (July 2023).**
+  The SEC's Division of Examinations and Division of Trading and
+  Markets issued joint guidance on conflicts of interest arising from
+  AI and predictive data analytics use by broker-dealers and
+  investment advisers. The bulletin emphasizes that firms must
+  identify, disclose, and address conflicts created by AI/PDA tools.
+- **SEC Proposed Rule on Predictive Data Analytics (Rel. No.
+  34-97990, July 2023).** Would require broker-dealers and
+  investment advisers using PDA in investor-facing activities to
+  identify and address conflicts of interest associated with the
+  technology. Status: proposed; not finalized as of 2026-05-08.
+  Firms should monitor for finalization.
+- **Investment Advisers Act fiduciary duty.** For dual-registered
+  firms, the IAA fiduciary duty applies to AI-driven advice on the
+  same terms as human-driven advice.
+
+## State-level overlays to be aware of
+
+- **NYDFS October 2024 cybersecurity / AI guidance.** Applies to
+  NYDFS-licensed entities (NY-licensed insurers, banks, money
+  transmitters, virtual currency licensees). Covers AI-related
+  cybersecurity risks; firms must address AI tool risks under their
+  23 NYCRR 500 cybersecurity programs.
+- **NAIC Model Bulletin on AI use by insurers (December 2023).**
+  Adopted in form by multiple states. Applies to insurer use of AI;
+  not directly to broker-dealers but relevant for firms with
+  cross-affiliated insurance operations.
+
+## Common compliance failure patterns
+
+- **WSPs that don't mention AI.** A firm has deployed an AI chatbot
+  but its written supervisory procedures don't address AI tool use,
+  vendor oversight, or hallucination risk. Rule 3110 deficiency on
+  inspection.
+- **No principal review of AI-generated retail communications.** AI
+  produces customer-facing content that goes out without principal
+  pre-approval under Rule 2210(b)(1)(A).
+- **Records gap.** AI chatbot conversations are stored only in the
+  vendor's system, with no copy in the firm's WORM-compliant records
+  store.
+- **Hallucination tolerance.** A firm deploys an AI tool that
+  occasionally states market facts that are wrong, treating it as
+  acceptable error. Rule 2210's "not misleading" standard is
+  violated by every such output.
+- **Suitability gap on AI-suggested actions.** An AI tool suggests
+  trades or portfolio changes; the rep delivers them without an
+  individual suitability evaluation against the customer's profile.
+- **Vendor opacity.** Firm cannot produce AI tool inputs or outputs
+  on demand because the vendor's system doesn't expose them.
+
+## How plainstamp helps
+
+`plainstamp` ships a `us-finra-rn-24-09-ai-customer-communications`
+rule that returns the live disclosure-element checklist, plain-
+language and formal-language disclosure templates suitable for
+inclusion in AI-generated customer communications, citation back to
+all six FINRA rules + RN 24-09, and a `last_verified` date. Lookup:
+
+```bash
+npx plainstamp lookup --jurisdiction us \
+                      --channel live-chat \
+                      --use-case financial-services
+```
+
+Returns the FINRA rule alongside the CFPB AI adverse-action rule and
+any other federal financial-services rules. For broker-dealer
+operations in California or other state-regulated environments, layer
+state-jurisdiction queries to capture the additional state overlays.
+
+## The minimum viable compliance posture
+
+If your firm is starting from zero on Notice 24-09 compliance, ship
+these five artifacts in order:
+
+1. **AI-tool inventory.** A maintained list of every AI tool in use
+   in the firm's securities business, with owner, vendor (if any),
+   purpose, and customer-facing flag.
+2. **WSP update.** WSPs that explicitly address AI tool use under
+   each of Rules 2210, 3110, 2111, 2090, 4511, and 3220, plus
+   hallucination / bias / data-privacy / IP risk.
+3. **Records pipeline.** AI tool inputs and outputs flowing into the
+   firm's existing WORM-compliant records store, with the same
+   retention rules as other customer communications.
+4. **Principal review workflow.** AI-generated retail communications
+   reviewed by a qualified principal under Rule 2210 before delivery.
+5. **Vendor due diligence file.** Where third-party AI tools are
+   used, a documented due-diligence file with audit rights, data
+   handling, incident response, and ongoing-monitoring evidence.
+
+Then layer the higher-fidelity work — output-quality monitoring,
+hallucination-rate metrics, conflict-of-interest analysis — onto the
+higher-risk tools first.
+
+## Source-of-truth links
+
+- **FINRA Regulatory Notice 24-09** ([finra.org](https://www.finra.org/rules-guidance/notices/24-09))
+- **FINRA Rule 2210 (Communications with the Public)** ([finra.org](https://www.finra.org/rules-guidance/rulebooks/finra-rules/2210))
+- **FINRA Rule 3110 (Supervision)** ([finra.org](https://www.finra.org/rules-guidance/rulebooks/finra-rules/3110))
+- **FINRA Rule 2111 (Suitability)** ([finra.org](https://www.finra.org/rules-guidance/rulebooks/finra-rules/2111))
+- **FINRA Rule 2090 (Know Your Customer)** ([finra.org](https://www.finra.org/rules-guidance/rulebooks/finra-rules/2090))
+- **FINRA Rule 4511 (Books and Records)** ([finra.org](https://www.finra.org/rules-guidance/rulebooks/finra-rules/4511))
+- **SEC Proposed Rule on PDA Conflicts (Rel. No. 34-97990)** ([sec.gov](https://www.sec.gov/rules-regulations/2023/07/s7-12-23))
+
+`plainstamp` is maintained by an autonomous AI agent operating under
+KS Elevated Solutions LLC. Accuracy reports, rule-update suggestions,
+and security disclosures: [helpfulbutton140@agentmail.to](mailto:helpfulbutton140@agentmail.to).
+
+---
+
+[`← Back to plainstamp`](https://plainstamp.pages.dev/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plainstamp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "AI disclosure compliance assistant — generates legally-grounded AI disclosure text per (jurisdiction × channel × use-case) and tracks regulatory updates. Operated by an autonomous AI agent under KS Elevated Solutions LLC.",
   "type": "module",
   "license": "MIT",