@nationaldesignstudio/rampart 0.1.1

package/dist/src/pipeline.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The PII filter pipeline: the single entry point a chat app wires in.
+ *
+ *   user message
+ *     → heuristics (sync, structured PII)
+ *     → NER (optional, async, contextual PII)
+ *     → merge + default-deny policy (keep {city, state, zip})
+ *     → session table: replace with stable placeholders
+ *     → send placeholdered text to the LLM
+ *   assistant reply
+ *     → outbound scrub (model can echo/emit PII too)
+ *     → rehydrate placeholders → render to user
+ *
+ * Heuristics run synchronously so the structured PII (SSNs in any separator
+ * form, cards, phones, emails) is gone immediately even before the model loads.
+ * The NER detector is injected, so callers can run it on a worker, skip it in
+ * tests, or swap models without touching this orchestration.
+ */
+import { type PlaceholderAliases, type ScrubResult } from "./session";
+import type { Span } from "./types";
+/** An async contextual detector. Matches both the in-process and worker forms. */
+export type NerDetector = (text: string) => Promise<Span[]>;
+export interface FilterOptions {
+    /** Optional contextual detector. Omit to run heuristics-only. */
+    readonly ner?: NerDetector;
+    /** Display aliases for placeholder tokens, e.g. `{ GIVEN_NAME: "NAME" }`. */
+    readonly aliases?: PlaceholderAliases;
+    /**
+     * When `true`, skip the structured-PII premask before the model. Use this with
+     * a model trained without prefilter (no-prefilter ablation), whose classes
+     * include SSN / CREDIT_CARD / IP_ADDRESS — the model expects raw digits, not
+     * sentinels. Heuristic spans for those types are still emitted and merged, so
+     * they act as belt-and-suspenders for the model's predictions.
+     */
+    readonly noPrefilter?: boolean;
+}
+/**
+ * Stateful filter bound to one conversation. Holds the session entity table so
+ * placeholders stay consistent across turns and rehydration can reverse them.
+ */
+export declare class PiiFilter {
+    private readonly options;
+    private readonly table;
+    constructor(options?: FilterOptions);
+    /**
+     * Detect all PII in a message: heuristics always, NER when configured.
+     *
+     * The heuristic layer (structured PII: SSN / CREDIT_CARD / IP_ADDRESS) runs
+     * first and its spans are substituted with neutral sentinels before the text
+     * reaches the model — the same masking the model was trained on, so it never
+     * sees raw structured digits. The model's spans, reported in masked
+     * coordinates, are projected back to raw offsets and merged with the
+     * (raw-offset) heuristic spans for redaction.
+     */
+    private detect;
+    /**
+     * Scrub an outgoing user message. The returned `text` is what may be sent to
+     * the LLM and written to logs — it contains no PII outside the keep-set.
+     */
+    scrubOutbound(text: string): Promise<ScrubResult>;
+    /**
+     * Restore real values in an assistant reply before showing it to the user.
+     * Run on every model response: the model reasons over placeholders and may
+     * repeat them, and we must not surface a bare `[PERSON_1]`.
+     */
+    rehydrateInbound(reply: string): string;
+    /**
+     * Defense in depth: scrub the *model's* output too. A model can emit PII the
+     * user never typed (hallucinated or inferred), so re-run detection on the
+     * reply and placeholder anything new before it is logged or persisted.
+     */
+    scrubInbound(reply: string): Promise<ScrubResult>;
+}
+/** Stateless one-shot scrub for non-conversational callers (e.g. log sinks). */
+export declare function scrubOnce(text: string, options?: FilterOptions): Promise<string>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/src/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,qBAAa,SAAS;IAGR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAEd,OAAO,GAAE,aAAkB;IAIxD;;;;;;;;;OASG;YACW,MAAM;IAoBpB;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKvD;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIvC;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAIxD;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1F"}

