@jinn-network/core 0.1.0 → 0.1.1-canary.7b188db5

package/dist/scrub/known-identity-detector.js

@@ -0,0 +1,284 @@
+/**
+ * Known-identity pack + non-address instance allowlist (#1971 / design §6.4).
+ *
+ * Locked Q1: stub ALL address-shaped values (no address pass-allowlist). The
+ * pack exact-matches operator self-PII only. The allowlist covers loopback /
+ * reserved IPs and repo-slug patterns — never wallets.
+ */
+import { applyDispositions } from './apply-dispositions.js';
+import { classifyKey } from './key-policy.js';
+const VERSION = '0.1.0';
+const ETH_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+const IPV4_RE = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g;
+/** Built-in non-address public values (Q1): loopback + common reserved. */
+export const DEFAULT_INSTANCE_ALLOWLIST = {
+    entries: [
+        { value: '127.0.0.1', kind: 'loopback-ip', provenance: 'RFC 1122 loopback' },
+        { value: '0.0.0.0', kind: 'reserved-ip', provenance: 'RFC 1122 this-host' },
+        { value: '::1', kind: 'loopback-ip', provenance: 'IPv6 loopback' },
+    ],
+};
+const PACK_FIELDS = [
+    { key: 'gitUserName', scrubClass: 'B3', evidence: 'known-identity:git-user-name' },
+    { key: 'gitUserEmail', scrubClass: 'B1', evidence: 'known-identity:git-user-email' },
+    { key: 'homeUsername', scrubClass: 'B4', evidence: 'known-identity:home-username' },
+    { key: 'hostname', scrubClass: 'D3', evidence: 'known-identity:hostname' },
+    { key: 'ghLogin', scrubClass: 'B4', evidence: 'known-identity:gh-login' },
+];
+export function isAddressShaped(value) {
+    return ETH_ADDRESS_RE.test(value.trim());
+}
+function normalizeToken(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed;
+}
+function normalizePack(pack) {
+    const out = {};
+    for (const field of PACK_FIELDS) {
+        const v = normalizeToken(pack[field.key]);
+        if (!v)
+            continue;
+        // Q1: never put addresses into the redact pack.
+        if (isAddressShaped(v))
+            continue;
+        out[field.key] = field.key === 'gitUserEmail' ? v.toLowerCase() : v;
+    }
+    return out;
+}
+function filterAllowlist(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of entries) {
+        const value = normalizeToken(entry.value);
+        if (!value)
+            continue;
+        // Q1: no address pass-allowlist.
+        if (isAddressShaped(value))
+            continue;
+        const key = `${entry.kind}:${value.toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ ...entry, value });
+    }
+    return out;
+}
+/**
+ * Assemble pack + allowlist from injected options, optionally filling gaps from
+ * env/homedir. Injectable pack is enough for this PR; daemon wiring stays thin.
+ */
+export function assembleKnownIdentity(opts = {}) {
+    const env = opts.env ?? {};
+    const pack = { ...(opts.pack ?? {}) };
+    if (!pack.gitUserName && env.GIT_AUTHOR_NAME) {
+        pack.gitUserName = env.GIT_AUTHOR_NAME;
+    }
+    if (!pack.gitUserEmail && env.GIT_AUTHOR_EMAIL) {
+        pack.gitUserEmail = env.GIT_AUTHOR_EMAIL;
+    }
+    if (!pack.ghLogin && (env.GH_USER || env.GITHUB_USER)) {
+        pack.ghLogin = env.GH_USER || env.GITHUB_USER;
+    }
+    if (!pack.homeUsername && opts.homedir) {
+        try {
+            const home = opts.homedir();
+            const base = home.split(/[/\\]/).filter(Boolean).pop();
+            if (base)
+                pack.homeUsername = base;
+        }
+        catch {
+            // ignore — injectable pack is the primary path
+        }
+    }
+    if (!pack.hostname && opts.hostname) {
+        try {
+            pack.hostname = opts.hostname();
+        }
+        catch {
+            // ignore
+        }
+    }
+    const entries = [
+        ...DEFAULT_INSTANCE_ALLOWLIST.entries,
+        ...(opts.allowlist?.entries ?? []),
+    ];
+    return {
+        pack: normalizePack(pack),
+        allowlist: { entries: filterAllowlist(entries) },
+    };
+}
+function isLoopbackOrReservedIpv4(ip) {
+    const parts = ip.split('.').map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n)))
+        return false;
+    const [a, b] = parts;
+    if (a === 127)
+        return true; // loopback
+    if (a === 0)
+        return true; // this-host
+    if (a === 169 && b === 254)
+        return true; // link-local
+    if (a >= 224)
+        return true; // multicast / reserved
+    return false;
+}
+function isPrivateIpv4(ip) {
+    const parts = ip.split('.').map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n)))
+        return false;
+    const [a, b] = parts;
+    if (a === 10)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Exact match with word-ish boundaries so `ann` does not hit `canonical`.
+ * Multi-word needles match the full phrase.
+ */
+function findExactSpans(text, needle) {
+    if (needle.length < 2)
+        return [];
+    const re = new RegExp(`(?<![A-Za-z0-9_])${escapeRegExp(needle)}(?![A-Za-z0-9_])`, 'gi');
+    const spans = [];
+    let match;
+    while ((match = re.exec(text)) !== null) {
+        spans.push({ start: match.index, end: match.index + match[0].length });
+    }
+    return spans;
+}
+function allowlistHit(matched, allowlist) {
+    const lower = matched.toLowerCase();
+    return allowlist.entries.find((e) => e.value.toLowerCase() === lower);
+}
+function overlaps(a, b) {
+    return a.start < b.end && a.end > b.start;
+}
+/**
+ * Detector: pack → VERY_HIGH redact findings; allowlist → pass findings with
+ * auditable evidence; public IPs → D2 redact; private IPs → D2 flag band.
+ */
+export function knownIdentityDetector(policy, opts = {}) {
+    const assembled = opts.assembled ??
+        assembleKnownIdentity({ pack: opts.pack, allowlist: opts.allowlist });
+    const meta = { name: 'known-identity', version: VERSION };
+    return {
+        ...meta,
+        detect(attributes) {
+            const findings = [];
+            const allowlistSpansByKey = new Map();
+            for (const [key, value] of Object.entries(attributes)) {
+                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content')
+                    continue;
+                const keyAllowlistSpans = [];
+                // --- Instance allowlist exact matches (pass + manifest) ---
+                for (const entry of assembled.allowlist.entries) {
+                    for (const span of findExactSpans(value, entry.value)) {
+                        keyAllowlistSpans.push(span);
+                        findings.push({
+                            class: entry.kind === 'repo-slug' ? 'B4' : 'D2',
+                            span: { key, start: span.start, end: span.end },
+                            confidence: 'VERY_LOW',
+                            evidence: [`allowlist:${entry.kind}`, `provenance:${entry.provenance}`],
+                            detector: meta,
+                        });
+                    }
+                }
+                // --- IPv4 shapes (D2), classified against allowlist / ranges ---
+                const ipRe = new RegExp(IPV4_RE.source, 'g');
+                let ipMatch;
+                while ((ipMatch = ipRe.exec(value)) !== null) {
+                    const ip = ipMatch[0];
+                    const span = { start: ipMatch.index, end: ipMatch.index + ip.length };
+                    const listed = allowlistHit(ip, assembled.allowlist);
+                    if (listed || isLoopbackOrReservedIpv4(ip)) {
+                        if (!keyAllowlistSpans.some((s) => overlaps(s, span))) {
+                            keyAllowlistSpans.push(span);
+                            const kind = listed?.kind
+                                ?? (ip.startsWith('127.') || ip === '0.0.0.0' ? 'loopback-ip' : 'reserved-ip');
+                            const provenance = listed?.provenance
+                                ?? (isLoopbackOrReservedIpv4(ip) ? 'RFC reserved/loopback' : 'allowlist');
+                            findings.push({
+                                class: 'D2',
+                                span: { key, start: span.start, end: span.end },
+                                confidence: 'VERY_LOW',
+                                evidence: [`allowlist:${kind}`, `provenance:${provenance}`],
+                                detector: meta,
+                            });
+                        }
+                        continue;
+                    }
+                    if (isPrivateIpv4(ip)) {
+                        findings.push({
+                            class: 'D2',
+                            span: { key, start: span.start, end: span.end },
+                            confidence: 'MEDIUM',
+                            evidence: ['ip-address', 'private-range'],
+                            detector: meta,
+                        });
+                        continue;
+                    }
+                    findings.push({
+                        class: 'D2',
+                        span: { key, start: span.start, end: span.end },
+                        confidence: 'VERY_HIGH',
+                        evidence: ['ip-address'],
+                        detector: meta,
+                    });
+                }
+                allowlistSpansByKey.set(key, keyAllowlistSpans);
+                // --- Known-identity pack exact matches ---
+                for (const field of PACK_FIELDS) {
+                    const needle = assembled.pack[field.key];
+                    if (!needle)
+                        continue;
+                    // Allowlist suppresses pack hits on the same span (e.g. slug == handle).
+                    for (const span of findExactSpans(value, needle)) {
+                        if (keyAllowlistSpans.some((s) => overlaps(s, span)))
+                            continue;
+                        findings.push({
+                            class: field.scrubClass,
+                            span: { key, start: span.start, end: span.end },
+                            confidence: 'VERY_HIGH',
+                            evidence: [field.evidence],
+                            detector: meta,
+                        });
+                    }
+                }
+            }
+            // Drop non-allowlist findings that overlap an allowlisted span (same key).
+            // Never suppress C1 — addresses are not allowlisted (Q1); this only covers
+            // pack/D2 collisions on non-address public values.
+            return findings.filter((f) => {
+                if (f.evidence.some((e) => e.startsWith('allowlist:')))
+                    return true;
+                if (f.class === 'C1')
+                    return true;
+                const spans = allowlistSpansByKey.get(f.span.key) ?? [];
+                return !spans.some((s) => overlaps(s, f.span));
+            });
+        },
+    };
+}
+/** Legacy ScrubStage wrapper for stage-chain tests. */
+export function knownIdentityStage(policy, opts = {}) {
+    const detector = knownIdentityDetector(policy, opts);
+    return {
+        name: detector.name,
+        version: detector.version,
+        scrub(attributes) {
+            const findings = detector.detect(attributes);
+            return applyDispositions(attributes, findings);
+        },
+    };
+}

package/dist/scrub/layer2.d.ts

@@ -1,23 +1,18 @@
 import { ScrubPipeline } from './pipeline.js';
-import { type KeyPolicy } from './key-policy.js';
+import type { KeyPolicy } from './key-policy.js';
+import type { AssembleKnownIdentityOptions, AssembledKnownIdentity } from './known-identity-detector.js';
+export interface BuildLayer2ScrubPipelineOptions {
+    policy?: KeyPolicy;
+    knownIdentity?: AssembleKnownIdentityOptions | AssembledKnownIdentity;
+}
 /**
- * The layer-2 / public / derived-content scrub altitude
- * (spec/2026-07-06-distillation-v1.md §10, D6; reconciled 2026-07-07 with the
- * shipped #1409 seed profile).
+ * Layer-2 / check-mode preset (#1969 / design §6.5).
  *
- * Secret-only: the structural key policy + deterministic plain-patterns
- * (emails, home-dir paths, credential-ID prefixes — #1330/#1415) + the FULL
- * secretlint stage (including its Pass-2 entropy secret-shape fallback). It
- * deliberately DROPS openredaction and ML-PII — the stages whose PII
- * shape-matching and trigger-word behaviour deface ordinary public prose
- * (#1409).
+ * Same owned detector inventory as the seed preset; checkMode maps any non-pass
+ * disposition to reject — one mapping line, not a second pipeline. Entropy
+ * fallback stays ON (stricter net; a false positive costs one re-distill, never
+ * defaces published content).
  *
- * Mode note vs the seed profile (`buildSeedScrubPipeline`): seeds are
- * REDACT-mode (the scrubbed output is published, so prose must survive →
- * entropy fallback OFF there). This pipeline serves CHECK-mode consumers —
- * `distillClusters` REJECTS a skill on any scrub change rather than publishing
- * a redacted body — so a false positive costs one re-distill, never defaces
- * published content, and the entropy fallback stays ON as the stricter net for
- * a fresh secret surface (DR-2026-07-06 decision 3).
+ * @deprecated Compatibility preset over the one inventory + policy table.
  */
-export declare function buildLayer2ScrubPipeline(policy?: KeyPolicy): ScrubPipeline;
+export declare function buildLayer2ScrubPipeline(policyOrOpts?: KeyPolicy | BuildLayer2ScrubPipelineOptions): ScrubPipeline;

package/dist/scrub/layer2.js

@@ -1,32 +1,28 @@
 import { ScrubPipeline } from './pipeline.js';
-import { keyPolicyStage } from './key-policy.js';
-import { secretlintStage } from './secretlint-stage.js';
-import { plainPatternsStage } from './plain-patterns-stage.js';
-import { DEFAULT_KEY_POLICY } from './build.js';
+import { DEFAULT_KEY_POLICY, buildProvenanceExtras, resolveKnownIdentity, sharedDetectorInventory, } from './build.js';
+import { DEFAULT_POLICY } from './policy.js';
 /**
- * The layer-2 / public / derived-content scrub altitude
- * (spec/2026-07-06-distillation-v1.md §10, D6; reconciled 2026-07-07 with the
- * shipped #1409 seed profile).
+ * Layer-2 / check-mode preset (#1969 / design §6.5).
  *
- * Secret-only: the structural key policy + deterministic plain-patterns
- * (emails, home-dir paths, credential-ID prefixes — #1330/#1415) + the FULL
- * secretlint stage (including its Pass-2 entropy secret-shape fallback). It
- * deliberately DROPS openredaction and ML-PII — the stages whose PII
- * shape-matching and trigger-word behaviour deface ordinary public prose
- * (#1409).
+ * Same owned detector inventory as the seed preset; checkMode maps any non-pass
+ * disposition to reject — one mapping line, not a second pipeline. Entropy
+ * fallback stays ON (stricter net; a false positive costs one re-distill, never
+ * defaces published content).
  *
- * Mode note vs the seed profile (`buildSeedScrubPipeline`): seeds are
- * REDACT-mode (the scrubbed output is published, so prose must survive →
- * entropy fallback OFF there). This pipeline serves CHECK-mode consumers —
- * `distillClusters` REJECTS a skill on any scrub change rather than publishing
- * a redacted body — so a false positive costs one re-distill, never defaces
- * published content, and the entropy fallback stays ON as the stricter net for
- * a fresh secret surface (DR-2026-07-06 decision 3).
+ * @deprecated Compatibility preset over the one inventory + policy table.
  */
-export function buildLayer2ScrubPipeline(policy = DEFAULT_KEY_POLICY) {
-    return new ScrubPipeline([
-        keyPolicyStage(policy),
-        plainPatternsStage(policy, { credentialIds: true }),
-        secretlintStage(policy),
-    ]);
+export function buildLayer2ScrubPipeline(policyOrOpts = DEFAULT_KEY_POLICY) {
+    const opts = policyOrOpts && 'safe' in policyOrOpts
+        ? { policy: policyOrOpts }
+        : policyOrOpts;
+    const policy = opts.policy ?? DEFAULT_KEY_POLICY;
+    const knownIdentity = resolveKnownIdentity(opts.knownIdentity);
+    return new ScrubPipeline(sharedDetectorInventory(policy, {
+        entropyFallback: true,
+        knownIdentity,
+    }), {
+        policy: DEFAULT_POLICY,
+        checkMode: true,
+        provenance: buildProvenanceExtras(knownIdentity),
+    });
 }

package/dist/scrub/ml-pii-stage.d.ts

@@ -1,24 +1,42 @@
+import type { Band, Detector } from './finding.js';
 import { type KeyPolicy } from './key-policy.js';
 import type { ScrubStage } from './types.js';
-/** A PII entity detected in text: a label (PER/ORG/LOC/…) and the matched span text. */
+/**
+ * A PII entity detected in text. When the detector supplies character offsets
+ * (`start`/`end`), those win; otherwise the stage recovers spans via whole-word
+ * search (Transformers.js NER fallback). Optional `score` maps to a Band.
+ */
 export interface PiiEntity {
     label: string;
     text: string;
+    /** Inclusive start offset in the source string, when the detector provides it. */
+    start?: number;
+    /** Exclusive end offset in the source string, when the detector provides it. */
+    end?: number;
+    /** Model confidence in [0, 1]. Mapped via {@link scoreToBand}. */
+    score?: number;
 }
 /**
- * ML PII detector seam. The production implementation wraps a Transformers.js
- * token-classification (NER) model; tests inject a deterministic fake. Kept
- * behind an interface so the stage logic is unit-tested without loading a model.
+ * ML PII detector seam. Production uses GLiNER ONNX (`gliner-detector.ts`);
+ * TransformersPiiDetector remains for tests. Kept behind an interface so stage
+ * logic is unit-tested without loading a model.
  */
 export interface PiiDetector {
     detect(text: string): Promise<PiiEntity[]>;
 }
 /**
- * ML PII stage. Runs the injected NER detector over each `content`-classified
- * string value and replaces whole-word occurrences of each detected entity with
- * `[PII:<label>]` (word-boundary matching so substrings aren't corrupted — e.g.
- * detecting "London" leaves "Londoner" intact). `safe` and non-string values
- * pass through untouched. The detector returns matched text rather than offsets
- * because the Transformers.js NER pipeline does not surface character offsets.
+ * Map a model score onto a DLP-style Band (#1973 / design §6.1).
+ *
+ * Thresholds chosen so B3 policy (VERY_HIGH → redact; HIGH/MEDIUM → flag)
+ * separates auto-redact names from review-queue candidates.
+ */
+export declare function scoreToBand(score: number | undefined): Band;
+/**
+ * ML PII detector — emits B3/B5/B6/… findings from NER/GLiNER entities.
+ * Prefers detector-supplied offsets; falls back to whole-word search.
+ */
+export declare function mlPiiDetector(policy: KeyPolicy, detector: PiiDetector): Detector;
+/**
+ * Legacy ScrubStage wrapper around {@link mlPiiDetector}.
  */
 export declare function mlPiiStage(policy: KeyPolicy, detector: PiiDetector): ScrubStage;

package/dist/scrub/ml-pii-stage.js

@@ -1,42 +1,119 @@
+import { applyDispositions } from './apply-dispositions.js';
 import { classifyKey } from './key-policy.js';
-const VERSION = '0.1.0';
+const VERSION = '0.3.0';
+/**
+ * Map a model score onto a DLP-style Band (#1973 / design §6.1).
+ *
+ * Thresholds chosen so B3 policy (VERY_HIGH → redact; HIGH/MEDIUM → flag)
+ * separates auto-redact names from review-queue candidates.
+ */
+export function scoreToBand(score) {
+    if (score === undefined || Number.isNaN(score))
+        return 'VERY_HIGH';
+    if (score >= 0.85)
+        return 'VERY_HIGH';
+    if (score >= 0.7)
+        return 'HIGH';
+    if (score >= 0.55)
+        return 'MEDIUM';
+    return 'LOW';
+}
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function classForLabel(label) {
+    const l = label.toUpperCase();
+    if (l === 'PER' || l === 'PERSON' || l.includes('PERSON') || l === 'NAME')
+        return 'B3';
+    if (l.includes('PHONE') || l.includes('TEL'))
+        return 'B5';
+    if (l.includes('EMAIL'))
+        return 'B1';
+    if (l.includes('LOC') || l.includes('ADDRESS') || l.includes('STREET'))
+        return 'B6';
+    if (l.includes('USER') || l.includes('HANDLE') || l.includes('USERNAME'))
+        return 'B4';
+    if (l.includes('IP'))
+        return 'D2';
+    if (l.includes('CARD') ||
+        l.includes('IBAN') ||
+        l.includes('SSN') ||
+        l.includes('SOCIAL SECURITY')) {
+        return 'B7';
+    }
+    return 'E1';
+}
+function offsetsValid(text, start, end) {
+    if (typeof start !== 'number' ||
+        typeof end !== 'number' ||
+        start < 0 ||
+        end > text.length ||
+        start >= end) {
+        return null;
+    }
+    return { start, end };
+}
 /**
- * ML PII stage. Runs the injected NER detector over each `content`-classified
- * string value and replaces whole-word occurrences of each detected entity with
- * `[PII:<label>]` (word-boundary matching so substrings aren't corrupted — e.g.
- * detecting "London" leaves "Londoner" intact). `safe` and non-string values
- * pass through untouched. The detector returns matched text rather than offsets
- * because the Transformers.js NER pipeline does not surface character offsets.
+ * ML PII detector — emits B3/B5/B6/… findings from NER/GLiNER entities.
+ * Prefers detector-supplied offsets; falls back to whole-word search.
  */
-export function mlPiiStage(policy, detector) {
+export function mlPiiDetector(policy, detector) {
+    const meta = { name: 'ml-pii', version: VERSION };
     return {
-        name: 'ml-pii',
-        version: VERSION,
-        async scrub(attributes) {
-            const out = {};
-            const redactions = [];
+        ...meta,
+        async detect(attributes) {
+            const findings = [];
             for (const [key, value] of Object.entries(attributes)) {
-                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content') {
-                    out[key] = value;
+                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content')
                     continue;
-                }
-                let text = value;
                 for (const ent of await detector.detect(value)) {
                     if (!ent.text)
                         continue;
+                    const confidence = scoreToBand(ent.score);
+                    const evidence = [`ml:${ent.label}`];
+                    if (typeof ent.score === 'number') {
+                        evidence.push(`score:${ent.score.toFixed(3)}`);
+                    }
+                    const offsets = offsetsValid(value, ent.start, ent.end);
+                    if (offsets) {
+                        findings.push({
+                            class: classForLabel(ent.label),
+                            span: { key, start: offsets.start, end: offsets.end },
+                            confidence,
+                            evidence,
+                            detector: meta,
+                        });
+                        continue;
+                    }
+                    // Offset-less fallback (Transformers.js NER).
                     const re = new RegExp(`\\b${escapeRegExp(ent.text)}\\b`, 'g');
-                    const replaced = text.replace(re, `[PII:${ent.label}]`);
-                    if (replaced !== text) {
-                        redactions.push({ key, stage: 'ml-pii', kind: 'pii', detail: ent.label });
-                        text = replaced;
+                    let match;
+                    while ((match = re.exec(value)) !== null) {
+                        findings.push({
+                            class: classForLabel(ent.label),
+                            span: { key, start: match.index, end: match.index + match[0].length },
+                            confidence,
+                            evidence,
+                            detector: meta,
+                        });
                     }
                 }
-                out[key] = text;
             }
-            return { attributes: out, redactions };
+            return findings;
+        },
+    };
+}
+/**
+ * Legacy ScrubStage wrapper around {@link mlPiiDetector}.
+ */
+export function mlPiiStage(policy, detector) {
+    const det = mlPiiDetector(policy, detector);
+    return {
+        name: det.name,
+        version: det.version,
+        async scrub(attributes) {
+            const findings = await det.detect(attributes);
+            return applyDispositions(attributes, findings);
         },
     };
 }

package/dist/scrub/pii-build.d.ts

@@ -1,32 +1,41 @@
-import { type TransformersPiiDetectorOptions } from './transformers-detector.js';
+import { type GlinerPiiDetectorOptions } from './gliner-detector.js';
 import type { PiiDetector } from './ml-pii-stage.js';
 export interface PiiDetectionConfig {
+    /**
+     * When true (default for publish lanes), build and warm the GLiNER detector.
+     * Explicit `false` disables the ML tier (deterministic detectors only).
+     * When enabled, a model-load failure fails closed at publish altitude.
+     */
     enabled: boolean;
-    /** Optional Transformers.js NER model id (defaults to Xenova/bert-base-NER). */
+    /**
+     * Optional GLiNER / ONNX model id. Defaults to
+     * {@link DEFAULT_GLINER_MODEL} (`urchade/gliner_multi_pii-v1`).
+     * Alternate: `knowledgator/gliner-pii-edge-v1.0` (benchmark before switching).
+     */
     model?: string;
 }
 export interface PiiDetectorLoader extends PiiDetector {
     init(): Promise<void>;
 }
 export interface PiiDetectorFactoryPort {
-    create(options: TransformersPiiDetectorOptions): PiiDetectorLoader;
+    create(options: GlinerPiiDetectorOptions): PiiDetectorLoader;
 }
 /** Thrown by the fail-closed detector on every scrub call when ML PII was enabled but the model never loaded. */
 export declare class MlPiiUnavailableError extends Error {
     constructor(cause: string);
 }
 /**
- * Builds the ML PII detector (Transformers.js NER, in-process) when enabled,
- * warming up the model.
+ * Builds the ML PII detector (GLiNER ONNX, in-process) when enabled, warming
+ * up the model. Default factory is {@link GlinerPiiDetector}; tests inject a
+ * mock factory so CI never hits the network.
  *
  * Failure altitude is **publish-time, not boot-time** (per
  * `spec/2026-06-15-ts-trajectory-scrub-stack.md`, §"Failure posture": "if any
  * stage errors or the model fails to load, the trajectory is **not**
  * published"). Three cases:
  *
- * - Disabled (the default): returns `undefined` — the scrub pipeline runs the
- *   structural key policy + openredaction + secretlint/entropy stages only, with
- *   no ML PII tier and no error. Exactly the legacy behaviour.
+ * - Disabled (`enabled: false`): returns `undefined` — deterministic inventory
+ *   only, no ML PII tier and no error.
  * - Enabled and the model loads: returns the real detector.
  * - Enabled but the model fails to load: does NOT throw at construction. Returns
  *   a fail-closed detector that hard-throws on every scrub call, so each affected