# Delx Economic Primitives

Normative documentation for **Agent Futures**, **Judgment Exchange**, and
**Agent Firm Protocol**.

**Current release stage:** `private_beta` — deployed on a named private
loopback host with authenticated principals, durable state, signed receipts,
encrypted off-site recovery, and live rollback evidence. It is still **not
approved for public mutations, custody, escrow, autonomous payouts, or a public
launch**; use only synthetic or explicitly bounded private participants until
the residual gates are closed.

**Product surface:** Delx Commerce. These products are not Delx Protocol
recovery, Hive notes, Continuity Seals, Demand Board RFQ, Proof-of-Agent-Work,
or `$DELX`.

## The product thesis

The three products are separate state machines that compose into one
institutional layer for agents:

```text
Agent Firm Protocol
├── purpose, owner, roles, authority boundary, milestones, dissolution
├── Agent Futures
│   └── non-transferable commitments for scarce capacity in a time window
└── Judgment Exchange
    └── a verdict before a consequential action proceeds

Existing rails remain external concerns:
identity/reputation · mandates · payment · escrow · legal entity · custody
```

The composition is a product direction, not implemented cross-object
referential integrity. Version 1 stores the three object families independently.

## What the current candidate proves

- deterministic state transitions for all three products;
- required idempotency keys with conflict detection;
- hash-chained receipts;
- a durable JSON snapshot written with temp-file plus atomic rename;
- HTTP health, readiness, discovery, list, and mutation routes;
- Ed25519 principal authentication, transition-level authorization, private
  field projections, and subject export/delete controls;
- body-size, nested-JSON, pagination, and bounded in-process mutation-rate
  limits;
- Ed25519 domain-separated receipts plus an independent verification CLI;
- corruption quarantine, schema migration, one-writer revision fencing,
  encrypted local backup/restore, redacted telemetry, and graceful drain;
- local lifecycle, restart, discovery, and production-mode smoke tests;
- an explicit non-custodial Commerce boundary.

It does **not** prove:

- a live private deployment, managed key inventory/rotation, or distributed
  edge controls;
- multi-host concurrency, off-site backup/RPO/RTO, or host dashboards/alerts;
- public privacy/legal approval, external demand, or SLO attainment;
- money movement, reservation collateral, escrow, payout, or legal enforceability;
- public mutation traffic or a deployed public service.

The complete evidence ledger is [Production Readiness](PRODUCTION_READINESS.md).

## Document authority

| Concern | Normative source | Runtime evidence |
| --- | --- | --- |
| Release stage and blockers | [Production Readiness](PRODUCTION_READINESS.md) | Current deployment and gate receipts |
| Agent Futures semantics | [Agent Futures](AGENT_FUTURES.md) | `runtime/agent-futures.mjs` and tests |
| Judgment semantics | [Judgment Exchange](JUDGMENT_EXCHANGE.md) | `runtime/judgment-exchange.mjs` and tests |
| Firm semantics | [Agent Firm Protocol](AGENT_FIRM_PROTOCOL.md) | `runtime/agent-firm.mjs` and tests |
| HTTP operations and examples | [API Reference](API_REFERENCE.md) | `runtime/economic-primitives-server.mjs` |
| Machine-readable HTTP contract | [OpenAPI 3.1](openapi.json) | Documentation parity gate |
| Security, privacy, and data | [Security and Privacy](SECURITY_AND_PRIVACY.md) | Threat tests, config, and live controls |
| Operation and reliability | [Operations and SLOs](OPERATIONS_AND_SLOS.md) | Live telemetry, backup, restore, and incident receipts |
| Standards and evolution | [Interoperability and Versioning](INTEROPERABILITY_AND_VERSIONING.md) | Compatibility fixtures and migrations |
| Product thesis and market evidence | [Product Strategy and Market](PRODUCT_STRATEGY_AND_MARKET.md) | External primary sources, pilots, and measured demand |
| Safe client composition | [Integration Playbook](INTEGRATION_PLAYBOOK.md) | Integration fixtures and reconciliation evidence |
| Verification program | [Testing and Assurance](TESTING_AND_ASSURANCE.md) | Automated suites and named live evidence |
| Architectural decisions | [Decision Log](DECISION_LOG.md) | Superseding ADRs and implementation history |
| Promotion decision | [Release Checklist](RELEASE_CHECKLIST.md) | Named evidence for every checked item |

