Skip to content

alaivOS Business — Capsule Registry

Version: 1.0 · Date: March 2026 · Owner: Citerius Holdings LLC
Audience: All agents, engineers, PM, capsule developers
Status: Canonical — locked taxonomy as of March 2026

This document is the single source of truth for all capsule IDs, specifications, dependencies, and the capsule marketplace model. Every branch manifest and every capsule developer references this document.


§01 — Taxonomy Overview

Seven Tractus capsules were generalized from domain-specific to function-generic IDs in March 2026. This table is the locked canonical reference. All branch manifests and developer program documentation use the Locked ID column.

Deprecated ID Locked Generic ID Shared Function
cargo-audit evidence-audit Field evidence capture, authenticity verification, reference model comparison, confidence-scored decision
kyc-mx entity-verification Legal identity and compliance standing verification of any external party
trust-score entity-reputation Weighted composite behavioral reputation scoring
field-worker-identity identity-lock Biometric identity binding and liveness confirmation at high-stakes action points
backhaul-matcher capacity-matcher Supply-demand matching on idle capacity (two-sided marketplace)
carta-porte regulatory-clearance Mandatory regulatory document submission with circuit breaker
insurance-mx coverage-referral Coverage verification and licensed provider referral
field-worker-safety field-worker-safety Already generic — unchanged
green-badge green-badge Already generic — unchanged

Deprecated alias policy: Aliases are supported in v1.0 branch manifests only. They resolve to the new generic ID at provisioning time. Aliases will NOT be documented in the public capsule marketplace. Engineers must update manifests to new IDs before the developer program opens.


§02 — Full Capsule Index

Capsule ID Type Mode Compat Branches (Day 1) Status
entity-verification Generic B Tractus, Construx Spec complete
identity-lock Generic A, B Tractus, Construx Spec complete
regulatory-clearance Generic B Tractus (Carta Porte MX), Construx (municipal permit MX) Spec complete
evidence-audit Generic B Tractus (cargo seals), Construx (base pipeline) Spec complete
field-worker-safety Generic A, B Tractus, Construx Spec complete
entity-reputation Generic A, B Tractus, Construx Spec complete
capacity-matcher Generic B Tractus (backhaul), Construx (subcontractor placement) Spec complete
coverage-referral Generic A, B Tractus, Construx Spec complete
green-badge Generic A, B Tractus Spec complete
marketplace-discovery Generic B Tractus, Construx Spec complete — see BIZ-MARKETPLACE-DISCOVERY.md
ar-progress-audit Construx-specific B Construx Spec pending — see §06
bim-data-vault Construx-specific B Construx Spec pending — split from bim-blueprint-vault
spatial-comparison-engine Construx-specific B Construx Spec pending — split from bim-blueprint-vault
drone-inspection Construx-specific B Construx Spec pending — see §07

§03 — Generic Capsule Specifications

entity-verification

Shared function: Legal identity and compliance standing verification of any external party before they can participate in platform transactions.

Capsule-owned logic (branch-agnostic): - Aggregator API orchestration (primary + fallback) with async webhook handling - Confidence gating: threshold-based approval/rejection/manual-review routing - Verification record written append-only to Firestore (kyc_verifications/{id}) - Re-verification scheduling on document expiry - Manual review queue for both-API-unavailable fallback (SLA: 24h)

Branch config declares:

{
  "entity_verification": {
    "entity_term": "carrier",         // "carrier" | "subcontractor" | "provider"
    "aggregator_primary": "truora",
    "aggregator_fallback": "metamap",
    "required_documents": ["RFC", "REPUVE", "INE", "insurance", "permit"],
    "confidence_thresholds": { "auto_approve": 92, "human_review": 70, "auto_block": 50 }
  }
}

Dependency: None (installs first)


identity-lock

Shared function: Biometric identity binding and liveness confirmation at high-stakes action points (cargo handoff, phase sign-off, etc.).

Capsule-owned logic: - On-device TFLite face match (primary — privacy-first, no server round-trip for low-risk checks) - AWS Rekognition cloud confirmation (≥ 92.0 threshold for high-stakes events) - LFPDPPP / biometric consent capture and storage - Biometric photo lifecycle: Firebase Storage sub-bucket with 30-day auto-delete - 6-hour offline grace period: last successful biometric allows continued operation - Offline SQLite queue for sync on reconnect