package/dist/src/policy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Span reconciliation + default-deny policy.
+ *
+ * Detectors (heuristic + NER) emit overlapping, possibly conflicting spans.
+ * {@link mergeSpans} resolves them into a non-overlapping set, then
+ * {@link applyPolicy} drops anything in the keep-set so only redactable spans
+ * remain. This is Option A: redact detected entities whose label is not kept.
+ */
+import { type PiiLabel, type Span } from "./types";
+/**
+ * Reduce overlapping spans to a disjoint set. When two spans overlap, the
+ * higher-confidence one wins; ties break toward the longer span, then toward
+ * heuristics (validator-backed, so most trustworthy). Biased to *keep* a
+ * redaction rather than drop one — recall over precision, per the threat model.
+ *
+ * On partial overlap (neither span contains the other) the previous span
+ * covers bytes the winner does not. Taking only the winner exposes those
+ * bytes; we take the byte-union under the preferred label so no detected
+ * bytes are silently dropped. Full containment still collapses to the winner.
+ */
+export declare function mergeSpans(spans: readonly Span[]): Span[];
+/**
+ * Apply the keep-set. Returns only spans that must be redacted, sorted right to
+ * left so callers can splice from the end and keep earlier offsets valid.
+ */
+export declare function applyPolicy(spans: readonly Span[], keepLabels?: ReadonlySet<PiiLabel>): Span[];
+//# sourceMappingURL=policy.d.ts.map

package/dist/src/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAA6B,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,IAAI,EAAE,CAuBzD;AAUD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,UAAU,GAAE,WAAW,CAAC,QAAQ,CAAe,GAAG,IAAI,EAAE,CAI3G"}

package/dist/src/premask.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pre-mask harness: substitute deterministically-detected structured PII with
+ * neutral sentinels *before* the contextual model runs.
+ *
+ * The heuristic layer (SSN / CREDIT_CARD / IP_ADDRESS / EMAIL / URL) is
+ * validator- or pattern-backed and runs synchronously. Rather than show the
+ * model raw card/SSN/IP digits or email/URL strings — which it never needs to
+ * classify and which only add noise — we replace each heuristic span with a
+ * fixed sentinel token (`[SSN]`, `[CREDIT_CARD]`, `[IP_ADDRESS]`, ...). The model
+ * is trained on text masked the exact same way, so the train-time and
+ * inference-time input distributions match by construction.
+ *
+ * Offsets: the masked string is paired with a per-character map back to the raw
+ * input, so a span the model reports in masked coordinates can be projected to
+ * exact raw offsets. Sentinel characters map onto their source span's raw range,
+ * so if the model happens to label part of a sentinel the projection lands
+ * inside the heuristic span (which then wins the merge on its score-1 weight).
+ *
+ * The heuristic spans themselves are returned with their original raw offsets,
+ * so final redaction and the session table are unaffected: only the text handed
+ * to the model is masked, never the text that gets placeholdered.
+ */
+import type { PiiLabel, Span } from "./types";
+/** A masked copy of the input plus a map from each masked char to raw offsets. */
+export interface PremaskResult {
+    /** Input with heuristic spans replaced by sentinel tokens. */
+    readonly masked: string;
+    /** `rawStart[i]` is the raw offset of the source of `masked[i]`. */
+    readonly rawStart: number[];
+    /** `rawEnd[i]` is the raw offset just past that source. */
+    readonly rawEnd: number[];
+}
+/** The sentinel substituted for a premasked label. Stable across train/serve. */
+export declare function sentinelFor(label: PiiLabel): string;
+/**
+ * Replace each (disjoint) heuristic span in `raw` with its label sentinel,
+ * recording per masked-character raw offsets. Spans are merged first so they are
+ * non-overlapping; verbatim runs between spans map 1:1 to raw, and sentinel
+ * characters map onto the whole span they stand in for.
+ */
+export declare function premask(raw: string, spans: readonly Span[]): PremaskResult;
+/**
+ * Project a span reported in masked coordinates back onto the raw input. Returns
+ * `null` for an empty/degenerate span. The raw `text` is sliced from `raw` so
+ * callers always carry the real substring for rehydration.
+ */
+export declare function projectMaskedSpan(span: Span, raw: string, map: PremaskResult): Span | null;
+//# sourceMappingURL=premask.d.ts.map

package/dist/src/premask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"premask.d.ts","sourceRoot":"","sources":["../../src/premask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE9C,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,aAAa,CA6B1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAM1F"}

