@mailwoman/core 2.1.0 → 2.2.0

package/out/pipeline/runtime-pipeline.js

@@ -0,0 +1,288 @@
+/**
+ * @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 { reconcileSpans } from "./reconcile.js";
+import { aggregateSpanLogits } from "./span-logit-aggregation.js";
+/**
+ * Known QueryShape format strings that indicate "this token is a postcode". Mirrors the set in
+ *
+ * @mailwoman/kind-classifier — kept duplicated so core/pipeline has no dep on kind-classifier.
+ */
+const POSTCODE_FORMATS = new Set([
+    "us_zip",
+    "us_zip4",
+    "uk_postcode",
+    "fr_postcode",
+    "de_postcode",
+    "ca_postcode",
+    "jp_postcode",
+]);
+function isPostcodeFormat(format) {
+    return POSTCODE_FORMATS.has(format);
+}
+function isPostcodeFormatHit(hit) {
+    return isPostcodeFormat(hit.format);
+}
+/** Pass-through normalize used when no `normalize` stage is wired. */
+function identityNormalize(raw, opts) {
+    return { raw, normalized: raw, appliedLocale: opts?.locale };
+}
+/** No-op query-shape used when no `computeQueryShape` stage is wired. */
+function emptyQueryShape() {
+    return { knownFormats: [] };
+}
+/** Default locale detector: trusts the caller's hint, or falls back to `und`. */
+async function defaultDetectLocale(_input, _shape, opts) {
+    const locale = opts?.hint ?? "und";
+    return {
+        locale,
+        confidence: opts?.hint ? 1.0 : 0.0,
+        alternatives: [],
+        source: opts?.hint ? "caller" : "detected",
+    };
+}
+/** Default kind classifier: always returns `structured_address` with low confidence (no fast-path). */
+async function defaultClassifyKind(_input, _shape, _locale) {
+    return {
+        kind: "structured_address",
+        confidence: 0.0,
+        alternatives: [],
+    };
+}
+/**
+ * Decide whether to short-circuit stages 3-5 and go straight to resolve. Conservative: requires
+ * high kind-classifier confidence AND a matching QueryShape known-format hit. See
+ * `STAGES.md#fast-path-routing` for the rationale.
+ */
+function canShortCircuit(kind, shape, opts) {
+    if (opts?.forceFullPipeline)
+        return false;
+    if (kind.confidence < 0.95)
+        return false;
+    if (kind.kind === "postcode_only") {
+        return shape.knownFormats.some(isPostcodeFormatHit);
+    }
+    if (kind.kind === "locality_only") {
+        return (shape.totalLength ?? Infinity) <= 30 && shape.characterClass === "alpha";
+    }
+    return false;
+}
+/**
+ * Build a stub `AddressTree` for the fast-path case (no classifier ran). Single root node tagged by
+ * the QueryShape's known-format hit.
+ */
+function buildFastPathTree(text, kind, shape) {
+    if (kind.kind === "postcode_only") {
+        const hit = shape.knownFormats.find((f) => isPostcodeFormat(f.format));
+        if (hit) {
+            return {
+                raw: text,
+                roots: [
+                    {
+                        tag: "postcode",
+                        value: text.slice(hit.span.start, hit.span.end),
+                        start: hit.span.start,
+                        end: hit.span.end,
+                        confidence: hit.confidence,
+                        children: [],
+                        source: "query-shape",
+                        sourceId: hit.format,
+                    },
+                ],
+            };
+        }
+    }
+    if (kind.kind === "locality_only") {
+        return {
+            raw: text,
+            roots: [
+                {
+                    tag: "locality",
+                    value: text.trim(),
+                    start: 0,
+                    end: text.length,
+                    confidence: kind.confidence,
+                    children: [],
+                    source: "query-shape",
+                    sourceId: "kind:locality_only",
+                },
+            ],
+        };
+    }
+    return { raw: text, roots: [] };
+}
+/**
+ * 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 async function runPipeline(raw, stages, opts) {
+    const timing = {};
+    const t0 = performance.now();
+    const normalize = stages.normalize ?? identityNormalize;
+    const computeQueryShape = stages.computeQueryShape ?? emptyQueryShape;
+    const detectLocale = stages.detectLocale ?? defaultDetectLocale;
+    const classifyKind = stages.classifyKind ?? defaultClassifyKind;
+    throwIfAborted(opts);
+    const normalized = normalize(raw, { locale: opts?.locale });
+    timing["normalize"] = performance.now() - t0;
+    throwIfAborted(opts);
+    const tQs = performance.now();
+    const queryShape = computeQueryShape(normalized, { locale: opts?.locale });
+    timing["query-shape"] = performance.now() - tQs;
+    throwIfAborted(opts);
+    const tLocale = performance.now();
+    const locale = await detectLocale(normalized, queryShape, { hint: opts?.locale });
+    timing["locale-gate"] = performance.now() - tLocale;
+    throwIfAborted(opts);
+    const tKind = performance.now();
+    const kind = await classifyKind(normalized, queryShape, locale);
+    timing["kind-classifier"] = performance.now() - tKind;
+    // Fast-path: trivial inputs short-circuit stages 3-5. The fast-path tree is built from
+    // QueryShape's format hits + kind alone — useful even without a wired resolver (a consumer
+    // who just wants the parsed structure for a bare postcode shouldn't be forced to pay for the
+    // classifier).
+    if (canShortCircuit(kind, queryShape, opts)) {
+        let tree = buildFastPathTree(normalized.normalized, kind, queryShape);
+        if (stages.resolver) {
+            throwIfAborted(opts);
+            const tResolve = performance.now();
+            tree = await safeResolve(stages.resolver, tree, opts);
+            timing["resolve"] = performance.now() - tResolve;
+        }
+        return {
+            input: raw,
+            normalized,
+            queryShape,
+            locale,
+            kind,
+            phraseProposals: [],
+            tree,
+            timing,
+            path: "fast-path",
+        };
+    }
+    // Full pipeline.
+    // Stage 2.7 — phrase grouper. Optional injection; runs when wired. Proposals flow forward to
+    // stages 3 + 5 (today: surfaced on the result; tomorrow: passed in as classifier conditioning).
+    let phraseProposals = [];
+    if (stages.groupPhrases) {
+        throwIfAborted(opts);
+        const tGroup = performance.now();
+        phraseProposals = await safeGroupPhrases(stages.groupPhrases, normalized, queryShape, locale);
+        timing["phrase-grouper"] = performance.now() - tGroup;
+    }
+    let tree = { raw: normalized.normalized, roots: [] };
+    // Joint-reconcile path: when the flag is set AND we have phrase proposals AND the classifier
+    // exposes parseWithLogits, use per-span logit aggregation + reconcileSpans instead of argmax.
+    const useJointReconcile = opts?.forceJointReconcile &&
+        phraseProposals.length > 0 &&
+        stages.classifier &&
+        "parseWithLogits" in stages.classifier;
+    if (useJointReconcile) {
+        const classifierWithLogits = stages.classifier;
+        throwIfAborted(opts);
+        const tClassify = performance.now();
+        const { tree: argmaxTree, logits, pieces, } = await classifierWithLogits.parseWithLogits(normalized.normalized, { queryShape });
+        timing["token-classify"] = performance.now() - tClassify;
+        throwIfAborted(opts);
+        const tReconcile = performance.now();
+        // The classifier must expose its label vocabulary so the aggregation can strip BIO prefixes.
+        // NeuralAddressClassifier surfaces this as `cfg.labels` — extracted via structural typing here.
+        const labels = "labels" in classifierWithLogits ? classifierWithLogits.labels : [];
+        const classifierTopK = aggregateSpanLogits(logits, pieces, phraseProposals.map((p) => ({ start: p.span.start, end: p.span.end })), { labels });
+        if (classifierTopK.length > 0) {
+            const result = reconcileSpans({
+                raw: normalized.normalized,
+                phraseProposals,
+                classifierTopK,
+            });
+            tree = result.tree;
+        }
+        else {
+            tree = argmaxTree;
+        }
+        timing["reconcile"] = performance.now() - tReconcile;
+    }
+    else if (stages.classifier) {
+        throwIfAborted(opts);
+        const tClassify = performance.now();
+        tree = await safeClassify(stages.classifier, normalized.normalized, queryShape);
+        timing["token-classify"] = performance.now() - tClassify;
+    }
+    if (stages.resolver) {
+        throwIfAborted(opts);
+        const tResolve = performance.now();
+        tree = await safeResolve(stages.resolver, tree, opts);
+        timing["resolve"] = performance.now() - tResolve;
+    }
+    return {
+        input: raw,
+        normalized,
+        queryShape,
+        locale,
+        kind,
+        phraseProposals,
+        tree,
+        timing,
+        path: "full",
+    };
+}
+/**
+ * Throws the signal's reason if aborted. Coarse-grained cancellation: we check between stages, so
+ * the longest cancellation latency is one stage's runtime. Fine-grained mid-stage cancellation
+ * requires plumbing `signal` into each stage's contract (`detectLocale`, `classifyKind`,
+ * `classifier.parse`, `resolver.resolveTree`) — a future enhancement once stage authors are ready
+ * for it. For now, in-flight stages always run to completion before the abort takes effect.
+ */
+function throwIfAborted(opts) {
+    if (opts?.signal?.aborted) {
+        throw opts.signal.reason ?? new DOMException("Pipeline aborted", "AbortError");
+    }
+}
+/** Defensive wrapper: if the classifier throws, return an empty tree rather than abort the pipeline. */
+async function safeClassify(classifier, text, queryShape) {
+    try {
+        return await classifier.parse(text, { queryShape });
+    }
+    catch {
+        return { raw: text, roots: [] };
+    }
+}
+/** Defensive wrapper: a grouper failure returns an empty proposal list rather than abort. */
+async function safeGroupPhrases(groupPhrases, normalized, shape, locale) {
+    try {
+        return await groupPhrases(normalized, shape, locale);
+    }
+    catch {
+        return [];
+    }
+}
+/** Defensive wrapper: a resolver failure leaves the classifier tree intact. */
+async function safeResolve(resolver, tree, opts) {
+    try {
+        return await resolver.resolveTree(tree, opts?.resolveOpts);
+    }
+    catch {
+        return tree;
+    }
+}
+//# sourceMappingURL=runtime-pipeline.js.map

