The pipeline contract

You don't have to take Mailwoman's pipeline as-is. The runtime coordinator (createRuntimePipeline) accepts each pipeline stage as an injectable function or interface; an integrator can swap any of them for a custom implementation without forking the core.

This article is the practical "how do I plug in" companion to:

The staged pipeline — the narrative for why the stages exist
STAGES.md (reference) — the full per-stage contract with type definitions, error semantics, and edge cases

Read those first if you're new. Use this page when you already know the shape and want to ship a custom stage.

Stage signatures

import type { RuntimePipelineStages } from "@mailwoman/core/pipeline"

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>
	// Coarse country router (#244). Soft prior for the resolver's re-rank, never the classifier;
	// off in the bare core coordinator (byte-stable), wired on by default in the `mailwoman` package.
	placeCountry?: (normalizedText: string) => { country: string | null; confidence: number; posterior?: Record&lt;string, number&gt; }
	groupPhrases?: (input: NormalizedInputLite, shape: QueryShapeLite, locale: LocaleHint) => Promise&lt;PhraseProposal[]&gt;
	classifier?: { parse(text: string, opts?: ClassifierOpts): Promise&lt;AddressTree&gt; }
	fst?: FSTMatcherLike  // FST gazetteer matcher — produces emission biases during classification
	resolver?: { resolveTree(tree: AddressTree, opts?: ResolveOpts): Promise&lt;AddressTree&gt; }
}

Every stage is optional. When you omit one, the coordinator either substitutes a no-op stub (normalize, computeQueryShape, detectLocale, classifyKind) or skips the stage entirely (classifier, placeCountry, resolver).

Decode-time constraint layers (v4.3.0+)

The neural classifier carries two constraint layers configured at construction, not as pipeline stages — they run inside classifier.parse and are part of the SHIP CONFIG contract (the model card's notes name the required settings per release):

Conventions mask (addressSystemConventions: "auto" | SystemCode, v4.3.0+): the model's exported locale head detects the address system; the codex conventions row removes that system's ungrammatical tags from the Viterbi vocabulary and arms the postcode-shape snap repair. Threshold-gated (0.8) — never fires on a guess; undetected systems parse unmasked.
Span bridge (bridgePunctuationGaps: true, REQUIRED from v4.4.0): merges same-tag fragments split at unlabeled intra-token punctuation ("P.O. Box" decoding as P+O+Box) — the corpus label format cannot express punctuation inside spans, so the bridge is decode-side containment. Separator punctuation (commas) never bridges; space-only gaps never bridge.

Running a v4.4.0+ model WITHOUT these settings reproduces measured gate failures (po_box 60.4 vs 89.1 with the bridge; the FR digit-split class without conventions) — they are not optional enhancements for those weights, they are the decode contract.

Replacing a stage

import { createRuntimePipeline } from "mailwoman"

const myLocaleDetector = async (input, shape, opts) => {
	if (opts?.hint) return { locale: opts.hint, confidence: 1.0, alternatives: [], source: "caller" }
	// Your detection logic here — fastText, a CLD, an LLM, whatever.
	const guess = await myModel.classify(input.normalized)
	return { locale: guess.tag, confidence: guess.score, alternatives: [], source: "detected" }
}

const pipeline = createRuntimePipeline({
	detectLocale: myLocaleDetector,
	// Other stages default to the shipped implementations.
})

const result = await pipeline("8 rue Lafayette, Paris")

Same pattern for any stage. The defaults you don't override (e.g. @mailwoman/normalize, @mailwoman/query-shape, @mailwoman/kind-classifier) keep running.

Error semantics

Not every stage failure is treated the same. The coordinator distinguishes graceful stages (failure produces a degraded but valid result) from non-graceful stages (failure surfaces to the caller).

Stage	If it throws
`normalize`	Propagates. Input preprocessing is a contract; a crash is a bug.
`computeQueryShape`	Propagates. Same rationale.
`detectLocale`	Propagates. A locale detector that crashes signals a real fault, not noise.
`classifyKind`	Propagates. Kind classification runs on the QueryShape we just computed — there's nothing external that can poison it.
`classifier.parse`	Swallowed. Returns an empty `AddressTree`; pipeline continues. The classifier runs against external weights / arbitrary user input; defensive.
`resolver.resolveTree`	Swallowed. Returns the classifier's tree unchanged. Backend may be unavailable; we surface what we have rather than fail the whole call.

This asymmetry is intentional. Stages 1, 2, 2.5 are pure functions over the input; if they crash, something is wrong with the request shape and the caller needs to know. Stages 3 and 6 are wrapped because their dependencies (ONNX model, SQLite database, network) are points where production failures legitimately happen and degrading gracefully beats taking the whole query down.

Cancellation

PipelineOpts.signal: AbortSignal is honored between stages, not within them.

const controller = new AbortController()
setTimeout(() => controller.abort(), 100)

try {
	const result = await pipeline("…", { signal: controller.signal })
} catch (err) {
	// err.name === "AbortError" if the coordinator caught the signal between stages.
	// err is whatever you passed to controller.abort(reason) if you supplied a reason.
}

If you abort while a stage is mid-execution, that stage runs to completion before the abort takes effect. The longest cancellation latency is one stage's runtime — typically the neural classifier (~10-70ms p99 for the en-US weights). Fine-grained mid-stage cancellation is a future enhancement that requires plumbing signal into each stage's contract.

Aborting before any stage runs throws immediately. Aborting between stages skips the rest of the pipeline.

Timing budget

PipelineResult.timing records per-stage wall time in milliseconds. The keys present depend on the path the coordinator took:

Key	Always present	Notes
`normalize`	yes
`query-shape`	yes
`locale-gate`	yes
`kind-classifier`	yes
`token-classify`	full path only, when classifier wired	Absent on fast-path; absent when no classifier injected
`resolve`	when resolver wired	Present on both full and fast-path

The path field tells you which branch ran: "full" (stages 3-5 ran) or "fast-path" (kind classifier + QueryShape agreed on a trivial input, stages 3-5 skipped, tree built from QueryShape alone).

Use mailwoman parse --benchmark <N> for percentile breakdowns over many iterations against a real input.

Fast-path criteria

The coordinator short-circuits stages 3-5 when:

forceFullPipeline is not set on PipelineOpts, AND
classifyKind returned confidence ≥ 0.95, AND
The kind matches a known shape signal:
- postcode_only → QueryShape has a postcode knownFormats hit
- locality_only → totalLength ≤ 30 AND characterClass === "alpha"

The fast-path tree is built from QueryShape's format hit alone — useful even without a resolver wired (a consumer who just wants the parsed structure for "10118" shouldn't pay for the classifier).

When to swap a stage

Common reasons:

Custom locale detector — replace detectLocale with a fastText / cld3 / commercial detector when you have a specific traffic profile
In-process resolver — swap resolver for an embedded WOF SQLite or in-memory gazetteer
Different classifier — your own ONNX model, a rule-based classifier, a remote inference endpoint
Test fakes — every stage takes a vi.fn() / sinon stub directly; no special harness needed

You should not swap a stage to bypass it cheaply. If you want the pipeline without locale detection, pass { locale: "en-US" } on every call — the default detectLocale is already a sub-microsecond caller-trust stub. The performance you'd reclaim by swapping is rounding error against the neural classifier's milliseconds.

See it in action

Loading demo embed…

Expand the Classification origin section to see which pipeline stage contributed to each parsed component.

Stage signatures​

Decode-time constraint layers (v4.3.0+)​

Replacing a stage​

Error semantics​

Cancellation​

Timing budget​

Fast-path criteria​

When to swap a stage​

See it in action​

See also​