Branch config declares:

{
  "identity_lock": {
    "action_term": "handoff",         // "handoff" | "phase_sign_off" | "delivery"
    "biometric_threshold": 92.0,
    "offline_grace_hours": 6,
    "consent_regulation": "LFPDPPP"  // "LFPDPPP" | "GDPR" | "CCPA"
  }
}

Dependency: entity-verification


regulatory-clearance

Shared function: Mandatory regulatory document generation and submission with PAC/authority circuit breaker, before a field event (shipment departure, phase commencement) is authorized.

Capsule-owned logic: - Regulatory document generation (CFDI XML or equivalent) - PAC/authority API integration: primary + fallback with circuit breaker (3× 5xx in 10min → failover for 60min) - Catalog validation against authority-published codes - Departure/commencement block enforcement: event cannot proceed without confirmed clearance - Append-only Firestore record (regulatory_documents/{id})

Branch config declares:

{
  "regulatory_clearance": {
    "document_type": "carta_porte_cfdi",  // "carta_porte_cfdi" | "municipal_permit" | "customs_manifest"
    "authority_primary": "finkok",
    "authority_fallback": "sw_sapien",
    "catalog_version": "cfdi_4.0_carta_porte_3.0",
    "retention_years": 5
  }
}

Dependency: entity-verification, identity-lock


evidence-audit

Shared function: Field evidence capture pipeline — media ingestion, authenticity verification, spoofing detection, reference model comparison, confidence-scored decision output.

Capsule-owned logic: - Photo/video capture pipeline with CLAHE preprocessing - pHash replay detection (resubmitted media is rejected) - GPS/EXIF multi-layer spoofing detection - Computer vision model invocation (model ID declared by branch) - Seal detection, ANPR, cargo/element count as available from CV model - Confidence score → APPROVED / PENDING_REVIEW / BLOCKED routing - Append-only Firestore record (evidence_records/{id})

Branch config declares:

{
  "evidence_audit": {
    "event_term": "handoff",          // "handoff" | "phase_submission" | "delivery"
    "cv_model_id": "tractus-cargo-v1",
    "confidence_thresholds": { "auto_approve": 92, "human_review": 70, "auto_block": 87 },
    "media_types": ["photo", "video"],
    "max_video_seconds": 30
  }
}

Dependency: identity-lock


field-worker-safety

Shared function: Silent alert, GPS pinging, and escalation protocol for field workers in any branch. Sector vocabulary supplied by branch config.

Capsule-owned logic (four silent activation methods):

Method Trigger Screen Change Enable Condition
Logo long-press 3-second press on branch logo in app header None — app appears identical All branches
Reverse PIN Enter PIN digits in reverse order at any PIN prompt PIN accepted normally Branches with PIN-gated features
Rapid shake Shake device 5× within 2 seconds during photo capture Brief toast — normal appearance Branches with photo capture workflows
Biometric fail + override Biometric fails + manual override code entered Shows as "admin override — approved" Branches with identity-lock

Escalation Ladder: - T+0: field_events document created (append-only). GPS pinging begins (60s interval). Safety Coordinator Persona alerted via high-priority channel. - T+2 min: Coded check-in sent to field worker via separate Twilio number. Neutral phrasing — no mention of safety event. - T+5 min: If no clear signal → notify emergency contact on file. Brief confidential message only. - T+10 min: Human (Safety Ops) — Job/shipment placed on hold. No communication to counterparty. - T+15 min: Human (Safety Ops) — If GPS shows deviation or worker stopped → contact local authorities via pre-configured protocol. - Post-event: Full audit trail exported (GPS log, activation method, escalation timeline, responses). Trust Score / entity record reviewed.

Branch config declares:

{
  "field_worker_safety": {
    "worker_term": "driver",
    "assignment_term": "shipment",
    "activation_methods": ["logo_longpress", "reverse_pin", "rapid_shake", "biometric_override"],
    "gps_ping_interval_seconds": 60,
    "clear_signal_window_minutes": 2,
    "authority_contacts": {
      "MX": { "agency": "SSPC", "protocol": "pre-established-MX-v1" },
      "US": { "agency": "local_911", "protocol": "standard" }
    },
    "checkin_twilio_number_secret": "TWILIO_SAFETY_NUMBER",
    "safety_ops_channel": "SAFETY_OPS_SLACK_CHANNEL"
  }
}

