@mailwoman/core 2.1.0 → 2.2.0

package/out/pipeline/reconcile.js

@@ -0,0 +1,355 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `reconcileSpans` — Stage 5 joint-decoding path.
+ *
+ *   Today's runtime Stage 5 (in `runtime-pipeline.ts`) just keeps the classifier-emitted spans in
+ *   start order. That fallback covers callers who don't yet have top-k inputs from Stages 2.7 / 3 /
+ *   6. This file is the **opt-in** joint-decoding path that turns Stage 5 from a sort into a
+ *   reconciler: pick the parse tree that maximizes
+ *
+ *   ```
+ *   ∏  phrase_grouper_confidence
+ *    × classifier_confidence
+ *    × resolver_score
+ *    × concordance_bonus(parent_id chain)
+ * ```
+ *
+ *   Closes the kryptonite catalogue (`NY-NY Steakhouse, Houston, TX`, `Paris, Texas`, `Saint
+ *   Petersburg, FL`, `Buffalo Buffalo`) where today's argmax-per-stage produces internally-
+ *   inconsistent parses that the layer above can't repair.
+ *
+ *   The implementation is a beam search over candidate slots — each slot is one `(phrase_span,
+ *   classifier_tag, resolver_place)` triple. Three knobs prune the cross product: `kSpan` (de-duped
+ *   phrase span proposals), `kTag` (classifier tag interpretations per span), and `kResolver`
+ *   (resolver candidates per `(span, tag)`). Concordance scoring is incremental — when a slot is
+ *   added, we check the new place's `parent_id` chain against the running admin assignment and
+ *   adjust the running score before pruning.
+ *
+ *   The Thread C-s classifier top-k contract is mocked locally for v0.5.0 (see `ClassifierCandidate`
+ *   below). The real classifier output adapter ships with `@mailwoman/neural` once Thread C-s
+ *   lands; the existing `ResolvedPlace` shape from `@mailwoman/core/resolver` is what backs the
+ *   resolver-candidates axis (parent_id chains live there).
+ *
+ *   See `docs/articles/plan/phases/PHASE_8_v0_5_0_fresh_slate.md` § D for the v0.5.0 context and
+ *   `docs/articles/concepts/the-knowledge-ladder.md` § Reconcile for the design rationale.
+ */
+const DEFAULTS = {
+    kSpan: 3,
+    kTag: 3,
+    kResolver: 5,
+    concordanceWeight: 1.0,
+    beamWidth: 16,
+    runnersUp: 3,
+};
+/**
+ * Log-space bonus per accepted slot. Counterweight for the multiplicative penalty inherent in
+ * "score = ∏ confidences": each factor in [0, 1] strictly lowers the running score, which would
+ * otherwise make the empty parse always win. log(2.5) — a slot whose product of factors exceeds
+ * 1/2.5 = 0.4 is worth including; below that, the search prefers to skip.
+ *
+ * The choice of 2.5 is a tuning constant, not a free parameter we expose — exposing it would invite
+ * callers to disable inclusion entirely (defeating the purpose of the reconciler) and the sensible
+ * range is narrow. Lives here rather than `ReconcileOpts` for that reason.
+ */
+const INCLUSION_LOG_BONUS = Math.log(2.5);
+/**
+ * Admin levels from coarse to fine. Concordance scoring walks pairs (parent_level, child_level) and
+ * checks the child's parent_id chain for the parent's place id.
+ */
+const ADMIN_LEVELS = ["country", "region", "locality", "dependent_locality"];
+const ADMIN_LEVEL_SET = new Set(ADMIN_LEVELS);
+/**
+ * Joint-decode the best parse tree from Stage 2.7 phrase proposals, Stage 3 classifier top-k, and
+ * Stage 6 resolver candidates. See file header for the scoring formula.
+ *
+ * The result tree's roots are the winning `(span, tag, place)` triples in source order. Each node's
+ * `placeId`, `lat`, `lon` come from the chosen resolver candidate; `confidence` reflects the per-
+ * factor score for that slot. `runnersUp` are the next-best parses for caller inspection.
+ *
+ * Empty `classifierTopK` short-circuits to an empty tree at confidence 0 — no joint decode is
+ * possible without tag interpretations. Callers without top-k should use the runtime-pipeline
+ * fallback (which keeps classifier-emitted spans sorted by start).
+ */
+export function reconcileSpans(inputs) {
+    const opts = { ...DEFAULTS, ...inputs.opts };
+    const slots = buildSlots(inputs, opts);
+    if (slots.length === 0) {
+        return emptyParseTree(inputs.raw);
+    }
+    // Beam search over left-to-right slot inclusion. Each slot is either accepted (if non-
+    // overlapping with the beam's claimed range) or skipped. Beam pruning keeps the top
+    // `beamWidth` by running log-score.
+    const slotsByStart = slots.slice().sort((a, b) => a.span.start - b.span.start);
+    let beams = [{ assignments: [], logScore: 0, lastEnd: -1 }];
+    for (const slot of slotsByStart) {
+        const next = [];
+        for (const beam of beams) {
+            next.push(beam);
+            if (slot.span.start >= beam.lastEnd) {
+                const concordanceDelta = concordanceDeltaFor(beam.assignments, slot, inputs, opts);
+                if (concordanceDelta === Number.NEGATIVE_INFINITY)
+                    continue;
+                const slotLog = logSafe(slot.phraseConf) +
+                    logSafe(slot.classifierScore) +
+                    logSafe(slot.resolverScore) +
+                    concordanceDelta +
+                    INCLUSION_LOG_BONUS;
+                next.push({
+                    assignments: [...beam.assignments, slot],
+                    logScore: beam.logScore + slotLog,
+                    lastEnd: slot.span.end,
+                });
+            }
+        }
+        next.sort((a, b) => b.logScore - a.logScore);
+        beams = next.slice(0, opts.beamWidth);
+    }
+    beams.sort((a, b) => b.logScore - a.logScore);
+    // Drop the empty beam if there's at least one non-empty competitor (the empty beam scores 0,
+    // which would otherwise dominate when all real candidates have very low log-scores).
+    const populated = beams.filter((b) => b.assignments.length > 0);
+    const ordered = populated.length > 0 ? populated : beams;
+    const top = ordered[0];
+    const runners = ordered.slice(1, 1 + opts.runnersUp);
+    const trees = ordered.map((b) => buildTree(b, inputs.raw));
+    const confidences = softmax(ordered.map((b) => b.logScore));
+    return {
+        tree: trees[0],
+        confidence: confidences[0],
+        runnersUp: runners.map((_, i) => trees[i + 1]),
+        scoreBreakdown: breakdownFor(top, inputs, opts),
+    };
+}
+/**
+ * Build the candidate slot set: dedupe phrase proposals by (start, end), join with classifier top-k
+ * tag candidates, join with resolver places per (span, tag).
+ *
+ * Spans with no classifier candidate are dropped — the reconciler cannot tag them. Spans with no
+ * resolver candidate still survive; the resolver score defaults to 1 (neutral) and the slot's place
+ * is null (won't contribute to concordance).
+ */
+function buildSlots(inputs, opts) {
+    const bySpanKey = new Map();
+    for (const p of inputs.phraseProposals) {
+        const k = spanKey(p.span.start, p.span.end);
+        const cur = bySpanKey.get(k);
+        if (!cur || p.confidence > cur.confidence) {
+            bySpanKey.set(k, p);
+        }
+    }
+    // `kSpan` limits the number of overlapping proposals anchored at each start position — NOT a
+    // global cap on phrase proposals. Two phrases at different starts (e.g. `Houston` at 18 +
+    // `TX` at 27) are independent candidates and both must survive `kSpan = 3`. Without this per-
+    // start grouping, a low-confidence-but-correct proposal (e.g. `Houston` @ 0.65) is dropped
+    // just because the input has many higher-confidence proposals elsewhere.
+    const byStart = new Map();
+    for (const p of bySpanKey.values()) {
+        const arr = byStart.get(p.span.start) ?? [];
+        arr.push(p);
+        byStart.set(p.span.start, arr);
+    }
+    const spans = [];
+    for (const arr of byStart.values()) {
+        spans.push(...topN(arr, opts.kSpan, (p) => p.confidence));
+    }
+    const tagsBySpan = new Map();
+    for (const c of inputs.classifierTopK) {
+        const k = spanKey(c.span.start, c.span.end);
+        const arr = tagsBySpan.get(k) ?? [];
+        arr.push(c);
+        tagsBySpan.set(k, arr);
+    }
+    const slots = [];
+    for (const phrase of spans) {
+        const key = spanKey(phrase.span.start, phrase.span.end);
+        const tagCandidates = topN(tagsBySpan.get(key) ?? [], opts.kTag, (c) => c.score);
+        for (const tagC of tagCandidates) {
+            const places = inputs.resolverCandidates
+                ? inputs.resolverCandidates.candidatesFor(tagC.span, tagC.tag).slice(0, opts.kResolver)
+                : [];
+            if (places.length === 0) {
+                slots.push({
+                    span: phrase.span,
+                    phraseConf: phrase.confidence,
+                    tag: tagC.tag,
+                    classifierScore: tagC.score,
+                    place: null,
+                    resolverScore: 1,
+                });
+                continue;
+            }
+            for (const place of places) {
+                slots.push({
+                    span: phrase.span,
+                    phraseConf: phrase.confidence,
+                    tag: tagC.tag,
+                    classifierScore: tagC.score,
+                    place,
+                    resolverScore: normalizeResolverScore(place.score),
+                });
+            }
+        }
+    }
+    return slots;
+}
+/**
+ * Concordance delta for adding `slot` to an existing beam. Returns the log-space contribution to
+ * add to the beam's running score, or `-Infinity` if the slot introduces a hard contradiction
+ * (would be admissible into the beam's admin chain but explicitly disagrees).
+ *
+ * Behavior at the boundaries:
+ *
+ * - Slot has no place or is non-admin → 0 (no chain contribution).
+ * - No admin neighbors yet → 0 (nothing to agree with).
+ * - Admin chain agrees → `+ concordanceWeight × log(1 + match_ratio)`.
+ * - Some admin pairs cannot be verified (missing parents) → 0 contribution per neutral pair.
+ * - Admin chain has any explicit contradiction → `-Infinity` (hard veto).
+ */
+function concordanceDeltaFor(existing, candidate, inputs, opts) {
+    if (!candidate.place || !ADMIN_LEVEL_SET.has(candidate.tag))
+        return 0;
+    const chainOf = inputs.parentChain;
+    if (!chainOf)
+        return 0;
+    const candIdx = ADMIN_LEVELS.indexOf(candidate.tag);
+    let matches = 0;
+    let neutrals = 0;
+    let pairs = 0;
+    for (const prior of existing) {
+        if (!prior.place || !ADMIN_LEVEL_SET.has(prior.tag))
+            continue;
+        const priorIdx = ADMIN_LEVELS.indexOf(prior.tag);
+        const child = priorIdx > candIdx ? prior : candidate;
+        const parent = priorIdx > candIdx ? candidate : prior;
+        if (child === parent)
+            continue;
+        const chain = chainOf.parentsOf(child.place);
+        pairs++;
+        if (chain.length === 0) {
+            neutrals++;
+            continue;
+        }
+        const hit = chain.some((p) => idsEqual(p.id, parent.place.id));
+        if (hit) {
+            matches++;
+        }
+        else {
+            return Number.NEGATIVE_INFINITY;
+        }
+    }
+    if (pairs === 0)
+        return 0;
+    const matchRatio = matches / pairs;
+    // Linear in matchRatio so a fully-consistent chain contributes exactly `+concordanceWeight`
+    // log-space — the briefing's "+1 for fully consistent" reading. Matches contribute
+    // proportionally; neutrals (no chain data) don't penalize.
+    return opts.concordanceWeight * matchRatio;
+}
+function idsEqual(a, b) {
+    return String(a) === String(b);
+}
+/**
+ * Compute the per-factor breakdown for the winning beam. Independently of the search's `logScore`
+ * (which carries the inclusion-bonus prior), the breakdown surfaces the bare `phrase × classifier ×
+ * resolver × concordance` product so callers can introspect why a tree won.
+ */
+function breakdownFor(beam, inputs, opts) {
+    let phrase = 1;
+    let classifier = 1;
+    let resolver = 1;
+    for (const a of beam.assignments) {
+        phrase *= Math.max(a.phraseConf, 0);
+        classifier *= Math.max(a.classifierScore, 0);
+        resolver *= Math.max(a.resolverScore, 0);
+    }
+    const concordanceLog = totalConcordanceLog(beam.assignments, inputs, opts);
+    const concordance = Math.exp(concordanceLog);
+    const total = phrase * classifier * resolver * concordance;
+    return { phrase, classifier, resolver, concordance, total };
+}
+/**
+ * Recompute the joint concordance contribution for the entire assignment list (vs the incremental
+ * `concordanceDeltaFor` used during search). Used by the breakdown.
+ */
+function totalConcordanceLog(assignments, inputs, opts) {
+    if (!inputs.parentChain)
+        return 0;
+    let acc = 0;
+    for (let i = 0; i < assignments.length; i++) {
+        const delta = concordanceDeltaFor(assignments.slice(0, i), assignments[i], inputs, opts);
+        if (delta === Number.NEGATIVE_INFINITY)
+            return Number.NEGATIVE_INFINITY;
+        acc += delta;
+    }
+    return acc;
+}
+function buildTree(beam, raw) {
+    const roots = beam.assignments
+        .slice()
+        .sort((a, b) => a.span.start - b.span.start)
+        .map((slot) => ({
+        tag: slot.tag,
+        value: raw.slice(slot.span.start, slot.span.end),
+        start: slot.span.start,
+        end: slot.span.end,
+        confidence: slot.classifierScore * slot.phraseConf,
+        children: [],
+        source: "reconcile",
+        sourceId: "reconcile:stage-5-joint",
+        ...(slot.place
+            ? {
+                lat: slot.place.lat,
+                lon: slot.place.lon,
+                placeId: `${placeIdPrefix(slot.place)}:${slot.place.id}`,
+            }
+            : {}),
+    }));
+    return { raw, roots };
+}
+function emptyParseTree(raw) {
+    return {
+        tree: { raw, roots: [] },
+        confidence: 0,
+        runnersUp: [],
+        scoreBreakdown: { phrase: 0, classifier: 0, resolver: 0, concordance: 1, total: 0 },
+    };
+}
+function placeIdPrefix(place) {
+    // Mirror the convention used by @mailwoman/resolver-wof-sqlite (`wof:<id>`). Resolver
+    // backends that don't carry an implicit vendor in `id` get a neutral `place:` prefix.
+    return typeof place.id === "number" ? "wof" : "place";
+}
+function spanKey(start, end) {
+    return `${start}:${end}`;
+}
+function topN(items, n, key) {
+    return items
+        .slice()
+        .sort((a, b) => key(b) - key(a))
+        .slice(0, n);
+}
+function logSafe(x) {
+    return x > 0 ? Math.log(x) : -50;
+}
+function normalizeResolverScore(score) {
+    // Resolver score scale is implementation-defined; clamp to (0, 1] for the multiplicative
+    // combiner. A backend that returns 0 still counts as a candidate (e.g. a partial match) but
+    // contributes a tiny log-factor.
+    if (!Number.isFinite(score) || score <= 0)
+        return 0.01;
+    if (score > 1)
+        return 1;
+    return score;
+}
+function softmax(scores) {
+    if (scores.length === 0)
+        return [];
+    const max = Math.max(...scores);
+    const exps = scores.map((s) => Math.exp(s - max));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+}
+//# sourceMappingURL=reconcile.js.map