package/out/pipeline/runtime-pipeline.js.map

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

package/out/pipeline/span-logit-aggregation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-span logit aggregation — Option C from the DeepSeek synthesis review.
+ *
+ *   Takes the per-token logits already emitted by the ONNX model (currently discarded after argmax in
+ *   `classifier.ts`) and aggregates them over phrase-grouper spans to produce per-span top-K tag
+ *   candidates. These feed directly into `reconcileSpans` as the `classifierTopK` input.
+ *
+ *   Why this instead of a sequence-level beam decoder: the reconciler takes `(span, tag, score)`
+ *   triples — per-span confidence, not BIO-sequence-level confidence. The phrase grouper has
+ *   already done boundary discovery. This module answers "given these boundaries, what tags does
+ *   the classifier think each span is?" — which is the right abstraction for joint decoding.
+ *
+ *   Code path matches the eventual production runtime: when a top-k-trained classifier exists, the TS
+ *   runtime just swaps "per-token softmax aggregation" for "classifier's native top-k API." Same
+ *   downstream contract.
+ */
+import type { ClassifierCandidate } from "./reconcile.js";
+/**
+ * A token piece with character-level offsets into the original text.
+ */
+export interface TokenPiece {
+    start: number;
+    end: number;
+}
+/**
+ * A span proposal from the phrase grouper, in character offsets.
+ */
+export interface SpanBounds {
+    start: number;
+    end: number;
+}
+/**
+ * Given per-token logits and phrase-grouper spans, produce per-span top-K tag candidates.
+ *
+ * For each span, finds the tokens whose character ranges overlap the span, sums their softmax
+ * probabilities per-tag, normalizes, and emits the top K tags with their aggregated scores.
+ *
+ * BIO prefix stripping: the model emits BIO labels (`B-locality`, `I-locality`, etc.) but the
+ * reconciler works with component tags (`locality`). This function strips the `B-`/`I-` prefix and
+ * merges probabilities: `score(locality) = sum(score(B-locality) + score(I-locality))` across the
+ * span's tokens.
+ *
+ * @param logits Per-token logits from ONNX inference, shape `[seqLen][numLabels]`.
+ * @param pieces Token pieces with character-level offsets (from the tokenizer's `encode`).
+ * @param spans Phrase-grouper span proposals in character offsets.
+ * @param opts Options — `topK` (default 3), `labels` (required — the BIO label vocabulary the model
+ *   emits, e.g. `["O", "B-locality", "I-locality", ...]`).
+ */
+export declare function aggregateSpanLogits(logits: number[][], pieces: readonly TokenPiece[], spans: readonly SpanBounds[], opts: {
+    topK?: number;
+    labels: readonly string[];
+}): ClassifierCandidate[];
+//# sourceMappingURL=span-logit-aggregation.d.ts.map

