@mailwoman/core 2.0.0

package/out/parser/proposal-pipeline.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Parser-level proposal pipeline.
+ *
+ *   Stitches together three pieces that already exist independently:
+ *
+ *   1. Per-section fan-out across a list of `ProposalClassifier`s (rule or neural — same shape).
+ *   2. `PolicyRegistry.apply()` filters the merged proposal stream by per-component policy modes.
+ *   3. Surviving proposals are written back into the `TokenContext` as legacy `Classification`s the
+ *        solver can read.
+ *
+ *   Pure module: no resource imports, no top-level await. Safe to import from anywhere.
+ */
+import type { PolicyRegistry } from "../policy/policy.js";
+import type { Span, TokenContext } from "../tokenization/index.js";
+import { type ClassificationProposal, type ClassifierContext, type ProposalClassifier } from "../types/index.js";
+/**
+ * Run every classifier against every section, concatenate the results.
+ *
+ * Classifiers that throw are isolated — their failure logs but does not block other classifiers'
+ * proposals from being collected. (Per the `ProposalClassifier` contract, implementations are
+ * supposed to swallow errors, but defense-in-depth lives here.)
+ */
+export declare function collectProposals(sections: readonly Span[], classifiers: readonly ProposalClassifier[], context?: ClassifierContext): Promise<ClassificationProposal[]>;
+/**
+ * Optional policy filter. Returns the input unchanged when `policy` is undefined, otherwise
+ * delegates to `PolicyRegistry.apply`.
+ */
+export declare function filterByPolicy(proposals: readonly ClassificationProposal[], policy: PolicyRegistry | undefined, locale: string | undefined): ClassificationProposal[];
+/**
+ * Locate the context Span whose [start, end] best matches the given char range.
+ *
+ * Strategy:
+ *
+ * - Prefer an exact match on both `start` and `end`.
+ * - Fall back to the smallest enclosing span (start ≤ target.start && end ≥ target.end).
+ * - Returns null if nothing covers the range — the caller drops the proposal silently.
+ */
+export declare function findSpanByRange(context: TokenContext, start: number, end: number): Span | null;
+/**
+ * Walk every span attached to a `TokenContext` — sections, words, phrases — in a single flat pass.
+ * Order isn't guaranteed.
+ */
+export declare function iterateContextSpans(context: TokenContext): Generator<Span>;
+export interface WritebackResult {
+    written: number;
+    skippedNoLegacyMap: number;
+    skippedNoSpan: number;
+}
+/**
+ * Write each surviving proposal back to the context's span graph as a legacy `Classification` so
+ * the solver can read it. Returns a small summary useful for telemetry and tests.
+ */
+export declare function writeProposalsToContext(proposals: readonly ClassificationProposal[], context: TokenContext): WritebackResult;
+/** Combined entrypoint: collect + filter + write. Returns the (post-filter) proposal list. */
+export declare function runProposalPipeline(context: TokenContext, classifiers: readonly ProposalClassifier[], options?: {
+    policy?: PolicyRegistry;
+    locale?: string;
+    classifierContext?: ClassifierContext;
+}): Promise<{
+    proposals: ClassificationProposal[];
+    writeback: WritebackResult;
+}>;
+//# sourceMappingURL=proposal-pipeline.d.ts.map

package/out/parser/proposal-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-pipeline.d.ts","sourceRoot":"","sources":["../../parser/proposal-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EAGtB,KAAK,kBAAkB,EACvB,MAAM,mBAAmB,CAAA;AAE1B;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,QAAQ,EAAE,SAAS,IAAI,EAAE,EACzB,WAAW,EAAE,SAAS,kBAAkB,EAAE,EAC1C,OAAO,GAAE,iBAAsB,GAC7B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAenC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC7B,SAAS,EAAE,SAAS,sBAAsB,EAAE,EAC5C,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB,sBAAsB,EAAE,CAG1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAc9F;AAED;;;GAGG;AACH,wBAAiB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC,IAAI,CAAC,CAc3E;AAED,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,EAAE,MAAM,CAAA;IAC1B,aAAa,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EAAE,SAAS,sBAAsB,EAAE,EAC5C,OAAO,EAAE,YAAY,GACnB,eAAe,CAqBjB;AAED,8FAA8F;AAC9F,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,SAAS,kBAAkB,EAAE,EAC1C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CAAO,GAC/F,OAAO,CAAC;IAAE,SAAS,EAAE,sBAAsB,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,CAK9E"}

