@jinn-network/client 0.1.9 → 0.2.0-canary.0b79cd5d

package/dist/vendor/@jinn-network/core/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/vendor/@jinn-network/core/dist/scrub/layer2.d.ts

@@ -0,0 +1,18 @@
+import { ScrubPipeline } from './pipeline.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;
+}
+/**
+ * Layer-2 / check-mode preset (#1969 / design §6.5).
+ *
+ * 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).
+ *
+ * @deprecated Compatibility preset over the one inventory + policy table.
+ */
+export declare function buildLayer2ScrubPipeline(policyOrOpts?: KeyPolicy | BuildLayer2ScrubPipelineOptions): ScrubPipeline;

package/dist/vendor/@jinn-network/core/dist/scrub/layer2.js

@@ -0,0 +1,28 @@
+import { ScrubPipeline } from './pipeline.js';
+import { DEFAULT_KEY_POLICY, buildProvenanceExtras, resolveKnownIdentity, sharedDetectorInventory, } from './build.js';
+import { DEFAULT_POLICY } from './policy.js';
+/**
+ * Layer-2 / check-mode preset (#1969 / design §6.5).
+ *
+ * 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).
+ *
+ * @deprecated Compatibility preset over the one inventory + policy table.
+ */
+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/vendor/@jinn-network/core/dist/scrub/ml-pii-stage.d.ts

@@ -0,0 +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. 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. 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[]>;
+}
+/**
+ * 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/vendor/@jinn-network/core/dist/scrub/ml-pii-stage.js

@@ -0,0 +1,119 @@
+import { applyDispositions } from './apply-dispositions.js';
+import { classifyKey } from './key-policy.js';
+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 detector — emits B3/B5/B6/… findings from NER/GLiNER entities.
+ * Prefers detector-supplied offsets; falls back to whole-word search.
+ */
+export function mlPiiDetector(policy, detector) {
+    const meta = { name: 'ml-pii', version: VERSION };
+    return {
+        ...meta,
+        async detect(attributes) {
+            const findings = [];
+            for (const [key, value] of Object.entries(attributes)) {
+                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content')
+                    continue;
+                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');
+                    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,
+                        });
+                    }
+                }
+            }
+            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/vendor/@jinn-network/core/dist/scrub/pii-build.d.ts

@@ -0,0 +1,47 @@
+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 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: 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 (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 (`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
+ *   publish aborts (fails closed — never publishes under-redacted/raw) while the
+ *   rest of the daemon keeps running. A loud one-time boot warning is emitted so
+ *   the degraded posture is visible in logs; the per-publish throw carries its own
+ *   clear error so aborted publishes are never silent.
+ */
+export declare function maybeBuildPiiDetector(cfg: PiiDetectionConfig, log?: (msg: string) => void, factory?: PiiDetectorFactoryPort): Promise<PiiDetector | undefined>;

package/dist/vendor/@jinn-network/core/dist/scrub/pii-build.js

@@ -0,0 +1,67 @@
+import { GlinerPiiDetector, DEFAULT_GLINER_MODEL, } from './gliner-detector.js';
+/** Thrown by the fail-closed detector on every scrub call when ML PII was enabled but the model never loaded. */
+export class MlPiiUnavailableError extends Error {
+    constructor(cause) {
+        super('ML PII detection was enabled but the model failed to load; failing closed — ' +
+            `this trajectory is NOT published (disable captures.piiDetection or fix the model to publish): ${cause}`);
+        this.name = 'MlPiiUnavailableError';
+    }
+}
+/**
+ * A detector that hard-throws on every `detect()` call. Used when ML PII is
+ * enabled but the model failed to load: the failure is narrowed to **publish
+ * altitude** — the throw propagates through the ML scrub stage and aborts the
+ * one publish in flight (capture publish aborts; task-trajectory ref drops to
+ * null), so no raw trajectory is ever published. The daemon's other loops
+ * (earning, claim, engine, balance-topup) are unaffected because the failure
+ * is no longer raised at construction/boot.
+ */
+function failClosedDetector(cause) {
+    return {
+        detect() {
+            return Promise.reject(new MlPiiUnavailableError(cause));
+        },
+    };
+}
+/**
+ * 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 (`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
+ *   publish aborts (fails closed — never publishes under-redacted/raw) while the
+ *   rest of the daemon keeps running. A loud one-time boot warning is emitted so
+ *   the degraded posture is visible in logs; the per-publish throw carries its own
+ *   clear error so aborted publishes are never silent.
+ */
+export async function maybeBuildPiiDetector(cfg, log = (m) => console.warn(m), factory = {
+    create(options) {
+        return new GlinerPiiDetector(options);
+    },
+}) {
+    if (!cfg.enabled)
+        return undefined;
+    try {
+        const detector = factory.create(cfg.model ? { model: cfg.model } : { model: DEFAULT_GLINER_MODEL });
+        await detector.init();
+        log(`[scrub] ML PII detection (GLiNER ONNX, model=${cfg.model ?? DEFAULT_GLINER_MODEL}) enabled.`);
+        return detector;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log('[scrub] WARNING: ML PII detection is enabled but the model failed to load. ' +
+            'Failing closed at publish altitude: trajectory/capture publishing will ABORT ' +
+            '(no raw trajectories are published) until this is resolved or captures.piiDetection ' +
+            `is disabled. The daemon's other loops continue running. Cause: ${message}`);
+        return failClosedDetector(message);
+    }
+}