Skip to content

Requirements 011: Reference Contracts for Bundled Dator and Arca

Based on:

  • doc/project/40-proposals/019-supervised-local-http-json-middleware-executor.md
  • doc/project/40-proposals/020-bundled-python-middleware-modules.md
  • doc/project/50-requirements/requirements-010-middleware-executor.md
  • doc/project/30-stories/story-006-voluntary-swarm-exchange.md
  • doc/project/60-solutions/000-node/000-node.md

Date: 2026-03-30 Status: Draft (hard MVP slice)

Executive Summary

This document freezes the minimum reference contract for the two bundled hard-MVP middleware modules:

  • Orbiplex Dator
  • Orbiplex Arca

It does not create a second middleware protocol. Both modules still consume the host WorkflowEnvelope and emit MiddlewareDecision through the supervised http_local_json runtime. What this document adds is the minimum semantic scope of each module so implementation can proceed without ambiguity.

Module Roles

Orbiplex Dator

Dator is the exchange-facing middleware module for priced service work.

Its hard-MVP role is to help the host with:

  • service publication and service metadata shaping,
  • procurement-facing execution shaping for offered services,
  • Inquirium/model-backed preprocessing or drafting requests routed through the host,
  • response shaping for exchange-visible outputs,
  • queue posture and bounded acceptance posture for service work.

Dator is not the authority for:

  • transport identity,
  • protocol signing,
  • settlement,
  • reputation,
  • participant restrictions.

Those remain host responsibilities.

Orbiplex Arca

Arca is the workflow orchestration middleware module.

Its hard-MVP role is to help the host with:

  • multi-step local and remote workflow orchestration,
  • bounded retries and phase sequencing,
  • host-mediated file or publication preparation,
  • coordination of repeated or scheduled content workflows,
  • preserving workflow-local causality in a way the host can trace.

Arca is not the authority for:

  • signing external contracts,
  • substituting operators silently,
  • bypassing procurement or settlement rules,
  • independently changing provider identity or payment semantics.

Shared Transport and Envelope Contract

Both bundled modules MUST:

  • be launched as supervised Python services through http_local_json,
  • expose loopback HTTP readiness and invocation endpoints,
  • accept host-generated WorkflowEnvelope input,
  • return host-validated MiddlewareDecision output,
  • support host-owned middleware-init and module reporting.

Neither module may require:

  • direct access to host secret material,
  • direct control of network peer sessions,
  • direct invocation of settlement rails,
  • direct bypass of host field-registry or policy checks.

Hard-MVP Dator Contract

At minimum, Dator MUST be able to:

  • shape service-offer publication metadata for exchange-facing work,
  • translate a selected service execution path into host-usable procurement and response workflow intent,
  • request Inquirium/model-backed work through the host rather than vendor APIs directly,
  • surface bounded queue pressure or temporary unavailability as host-visible middleware outcomes,
  • shape final response payloads without becoming the settlement authority.

For hard MVP, Dator SHOULD treat the current executable substrate as canonical:

  • procurement-contract.v1
  • response-envelope.v1
  • procurement-receipt.v1
  • ledger-hold.v1
  • ledger-transfer.v1
  • gateway-receipt.v1

That means Dator MAY present richer exchange semantics, but MUST project them back into the current host procurement and settlement artifacts.

Hard-MVP Arca Contract

At minimum, Arca MUST be able to:

  • orchestrate multi-phase content workflows spanning local and remote execution,
  • preserve explicit phase boundaries and retry posture,
  • request remote paid work through host procurement rather than side channels,
  • stage local output preparation through host-approved mutations,
  • stop and surface failure when a downstream phase cannot proceed under policy.

Arca MUST NOT silently replace one provider with another or alter the economic meaning of a workflow step without an explicit host-approved transition.

Module Report Expectations

Both bundled modules MUST report at least:

  • module name,
  • short description,
  • module version,
  • capability ids,
  • middleware contract version,
  • host API version expectation.

Recommended capability ids:

  • dator/exchange-service-publication
  • dator/service-execution-shaping
  • arca/workflow-orchestration
  • arca/phase-retry-and-publication-shaping

These ids remain descriptive in MVP; they are not yet independent protocol authorities.

Functional Requirements

ID Requirement Type Source Status
FR-001 The hard MVP MUST bundle two reference middleware modules: Orbiplex Dator and Orbiplex Arca. Fact Proposal 020 implemented
FR-002 Both bundled modules MUST be implemented in Python and launched through the supervised http_local_json executor. Fact Proposal 020 + Requirements 010 implemented
FR-003 Dator MUST consume WorkflowEnvelope and emit MiddlewareDecision without introducing a second invocation protocol. Fact Requirements 010 implemented
FR-004 Arca MUST consume WorkflowEnvelope and emit MiddlewareDecision without introducing a second invocation protocol. Fact Requirements 010 implemented
FR-005 Dator MUST shape exchange-facing service work while delegating model invocation, settlement, signing, and restriction enforcement to the host. Fact Story 006 + project values implemented
FR-006 Arca MUST shape workflow orchestration while delegating signing, settlement, and policy authority to the host. Fact Story 006 + project values implemented
FR-007 Dator MUST project its richer service semantics back into the currently executable host substrate based on procurement, response, and settlement artifacts. Fact Story 006 implemented
FR-008 Arca MUST route remote paid steps through host procurement rather than side-channel execution. Fact Story 006 implemented
FR-009 Both bundled modules MUST support middleware-init and return module reports with stable version and capability metadata. Fact Requirements 010 implemented
FR-010 The host MUST remain free to reject or clip module-proposed mutations through field-registry and policy validation. Fact Story 006 + project values implemented

Non-Functional Requirements

ID Requirement Type Source Status
NFR-001 Bundled reference modules SHOULD accelerate hard-MVP delivery without becoming privileged special cases outside the generic middleware host contract. Fact Proposal 020 implemented
NFR-002 The semantic difference between Dator and Arca MUST stay visible in module reports and operator surfaces. Inference Operability implemented
NFR-003 The modules SHOULD remain replaceable by other implementations as long as the host-facing middleware contract is preserved. Fact Proposal 020 implemented

Failure Modes and Mitigations

| Failure Mode | Impact | Mitigation | |---|---|---|---|---| | Dator starts calling model vendors directly | Hidden credentials and trace collapse | Keep model access host-mediated only. | | Arca treats workflow intent as authority to bypass procurement | Hidden economic side channels | Require remote paid work to project into host procurement artifacts. | | Bundled modules become effectively privileged because they ship with Node | Architecture drifts into opaque monolith | Preserve the same WorkflowEnvelope / MiddlewareDecision and supervision boundary as for any external module. | | Module metadata is too weak to diagnose runtime drift | Operators cannot tell which module build is running | Require versioned module reports on middleware-init. |

Next Actions

  1. Add hard-MVP component configs for bundled Dator and Arca.
  2. Define their first capability ids and version strings.
  3. Add integration scenarios covering:
  4. Dator publication and service execution shaping,
  5. Arca multi-phase workflow orchestration,
  6. host rejection of invalid module decisions,
  7. startup and lifecycle supervision for both modules.