plainstamp 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -16,6 +16,29 @@ 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.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
+
+- README now features the hosted MCP Streamable-HTTP endpoint at `https://plainstamp.helpfulbutton140.workers.dev/mcp` — no install required for clients that prefer the hosted transport.
+- README documents the parallel JSON-over-HTTP API on the same Worker (`/jurisdictions`, `/rules`, `/lookup`, `/validate`) for clients that don't speak MCP.
+- Coverage table refreshed against the live 23-rule corpus and reorganized by jurisdiction tier (federal / state / city / EU). Federal additions now visible in README: EEOC, CFPB, FINRA, HHS Section 1557, FDA PCCP, FCC TCPA. State additions: SB 1120, Tennessee ELVIS Act. EU: GDPR Article 22.
+
+No code changes; npm publish refreshes the README rendered on npmjs.com.
+
 ## [0.7.1] — 2026-05-08
 
 ### Fixed (cross-runtime compatibility)

package/README.md

@@ -93,6 +93,38 @@ Add to your MCP config:
 
 The server speaks the standard MCP stdio transport. Spawn `npx plainstamp mcp` (or run `node dist/mcp-server.js` from a checkout) and connect to its stdin/stdout.
 
+### Hosted MCP HTTP endpoint
+
+A hosted MCP Streamable-HTTP endpoint runs on Cloudflare Workers — no install required:
+
+```
+https://plainstamp.helpfulbutton140.workers.dev/mcp
+```
+
+It speaks the standard MCP Streamable-HTTP transport (`POST` JSON-RPC, `GET`/`DELETE` per spec) and exposes the same five tools as the stdio server. Stateless, free to call.
+
+## Hosted JSON API
+
+The same Worker also exposes a plain JSON-over-HTTP API at `https://plainstamp.helpfulbutton140.workers.dev` for clients that don't speak MCP:
+
+```
+GET  /                       service info + bundled-rule version
+GET  /health                 liveness probe
+GET  /jurisdictions          list supported jurisdiction ids
+GET  /rules                  list compact rule summaries
+GET  /rules/:id              full rule by id
+GET  /lookup?jurisdiction=&channel=&use_case=
+                             applicable rules + generated text
+POST /validate               { jurisdiction, channel, use_case, candidate_text }
+                             heuristic compliance check
+```
+
+Example:
+
+```bash
+curl "https://plainstamp.helpfulbutton140.workers.dev/lookup?jurisdiction=us-ca&channel=live-chat&use_case=b2c-customer-support"
+```
+
 ## Library
 
 ```ts
@@ -131,24 +163,52 @@ const reports = validateDisclosureForQuery(
 
 ## Coverage
 
+23 rules across 11 jurisdictions, last verified 2026-05-08.
+
+**Federal (US):**
+
+| Rule | Jurisdiction | Effective | Last verified |
+|---|---|---|---|
+| FTC rule on fake reviews and testimonials (16 CFR Part 465) | us | 2024-10-21 | 2026-05-08 |
+| EEOC Title VII technical assistance — AI selection procedures (2023) | us | 2023-05-18 | 2026-05-08 |
+| CFPB Circular 2023-03 — adverse-action notices for AI credit decisions (ECOA / Regulation B) | us | 2023-09-19 | 2026-05-08 |
+| FINRA Regulatory Notice 24-09 — AI in customer communications | us | 2024-06-27 | 2026-05-08 |
+| HHS Section 1557 — Patient Care Decision Support Tools nondiscrimination (2024 final rule) | us | 2025-05-01 | 2026-05-08 |
+| FDA Predetermined Change Control Plans for AI/ML-Enabled Device Software | us | 2024-12-04 | 2026-05-08 |
+| FCC Declaratory Ruling — AI-generated voice in robocalls under TCPA (Feb 2024) | us | 2024-02-08 | 2026-05-08 |
+
+**State (US):**
+
 | Rule | Jurisdiction | Effective | Last verified |
 |---|---|---|---|
 | California bot disclosure (B&P § 17941) | us-ca | 2019-07-01 | 2026-05-08 |
-| EU AI Act Article 50(1) — chatbot disclosure | eu | 2026-08-02 | 2026-05-08 |
-| EU AI Act Article 50(2) — AI-generated content labeling | eu | 2026-08-02 | 2026-05-08 |
-| FTC fake reviews/testimonials (16 CFR Part 465) | us | 2024-10-21 | 2026-05-08 |
-| California AI Transparency Act (SB 942) | us-ca | 2026-01-01 | 2026-05-08 |
+| California AI provenance and labeling (SB 942 / AB 2655 family) | us-ca | 2026-01-01 | 2026-05-08 |
+| California AB 2013 — Generative AI Training Data Transparency Act | us-ca | 2026-01-01 | 2026-05-08 |
+| California SB 1120 — Physicians Make Decisions Act (utilization review) | us-ca | 2025-01-01 | 2026-05-08 |
 | Colorado AI Act (SB 24-205) — consumer disclosure | us-co | 2026-06-30 | 2026-05-08 |
 | Utah AI Policy Act (SB 149, as amended by SB 226 / SB 332) | us-ut | 2024-05-01 | 2026-05-08 |
-| Texas TRAIGA (HB 149) — government agency | us-tx | 2026-01-01 | 2026-05-08 |
-| Texas TRAIGA (HB 149) — healthcare provider | us-tx | 2026-01-01 | 2026-05-08 |
+| Texas TRAIGA (HB 149) — government agency disclosure | us-tx | 2026-01-01 | 2026-05-08 |
+| Texas TRAIGA (HB 149) — healthcare-provider disclosure | us-tx | 2026-01-01 | 2026-05-08 |
 | New York AI Companion Models (NY GBL Art. 47, A6767) | us-ny | 2025-11-05 | 2026-05-08 |
 | Illinois Human Rights Act — AI in employment (HB 3773) | us-il | 2026-01-01 | 2026-05-08 |
-| NYC Local Law 144 — Automated Employment Decision Tools | us-ny-nyc | 2023-07-05 | 2026-05-08 |
-| California AB 2013 — Generative AI Training Data Transparency | us-ca | 2026-01-01 | 2026-05-08 |
 | Maryland LE § 3-717 — facial recognition in interviews (HB 1202) | us-md | 2020-10-01 | 2026-05-08 |
+| Tennessee ELVIS Act — voice and likeness protection (HB 2091 / SB 2096) | us-tn | 2024-07-01 | 2026-05-08 |
+
+**City (US):**
+
+| Rule | Jurisdiction | Effective | Last verified |
+|---|---|---|---|
+| NYC Local Law 144 — Automated Employment Decision Tools | us-ny-nyc | 2023-07-05 | 2026-05-08 |
+
+**EU:**
+
+| Rule | Jurisdiction | Effective | Last verified |
+|---|---|---|---|
+| EU AI Act Article 50(1) — chatbot disclosure | eu | 2026-08-02 | 2026-05-08 |
+| EU AI Act Article 50(2) — AI-generated content labeling | eu | 2026-08-02 | 2026-05-08 |
+| EU GDPR Article 22 — automated decision-making rights | eu | 2018-05-25 | 2026-05-08 |
 
-Coverage will expand to EU member-state implementations and sector-specific rules (healthcare, financial services). See [`CHANGELOG.md`](CHANGELOG.md).
+Coverage continues to expand. See [`CHANGELOG.md`](CHANGELOG.md).
 
 ## Disclaimers
 

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":"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"}

package/dist/watcher/sources/federal-register.d.ts

@@ -1,13 +1,21 @@
 import type { Source } from "../types.js";
 /**
- * Federal Register source. Fetches recent rules and proposed rules matching
- * a search term (default: "artificial intelligence"). The Federal Register
- * search is permissive — results often include items only tangentially
- * related — so the orchestrator should treat new articles as candidates for
- * review rather than guaranteed plainstamp-relevant updates.
+ * Federal Register source. Fetches recent rules, proposed rules, agency
+ * notices, and presidential documents matching a search term (default:
+ * "artificial intelligence"). The Federal Register search is permissive —
+ * results often include items only tangentially related — so the
+ * orchestrator should treat new articles as candidates for review rather
+ * than guaranteed plainstamp-relevant updates.
+ *
+ * Notices and presidential documents are included alongside rules and
+ * proposed rules because much actionable AI regulatory activity (FCC
+ * declaratory rulings, OCC bulletins, OMB memoranda, executive orders)
+ * appears in those categories rather than in formal rulemaking.
  */
 export declare function federalRegisterSource(opts?: {
     searchTerm?: string;
     perPage?: number;
+    /** Override the default doc-type filter. Defaults to RULE + PRORULE + NOTICE + PRESDOCU. */
+    types?: ReadonlyArray<"RULE" | "PRORULE" | "NOTICE" | "PRESDOCU">;
 }): Source;
 //# sourceMappingURL=federal-register.d.ts.map

package/dist/watcher/sources/federal-register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"federal-register.d.ts","sourceRoot":"","sources":["../../../src/watcher/sources/federal-register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAmBnD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAsCT"}
+{"version":3,"file":"federal-register.d.ts","sourceRoot":"","sources":["../../../src/watcher/sources/federal-register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAmBnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC;CACnE,GAAG,MAAM,CAwCT"}

package/dist/watcher/sources/federal-register.js

@@ -1,23 +1,31 @@
 const ENDPOINT = "https://www.federalregister.gov/api/v1/articles.json";
 /**
- * Federal Register source. Fetches recent rules and proposed rules matching
- * a search term (default: "artificial intelligence"). The Federal Register
- * search is permissive — results often include items only tangentially
- * related — so the orchestrator should treat new articles as candidates for
- * review rather than guaranteed plainstamp-relevant updates.
+ * Federal Register source. Fetches recent rules, proposed rules, agency
+ * notices, and presidential documents matching a search term (default:
+ * "artificial intelligence"). The Federal Register search is permissive —
+ * results often include items only tangentially related — so the
+ * orchestrator should treat new articles as candidates for review rather
+ * than guaranteed plainstamp-relevant updates.
+ *
+ * Notices and presidential documents are included alongside rules and
+ * proposed rules because much actionable AI regulatory activity (FCC
+ * declaratory rulings, OCC bulletins, OMB memoranda, executive orders)
+ * appears in those categories rather than in formal rulemaking.
  */
 export function federalRegisterSource(opts) {
     const term = opts?.searchTerm ?? "artificial intelligence";
     const perPage = opts?.perPage ?? 20;
+    const types = opts?.types ?? ["RULE", "PRORULE", "NOTICE", "PRESDOCU"];
     const id = `federal-register-${term.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
     return {
         id,
-        description: `Federal Register articles (Rules and Proposed Rules) matching "${term}"`,
+        description: `Federal Register articles (${types.join(", ")}) matching "${term}"`,
         async fetch() {
             const url = new URL(ENDPOINT);
             url.searchParams.set("conditions[term]", term);
-            url.searchParams.append("conditions[type][]", "RULE");
-            url.searchParams.append("conditions[type][]", "PRORULE");
+            for (const t of types) {
+                url.searchParams.append("conditions[type][]", t);
+            }
             url.searchParams.set("per_page", String(perPage));
             url.searchParams.set("order", "newest");
             const res = await fetch(url.toString());

package/dist/watcher/sources/federal-register.js.map

@@ -1 +1 @@
-{"version":3,"file":"federal-register.js","sourceRoot":"","sources":["../../../src/watcher/sources/federal-register.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,sDAAsD,CAAC;AAiBxE;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAGrC;IACC,MAAM,IAAI,GAAG,IAAI,EAAE,UAAU,IAAI,yBAAyB,CAAC;IAC3D,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;IACpC,MAAM,EAAE,GAAG,oBAAoB,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;IAEjF,OAAO;QACL,EAAE;QACF,WAAW,EAAE,kEAAkE,IAAI,GAAG;QACtF,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;YAC/C,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;YACtD,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,oBAAoB,EAAE,SAAS,CAAC,CAAC;YACzD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAClD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAExC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,sCAAsC,GAAG,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,EAAE,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAe,CAAC;YAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9B,EAAE,EAAE,CAAC,CAAC,eAAe;gBACrB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,QAAQ;gBACf,WAAW,EAAE,CAAC,CAAC,gBAAgB;gBAC/B,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;oBACjD,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;oBACzB,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS;oBAC1B,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;oBAC7C,CAAC,CAAC,EAAE,CAAC;gBACP,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aACxB,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"federal-register.js","sourceRoot":"","sources":["../../../src/watcher/sources/federal-register.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,sDAAsD,CAAC;AAiBxE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAKrC;IACC,MAAM,IAAI,GAAG,IAAI,EAAE,UAAU,IAAI,yBAAyB,CAAC;IAC3D,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,oBAAoB,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;IAEjF,OAAO;QACL,EAAE;QACF,WAAW,EAAE,8BAA8B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,GAAG;QACjF,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;YAC/C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;YACnD,CAAC;YACD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAClD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAExC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,sCAAsC,GAAG,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,EAAE,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAe,CAAC;YAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9B,EAAE,EAAE,CAAC,CAAC,eAAe;gBACrB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,QAAQ;gBACf,WAAW,EAAE,CAAC,CAAC,gBAAgB;gBAC/B,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;oBACjD,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;oBACzB,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS;oBAC1B,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;oBAC7C,CAAC,CAAC,EAAE,CAAC;gBACP,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aACxB,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;AACJ,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/docs/guides/hhs-section-1557-pcdst-builder-guide.md

@@ -0,0 +1,268 @@
+# HHS Section 1557 (Patient Care Decision Support Tools): 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 healthcare organization deploys an AI/ML clinical decision-support
+tool — sepsis risk scores, discharge risk models, prior-auth scoring, AI
+triage chatbots, anything that informs a care decision — and the
+organization receives any federal financial assistance (Medicare,
+Medicaid, federally-qualified health center funding, etc.), HHS Section
+1557's **Patient Care Decision Support Tool (PCDST) nondiscrimination
+rule** applies to you. The rule has been enforceable since **May 1, 2025**
+and is one of the most concrete federal AI compliance regimes operating
+today. This guide covers what it requires, who is covered, what counts
+as compliance, and the elements that catch builders off guard.
+
+## What 45 CFR § 92.210 actually requires
+
+On May 6, 2024, the U.S. Department of Health and Human Services Office
+for Civil Rights (HHS OCR) published a final rule (89 Fed. Reg. 37522)
+implementing Section 1557 of the Affordable Care Act (42 U.S.C. § 18116).
+The rule, codified at 45 CFR Part 92 and effective in stages with PCDST
+enforcement starting May 1, 2025, imposes nondiscrimination obligations
+on covered entities' use of "patient care decision support tools" — a
+deliberately broad category that **includes AI/ML-based clinical
+decision support**.
+
+A covered entity must:
+
+1. **Identify uses of PCDSTs** in its health programs and activities that
+   employ input variables or factors that measure race, color, national
+   origin, sex, age, or disability.
+2. **Mitigate the risk of discrimination** resulting from each such tool's
+   use.
+
+Both obligations are framed as "reasonable efforts" — OCR has stated in
+commentary that what is reasonable scales with the entity's size, resources,
+and the tool's risk profile. But documentation of those efforts is essential.
+
+Penalties: loss of federal financial assistance, OCR-imposed corrective
+action plans, potential private right-of-action discrimination claims,
+and reputational fallout. OCR has historically taken Section 1557 seriously
+in enforcement.
+
+## What's a "PCDST" — and why it sweeps in basically every clinical AI
+
+OCR's definition of patient care decision support tool is broad on
+purpose:
+
+> *"any automated or non-automated tool, mechanism, method, technology,
+> or combination thereof used by a covered entity to support clinical
+> decision-making in its health programs or activities."*
+
+This explicitly includes:
+
+- **AI/ML clinical decision support** tools (the central focus of OCR's
+  commentary).
+- **Rule-based scoring algorithms** (e.g., MEWS, NEWS, qSOFA, CHA₂DS₂-VASc).
+- **Tools that consume race, sex, age, etc. as input variables** — the
+  Epic Sepsis Model, the Beth Israel Deaconess Discharge Risk Score, and
+  many commonly-deployed risk scores.
+- **Tools that produce clinical scores** even where the underlying
+  computation is non-AI. Statistical models count.
+- **Triage and routing tools** that affect access to clinical resources.
+
+The "non-automated" inclusion is significant: paper-based scoring sheets
+that a clinician uses to allocate care also count. The rule is not
+specific to digital tools.
+
+Three definitional gotchas:
+
+- **"Used by a covered entity to support clinical decision-making."** A
+  tool merely available in the EHR but never actually consulted in a
+  clinical decision is arguably not in scope. A tool that's part of any
+  routine workflow — even informally — is in scope.
+- **"Input variables or factors that measure race, color, national origin,
+  sex, age, or disability."** This is broader than just having a literal
+  "race" field. Tools that use ZIP code (proxy for race), insurance type
+  (proxy for income/national origin), or chronic condition counts (proxy
+  for disability) are within the identification obligation.
+- **OCR's "reasonable efforts" standard scales but doesn't disappear.**
+  A small rural clinic doesn't have the same compliance burden as a
+  major academic medical center, but both must do something.
+
+## Who is a "covered entity"
+
+Section 1557 applies broadly to any health program or activity that
+receives federal financial assistance. In practice this includes:
+
+- **Most healthcare providers** that participate in Medicare or Medicaid
+  (effectively almost all hospitals, most physician practices, most
+  long-term care facilities).
+- **Federally-qualified health centers** and their clinical operations.
+- **Health insurers in HHS-administered marketplaces** (and many
+  Medicaid managed care organizations).
+- **HHS-administered programs** themselves (Indian Health Service, etc.).
+- **Any program receiving federal grants** with health-related components.
+
+Three exclusions to know about:
+
+- **ERISA self-funded employer health plans** that don't otherwise
+  receive federal financial assistance are typically outside Section 1557
+  (though they may have parallel obligations under ERISA + state law).
+- **Cash-only or fully-private practices** that decline all federal
+  funding may be outside Section 1557 (rare; most providers participate
+  in Medicare).
+- **Federal contractors providing non-health services** — not in scope
+  even if their contractor receives federal money.
+
+## What "reasonable efforts" actually looks like
+
+OCR commentary and informal guidance suggest a **risk-tiered approach**:
+
+**Higher-risk tools (more documentation expected):**
+- Tools that explicitly use race, sex, age, or disability as input
+  variables.
+- Tools used in life-threatening contexts (sepsis prediction, organ
+  transplant risk).
+- Tools that affect resource allocation across patients (ICU bed
+  triage, transplant priority).
+
+**Lower-risk tools (lighter documentation acceptable):**
+- Tools that don't use protected-class variables.
+- Tools that surface information without producing a ranking or score.
+- Tools whose output is one of many factors in a clinician's
+  unstructured judgment.
+
+Concrete documentation to maintain for each PCDST:
+
+1. **Tool inventory entry** — name, vendor, purpose, deployment date,
+   input variables (with notation of any protected-class factors), use
+   cases, decision contexts.
+2. **Mitigation documentation** — what the entity has done to identify
+   and mitigate the risk of discriminatory output. Examples: vendor's
+   bias-audit report, internal performance comparison across protected
+   classes, threshold adjustments, monitoring dashboards.
+3. **Designation** — the Civil Rights Coordinator (a Section 1557 §
+   92.7 requirement) is responsible for PCDST nondiscrimination.
+4. **Periodic review** — at least annual review of the tool's
+   performance, documented.
+
+## The patient-facing element (most builders miss this)
+
+The PCDST rule's primary obligation is *governance-side* — identification
+and mitigation. But where the entity exposes AI-informed decisions to
+patients (or where notice-of-availability obligations under § 92.11 apply),
+a **patient-facing notice** that automated tools may inform clinical
+decisions is also expected. The notice typically lives in:
+
+- The Section 1557 notice of nondiscrimination (printed and posted
+  per § 92.10).
+- Patient-facing materials about specific decisions (denial letters,
+  triage explanations).
+
+Plain-language template:
+
+> *"Notice — Use of Decision-Support Tools in Your Care: Some clinical
+> decisions in your care may be informed by automated decision-support
+> tools, including artificial-intelligence and machine-learning systems.
+> These tools assist your healthcare team and do not replace the
+> judgment of a licensed clinician. You have the right to discuss any
+> care decision with your provider. If you believe you have experienced
+> discrimination on the basis of race, color, national origin, sex, age,
+> or disability in connection with these tools or any other aspect of
+> your care, please contact our Civil Rights Coordinator at [contact]
+> or file a complaint with the HHS Office for Civil Rights at
+> https://www.hhs.gov/ocr/."*
+
+## How Section 1557 stacks with other rules
+
+Section 1557 is the federal floor for healthcare AI nondiscrimination.
+Builders deploying AI/ML clinical tools at scale need to layer:
+
+- **California SB 1120 (Physicians Make Decisions Act)** — adds a
+  *procedural* requirement: AI used in utilization review for medical
+  necessity must be reviewed by a licensed physician considering the
+  enrollee's clinical circumstances. Effective January 1, 2025.
+  California-specific.
+- **FDA Predetermined Change Control Plans (FD&C Act § 515C, December
+  2024 final guidance)** — applies to AI/ML medical devices that have
+  been cleared/authorized by FDA. Adds device-labeling AI/ML disclosure
+  obligations.
+- **HIPAA Privacy Rule (45 CFR Part 164)** — separate privacy regime.
+  Section 1557 doesn't change HIPAA; both apply.
+- **State medical-board rules** on AI in scope of practice (Texas,
+  several others have specific scope-of-practice rules for AI).
+- **EU AI Act + GDPR Art. 22** — for any care delivered to EU residents,
+  including telehealth.
+- **NIST AI RMF + healthcare-sector profile** — voluntary but widely
+  treated as a benchmark by hospital AI committees.
+
+## Common compliance pitfalls
+
+- **Treating "vendor said the model was bias-audited" as enough.** OCR
+  commentary expects the covered entity to do its own due diligence;
+  vendor audits are an input, not a substitute.
+- **Forgetting non-AI tools.** The rule covers any decision-support
+  tool, not just AI. Rule-based scoring tools that use protected-class
+  variables are within scope.
+- **Documenting only the highest-risk tools.** OCR expects an
+  identification process for *all* PCDSTs, even if most have minimal
+  mitigation documentation.
+- **No designated Civil Rights Coordinator with PCDST awareness.** The
+  Coordinator role under § 92.7 needs to know about the entity's AI/ML
+  tools; siloing AI governance from CRC creates compliance gaps.
+- **Skipping the patient-facing language** under the assumption that
+  PCDST obligations are purely governance. Where AI informs decisions
+  exposed to patients, notice is expected.
+- **Annual review never happens.** Documentation that the tool's
+  performance is monitored and reviewed is part of the "reasonable
+  efforts" standard.
+
+## How plainstamp helps
+
+`plainstamp` ships an `us-hhs-section-1557-pcdst-2024` rule that
+returns the live disclosure-element checklist for the PCDST regime,
+plain-language and formal-language patient-facing notices, citation
+back to 45 CFR § 92.210 + the Federal Register source URL, and a
+`last_verified` date. Lookup:
+
+```bash
+npx plainstamp lookup --jurisdiction us \
+                      --channel ai-generated-content \
+                      --use-case healthcare
+```
+
+Returns the Section 1557 PCDST rule. For California-operating entities,
+also query `--jurisdiction us-ca` to layer on SB 1120's
+physician-review requirement.
+
+For multi-jurisdiction systems, query each state's healthcare
+jurisdiction in parallel — the disclosure copy must satisfy each
+applicable layer.
+
+## The minimum viable compliance posture
+
+If your organization is starting from zero on PCDST nondiscrimination,
+ship these four artifacts in order:
+
+1. **PCDST inventory** — a spreadsheet/database of every clinical
+   decision-support tool in use, with input variables and protected-
+   class flags.
+2. **Civil Rights Coordinator briefing** — your CRC reads the inventory
+   and signs off that mitigation efforts are documented for each tool.
+3. **Patient-facing notice** — added to the entity's Section 1557
+   nondiscrimination notice and to patient-facing materials about
+   AI-informed decisions.
+4. **Annual review schedule** — calendar entry for next-year review
+   of each tool's performance and mitigation.
+
+Then, layer the higher-fidelity work — vendor diligence, performance
+testing, bias audits — onto the higher-risk tools first.
+
+## Source-of-truth links
+
+- **45 CFR § 92.210 (PCDST nondiscrimination)** ([ecfr.gov](https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-A/part-92/subpart-C/section-92.210))
+- **HHS OCR final rule, May 6, 2024 (89 Fed. Reg. 37522)** ([federalregister.gov](https://www.federalregister.gov/documents/2024/05/06/2024-08711/nondiscrimination-in-health-programs-and-activities))
+- **Section 1557 of the ACA (42 U.S.C. § 18116)** ([uscode.house.gov](https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title42-section18116&num=0&edition=prelim))
+- **HHS OCR Section 1557 program page** ([hhs.gov/ocr](https://www.hhs.gov/civil-rights/for-providers/laws-regulations-guidance/laws/section-1557/index.html))
+
+`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.1",
+  "version": "0.7.3",
   "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",