Dependency: identity-lock


entity-reputation

Shared function: Weighted composite behavioral reputation scoring for any platform participant. Produces Trust Score (0–10), Green Badge threshold, and Probation flag.

Capsule-owned logic: - Composite score: dimensions and weights declared by branch config - Green Badge threshold: configurable per branch (default: ≥ 8.5) - Probation flag: automatic if score drops below configurable threshold (default: < 4.0) - Score written nightly to entity_scores/{entityId} and synced to Odoo res.partner.trust_score - Score history retained as append-only subcollection

Branch config declares (longhaul / generic):

{
  "entity_reputation": {
    "entity_term": "carrier",
    "score_dimensions": {
      "incident_rate": 0.40,
      "completion_rate": 0.25,
      "review_rate": 0.20,
      "compliance_standing": 0.15
    },
    "green_badge_threshold": 8.5,
    "probation_threshold": 4.0
  }
}

Branch config declares (delivery_model: "lastmile"):

{
  "entity_reputation": {
    "entity_term": "driver",
    "score_dimensions": {
      "incident_rate": 0.40,
      "completion_rate": 0.25,
      "cod_integrity_rate": 0.20,
      "compliance_standing": 0.15
    },
    "green_badge_threshold": 8.5,
    "probation_threshold": 4.0
  }
}

cod_integrity_rate replaces review_rate for lastmile drivers. COD fraud — drivers collecting and not remitting — is the largest recurring loss vector in last-mile operations. cod_integrity_rate = shifts_with_zero_variance / total_shifts_closed. A driver with consistent clean reconciliation scores 1.0; one with chronic variances trends toward 0. This dimension is computed by the cod-treasury capsule and consumed by entity-reputation. review_rate is not meaningful in a B2B contracted delivery model where recipients don't rate couriers.

Dependency: evidence-audit


capacity-matcher

Shared function: Supply-demand matching on idle capacity — two-sided marketplace connecting available capacity with demand requests.

Capsule-owned logic: - Route graph construction and match scoring algorithm - External supply board integration (Beta: Cargamos, Traycap for logistics; equivalent for other sectors) - Match notification via hr-agent (dispatch/notification persona) - Transitions to platform-native supply as marketplace matures

Branch config declares:

{
  "capacity_matcher": {
    "capacity_term": "backhaul_load",   // "backhaul_load" | "subcontractor_slot" | "appointment_slot"
    "demand_term": "return_route",
    "external_boards": ["cargamos.mx", "traycap.com"],  // branch-specific
    "match_radius_km": 100
  }
}

Dependency: evidence-audit


coverage-referral

Shared function: Coverage validity check at onboarding, licensed provider referral, claim initiation on incident escalation, referral fee processing.

Capsule-owned logic: - Insurance/coverage validity check against provider API at onboarding - White-label referral to licensed provider (branch-configured) - Referral fee event → Finance Agent real-time Odoo sync - Claim initiation trigger when field_events incident reaches threshold

Branch config declares:

{
  "coverage_referral": {
    "coverage_term": "cargo insurance",
    "provider_primary": "genda",
    "provider_fallback": "mutuus",
    "referral_fee_pct": 12,
    "regulatory_framework": "CNSF"    // "CNSF" | "other"
  }
}

Dependency: entity-verification


green-badge

Shared function: Capacity utilization tracking, empty mile/resource reduction metrics, carbon footprint estimate, ESG report generation.

Branch config declares:

{
  "green_badge": {
    "utilization_metric": "backhaul_pct",   // "backhaul_pct" | "subcontractor_utilization"
    "carbon_model": "distance_weight_v1",
    "esg_report_enabled": true
  }
}

Dependency: capacity-matcher


§04 — Construx-Specific Capsule Stubs

These capsules are Construx-only. Full specs are pending (see §06–§07) but their IDs, roles, and dependency positions are locked.

ar-progress-audit