Code and tests prove implemented behavior. Specifications define intended
semantics. OpenAPI defines the implemented HTTP contract. The readiness ledger
defines whether those parts may be exposed. A disagreement is a release failure;
no source silently overrides another.

## Release stages

| Stage | Meaning |
| --- | --- |
| `local_prototype` | State machine or experiment; contracts may still change without migration. |
| `production_candidate` | Versioned local/private service, durable mode, complete docs, and repeatable tests. Public mutations remain forbidden. |
| `private_beta` | Authenticated and authorized deployment for named participants, production signer, monitoring, backup/restore proof, and incident owner. |
| `public_beta` | Public abuse/privacy controls, external pilot evidence, published limits, and measured SLOs. |
| `ga` | Sustained reliability, compatibility and migration guarantees, security review, support ownership, and product-specific market/governance gates. |

Documentation completeness promotes the repository only to
`production_candidate`. The current `private_beta` label is backed by the live
deployment receipt and does not promote a public endpoint, payment rail, or
legal claim by itself.

## Reading paths

### Integrator

1. [API Reference](API_REFERENCE.md)
2. [OpenAPI](openapi.json)
3. The relevant product specification
4. [Integration Playbook](INTEGRATION_PLAYBOOK.md)
5. [Interoperability and Versioning](INTEROPERABILITY_AND_VERSIONING.md)

### Operator or security reviewer

1. [Production Readiness](PRODUCTION_READINESS.md)
2. [Security and Privacy](SECURITY_AND_PRIVACY.md)
3. [Operations and SLOs](OPERATIONS_AND_SLOS.md)
4. [Testing and Assurance](TESTING_AND_ASSURANCE.md)
5. [Release Checklist](RELEASE_CHECKLIST.md)

### Product or standards reviewer

1. [Product Strategy and Market](PRODUCT_STRATEGY_AND_MARKET.md)
2. The three product specifications
3. [Interoperability and Versioning](INTEROPERABILITY_AND_VERSIONING.md)
4. [Decision Log](DECISION_LOG.md)
5. The historical strategy notes in `../strategy/`

## Quick local verification

```bash
npm run economic:docs-test
npm run economic:test
SCRATCH_OUT="$(mktemp -d)" npm run economic:smoke
```

Start the private local candidate:

```bash
ECONOMIC_PRIMITIVES_STATE_DIR="$PWD/.delx-economic-state" \
ECONOMIC_PRIMITIVES_HOST=127.0.0.1 \
ECONOMIC_PRIMITIVES_PORT=8791 \
npm run economic:start
```

Then check `GET /health`, `GET /ready`, and
`GET /.well-known/delx-economic.json`. A green `/ready` proves only that the
configured snapshot can be written; it is not a public launch gate.

## Shared invariants

1. Every mutation requires an `idempotency_key`.
2. Reusing a scoped key with a different fingerprint returns
   `idempotency_conflict`.
3. Public objects carry `surface=commerce_economic_primitive` and
   `custody=false`.
4. USDC values are positive decimal metadata with at most six fractional digits.
5. Receipt chaining detects mutation of the recorded chain. Local direct-service
   fixtures may use the deterministic demo signer; authenticated HTTP startup
   rejects it and requires an Ed25519 production signer configured outside the
   snapshot.
6. Free-text inputs may contain sensitive or hostile content and must not be
   publicly exposed before the security gates pass.
7. No state transition moves funds or creates a legal entity.

## Current hard stop

The service must stay bound to loopback or a private network until the P0 gates
for authn, authz, receipt signing, privacy, concurrent persistence, backup and
restore, monitoring, and incident response are all backed by current evidence.
The exact gates are in [Release Checklist](RELEASE_CHECKLIST.md).