package/out/pipeline/reconcile.js.map

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

package/out/pipeline/runtime-pipeline.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `runPipeline` — the runtime coordinator that composes all six stages.
+ *
+ *   Generic over stage implementations (see `types.ts::RuntimePipelineStages`). Each stage is
+ *   injected; the coordinator handles composition, timing, fast-path routing, and graceful
+ *   degradation when stages are absent.
+ *
+ *   Implementation contract per `docs/articles/plan/reference/STAGES.md`.
+ */
+import type { PipelineOpts, PipelineResult, RuntimePipelineStages } from "./types.js";
+/**
+ * Run the runtime pipeline.
+ *
+ * Composition order (per STAGES.md):
+ *
+ * 1. Normalize (or identity)
+ * 2. Compute QueryShape (or empty)
+ * 3. Locale gate (or caller-trust)
+ * 4. Kind classifier (or default structured_address)
+ * 5. Branch: fast-path → resolver; full → classifier → resolver
+ *
+ * Per-stage timing recorded on `result.timing`. Fast-path stages are absent from the timing map.
+ */
+export declare function runPipeline(raw: string, stages: RuntimePipelineStages, opts?: PipelineOpts): Promise<PipelineResult>;
+//# sourceMappingURL=runtime-pipeline.d.ts.map

package/out/pipeline/runtime-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-pipeline.d.ts","sourceRoot":"","sources":["../../pipeline/runtime-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAMX,YAAY,EACZ,cAAc,EAGd,qBAAqB,EACrB,MAAM,YAAY,CAAA;AA6HnB;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,qBAAqB,EAC7B,IAAI,CAAC,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,CA8IzB"}