Role: Extends evidence-audit for spatial construction inspection. Spatial CAD overlay engine, BIM model retrieval from bim-data-vault, point-cloud comparison, volume/placement variance scoring. CV model: construx-spatial-v1.

What it is NOT: A standalone inspection app. It is a downstream consumer of bim-data-vault and spatial-comparison-engine, and an upstream feed to risk-agent.

Dependency: evidence-audit, bim-data-vault, spatial-comparison-engine

Spec status: Pending — write before Construx build sprint.


bim-data-vault

Role: BIM/DWG file storage, version control, parsing, and geometry export API. Serves geometry to spatial-comparison-engine and waypoint files to drone-inspection.

Split rationale (locked): The storage/indexing concern and the AR engine feed concern are computationally and functionally distinct. A single bim-blueprint-vault monolith would force both to be replaced when either evolves. Split confirmed before spec work begins.

Dependency: entity-verification

Spec status: Pending — write before Construx build sprint.


spatial-comparison-engine

Role: Point cloud ingestion, BIM mesh reference loading from bim-data-vault, deviation scoring, drone video feed integration. Runs Structure from Motion (SfM) on drone footage (via third-party photogrammetry API v1.0: Pix4D / OpenDroneMap cloud). Produces structured deviation report consumed by risk-agent.

Photogrammetry v1.0 approach: External API (Pix4D / OpenDroneMap / RealityCapture) as a circuit-breaker-backed external service. Same pattern as PAC for Carta Porte. GEX44 node for self-hosted SfM deferred to v1.1.

Dependency: bim-data-vault, evidence-audit

Spec status: Pending — write before Construx build sprint.


drone-inspection

Role: End-to-end drone mission management and video ingestion pipeline. Sits between bim-data-vault and ar-progress-audit in the dependency chain.

Key responsibilities: - BIM → DJI waypoint mission file generation (.kmz / DJI JSON) from active phase geometry - Mission authorization event (identity-lock trigger — who authorized the flight) - DJI flight telemetry log ingestion (GPS track, altitude, heading, timestamps) — stored append-only as tamper-evidence alongside video - Video upload handler (Wi-Fi on site or offline queue + deferred upload) - Keyframe extraction (every 0.5s = ~60 frames per 30s flight) - Equirectangular → cube face projection for CV processing - Queue submission to spatial-comparison-engine - Multi-flight comparison: current flight vs. previous inspection vs. BIM reference - Structured deviation report output to risk-agent

Offline queue: Same HMAC-SHA256 hardware-signed SQLite pattern as identity-lock. Sites with poor connectivity upload on Wi-Fi reconnect.

Regulatory: Drone operations registered in regulatory-clearance — MX drone operations sub-schema (AFAC) alongside Carta Porte schema. Not a new capsule.

Ownership model (locked): Client-owned drone. Citerius platform provides mission software and ingestion pipeline only.

Dependency: bim-data-vault, identity-lock

Spec status: Pending — write before Construx build sprint.


§05 — marketplace-discovery Capsule

This capsule is fully specified in BIZ-MARKETPLACE-DISCOVERY.md. Summary:

  • Demand-side auction: Blind hybrid auction — providers bid independently, see pseudonymous aggregate stats after submitting own bid. Client sees all bids pseudonymously, selects provider.
  • Ranking algorithm: FinalScore = (ReputationScore × W_rep) + (ContextualFitScore × W_fit) + (BidCompetitivenessScore × W_bid)
  • Blockchain anchoring: Every material event anchored to Polygon. Async — operational flow never waits.
  • Dependency: entity-reputation, entity-verification, identity-lock, coverage-referral

Branch config block (required in both TRX and CNX manifests — currently pending):

{
  "marketplace_discovery": {
    "request_term": "shipment",
    "provider_term": "carrier",
    "client_term": "shipper",
    "currency_primary": "MXN",
    "currency_secondary": "USD",
    "bid_window_hours": 24,
    "client_selection_window_hours": 24,
    "min_bids_before_stats_visible": 3,
    "ranking_weights": { "W_rep": 0.40, "W_fit": 0.35, "W_bid": 0.25 },
    "blockchain": {
      "chain": "polygon",
      "network": "mumbai",
      "contract": "CiteriumMarketplace.sol",
      "anchor_async": true
    }
  }
}


