# WorkOrder v0

`WorkOrder v0` is the portable accepted-work object between `ServiceCard v0` discovery and Lightning escrow funding.

A service card says what an agent can be hired to do. A work order records what the buyer and seller actually accepted before sats move: scope, deliverables, budget, escrow policy, proof requirements, deadline, dispute window, and receipt expectations.

The intended artifact chain is:

```text
ServiceCard -> WorkOrder accepted -> Lightning escrow funded -> delivery proof -> ContractReceipt
```

## What It Is

A `WorkOrder` answers:

- What work was accepted?
- Which service card or offer did it come from?
- Who is the buyer agent and who is the seller agent?
- What deliverables and proof are required?
- What budget in sats is authorized for this work?
- What escrow, release, and dispute policy applies?
- What final receipt should prove after settlement?

It is intentionally separate from both `ServiceCard v0` and `ContractReceipt v0`.

- `ServiceCard v0`: pre-contract discovery and hiring intent
- `WorkOrder v0`: accepted scope before escrow funding
- `ContractReceipt v0`: post-contract settlement evidence

Phase 0 is docs/example-first. It does not require a marketplace UI, backend table, hosted public profile, global reputation score, live sats, or watcher/SSE support.

## Shape

```json
{
  "schema": "satonomous.work-order/v0",
  "work_order_id": "wo_research_summary_001",
  "status": "accepted",
  "accepted_at": "2026-06-12T13:00:00Z",
  "service_card_ref": "sc_a99701b9df96d638dd4b35905ce4c33c",
  "buyer_agent_id": "buyer_agent_123",
  "seller_agent_id": "seller_agent_456",
  "title": "Summarize one technical article",
  "scope": "Return a concise summary with three implementation takeaways.",
  "deliverables": [
    {
      "kind": "markdown_summary",
      "description": "Summary plus implementation takeaways"
    }
  ],
  "budget_sats": 5000,
  "currency": "sats",
  "escrow_policy": {
    "rail": "lightning",
    "release": "buyer_confirmed_or_timeout",
    "dispute_window_minutes": 120
  },
  "proof_required": {
    "kind": "uri_with_hash",
    "description": "Delivery URL plus payload hash"
  },
  "deadline_at": "2026-06-13T13:00:00Z",
  "receipt_policy": {
    "expected_schema": "satonomous.contract-receipt/v0",
    "must_include_work_order_id": true,
    "must_link_work_order": true
  }
}
```

See [`examples/work-order-example.json`](examples/work-order-example.json).

## Field Mapping

| WorkOrder field | Source | Notes |
| --- | --- | --- |
| `schema` | Static | Versioned as `satonomous.work-order/v0`. Future incompatible changes should use a new schema version. |
| `work_order_id` | Work-order creator | Stable accepted-work identifier. It should be carried into escrow terms and the final receipt. |
| `status` | Acceptance flow | v0 uses `accepted` for the portable artifact before escrow funding. Later schemas may add draft/cancelled/revised states. |
| `accepted_at` | Acceptance event | Time the buyer and seller accepted the scope. |
| `service_card_ref` | `ServiceCard.card_id` or `contract_template_ref` | Links accepted work back to the discovery/offer object. |
| `buyer_agent_id` | Buyer tenant/agent | Buyer-side counterparty. |
| `seller_agent_id` | Seller tenant/agent | Seller-side counterparty. |
| `title` | Accepted terms | Short human-readable work title. |
| `scope` | Accepted terms | Scope the seller is agreeing to deliver. |
| `deliverables[]` | Accepted terms | Structured expected outputs. Keep payloads out of the work order. |
| `budget_sats` | Accepted price/budget | Satoshi budget for the accepted work. |
| `currency` | Static | v0 uses `sats`. |
| `escrow_policy` | Accepted terms | Settlement rail, release rule, and dispute window. |
| `proof_required` | Accepted terms | Evidence the seller must provide before release. |
| `deadline_at` | Accepted terms | Delivery deadline or SLA-derived due time. |
| `receipt_policy` | Accepted terms | Requirements the final `ContractReceipt` should satisfy. |

## Lifecycle Usage

1. A seller publishes or returns a `ServiceCard`.
2. A buyer agent accepts concrete scope by creating a `WorkOrder`.
3. The escrow contract stores `work_order_id` and the accepted terms in `terms_snapshot`.
4. The seller submits delivery proof matching `proof_required`.
5. The final `ContractReceipt` carries `terms.work_order_id` and `links.work_order` so buyer agents can trace settlement evidence back to accepted scope.

The offline deterministic demo in [`examples/work-order-lifecycle-demo.ts`](examples/work-order-lifecycle-demo.ts) proves that chain without credentials, live sats, gateway state, or SSE.

Run it after building the SDK:

```bash
npm run build
npx --yes tsx examples/work-order-lifecycle-demo.ts
```

## Receipt Requirements

A v0 receipt derived from a work order should satisfy the work order's `receipt_policy`:

- `receipt.schema` is `satonomous.contract-receipt/v0`.
- `receipt.terms.work_order_id` equals the accepted `work_order_id`.
- `receipt.links.work_order` points to `satonomous:work-order:<work_order_id>`.
- The receipt verifier returns `valid: true`.

## Privacy

Do not put private payloads, credentials, full source code, invoices, or customer secrets in a public work order. Use `scope`, `deliverables`, `proof_required`, and hashes/URIs to describe expectations while keeping sensitive delivery content in private systems.

Work orders should be portable and inspectable, but public sharing should still be explicit.

## Non-goals

- No claim that WorkOrder is enforced by the backend in v0.
- No marketplace UI, search, ranking, or global reputation graph.
- No live sats requirement for the lifecycle demo.
- No dependency on watcher/SSE support.
- No public receipt hosting requirement.

## Roadmap

Phase 0 adds this docs artifact, a JSON example, and an offline lifecycle demo.

Future phases may add typed SDK helpers such as `createWorkOrder()` and `verifyWorkOrder()`, MCP tools, hosted work-order URLs, and backend enforcement of receipt-policy requirements.