package/dist/src/session.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Session entity table: reversible placeholders for coherent chat.
+ *
+ * Blanket `[REDACTED]` makes the assistant's replies nonsense. Instead each
+ * redacted value gets a stable, typed placeholder (`[GIVEN_NAME_1]`, `[SSN_2]`)
+ * that survives across turns: the same raw value always maps to the same token,
+ * so the model can reason about "GIVEN_NAME_1" and we {@link rehydrate} the real
+ * value back into its reply before display.
+ *
+ * The map lives only on the client. What leaves the device is placeholdered
+ * text; the table never crosses the wire.
+ */
+import { type PiiLabel, type Span } from "./types";
+/** Result of scrubbing one message. */
+export interface ScrubResult {
+    /** Text with PII replaced by placeholders. Safe to send/log. */
+    readonly text: string;
+    /** Placeholders introduced or reused in this message. */
+    readonly placeholders: readonly string[];
+}
+/**
+ * Optional display aliases for placeholder tokens. By default a GIVEN_NAME span
+ * becomes `[GIVEN_NAME_1]`; pass `{ GIVEN_NAME: "NAME" }` to get `[NAME_1]` instead.
+ * Only the visible token changes — detection and policy are unaffected.
+ */
+export type PlaceholderAliases = Partial<Record<PiiLabel, string>>;
+/** Token shape minted by the table; also the regex used to find them on the
+ * way back. Kept in one place so scrub and rehydrate can never disagree. */
+export declare const PLACEHOLDER_PATTERN: RegExp;
+/**
+ * A per-conversation store mapping raw PII values to stable placeholders.
+ * Keyed by `label + normalized value` so "John" stays `GIVEN_NAME_1` on every turn
+ * and casing/whitespace noise doesn't mint duplicate tokens.
+ */
+export declare class SessionEntityTable {
+    private readonly aliases;
+    private readonly keepLabels;
+    private readonly forward;
+    private readonly reverse;
+    private readonly counters;
+    constructor(aliases?: PlaceholderAliases, keepLabels?: ReadonlySet<PiiLabel>);
+    /** The visible name used in tokens for a label (alias or the label itself). */
+    private displayName;
+    /** Get or mint the placeholder for a given label+value. Idempotent. */
+    placeholderFor(label: PiiLabel, value: string): string;
+    /**
+     * Replace each redactable span with its placeholder. Spans are pre-sorted
+     * right-to-left by {@link applyPolicy}, so splicing never invalidates an
+     * earlier offset.
+     */
+    scrub(raw: string, spans: readonly Span[]): ScrubResult;
+    /**
+     * Restore real values in an assistant reply. Used on the *outbound* response
+     * so the user sees "John", not "[NAME_1]". Unknown tokens are left intact.
+     */
+    rehydrate(text: string): string;
+    /** True if `token` is a placeholder this table can resolve. */
+    knows(token: string): boolean;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/src/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAe,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAEhE,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;4EAC4E;AAC5E,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAE3D;;;;GAIG;AACH,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAN7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAGnC,OAAO,GAAE,kBAAuB,EAChC,UAAU,GAAE,WAAW,CAAC,QAAQ,CAAe;IAGlE,+EAA+E;IAC/E,OAAO,CAAC,WAAW;IAInB,uEAAuE;IACvE,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAatD;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,WAAW;IAYvD;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI/B,+DAA+D;IAC/D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAG9B"}

package/dist/src/streaming.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Streaming placeholder reveal.
+ *
+ * The assistant streams tokens, so a placeholder can be split across chunks:
+ *   chunk A: "...thanks [NA"
+ *   chunk B: "ME_1] for..."
+ * A per-chunk regex replace would emit the broken `[NA` and never match. This
+ * buffers the smallest suffix that could still become a placeholder, emits
+ * everything safe before it, and flushes the remainder at stream end.
+ */
+/** Resolves a placeholder token to its real value, or null to leave it as-is. */
+export type PlaceholderResolver = (token: string) => string | null;
+/**
+ * Stateful reveal for a token stream. Feed chunks in order; `push` returns the
+ * text safe to render now, `flush` returns whatever was held at the end.
+ */
+export declare class StreamingReveal {
+    private readonly resolve;
+    private buffer;
+    constructor(resolve: PlaceholderResolver);
+    /** Reveal complete placeholders in `chunk`, holding any partial tail. */
+    push(chunk: string): string;
+    /** Emit any buffered tail (e.g. a lone `[` that never became a token). */
+    flush(): string;
+    private replaceComplete;
+}
+/**
+ * A Web Streams transform that reveals placeholders in a string stream — drop
+ * it into an AI SDK text stream pipeline so the user never sees `[NAME_1]`.
+ */
+export declare function createRevealTransform(resolve: PlaceholderResolver): TransformStream<string, string>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/src/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,iFAAiF;AACjF,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAMnE;;;GAGG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,MAAM,CAAM;gBAES,OAAO,EAAE,mBAAmB;IAEzD,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAc3B,0EAA0E;IAC1E,KAAK,IAAI,MAAM;IAMf,OAAO,CAAC,eAAe;CAGxB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAYnG"}

package/dist/src/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared vocabulary for the PII filter.
+ *
+ * The whole system is *default-deny*: every detected entity is redacted unless
+ * its label is in {@link KEEP_LABELS} (currently {CITY, STATE, ZIP_CODE}). An
+ * unrecognized span is dropped, never leaked.
+ *
+ * Two layers emit labels:
+ *  - Heuristics (synchronous, validator-backed) detect and premask the
+ *    structured numeric identifiers below before the model ever runs.
+ *  - The NER model learns the contextual "fine set": split names, contact and
+ *    document identifiers, and address components.
+ */
+/** Every entity class the heuristics and the NER model can emit. */
+export type PiiLabel = "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "GIVEN_NAME" | "SURNAME" | "EMAIL" | "PHONE" | "URL" | "TAX_ID" | "BANK_ACCOUNT" | "ROUTING_NUMBER" | "GOVERNMENT_ID" | "PASSPORT" | "DRIVERS_LICENSE" | "BUILDING_NUMBER" | "STREET_NAME" | "SECONDARY_ADDRESS" | "CITY" | "STATE" | "ZIP_CODE";
+/**
+ * Labels that are intentionally preserved (classified but never redacted).
+ * The model still learns these; the JS policy layer simply keeps them in the
+ * text. Public-benefits assistants need broad geography (city / state / ZIP)
+ * for area-median-income (AMI) eligibility, so those are kept while the precise
+ * street line (BUILDING_NUMBER + STREET_NAME) is still redacted.
+ */
+export declare const KEEP_LABELS: ReadonlySet<PiiLabel>;
+/** A detected entity span over the *original* (raw) text. */
+export interface Span {
+    /** Inclusive start offset into the raw input. */
+    readonly start: number;
+    /** Exclusive end offset into the raw input. */
+    readonly end: number;
+    /** The classified entity type. */
+    readonly label: PiiLabel;
+    /** Detector confidence in [0, 1]. Heuristics with validators report 1. */
+    readonly score: number;
+    /** Which layer produced the span; used for merge tie-breaks and audit. */
+    readonly source: "heuristic" | "ner";
+    /** The raw substring covered, retained for placeholder rehydration. */
+    readonly text: string;
+}
+/** Resolve a caller keep-set; omitted → {@link KEEP_LABELS}. */
+export declare function resolveKeepLabels(keepLabels?: readonly PiiLabel[]): ReadonlySet<PiiLabel>;
+/** True when a label must be redacted under the default-deny policy. */
+export declare function shouldRedact(label: PiiLabel, keepLabels?: ReadonlySet<PiiLabel>): boolean;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAEhB,KAAK,GACL,aAAa,GACb,YAAY,GAEZ,YAAY,GACZ,SAAS,GACT,OAAO,GACP,OAAO,GACP,KAAK,GACL,QAAQ,GACR,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,UAAU,GACV,iBAAiB,GAEjB,iBAAiB,GACjB,aAAa,GACb,mBAAmB,GACnB,MAAM,GACN,OAAO,GACP,UAAU,CAAC;AAEf;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,QAAQ,CAAoD,CAAC;AAEnG,6DAA6D;AAC7D,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC,CAEzF;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,GAAE,WAAW,CAAC,QAAQ,CAAe,GAAG,OAAO,CAEtG"}

package/dist/src/validators.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Validators that turn "a run of digits" into "a *valid* SSN / card / phone".
+ *
+ * These exist to suppress false positives so the filter doesn't mangle numbers
+ * the assistant is allowed to keep (income figures, ages, years). A detector
+ * proposes a span; a validator decides whether it is really that entity.
+ */
+/** Luhn checksum — gates CREDIT_CARD so arbitrary 16-digit runs don't match. */
+export declare function isLuhnValid(digits: string): boolean;
+/**
+ * US SSN structural rules. Area (first 3) cannot be 000, 666, or 900-999;
+ * group (middle 2) cannot be 00; serial (last 4) cannot be 0000. Rejects
+ * obvious non-SSNs like phone numbers padded to nine digits.
+ */
+export declare function isValidSsn(digits: string): boolean;
+//# sourceMappingURL=validators.d.ts.map

package/dist/src/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/validators.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAanD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAUlD"}

package/eval/bench/README.md

@@ -0,0 +1,91 @@
+# Native benchmark
+
+The benchmark runs the **shipped TypeScript pipeline** — the exact
+`@nationaldesignstudio/rampart` code that consumers run — over a frozen
+held-out slice of [`ai4privacy/pii-masking-openpii-1.5m`](https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1.5m)
+and scores it. The predictions come straight from `src/`, scored by
+`eval/bench/score.ts`, so the benchmark measures the artifact it describes.
+
+## Layout
+
+| File | Role |
+| --- | --- |
+| `labels.ts` | OpenPII gold label → Rampart policy projection (default-deny, keep-set wins). |
+| `score.ts` | Term-presence recall/retention (Wilson + bootstrap CI), span F1, ECE, latency. |
+| `fetch.ts` | Pull the frozen held-out rows; writes the **committed manifest** (`heldout.manifest.json`) and the gitignored data. |
+| `run.ts` | Run the shipped detectors + policy over the rows and emit `runs/<name>/summary.json` + `by_language.json`. |
+
+## Reproduce
+
+```bash
+# 1. Materialise the held-out rows named in heldout.manifest.json.
+#    OpenPII is public (CC BY 4.0); HF_TOKEN is optional (higher rate limits).
+bun run bench:fetch --n 30000 --seed 0
+
+# 2. Run the bench (loads nationaldesignstudio/rampart q4 from Hugging Face).
+bun run bench --out eval/bench/runs/native
+```
+
+`fetch.ts` selects rows by a seeded shuffle over the validation split and pins
+the exact row `uid`s in `heldout.manifest.json`, so the held-out set is frozen
+and any upstream dataset drift is caught on the next fetch. The row data itself
+is regenerable and gitignored; only the manifest and the `summary.json` are
+committed, so every published number traces to committed evidence.
+
+## Committed sample
+
+`runs/sample-900/` is a committed proof run over a 900-row held-out slice (all
+seven languages, `manifest.json` pins the `uid`s). It shows the shipped runtime
+at **99.70%** private-term recall on that small slice — a smoke test that the
+benchmark measures the same artifact it describes. The published headline
+(**98.42%**) comes from the full 30k run committed in `runs/m06-v3-30k/`; scale
+the manifest to the full 30k with `bun run bench:fetch --n 30000` to regenerate it.
+
+## Metrics
+
+Identical definitions to the figures in `MODEL_CARD.md` / `WHITEPAPER.md`:
+private-term recall and public-term retention (term-presence, Wilson 95% CI),
+span-F1 at IoU ∈ {1.0, 0.5, 0.0}, ECE, and Node-ONNX latency percentiles —
+now measured end-to-end through the form factor that ships.
+
+## WebGPU latency (`webgpu.ts`)
+
+`run.ts` measures ONNX-CPU latency under Node. `webgpu.ts` measures the form
+factor that actually ships: the same shipped detection path (heuristics →
+premask → NER → policy), bundled for the browser and run inside a real Chromium
+tab with the NER model on the **WebGPU** backend.
+
+```bash
+bun run bench:webgpu              # WebGPU, q4 (writes runs/webgpu-q4/latency.json)
+bun run bench:webgpu:wasm         # WASM backend baseline for contrast
+bun eval/bench/webgpu.ts --headed --iters 400
+```
+
+By default it times one inference per row over the frozen held-out slice
+(`eval/bench/data/heldout.jsonl`, materialised by `bench:fetch`), so browser
+latency is measured over the same OpenPII rows as the Node bench. When that file
+is absent it falls back to the committed `eval/public-cases.ts` chat strings;
+override with `--data <path>`.
+
+It serves the repo over `http://localhost` (a WebGPU secure context — `about:blank`
+will not expose `navigator.gpu`) and drives **Playwright's bundled Chromium** — no
+system Chrome required. The launch strips Playwright's GPU-disabling default args
+(notably `--use-gl=swiftshader`) and forces ANGLE/Metal, so the headless browser
+reaches the real GPU (`apple/metal-3`) instead of the SwiftShader software adapter
+(which is ~400× slower and meaningless for latency). Pass `--chrome /path/to/chrome`
+to use a system Chrome instead.
+
+Latency is hardware-dependent and machine-specific, so latency runs are **not
+committed** (`runs/*/latency.json` is gitignored — regenerate locally). For
+reference, an 800-row held-out slice, q4, on Apple Metal:
+
+| Backend | p50 | p95 | p99 | mean |
+| --- | --: | --: | --: | --: |
+| WebGPU | 3.9 ms | 9.3 ms | 13.4 ms | 4.8 ms |
+| WASM | 12.6 ms | 35.5 ms | 53.7 ms | 15.8 ms |
+
+The Node ONNX (CPU) bench is 6.6 ms p50 over the full 30k slice — so WebGPU beats
+Node CPU and WASM is the no-GPU floor. Reproduce with `bun run bench:webgpu` on
+your own hardware.
+
+

package/eval/bench/fetch.ts

@@ -0,0 +1,152 @@
+/**
+ * Fetch a frozen, reproducible held-out sample from the OpenPII validation split.
+ *
+ * The row *data* is a regenerable local artifact (gitignored); the committed
+ * output is the manifest — dataset revision, seed, and the exact row `uid`s — so
+ * the held-out set is pinned and any drift in the upstream dataset is detected
+ * on the next fetch. Rows are restricted to the seven supported Latin-script
+ * languages.
+ *
+ *   HF_TOKEN=... bun eval/bench/fetch.ts --n 5000 --seed 0
+ *
+ * The OpenPII dataset is public (CC BY 4.0), so HF_TOKEN is optional — it is
+ * used when present (higher rate limits) and the anonymous datasets-server
+ * endpoint is used otherwise.
+ */
+
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const DATASET = "ai4privacy/pii-masking-openpii-1.5m";
+const SPLIT = "validation";
+const LATIN = new Set(["en", "es", "fr", "de", "it", "pt", "nl"]);
+const PAGE = 100;
+
+interface Row {
+  uid: number;
+  language: string;
+  source_text: string;
+  privacy_mask: { label: string; start: number; end: number; value: string }[];
+}
+
+function arg(name: string, fallback: string): string {
+  const hit = Bun.argv.find((a) => a.startsWith(`--${name}=`)) ?? Bun.argv[Bun.argv.indexOf(`--${name}`) + 1];
+  return hit?.startsWith("--") ? fallback : (hit?.replace(`--${name}=`, "") ?? fallback);
+}
+
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Write with a couple of retries: the sandbox occasionally returns ETXTBSY/EBUSY. */
+async function safeWrite(path: string, contents: string): Promise<void> {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      await writeFile(path, contents);
+      return;
+    } catch (e) {
+      if (attempt === 3) throw e;
+      await sleep(500 * (attempt + 1));
+    }
+  }
+}
+
+async function getJson(url: string, token: string | undefined): Promise<any> {
+  const headers: Record<string, string> = token ? { Authorization: `Bearer ${token}` } : {};
+  for (let attempt = 0; attempt < 8; attempt++) {
+    try {
+      const res = await fetch(url, { headers });
+      if (res.ok) return await res.json();
+      if (res.status === 429) {
+        const retryAfter = Number(res.headers.get("retry-after")) || 0;
+        await sleep(Math.max(retryAfter * 1000, 2000 * 2 ** attempt));
+        continue;
+      }
+      process.stderr.write(`\n[fetch ${res.status}] ${url}\n`);
+    } catch (e) {
+      process.stderr.write(`\n[fetch error] ${String(e)}\n`);
+    }
+    await sleep(1000 * 2 ** attempt);
+  }
+  throw new Error(`failed to fetch ${url}`);
+}
+
+async function main(): Promise<void> {
+  const token = process.env.HF_TOKEN; // optional: public dataset, used for higher rate limits
+  const n = Number(arg("n", "5000"));
+  const seed = Number(arg("seed", "0"));
+  const dataPath = arg("out", "eval/bench/data/heldout.jsonl");
+  const manifestPath = arg("manifest", "eval/bench/heldout.manifest.json");
+
+  const info = await getJson(`https://datasets-server.huggingface.co/size?dataset=${DATASET}`, token);
+  const splitInfo = info.size.splits.find((s: any) => s.split === SPLIT);
+  const total: number = splitInfo.num_rows;
+
+  // Deterministic, shuffled offsets so the sample spans the split rather than
+  // one contiguous (language-clustered) region.
+  const rng = mulberry32(seed);
+  const offsets = Array.from({ length: Math.ceil(total / PAGE) }, (_, i) => i * PAGE);
+  for (let i = offsets.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [offsets[i], offsets[j]] = [offsets[j], offsets[i]];
+  }
+
+  await mkdir(dirname(dataPath), { recursive: true });
+  await safeWrite(dataPath, ""); // truncate; rows are streamed in as collected
+
+  const selected: Row[] = [];
+  const seen = new Set<number>();
+  for (const offset of offsets) {
+    if (selected.length >= n) break;
+    const page = await getJson(
+      `https://datasets-server.huggingface.co/rows?dataset=${DATASET}&config=default&split=${SPLIT}&offset=${offset}&length=${PAGE}`,
+      token,
+    );
+    let batch = "";
+    for (const item of page.rows ?? []) {
+      const r = item.row;
+      if (!LATIN.has(r.language) || seen.has(r.uid) || selected.length >= n) continue;
+      seen.add(r.uid);
+      const row: Row = { uid: r.uid, language: r.language, source_text: r.source_text, privacy_mask: r.privacy_mask };
+      selected.push(row);
+      batch += JSON.stringify(row) + "\n";
+    }
+    if (batch) await appendFile(dataPath, batch); // persist incrementally
+    process.stderr.write(`\rcollected ${selected.length}/${n}`);
+    await sleep(700); // throttle to stay under the datasets-server rate limit
+  }
+  process.stderr.write("\n");
+
+  const byLang: Record<string, number> = {};
+  for (const r of selected) byLang[r.language] = (byLang[r.language] ?? 0) + 1;
+
+  const manifest = {
+    dataset: DATASET,
+    split: SPLIT,
+    revision: info.size?.dataset ?? null,
+    seed,
+    languages: [...LATIN],
+    rows: selected.length,
+    by_language: byLang,
+    uids: selected.map((r) => r.uid),
+  };
+  const manifestJson = JSON.stringify(manifest, null, 2) + "\n";
+  try {
+    await safeWrite(manifestPath, manifestJson);
+    console.log(`wrote ${selected.length} rows -> ${dataPath}\nmanifest -> ${manifestPath}\nby language: ${JSON.stringify(byLang)}`);
+  } catch {
+    // Sandbox teardown can ETXTBSY the final write; emit the manifest so it can
+    // be captured from stdout. The streamed data file is already complete.
+    console.log(`MANIFEST_BEGIN\n${manifestJson}MANIFEST_END`);
+  }
+}
+
+await main();