§06 — Capsule Installation Order by Branch

Tractus (Logistics)

Step 1: entity-verification        (no dependencies)
Step 2: identity-lock              (requires: entity-verification)
Step 3: regulatory-clearance       (requires: entity-verification, identity-lock)
Step 4: evidence-audit             (requires: identity-lock)
Step 5: field-worker-safety        (requires: identity-lock)
Step 6: entity-reputation          (requires: evidence-audit)
Step 7: capacity-matcher           (requires: evidence-audit)
Step 8: coverage-referral          (requires: entity-verification)
Step 9: green-badge                (requires: capacity-matcher)
Step 10: marketplace-discovery     (requires: entity-reputation, entity-verification, identity-lock, coverage-referral)

Construx (Construction)

Step 1: entity-verification        (no dependencies)
Step 2: identity-lock              (requires: entity-verification)
Step 3: regulatory-clearance       (requires: entity-verification, identity-lock)
Step 4: evidence-audit             (requires: identity-lock)
Step 5: field-worker-safety        (requires: identity-lock)
Step 6: bim-data-vault             (requires: entity-verification)
Step 7: spatial-comparison-engine  (requires: bim-data-vault, evidence-audit)
Step 8: drone-inspection           (requires: bim-data-vault, identity-lock)
Step 9: ar-progress-audit          (requires: evidence-audit, bim-data-vault, spatial-comparison-engine)
Step 10: entity-reputation         (requires: evidence-audit, ar-progress-audit)
Step 11: capacity-matcher          (requires: evidence-audit)
Step 12: coverage-referral         (requires: entity-verification)
Step 13: marketplace-discovery     (requires: entity-reputation, entity-verification, identity-lock, coverage-referral)

§07 — Lastmile-Specific Capsules

These capsules are logistics.lastmile only. They are not applicable to longhaul or other branches.

cod-treasury

Role: COD collection recording at ePOD, driver-level shift reconciliation, SPEI/CoDi automatic matching, float reporting, overnight investment trigger.

The scale problem this solves: At 217K deliveries/day × MXN 200 average COD = MXN 43M+ daily float. Without automated reconciliation, cash leakage at the driver level is undetectable and the float is invisible to finance.

Capsule-owned logic: - Per-delivery COD capture (amount + payment method: cash/CoDi/SPEI) written append-only at ePOD moment - Shift reconciliation: expected vs. collected vs. remitted per driver - SPEI/CoDi deposit auto-matching by transaction reference to shipment IDs - Cash remittance confirmation at hub (scan-in event) - Variance exception queue (threshold declared by branch config) - Nightly float aggregation by hub → Finance Agent → Odoo - Investment recommendation trigger (CFO/Treasurer WhatsApp alert with projected overnight float)

Branch config declares:

{
  "cod_treasury": {
    "enabled": true,
    "payment_methods": ["cash", "codi", "spei"],
    "shift_reconciliation": true,
    "float_reporting_enabled": true,
    "variance_alert_threshold_mxn": 200,
    "spei_matching_enabled": true,
    "investment_alert_channel": "WHATSAPP_CFO_NUMBER"
  }
}

Firestore collections (append-only): - cod_collections/{driverId}/shifts/{shiftId}/deliveries/{deliveryId} - cod_settlement_events/{id} - cod_exceptions/{id}

Dependency: evidence-audit, identity-lock

Compatibility: delivery_model: "lastmile" only


carrier-integration

Role: Inbound order ingestion from contracted shipper platforms (MELI, Amazon Seller Services, future: Temu, Shein) via webhook. Normalizes platform-specific payloads into the internal shipments schema and triggers dispatch pipeline.

The problem this solves: lastmile operators with contracted clients do not receive orders through a marketplace — platforms push orders via webhook. Without this capsule, order ingestion is manual or requires custom per-client integration for each operator.

Capsule-owned logic: - Per-platform webhook authentication (HMAC for MELI; AWS SigV4 for Amazon) - Platform-specific payload → internal shipments/{id} schema normalization - Acknowledgment within platform SLA window (MELI: < 2s) - Retry queue with exponential backoff → dead-letter → ops alert on persistent failure - capacity-matcher trigger on successful ingestion (zone assignment + driver dispatch) - Platform status callback on delivery confirmation (closes the loop with MELI/Amazon)

