Deterministic parser
Correction (2026-08-02, verified against canonical origin/main): several claims below don't match the real crate. service-extraction's real CLAUDE.md/src/main.rs describe a single-purpose filesystem watcher that ingests JSON email payloads and writes CRM_<worm_id>.json records for service-people only — not a general-purpose "traffic controller" for all platform-boundary payloads. The "Entity Bundle" (payload.txt + binary attachments in a timestamped Unix directory), transaction-ID chain-of-custody, TOML routing config, and the multi-path routing matrix have no match in the real source. Most significantly, the real pipeline explicitly consumes pre-classified edge_entities from WASM AI inference — directly contradicting this article's "no AI inference required for routing" framing. Note this is a different crate from the document-parsing pipeline (PDF/DOCX/XLSX via lopdf/docx-rs/calamine) already confirmed to live here per governance/adr-07-zero-ai-in-ring-1.md's correction — that finding still holds; this is an additional, separate defect in this article's own routing/entity-bundle description. Flagged, not resolved.
Every payload that crosses the platform boundary lands at service-extraction, the Ring 2 traffic controller that strips proprietary formatting (JSON, MIME, Base64), constructs a machine-readable Entity Bundle, and assigns the transaction identifier that follows the bundle through every downstream step. Structured payloads route entirely within Ring 2; unstructured text routes onward to AI inference service for AI-assisted extraction. service-extraction is the canonical successor to the legacy working name service-parser.
Architectural Baseline
Every message that passes through Ring 1 arrives at service-extraction as an unprocessed, vendor-formatted payload. The first Ring 1 service to produce such payloads is typically Email ingest or service-input — reference-archive migration and calibration. The service has one responsibility: transform that payload into a clean, traceable Entity Bundle and route it to the correct downstream service. It assigns a transaction ID to each bundle, providing a chain-of-custody reference that persists through every subsequent processing step.
Ring and Role
service-extraction occupies Ring 2 — Knowledge and Processing in the Three-ring architecture. Ring 2 is multi-tenant (via moduleId namespacing) and deterministic: it processes data without invoking AI inference unless the data shape requires it. When a payload contains unstructured text that cannot be classified by deterministic rules, service-extraction routes that text to Ring 3 (AI inference service) for AI-assisted extraction. Structured and semi-structured payloads route entirely within Ring 2. Entity identifiers produced here are consumed by the Chart of Accounts socket-assignment logic in service-people — the identity ledger service.
Structural Organization of Components
The Entity Bundle
Each payload is isolated into a Unix directory named by its timestamp and routing ID. The bundle is eventually stored as an immutable record in service-fs. The bundle contains:
payload.txt— the core text payload reduced to plain-text frontmatter format. This file is the permanent, human-readable record of the communication.- Binary attachments — PDFs, images, and other attached files stored natively alongside the text payload. Binary decoupling eliminates split-brain metadata tracking between the text record and its attachments.
The Multi-Path Routing Matrix
After constructing the bundle, the service routes it based on the payload's origin tags:
| Route | Destination | Condition |
|---|---|---|
| Immutable ledger | Cold storage via service-fs | Standard assets (most messages) |
| Identity ledger | service-people — the identity ledger service | Sender identity records for CRM downstream ingestion |
| AI synthesis | AI inference service, then purge | Consumable media (newsletters, low-retention items) |
The routing decision is deterministic and tag-driven. No AI inference is required for the routing step itself.
Configuration
| Parameter | Purpose |
|---|---|
| Queue path | Input path for Ring 1 payloads (e.g., assets/tmp-maildir/) |
| Bundle output path | Filesystem location for completed Entity Bundles |
| Routing rules | TOML configuration file mapping origin tags to routing destinations |
| Transaction ID format | Timestamp + routing ID composition format |