package/out/pipeline/span-logit-aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-logit-aggregation.d.ts","sourceRoot":"","sources":["../../pipeline/span-logit-aggregation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEzD;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,EAAE,EAAE,EAClB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChD,mBAAmB,EAAE,CAiDvB"}

package/out/pipeline/span-logit-aggregation.js

@@ -0,0 +1,105 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-span logit aggregation — Option C from the DeepSeek synthesis review.
+ *
+ *   Takes the per-token logits already emitted by the ONNX model (currently discarded after argmax in
+ *   `classifier.ts`) and aggregates them over phrase-grouper spans to produce per-span top-K tag
+ *   candidates. These feed directly into `reconcileSpans` as the `classifierTopK` input.
+ *
+ *   Why this instead of a sequence-level beam decoder: the reconciler takes `(span, tag, score)`
+ *   triples — per-span confidence, not BIO-sequence-level confidence. The phrase grouper has
+ *   already done boundary discovery. This module answers "given these boundaries, what tags does
+ *   the classifier think each span is?" — which is the right abstraction for joint decoding.
+ *
+ *   Code path matches the eventual production runtime: when a top-k-trained classifier exists, the TS
+ *   runtime just swaps "per-token softmax aggregation" for "classifier's native top-k API." Same
+ *   downstream contract.
+ */
+/**
+ * Given per-token logits and phrase-grouper spans, produce per-span top-K tag candidates.
+ *
+ * For each span, finds the tokens whose character ranges overlap the span, sums their softmax
+ * probabilities per-tag, normalizes, and emits the top K tags with their aggregated scores.
+ *
+ * BIO prefix stripping: the model emits BIO labels (`B-locality`, `I-locality`, etc.) but the
+ * reconciler works with component tags (`locality`). This function strips the `B-`/`I-` prefix and
+ * merges probabilities: `score(locality) = sum(score(B-locality) + score(I-locality))` across the
+ * span's tokens.
+ *
+ * @param logits Per-token logits from ONNX inference, shape `[seqLen][numLabels]`.
+ * @param pieces Token pieces with character-level offsets (from the tokenizer's `encode`).
+ * @param spans Phrase-grouper span proposals in character offsets.
+ * @param opts Options — `topK` (default 3), `labels` (required — the BIO label vocabulary the model
+ *   emits, e.g. `["O", "B-locality", "I-locality", ...]`).
+ */
+export function aggregateSpanLogits(logits, pieces, spans, opts) {
+    const topK = opts.topK ?? 3;
+    const labels = opts.labels;
+    const candidates = [];
+    for (const span of spans) {
+        // Find tokens overlapping this span (character-level).
+        const overlapping = [];
+        for (let t = 0; t < pieces.length; t++) {
+            const p = pieces[t];
+            if (p.end <= span.start)
+                continue;
+            if (p.start >= span.end)
+                break;
+            overlapping.push(t);
+        }
+        if (overlapping.length === 0)
+            continue;
+        // Aggregate softmax probabilities per component tag (strip BIO prefix).
+        const tagScores = new Map();
+        for (const t of overlapping) {
+            const probs = softmax(logits[t]);
+            for (let l = 0; l < labels.length; l++) {
+                const bioLabel = labels[l];
+                const tag = stripBioPrefix(bioLabel);
+                if (tag === "O")
+                    continue;
+                const prev = tagScores.get(tag) ?? 0;
+                tagScores.set(tag, prev + probs[l]);
+            }
+        }
+        // Normalize by number of overlapping tokens so longer spans don't auto-win.
+        const norm = overlapping.length;
+        const sorted = [...tagScores.entries()]
+            .map(([tag, score]) => ({ tag, score: score / norm }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+        for (const { tag, score } of sorted) {
+            candidates.push({
+                span: { start: span.start, end: span.end },
+                tag: tag,
+                score,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Strip `B-` or `I-` prefix from a BIO label, returning the component tag. `O` returns `"O"`.
+ */
+function stripBioPrefix(label) {
+    if (label === "O")
+        return "O";
+    const dash = label.indexOf("-");
+    if (dash === -1)
+        return label;
+    return label.slice(dash + 1);
+}
+/** Numerically stable softmax over a row of logits. */
+function softmax(row) {
+    let max = row[0];
+    for (let i = 1; i < row.length; i++)
+        if (row[i] > max)
+            max = row[i];
+    const exps = row.map((v) => Math.exp(v - max));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+}
+//# sourceMappingURL=span-logit-aggregation.js.map

package/out/pipeline/span-logit-aggregation.js.map

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

package/out/pipeline/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Types for the runtime pipeline coordinator (`runPipeline`).
+ *
+ *   Generic over its stage implementations — each stage is an injected function or class, defined
+ *   structurally. Keeps `@mailwoman/core` free of dependencies on the concrete neural / normalize /
+ *   query-shape / resolver packages while still composing them at runtime when callers wire them
+ *   up.
+ *
+ *   See `docs/articles/plan/reference/STAGES.md` for the full contract this implements.
+ */
+import type { AddressTree } from "../decoder/types.js";
+import type { ResolveOpts, Resolver } from "../resolver/types.js";
+import type { Section } from "../types/classifier.js";
+export type LocaleTag = string;
+/** Optional user-location signal for Stage 6 resolver scoring. */
+export type UserLocation = {
+    lat: number;
+    lon: number;
+} | {
+    country: string;
+} | {
+    region: string;
+    country: string;
+};
+/** Common opts threaded through every stage. */
+export interface PipelineOpts {
+    locale?: LocaleTag;
+    userLocation?: UserLocation;
+    /** Disable fast-path shortcuts; always run the full pipeline. */
+    forceFullPipeline?: boolean;
+    /**
+     * Enable the joint-reconcile path (Stage 5 beam search over candidates). When set, the pipeline:
+     *
+     * 1. Aggregates per-token logits over phrase-grouper spans (per-span top-K tag candidates).
+     * 2. Feeds candidates into `reconcileSpans` for joint-coherence scoring.
+     * 3. Returns the reconciled tree instead of the argmax tree.
+     *
+     * Requires both a phrase grouper AND a classifier that exposes raw logits (the standard
+     * `NeuralAddressClassifier` does via its `parseWithLogits` method). Falls back to argmax if
+     * either is missing.
+     */
+    forceJointReconcile?: boolean;
+    /** Hard cap on lookups the resolver may issue; passed through. */
+    resolveOpts?: ResolveOpts;
+    signal?: AbortSignal;
+}
+/** Minimal structural shape `NormalizedInput` must satisfy. Compatible with @mailwoman/normalize. */
+export interface NormalizedInputLite {
+    raw: string;
+    normalized: string;
+    appliedLocale?: string;
+}
+/** Minimal structural shape `QueryShape` must satisfy. Compatible with @mailwoman/query-shape. */
+export interface QueryShapeLite {
+    knownFormats: ReadonlyArray<{
+        format: string;
+        span: {
+            start: number;
+            end: number;
+        };
+        confidence: number;
+    }>;
+    segments?: ReadonlyArray<{
+        body: string;
+        index: number;
+    }>;
+    characterClass?: string;
+    totalLength?: number;
+}
+/** Detected (or asserted) locale + alternatives. */
+export interface LocaleHint {
+    locale: LocaleTag;
+    confidence: number;
+    alternatives: ReadonlyArray<{
+        locale: LocaleTag;
+        confidence: number;
+    }>;
+    source: "caller" | "detected" | "ensemble";
+}
+/** Kind classifier output. */
+export type QueryKind = "postcode_only" | "locality_only" | "structured_address" | "intersection" | "po_box" | "landmark" | "vague";
+export interface QueryKindResult {
+    kind: QueryKind;
+    confidence: number;
+    alternatives: ReadonlyArray<{
+        kind: QueryKind;
+        confidence: number;
+    }>;
+}
+/**
+ * Stage 2.7 phrase grouper output. Coarse phrase-shape hypothesis attached to a `Section` (sub-Span
+ * of the tokenized input). The classifier (Stage 3) conditions on these proposals so it can answer
+ * the simpler "what type is this proposed span?" instead of jointly discovering boundaries and
+ * types. The reconciler (Stage 5) consumes them as boundary candidates for joint decoding.
+ *
+ * Taxonomy is purely structural — no place-name knowledge. A `LOCALITY_PHRASE` proposal is "this
+ * looks shaped like a multi-word capitalized phrase that could be a city name" — not "this IS New
+ * York." Typing the span is the classifier's job.
+ *
+ * See `docs/articles/concepts/the-knowledge-ladder.md` § Phrase grouper for the design rationale.
+ */
+export type PhraseKind = "NUMERIC" | "STREET_PHRASE" | "LOCALITY_PHRASE" | "REGION_ABBREVIATION" | "POSTCODE" | "VENUE_PHRASE" | "HYPHENATED_COMPOUND";
+/**
+ * One phrase proposal emitted by Stage 2.7. The contract:
+ *
+ * - `span`: the input slice (sub-Span of the tokenized input) the proposal applies to.
+ * - `kindHypothesis`: structural shape this slice looks like.
+ * - `confidence`: 0..1 score. Used by downstream stages to weight proposals.
+ *
+ * Per "possibilities not constraints", emit a proposal whenever a rule fires — overlapping
+ * proposals over the same tokens are expected (e.g. `Saint Petersburg` may surface as one
+ * `LOCALITY_PHRASE` AND two `LOCALITY_PHRASE`s, with confidence ordering signalling which the
+ * grouper prefers).
+ */
+export interface PhraseProposal {
+    span: Section;
+    kindHypothesis: PhraseKind;
+    confidence: number;
+}
+/**
+ * Stage 2.7 contract. Structural — any of the rule-based grouper (`@mailwoman/phrase-grouper`), a
+ * learned span proposer (future), or a fake for tests satisfies this. Async so the coordinator can
+ * stay uniform even when implementations call into models.
+ */
+export interface PhraseGrouper {
+    group(input: NormalizedInputLite, shape: QueryShapeLite, locale: LocaleHint): Promise<PhraseProposal[]>;
+}
+/**
+ * Stage 3 contract: classifier that turns a text into an `AddressTree`. Structural — any of
+ * `@mailwoman/neural`'s `NeuralAddressClassifier`, a rule-based classifier, or a fake for tests
+ * satisfies this.
+ */
+export interface AddressClassifier {
+    parse(text: string, opts?: {
+        queryShape?: QueryShapeLite;
+    }): Promise<AddressTree>;
+}
+/**
+ * Injectable stage implementations. All optional — when a stage is absent, the coordinator either
+ * skips it (resolver) or substitutes a no-op stub (normalize / queryShape / locale gate / kind
+ * classifier). The classifier is required for the full pipeline path; without it, the coordinator
+ * can only fast-path on QueryShape known-formats.
+ */
+export interface RuntimePipelineStages {
+    normalize?: (raw: string, opts?: {
+        locale?: string;
+    }) => NormalizedInputLite;
+    computeQueryShape?: (input: NormalizedInputLite | string, opts?: {
+        locale?: string;
+    }) => QueryShapeLite;
+    detectLocale?: (input: NormalizedInputLite, shape: QueryShapeLite, opts?: {
+        hint?: LocaleTag;
+    }) => Promise<LocaleHint>;
+    classifyKind?: (input: NormalizedInputLite, shape: QueryShapeLite, locale: LocaleHint) => Promise<QueryKindResult>;
+    /**
+     * Stage 2.7 phrase grouper. Emits coherent input-unit proposals consumed by Stage 3 (as
+     * conditioning) and Stage 5 (as boundary candidates). Hard dep in v0.5.0; pre-v0.5.0 callers run
+     * with no grouper and the result `phraseProposals` field is empty.
+     */
+    groupPhrases?: (input: NormalizedInputLite, shape: QueryShapeLite, locale: LocaleHint) => Promise<PhraseProposal[]>;
+    classifier?: AddressClassifier;
+    resolver?: Resolver;
+}
+export interface PipelineTiming {
+    [stage: string]: number;
+}
+/** Result of one `runPipeline` call. */
+export interface PipelineResult {
+    input: string;
+    normalized: NormalizedInputLite;
+    queryShape: QueryShapeLite;
+    locale: LocaleHint;
+    kind: QueryKindResult;
+    /**
+     * Stage 2.7 phrase proposals when a grouper was wired. Empty array when the coordinator ran with
+     * no grouper (pre-v0.5.0 callers) or when the fast-path skipped Stage 2.7. Stage 3 consumes this
+     * as conditioning; Stage 5 consumes it as boundary candidates.
+     */
+    phraseProposals: PhraseProposal[];
+    tree: AddressTree;
+    timing: PipelineTiming;
+    /** Which path the coordinator took. `"fast-path"` skipped stages 3-5. */
+    path: "fast-path" | "full";
+}
+//# sourceMappingURL=types.d.ts.map