# DSRC mock API server

The V10 studio adds an HTTP walkthrough to the existing browser simulation. A Cloudflare Worker serves JSON APIs; each demonstration has an isolated Durable Object holding its quotes, orders, evidence and settlement records. The network allocation and purchasing experiments continue to compute in the browser. Their economic totals are not combined with this walkthrough's transfer payments.

## Run locally

```sh
npm ci
npm run dev
```

Open `http://127.0.0.1:8879/simulation-lab/#api-demo`. Choose a scenario, start a session, then step through the calls or play the walkthrough. Expand the request log to inspect the actual HTTP request and response bodies. No account credentials, operator systems or payment providers are contacted.

The UI uses ordinary same-origin `fetch`, not the browser simulation's internal worker RPC. The `X-Demo-Session` header identifies a private mock session; mutation requests carry an `Idempotency-Key`. The browser can replay a request with the same key to demonstrate that it does not duplicate the transaction. Session identifiers are capabilities for this synthetic demo, not production operator authentication.

## Responsibilities

| Part | API family | What the mock demonstrates |
|---|---|---|
| Offer catalogue and standing agreement | TMF620 and TMF651 | What can be purchased and under which framework |
| Quote | TMF648 | Service quantity, price, expiry and buyer assent |
| Commercial order | TMF622 | Binding the purchase to its quote; checking budget, seller exposure and available capacity |
| Fulfilment | TMF641 | Creating the service order separately from settlement |
| Service inventory | TMF638 | Recording the simulated service instances and their resulting states |
| Settlement | Proposed IODSP v0.3 | Accepted terms, evidence-linked commitments, charges, statements and net position |
| External events | Explicit `/mock-api/control` endpoints | Simulated fulfilment, failure, time advance and payment confirmation |

Mock controls are not TM Forum standards. The server does not expose a fake IODSP provisioning operation. Fulfilment emits evidence; IODSP references that evidence and derives charges. Creating a statement does not confirm payment.

The quote and catalogue profiles draw on the fullCIRCLE repository. Exact versions, public source links and local implementation differences are documented in [the standards profile](MOCK_API_STANDARDS.md). This is a supported subset with explicit DSRC extensions, not a complete or certified TM Forum implementation. The executable request/response contract is in [CONTRACT.md](../../cloudflare/mock/CONTRACT.md).

## Scenarios and accounts

The first walkthrough uses one buyer, one seller, a RAN-plus-backhaul purchase, synthetic USD prices and bounded quantity/duration. Location is context from the studio; selecting a real place does not make the inventory or tariff real. Imported network evidence is not silently converted into a commercial offer.

- Successful fulfilment produces usable-service evidence and the corresponding charges.
- Seller backhaul failure before verification earns no service or cancellation charge under the pilot terms.
- Buyer cancellation after reservation earns the agreed cancellation fees.
- Unknown activation retains the unresolved reservations and permits a later explicit resolution; it is not automatically billed as success.
- Expired quotes reject new acceptance. Replaying a previously committed request returns its recorded outcome.

The ledger separates buyer budget reserved, buyer spend incurred, seller credit reserved, unpaid receivable and confirmed payment. Capturing a charge transfers a hold into an incurred amount rather than counting both. Payment clears receivables without restoring the buyer's spending budget. Resource release depends on external evidence, not a billing status.

The walkthrough clock advances through explicit controls and simulated fulfilment, so a pause to explain the demo does not consume an offer. The 24-hour session lifetime uses real time. A statement for zero closes without a payment.

## Storage and implementation limits

The Worker uses a Durable Object per session to persist and serialize session operations. Local Wrangler state survives reloads; sessions expire after 24 hours. Independent sessions cannot read one another's records through their own session identifier. Demo inputs and histories are bounded. No shared global array is used as the persistence layer.

The mock supplies synthetic authority and fulfilment evidence. It does not implement the signed delegation assertions, real countersigned commercial agreements, independent physical meters, external bank confirmation, multi-operator distributed transactions, or all proposed v0.3 correction and dispute workflows. Passing tests establishes mock behavior only. The first purpose is to test the interface boundary and make the commercial record understandable.

## Verification and packaging

```sh
npm run test:mock
# In another terminal, with npm run dev already running:
MOCK_API_TEST_ORIGIN=http://127.0.0.1:8879 npm run test:mock
npm test
npm run build
npm run package
```

V9 remains immutable in `releases/cloudflare/v9/`. V10 packaging includes static assets, the routing Worker, mock modules, Durable Object binding/migration configuration and a hash manifest. Packaging refuses to overwrite an existing release. Local testing uses Wrangler; deployment has not been requested or performed.

## Review and checks

The [review decisions](MOCK_API_REVIEW_DISPOSITIONS.md) record two Fable reviews and the repairs. Final handler coverage includes 27 tests; a separate live HTTP test exercises actual workerd storage, all four server outcomes and concurrent retries. Five browser scenarios also cover quote expiry, lost-response recovery, same-key replay, navigation pause and a 390px phone layout. Full process restart was checked against persistent local storage.

The broader IODSP design-example tests include rounding and correction concepts that are not implemented in this bounded server. They must not be read as server feature coverage.