package/out/parser/proposal-pipeline.js

@@ -0,0 +1,127 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Parser-level proposal pipeline.
+ *
+ *   Stitches together three pieces that already exist independently:
+ *
+ *   1. Per-section fan-out across a list of `ProposalClassifier`s (rule or neural — same shape).
+ *   2. `PolicyRegistry.apply()` filters the merged proposal stream by per-component policy modes.
+ *   3. Surviving proposals are written back into the `TokenContext` as legacy `Classification`s the
+ *        solver can read.
+ *
+ *   Pure module: no resource imports, no top-level await. Safe to import from anywhere.
+ */
+import { componentTagToLegacyClassification, } from "../types/index.js";
+/**
+ * Run every classifier against every section, concatenate the results.
+ *
+ * Classifiers that throw are isolated — their failure logs but does not block other classifiers'
+ * proposals from being collected. (Per the `ProposalClassifier` contract, implementations are
+ * supposed to swallow errors, but defense-in-depth lives here.)
+ */
+export async function collectProposals(sections, classifiers, context = {}) {
+    const tasks = [];
+    for (const classifier of classifiers) {
+        for (const section of sections) {
+            tasks.push(classifier.classify(section, context).catch((err) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[proposal-pipeline] ${classifier.id} threw on section "${section.body}":`, err);
+                return [];
+            }));
+        }
+    }
+    const results = await Promise.all(tasks);
+    return results.flat();
+}
+/**
+ * Optional policy filter. Returns the input unchanged when `policy` is undefined, otherwise
+ * delegates to `PolicyRegistry.apply`.
+ */
+export function filterByPolicy(proposals, policy, locale) {
+    if (!policy)
+        return [...proposals];
+    return policy.apply(proposals, locale);
+}
+/**
+ * Locate the context Span whose [start, end] best matches the given char range.
+ *
+ * Strategy:
+ *
+ * - Prefer an exact match on both `start` and `end`.
+ * - Fall back to the smallest enclosing span (start ≤ target.start && end ≥ target.end).
+ * - Returns null if nothing covers the range — the caller drops the proposal silently.
+ */
+export function findSpanByRange(context, start, end) {
+    let best = null;
+    let bestWidth = Infinity;
+    for (const span of iterateContextSpans(context)) {
+        if (span.start === start && span.end === end)
+            return span;
+        if (span.start <= start && span.end >= end) {
+            const width = span.end - span.start;
+            if (width < bestWidth) {
+                best = span;
+                bestWidth = width;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Walk every span attached to a `TokenContext` — sections, words, phrases — in a single flat pass.
+ * Order isn't guaranteed.
+ */
+export function* iterateContextSpans(context) {
+    const visited = new Set();
+    const queue = [];
+    if (context.span)
+        queue.push(context.span);
+    for (const section of context.sections)
+        queue.push(section);
+    while (queue.length > 0) {
+        const span = queue.pop();
+        if (visited.has(span.id))
+            continue;
+        visited.add(span.id);
+        yield span;
+        for (const child of span.children)
+            queue.push(child);
+        for (const phrase of span.phrases)
+            queue.push(phrase);
+    }
+}
+/**
+ * Write each surviving proposal back to the context's span graph as a legacy `Classification` so
+ * the solver can read it. Returns a small summary useful for telemetry and tests.
+ */
+export function writeProposalsToContext(proposals, context) {
+    let written = 0;
+    let skippedNoLegacyMap = 0;
+    let skippedNoSpan = 0;
+    for (const proposal of proposals) {
+        const legacy = componentTagToLegacyClassification(proposal.component);
+        if (!legacy) {
+            skippedNoLegacyMap++;
+            continue;
+        }
+        const span = findSpanByRange(context, proposal.span.start, proposal.span.end);
+        if (!span) {
+            skippedNoSpan++;
+            continue;
+        }
+        span.classifications.add(legacy, proposal.confidence);
+        written++;
+    }
+    return { written, skippedNoLegacyMap, skippedNoSpan };
+}
+/** Combined entrypoint: collect + filter + write. Returns the (post-filter) proposal list. */
+export async function runProposalPipeline(context, classifiers, options = {}) {
+    const raw = await collectProposals(context.sections, classifiers, options.classifierContext ?? {});
+    const filtered = filterByPolicy(raw, options.policy, options.locale);
+    const writeback = writeProposalsToContext(filtered, context);
+    return { proposals: filtered, writeback };
+}
+//# sourceMappingURL=proposal-pipeline.js.map

package/out/parser/proposal-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-pipeline.js","sourceRoot":"","sources":["../../parser/proposal-pipeline.ts"],"names":[],"mappings":"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"}

package/out/policy/defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Default policy table: every component is `rule_only` until per-tag golden-set metrics justify a
+ *   migration. This file is the canonical place to record such migrations; each Phase 2+ rollout
+ *   edits one entry here with a commit-message rationale.
+ */
+import { type ComponentTag } from "@mailwoman/core/types";
+import type { ClassifierPolicy } from "./policy.js";
+/**
+ * Build a fresh array of `rule_only` policies — one per `ComponentTag`. Returns a new array on each
+ * call; callers may mutate it freely.
+ */
+export declare function buildDefaultPolicies(): ClassifierPolicy[];
+/**
+ * Convenience accessor for a single-component default.
+ */
+export declare function defaultPolicyFor(component: ComponentTag): ClassifierPolicy;
+//# sourceMappingURL=defaults.d.ts.map

package/out/policy/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../policy/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CAKzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,YAAY,GAAG,gBAAgB,CAE1E"}

package/out/policy/defaults.js

@@ -0,0 +1,27 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Default policy table: every component is `rule_only` until per-tag golden-set metrics justify a
+ *   migration. This file is the canonical place to record such migrations; each Phase 2+ rollout
+ *   edits one entry here with a commit-message rationale.
+ */
+import { COMPONENT_TAGS } from "@mailwoman/core/types";
+/**
+ * Build a fresh array of `rule_only` policies — one per `ComponentTag`. Returns a new array on each
+ * call; callers may mutate it freely.
+ */
+export function buildDefaultPolicies() {
+    return COMPONENT_TAGS.map((component) => ({
+        component,
+        mode: "rule_only",
+    }));
+}
+/**
+ * Convenience accessor for a single-component default.
+ */
+export function defaultPolicyFor(component) {
+    return { component, mode: "rule_only" };
+}
+//# sourceMappingURL=defaults.js.map

package/out/policy/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../policy/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAqB,MAAM,uBAAuB,CAAA;AAGzE;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IACnC,OAAO,cAAc,CAAC,GAAG,CAAmB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC3D,SAAS;QACT,IAAI,EAAE,WAAW;KACjB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAuB;IACvD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;AACxC,CAAC"}

package/out/policy/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "./defaults.js";
+export * from "./policy.js";
+export * from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/out/policy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../policy/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/out/policy/index.js

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export * from "./defaults.js";
+export * from "./policy.js";
+export * from "./registry.js";
+//# sourceMappingURL=index.js.map

package/out/policy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../policy/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/out/policy/policy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Classifier policy types (per #6). A `ClassifierPolicy` declares which classifier family (rule /
+ *   neural / both / preferred) has authority for each `ComponentTag`, optionally narrowed by
+ *   locale. The default table starts every component in `rule_only` mode; migrations to
+ *   neural-backed modes happen one component at a time, gated on golden-set metrics.
+ */
+import type { ClassificationProposal, ComponentTag } from "@mailwoman/core/types";
+/**
+ * How a component is sourced.
+ *
+ * - `rule_only`: keep only `source === "rule"` proposals (default).
+ * - `neural_only`: keep only `source === "neural"` proposals.
+ * - `both`: keep proposals from any source.
+ * - `neural_preferred`: keep all proposals, but drop rule proposals when at least one neural proposal
+ *   exists for the same component.
+ * - `rule_preferred`: mirror of `neural_preferred`, with rule winning.
+ */
+export type PolicyMode = "rule_only" | "neural_only" | "both" | "neural_preferred" | "rule_preferred";
+/**
+ * A single policy entry. Locale-less entries are the global default; locale-scoped entries override
+ * the global default for that locale.
+ */
+export interface ClassifierPolicy {
+    component: ComponentTag;
+    mode: PolicyMode;
+    /**
+     * Minimum confidence for a proposal to be retained. Applied before the policy-mode filter.
+     * Inclusive ([threshold, 1.0]). Undefined means "no threshold."
+     */
+    confidence_threshold?: number;
+    /**
+     * Locale scope. If absent, the entry applies to every locale unless overridden by a
+     * locale-specific entry.
+     */
+    locale?: string;
+}
+/**
+ * Read-side view of the policy table.
+ */
+export interface PolicyRegistry {
+    /**
+     * Look up the effective policy for a (component, locale) pair. A locale-specific entry wins over
+     * a global one; if neither exists, the registry-wide default (`rule_only`, no threshold) is
+     * returned.
+     */
+    lookup(component: ComponentTag, locale?: string): ClassifierPolicy;
+    /**
+     * Apply policy filtering to a flat list of proposals. Output is a new array; the input is not
+     * mutated.
+     */
+    apply(proposals: readonly ClassificationProposal[], locale?: string): ClassificationProposal[];
+}
+//# sourceMappingURL=policy.d.ts.map

package/out/policy/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../policy/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEjF;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,GAAG,kBAAkB,GAAG,gBAAgB,CAAA;AAErG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,YAAY,CAAA;IACvB,IAAI,EAAE,UAAU,CAAA;IAEhB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAA;IAElE;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,sBAAsB,EAAE,CAAA;CAC9F"}

package/out/policy/policy.js

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Classifier policy types (per #6). A `ClassifierPolicy` declares which classifier family (rule /
+ *   neural / both / preferred) has authority for each `ComponentTag`, optionally narrowed by
+ *   locale. The default table starts every component in `rule_only` mode; migrations to
+ *   neural-backed modes happen one component at a time, gated on golden-set metrics.
+ */
+export {};
+//# sourceMappingURL=policy.js.map

package/out/policy/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../policy/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/out/policy/registry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   In-memory `PolicyRegistry`. Stores per-(component, locale) policy entries and applies them to a
+ *   flat list of `ClassificationProposal`s.
+ *
+ *   Mutation API (`set`, `remove`) lives here so that locale profiles (#6 §LocaleProfile) can install
+ *   per-locale overrides at startup. Look-up and `apply` are pure.
+ */
+import type { ClassificationProposal, ComponentTag } from "@mailwoman/core/types";
+import type { ClassifierPolicy, PolicyRegistry } from "./policy.js";
+/**
+ * Concrete registry implementation. Construct empty with `new InMemoryPolicyRegistry()` and load
+ * entries via `set()`, or pre-load defaults via `InMemoryPolicyRegistry.withDefaults()`.
+ */
+export declare class InMemoryPolicyRegistry implements PolicyRegistry {
+    #private;
+    /** Build a registry pre-loaded with `rule_only` for every component. */
+    static withDefaults(): InMemoryPolicyRegistry;
+    /** Install a policy entry. Replaces any prior entry with the same key. */
+    set(policy: ClassifierPolicy): void;
+    /** Remove a policy entry, if present. */
+    remove(component: ComponentTag, locale?: string): void;
+    /** All current entries, in insertion order. */
+    entries(): ClassifierPolicy[];
+    lookup(component: ComponentTag, locale?: string): ClassifierPolicy;
+    apply(proposals: readonly ClassificationProposal[], locale?: string): ClassificationProposal[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/out/policy/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../policy/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEjF,OAAO,KAAK,EAAE,gBAAgB,EAAc,cAAc,EAAE,MAAM,aAAa,CAAA;AAQ/E;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,cAAc;;IAG5D,wEAAwE;IACxE,MAAM,CAAC,YAAY,IAAI,sBAAsB;IAQ7C,0EAA0E;IAC1E,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAInC,yCAAyC;IACzC,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAItD,+CAA+C;IAC/C,OAAO,IAAI,gBAAgB,EAAE;IAI7B,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAUlE,KAAK,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,sBAAsB,EAAE;CAkB9F"}

package/out/policy/registry.js

@@ -0,0 +1,114 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   In-memory `PolicyRegistry`. Stores per-(component, locale) policy entries and applies them to a
+ *   flat list of `ClassificationProposal`s.
+ *
+ *   Mutation API (`set`, `remove`) lives here so that locale profiles (#6 §LocaleProfile) can install
+ *   per-locale overrides at startup. Look-up and `apply` are pure.
+ */
+import { buildDefaultPolicies, defaultPolicyFor } from "./defaults.js";
+const GLOBAL_LOCALE_KEY = "*";
+function policyKey(component, locale) {
+    return `${component}::${locale ?? GLOBAL_LOCALE_KEY}`;
+}
+/**
+ * Concrete registry implementation. Construct empty with `new InMemoryPolicyRegistry()` and load
+ * entries via `set()`, or pre-load defaults via `InMemoryPolicyRegistry.withDefaults()`.
+ */
+export class InMemoryPolicyRegistry {
+    #entries = new Map();
+    /** Build a registry pre-loaded with `rule_only` for every component. */
+    static withDefaults() {
+        const registry = new InMemoryPolicyRegistry();
+        for (const policy of buildDefaultPolicies()) {
+            registry.set(policy);
+        }
+        return registry;
+    }
+    /** Install a policy entry. Replaces any prior entry with the same key. */
+    set(policy) {
+        this.#entries.set(policyKey(policy.component, policy.locale), policy);
+    }
+    /** Remove a policy entry, if present. */
+    remove(component, locale) {
+        this.#entries.delete(policyKey(component, locale));
+    }
+    /** All current entries, in insertion order. */
+    entries() {
+        return Array.from(this.#entries.values());
+    }
+    lookup(component, locale) {
+        if (locale) {
+            const localized = this.#entries.get(policyKey(component, locale));
+            if (localized)
+                return localized;
+        }
+        const global = this.#entries.get(policyKey(component, undefined));
+        if (global)
+            return global;
+        return defaultPolicyFor(component);
+    }
+    apply(proposals, locale) {
+        const passedThreshold = [];
+        const policyByComponent = new Map();
+        for (const proposal of proposals) {
+            const policy = policyByComponent.get(proposal.component) ?? this.lookup(proposal.component, locale);
+            policyByComponent.set(proposal.component, policy);
+            if (typeof policy.confidence_threshold === "number" && proposal.confidence < policy.confidence_threshold) {
+                continue;
+            }
+            if (!matchesMode(proposal, policy.mode))
+                continue;
+            passedThreshold.push(proposal);
+        }
+        return applyPreferenceFilters(passedThreshold, policyByComponent);
+    }
+}
+function matchesMode(proposal, mode) {
+    switch (mode) {
+        case "rule_only":
+            return proposal.source === "rule";
+        case "neural_only":
+            return proposal.source === "neural";
+        case "both":
+        case "rule_preferred":
+        case "neural_preferred":
+            return proposal.source === "rule" || proposal.source === "neural" || proposal.source === "merged";
+    }
+}
+/**
+ * Second pass for `rule_preferred` / `neural_preferred`: within each component, drop the
+ * dispreferred source when the preferred source has at least one survivor.
+ */
+function applyPreferenceFilters(proposals, policyByComponent) {
+    const grouped = new Map();
+    for (const proposal of proposals) {
+        const list = grouped.get(proposal.component) ?? [];
+        list.push(proposal);
+        grouped.set(proposal.component, list);
+    }
+    const out = [];
+    for (const [component, list] of grouped) {
+        const policy = policyByComponent.get(component);
+        if (!policy) {
+            out.push(...list);
+            continue;
+        }
+        if (policy.mode === "neural_preferred") {
+            const hasNeural = list.some((p) => p.source === "neural");
+            out.push(...(hasNeural ? list.filter((p) => p.source !== "rule") : list));
+            continue;
+        }
+        if (policy.mode === "rule_preferred") {
+            const hasRule = list.some((p) => p.source === "rule");
+            out.push(...(hasRule ? list.filter((p) => p.source !== "neural") : list));
+            continue;
+        }
+        out.push(...list);
+    }
+    return out;
+}
+//# sourceMappingURL=registry.js.map

package/out/policy/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../policy/registry.ts"],"names":[],"mappings":"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"}

package/out/resources/LocaleIndex.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { TextNormalizer } from "../tokenization/normalizer.js";
+import type { Displayable } from "./debugging.js";
+/**
+ * Options for the locale index.
+ */
+export interface LocaleIndexOptions {
+    displayName: string;
+    normalizer?: TextNormalizer;
+}
+/**
+ * Index mapping a specific value to originating languages.
+ *
+ * If a value is present in this index, it means that the value is a valid value in at least one
+ * language.
+ */
+export declare class LocaleIndex<LanguageCodes extends string> extends Map<string, Set<LanguageCodes>> {
+    /**
+     * The normalizer to use for placenames.
+     */
+    readonly normalizer?: TextNormalizer;
+    /**
+     * The source of the index.
+     */
+    displayName: string;
+    constructor(entries: Iterable<readonly [string, Iterable<LanguageCodes>]> | undefined, options: LocaleIndexOptions);
+    /**
+     * Add a placename to the index, associating it with the given language codes.
+     *
+     * @param placename The placename to add.
+     * @param languageCodes The language codes to associate with the placename.
+     */
+    add(placename: string, ...languageCodes: LanguageCodes[]): void;
+    /**
+     * Remove a placename from the index.
+     *
+     * @param placename The placename to remove.
+     */
+    remove(placename: string): void;
+    open(placename: string): Displayable<Set<LanguageCodes>>;
+    /**
+     * Get the language codes associated with a placename.
+     */
+    get: (placename: string) => Displayable<Set<LanguageCodes>> | undefined;
+    /**
+     * Serialize the index to JSON.
+     */
+    toJSON(): [string, LanguageCodes[]][];
+}
+//# sourceMappingURL=LocaleIndex.d.ts.map

package/out/resources/LocaleIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocaleIndex.d.ts","sourceRoot":"","sources":["../../resources/LocaleIndex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,cAAc,CAAA;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,aAAa,SAAS,MAAM,CAAE,SAAQ,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;IAC7F;;OAEG;IACH,SAAgB,UAAU,CAAC,EAAE,cAAc,CAAA;IAE3C;;OAEG;IACI,WAAW,EAAE,MAAM,CAAA;gBAEd,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,YAAK,EAAE,OAAO,EAAE,kBAAkB;IAW3G;;;;;OAKG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,aAAa,EAAE,GAAG,IAAI;IAsBtE;;;;OAIG;IACI,MAAM,CAAC,SAAS,EAAE,MAAM;IAUxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAmB/D;;OAEG;IACK,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,GAAG,SAAS,CAAA;IAE/E;;OAEG;IACI,MAAM;CASb"}