package/eval/bench/labels.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenPII (`ai4privacy/pii-masking-openpii-1.5m`) gold-label projection onto the
+ * Rampart policy: default-deny, keep-set wins, and any unknown label fails safe
+ * to a redacted class.
+ *
+ * This projection lives in TS alongside the runtime it scores, so the gold-label
+ * mapping the benchmark uses is the same mapping the shipped policy enforces.
+ */
+
+/** Keep set / not-PII sentinel. */
+export const KEEP = "O";
+
+const OPENPII_TO_OURS: Readonly<Record<string, string>> = {
+  // Split names (a household may share a surname, so they stay distinct).
+  GIVENNAME: "GIVEN_NAME",
+  SURNAME: "SURNAME",
+  // Direct contact identifiers
+  EMAIL: "EMAIL",
+  TELEPHONENUM: "PHONE",
+  // Government / financial strong identifiers (redact)
+  SOCIALNUM: "SSN",
+  CREDITCARDNUMBER: "CREDIT_CARD",
+  IDCARDNUM: "GOVERNMENT_ID",
+  PASSPORTNUM: "PASSPORT",
+  DRIVERLICENSENUM: "DRIVERS_LICENSE",
+  TAXNUM: "TAX_ID",
+  // Address components: only the precise street line is redacted at runtime.
+  // CITY / STATE / ZIPCODE are in KEEP_LABELS (see src/types.ts) — they ride
+  // through the runtime untouched, so the bench must NOT count them as leaks.
+  BUILDINGNUM: "BUILDING_NUMBER",
+  STREET: "STREET_NAME",
+  CITY: KEEP,
+  STATE: KEEP,
+  ZIPCODE: KEEP,
+};
+
+/** Project an OpenPII label onto our schema; unknown → O (pass through). */
+export function mapOpenPiiLabel(label: string): string {
+  return OPENPII_TO_OURS[label] ?? KEEP;
+}
+
+/** A gold value is "private" iff its label maps to a redacted (non-keep) class. */
+export function isPrivateLabel(label: string): boolean {
+  return mapOpenPiiLabel(label) !== KEEP;
+}