Platform adapters (v1.0): - meli — HMAC auth, MercadoLibre Flex shipment schema - amazon_seller_services — SigV4 auth, Amazon delivery partner schema

Adding a new platform: Implement a new auth handler + payload normalizer. The normalization pipeline and dispatch trigger are shared and reused.

Branch config declares:

{
  "carrier_integration": {
    "enabled": true,
    "platforms": ["meli", "amazon_seller_services"],
    "ingestion_model": "webhook_inbound",
    "meli_webhook_secret": "MELI_WEBHOOK_HMAC_SECRET",
    "amazon_role_arn": "AMAZON_DELIVERY_PARTNER_ROLE_ARN",
    "acknowledgment_sla_ms": 1800
  }
}

Dependency: entity-verification, capacity-matcher

Compatibility: delivery_model: "lastmile" only. Min 1 Cloud Function instance required (webhook acknowledgment SLA).


§08 — Updated Capsule Index

Capsule ID Type Mode Sub-branch Status
entity-verification Generic B Both Spec complete
identity-lock Generic A, B Both Spec complete
regulatory-clearance Generic B Both Spec complete
evidence-audit Generic B Both Spec complete
field-worker-safety Generic A, B Both Spec complete
entity-reputation Generic A, B Both Spec complete
capacity-matcher Generic B Both Spec complete
coverage-referral Generic A, B Longhaul Spec complete
green-badge Generic A, B Longhaul Spec complete
marketplace-discovery Generic B Longhaul (lastmile Phase 2) Spec complete — BIZ-MARKETPLACE-DISCOVERY.md
cod-treasury Lastmile-specific B Lastmile only Spec complete — §07 above
carrier-integration Lastmile-specific B Lastmile only Spec complete — §07 above
ar-progress-audit Construx-specific B Construx Spec pending
bim-data-vault Construx-specific B Construx Spec pending
spatial-comparison-engine Construx-specific B Construx Spec pending
drone-inspection Construx-specific B Construx Spec pending

§09 — Capsule Installation Order (Lastmile)

Step 1: entity-verification        (no dependencies)
Step 2: identity-lock              (requires: entity-verification)
Step 3: regulatory-clearance       (requires: entity-verification, identity-lock)
Step 4: evidence-audit             (requires: identity-lock)
Step 5: field-worker-safety        (requires: identity-lock)
Step 6: entity-reputation          (requires: evidence-audit)
Step 7: capacity-matcher           (requires: evidence-audit)
Step 8: cod-treasury               (requires: evidence-audit, identity-lock)
Step 9: carrier-integration        (requires: entity-verification, capacity-matcher)
Step 10: marketplace-discovery     (Phase 2 — requires: entity-reputation, entity-verification, identity-lock, coverage-referral)

§10 — Phase 2 Capsule Stubs

pudo-network

Role: PUDO (Pick-Up/Drop-Off) point recruitment, scoring, and routing. Reduces failed first-attempt delivery rate in urban MX by routing failed deliveries to nearby verified PUDO points with WhatsApp recipient notification.

The problem: Urban MX first-attempt failure rate is 18–25% without a PUDO alternative. Each failed attempt costs the operator the delivery fee (no revenue recognized) plus re-attempt cost.

Capsule-owned logic: - PUDO point entity type added to entity-verification scope (RFC verification, premises photo, capacity declaration) - PUDO scores via entity-reputation (new entity type: pudo_point) — capacity, reliability, zone coverage, rejection rate - On HANDOFF_BLOCKED (failed delivery): PUDO matcher identifies nearest available PUDO with capacity - hr-agent sends WhatsApp to recipient: "Tu paquete está disponible en [PUDO name + address]. Puedes recogerlo hasta [date]." - PUDO confirmation ePOD (pudo_agent confirms recipient pickup) - Revenue recognition on PUDO pickup, not failed first attempt

Dependency: entity-reputation, carrier-integration, evidence-audit Compatibility: delivery_model: "lastmile" only Status: Phase 2 — spec pending