@allorc/a423-sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0
+
+- Add opt-in `@allorc/a423-sdk/workflow` exports: workflow engine, Next.js-compatible handler, typed HTTP client and canonical agreement hashing.
+- Add versioned quotes, bilateral acceptance, role checks, application policies and configurable transitions.
+- Cover funding, execution gate, submission, verification, release, refund, cancellation, expiry, disputes and resolution through explicit adapters.
+- Persist pending operations before effects, stable provider idempotency keys, reconciliation observations and structured evidence.
+- Preserve the 0.1 root API unchanged. Its approval/settlement behaviour is distinct from the new workflow.
+- Add migration instructions and lifecycle/recovery/HTTP tests. No chain adapter, database driver, signer, queue or PDF renderer is bundled.

package/INTEGRATION.md

@@ -0,0 +1,63 @@
+# Integration instructions for the MVP coding agent
+
+Install after the maintainer publishes:
+
+```sh
+npm install @allorc/a423-sdk@0.2.0
+```
+
+For testing before publication, install the maintainer's `npm pack` tarball instead. Do not silently install 0.1 and assume the workflow entry point exists.
+
+## Task
+
+Integrate the opt-in `@allorc/a423-sdk/workflow` API into the existing MVP. Inspect the installed README, declarations and exports first. Preserve the existing app until a complete equivalent journey passes. Do not introduce demo keys, positional signer lookup, unknown-agent fallback, or authentication based only on x-agent-id. Do not deploy or move real funds as part of integration tests.
+
+1. Implement a durable `WorkflowStore` in the app's database using atomic create and version-checked replacement. Store the whole workflow record together. Keep legacy data separate; explicitly migrate records only after reviewing the mapping. Use stable application-assigned job IDs; recover duplicate creates by loading and comparing the record.
+2. Implement authentication and bind authenticated agent IDs to the application's wallet/signer registry. Keep `@allorc/identity` as public identity derivation only. Configure participants as requester, worker and verifier. Reject unknown agents before signing anything.
+3. Define the application's JSON agreement terms and `validateTerms`: task specification, price, raw amount string, token/chain/contract, participant wallets, deadline, artifact requirements and verification/refund/dispute policy. Preserve decimal metadata. Use the returned SHA-256 agreement hash and revision for bilateral acceptance. Do not substitute this for the existing contract's keccak spec hash: explicitly map and verify both formats where needed.
+4. Implement `fund.execute/reconcile`. Use `operation.id` for persistent deduplication; save provider transaction identifiers before waiting. Validate successful funding event plus actual escrow fields against the agreed terms and trusted chain/contract configuration. Return pending while unconfirmed, confirmed with structured observations only when policy passes, and rejected only on definitive failure. Confirm how the actual ABI exposes specHash; do not skip the comparison silently.
+5. Implement `start` as a fresh eligibility gate. Fail closed if escrow configuration, evidence or chain access is missing. Match funding and assigned worker before scheduling execution. Dispatch actual work through the app's durable queue using a deduplicated run key. The SDK itself does not execute an AI agent.
+6. Implement one submission path: store the actual artifact bytes, hash them, persist the manifest/reference, submit the required on-chain commitment, and wait/reconcile before confirming. If durable execution starts asynchronously, it must not report submitted just because the queue accepted it.
+7. Implement `verify`: validate the exact committed artifact against accepted criteria. Only return confirmed after checks pass. A definitive failure returns rejected, then a separately authorized dispute action records the dispute. Record check results and validator version. If revisions are needed, add explicit transitions and define how they interact with already submitted commitments.
+8. Implement `release.execute/reconcile`, checking caller role, recorded verification and actual payment evidence. Verify exact amount/recipient and relevant event. The SDK state guard does not change contract rules; document whether the contract itself requires submission. Never infer successful payment from a broadcast hash alone.
+9. Implement `refund.execute/reconcile` based on actual contract eligibility. The default rule allows requesting a refund while funded/running; the adapter must enforce the deadline and absence of submission. Submitted disputes require an explicit supported resolution policy. Implement `resolve` only when that policy exists; confirmed resolution evidence must state whether money was released, refunded or remains locked. `resolved` alone does not imply payment.
+10. Add application deadline/expiry checks to authorization and the `expire` adapter. Schedule sweeps with authorized roles. Cancellation only applies before funding in the default workflow. Do not claim automatic sweeps or a dispute timeout exist if they are not implemented.
+11. Configure each adapter's `reconcile` to inspect the provider using durable operation records. Unknown outcomes remain pending. Poll/reconcile in a durable worker. Handle configured confirmations, disappearing observations and reorgs according to the app's policy; the SDK does not include a chain watcher. Add explicit corrective transitions/policies if required rather than editing records outside CAS.
+12. Expose `createWorkflowHandler` through a Node-runtime Next.js catch-all route. Use `createWorkflowClient` or documented HTTP endpoints externally. The old root API and new workflow API use distinct models; migrate the client deliberately.
+13. Build machine-readable receipts through `workflow.receipts`. Revalidate chain evidence before generating chain-backed PDFs; derive amounts/participants from validated observations and use actual token decimals. Distinguish cached observations from freshly checked evidence.
+
+## Adapter shape
+
+```ts
+const adapters = {
+  fund: {
+    async execute({ job, input, operation }) {
+      // Deduplicate operation.id durably, enforce agreed terms and submit/observe.
+      return { status: 'pending', reference: 'your-provider-operation-id' };
+    },
+    async reconcile({ job, operation }) {
+      // Query your saved provider operation. Do not blindly resend.
+      return { status: 'confirmed', evidence: { /* independently validated fields */ } };
+    },
+  },
+  // start, submit, verify, release, refund, expire, resolve as applicable.
+};
+```
+
+This is a structural example, not a working escrow adapter. Never return confirmed unconditionally in an actual integration.
+
+## Required validation before replacing MVP routes
+
+- Happy path: create → quote → both accept same revision/hash → fund confirmed → start gate → submit confirmed → verify → release confirmed → JSON/PDF evidence.
+- Quotes: revised terms clear acceptances; stale revision rejected; funding prevents edits; deadline policy rejects expired quotes.
+- Permissions: anonymous/unknown/unrelated actors blocked; each role enforced; identity hash alone cannot authenticate.
+- Funding: wrong amount, token, chain, contract, payer, worker, verifier, deadline or spec commitment blocks work; missing escrow configuration fails closed.
+- Effects: duplicate requests and simultaneous retries produce one provider operation; differing input with reused key rejected; crashes before/after broadcast and before final DB save recover by reconciliation.
+- Submission: asynchronous execution cannot prematurely submit; bytes match committed digest; missing/failed chain submission stays pending/rejected.
+- Verification: bad output never enables release; dispute recorded; unsupported resolution leaves explicit unresolved state.
+- Refund: before deadline rejected; after deadline/unsubmitted succeeds; submitted work obeys contract restrictions.
+- Exceptions: pre-funding cancellation, unfunded expiry, definitive provider rejection and long pending operations.
+- Receipts: correct raw units/decimals, matching funding/payment/refund events and artifact linkage; provider outage is distinguished from absent evidence.
+- Custom use case: prove a second task type or non-chain provider works without modifying SDK internals.
+
+Report changed files, adapter capabilities, test results and unsupported contract guarantees. Keep real-chain tests opt-in. Do not claim every possible workflow or payment provider is implemented merely because adapter hooks exist.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allorc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,349 @@
-# Temporary Holding Version
+# Configurable workflows in 0.2.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The new `@allorc/a423-sdk/workflow` entry point provides middleware for agent job lifecycles. It supports different task types and payment systems through application-supplied policies and adapters. It does not assume a particular blockchain, token, wallet, artifact format, database or AI framework. This is experimental software with a reference lifecycle; it does not promise every possible business workflow.
+
+The original root exports remain compatible. Choose the workflow entry point for the full lifecycle; do not mix its records with the original root API. See [integration and migration instructions](./INTEGRATION.md).
+
+```ts
+import { createWorkflow, createWorkflowHandler } from '@allorc/a423-sdk/workflow';
+
+const workflow = createWorkflow({
+  store: durableWorkflowStore,
+  adapters: applicationAdapters,
+  validateTerms: validateYourTerms,
+  authorize: checkYourPolicy,
+});
+const handler = createWorkflowHandler({ workflow, authenticate: authenticateRequest });
+// app/api/a423/[...path]/route.ts
+export const runtime = 'nodejs';
+export { handler as GET, handler as POST };
+```
+
+The names `durableWorkflowStore`, `applicationAdapters`, `validateYourTerms`, `checkYourPolicy` and `authenticateRequest` are application implementations, not SDK exports. Configure them once in a server module and import the handler into your route.
+
+## Workflow coverage
+
+| Action | From | Default role | Result | Required adapter |
+|---|---|---|---|---|
+| create | — | requester | draft | none |
+| quote | draft / quoted / accepted | requester or worker | quoted, acceptances reset | none |
+| accept | quoted | requester and worker separately | accepted after both | none |
+| fund | accepted | requester | funded | fund |
+| start | funded | worker | running | start (funding/work gate) |
+| submit | running | worker | submitted | submit |
+| verify | submitted | verifier | verified | verify |
+| release | verified | verifier | paid | release |
+| refund | funded / running | requester | refunded | refund |
+| cancel | draft / quoted / accepted | requester | cancelled | none |
+| expire | draft / quoted / accepted | requester or worker | expired | expire |
+| dispute | submitted / verified | any of the three parties | disputed | none |
+| resolve | disputed | verifier | resolved | resolve |
+
+`resolved` records a completed resolution process; it does not mean paid or refunded. The resolution adapter must record its actual outcome in evidence. Refund eligibility, quote expiry, deadlines, spending limits, asset rules and verification semantics belong in application policies/adapters. There is no automatic timer. A scheduler calls the API using an authenticated participant or an explicitly configured scheduler role.
+
+### Terms and acceptance
+
+Use JSON terms for your domain: task specification, price, asset, raw amount, deadline, wallet addresses, verifier policy and artifact expectations. Put every term you want committed into this object, including parties and settlement configuration where relevant. The SDK does not invent or validate those domain fields; `validateTerms` should throw on invalid terms. Use decimal strings for raw token amounts, not floating point or JSON bigint.
+
+The SDK hashes sorted-key canonical JSON with SHA-256 (array order preserved, no whitespace). Hash inputs must be plain JSON; avoid cyclic structures and sparse arrays. This is the SDK's own format, not a claim of RFC 8785 compatibility. Names and IDs are case-sensitive. A quote stores revision, terms, hash and acceptances. Accept requires both `agreement_hash` and `revision`; editing a quote clears acceptance. Terms cannot be revised after funding begins under the default rules. Hashes establish integrity, not caller identity or legal consent.
+
+### Adapter contract and recovery
+
+Each effect adapter is either an async function or `{ execute, reconcile }`. It receives `{ job, input, operation }` and returns:
+
+```js
+{ status: 'pending', reference: 'provider-operation-reference' }
+{ status: 'confirmed', evidence: { /* domain-specific verified observations */ } }
+{ status: 'rejected', reason: 'definitive rejection' }
+```
+
+Confirmed results require an evidence object. The SDK trusts the adapter's verdict; it cannot independently establish payment, artifact quality or chain finality. An arbitrary reference is not payment proof. Chain adapters should compare configured chain/contract, job ID, amount, token, participants, deadline and commitments against the accepted terms, plus relevant successful transaction events and the chosen finality policy. `start` must recheck eligibility before work is dispatched.
+
+The SDK atomically stores a pending operation before invoking an effect. Its `operation.id` is stable across retries: use it as the provider idempotency key. **Adapters must durably deduplicate effects, including concurrent calls.** Compare-and-set does not make an external payment exactly-once. If execution throws or returns an invalid result, pending remains; inspect/reconcile it. A pending result retains its observation. A rejected result clears pending without advancing state; repeat the same action key returns the stored job, so use a new key only after a definitive rejection and a deliberate new attempt.
+
+`reconcile(id, actor)` calls only the pending adapter's `reconcile`, never its execute method. That implementation should inspect known provider operations, not blindly repeat a transaction. Supply reconciliation for every external effect. Reuse the same adapter configuration and transitions across restarts. Reconciliation can record additional pending observations. No other action runs while an operation remains pending. If a final database save fails, recovery relies on the same persisted operation and provider key.
+
+The SDK does not run agents or background queues. Persist intent and schedule work in adapters; use a durable worker to submit actual output. Do not mark work submitted merely because a worker was queued. Custom transitions can add milestones, rejection/revision loops, manual review, nonpayment completion, or alternative arbitration. Override whole rules with `{ from, roles, to, effect }`; applications assume responsibility for the resulting invariants. Effect adapters must be trusted server code.
+
+### Storage, permissions and receipts
+
+A workflow store implements `get`, atomic insert-if-absent `create`, and atomic version-checked `compareAndSet`. Persist the entire record (state, pending operation, evidence, events, idempotency history) atomically. Use a separate table/namespace from legacy records. The root `createMemoryStore()` also works structurally at runtime for development, but is not durable or suitable for distributed deployment; a typed workflow store should implement the interface from the workflow entry point.
+
+The handler requires authentication. It obtains actor identity from your callback, never from action bodies. Default role checks always run; `authorize` adds application policy and must return exactly true. Creation requires requester authentication, and requester must differ from worker. The verifier may be the requester or a separate participant. Authentication, wallet/key custody, identity-to-wallet binding and proof of ownership remain application responsibilities. `@allorc/identity` only derives public identifiers.
+
+Receipts are JSON snapshots of agreement, submission, stored adapter evidence, events and pending state. They are not freshly queried chain proofs or signed attestations. Render PDFs separately, and revalidate provider evidence if fresh verification is required. Protect credentials and never put secrets in terms, evidence, metadata or events: all participants can read these fields. Records/events grow over time; production storage should enforce application quotas. The HTTP client limits responses to 1 MiB.
+
+### HTTP and client
+
+| Method | Path beneath `/api/a423` | Body |
+|---|---|---|
+| POST | `/jobs` | `{ id, participants, metadata? }` |
+| GET | `/jobs/:id` | — |
+| POST | `/jobs/:id/actions` | `{ action, input }` plus `Idempotency-Key` |
+| POST | `/jobs/:id/reconcile` | `{}` |
+| GET | `/jobs/:id/receipts` | — |
+
+The handler uses standard Web Request/Response, bounded streaming JSON (64 KiB default), explicit errors, and no background HTTP work. IDs and idempotency keys use 1–128 ASCII letters/digits/underscores/hyphens. Create with a stable application-assigned ID; duplicate creation returns conflict, then retrieve and compare the existing record. Every action needs an actor-scoped key; reusing it with different input fails. Transient conflicts should reload and retry using the same key. Authentication callbacks must inspect headers/cookies or a cloned request if they need the body.
+
+```ts
+import { createWorkflowClient } from '@allorc/a423-sdk/workflow';
+const client = createWorkflowClient({
+  baseUrl: 'https://your-app.example/api/a423',
+  headers: () => ({ Authorization: `Bearer ${serverCredential}` }),
+});
+const quote = await client.act(jobId, 'quote', { terms }, { idempotencyKey: 'quote_1' });
+await client.act(jobId, 'accept', {
+  agreement_hash: quote.agreement!.hash,
+  revision: quote.agreement!.revision,
+}, { idempotencyKey: 'accept_1' });
+```
+
+Each participant needs its own credentials. The client does not automatically retry. Default timeout is 30 seconds; adapters should return pending quickly for long operations. Use TLS and appropriate CSRF protection for cookie-authenticated mutations.
+
+## Original 0.1 API documentation
+
+# @allorc/a423-sdk
+
+One experimental package for exposing an agent job API from a Next.js App Router application. Configure a handler, export it from a catch-all route, and use the typed client to offer, accept, submit and approve work.
+
+**Status:** local experimental v0.1.0. The npm package has not been published by this checkout. Source repository: https://github.com/Allorc-official/A423-SDK. This implements an initial workflow, not a finalized A423 standard or a production escrow system. Node.js 22+. ESM, CommonJS and TypeScript declarations; zero runtime dependencies.
+
+## Quick setup in Next.js
+
+Until publication, install the local package into your existing Next.js application:
+
+```sh
+npm install /absolute/path/to/servers/server/a423_sdk
+```
+
+After publication: `npm install @allorc/a423-sdk`.
+
+Create `lib/a423.ts`:
+
+```ts
+import 'server-only';
+import { createA423Handler, createMemoryStore } from '@allorc/a423-sdk';
+
+// Development only. Replace with a durable StateStore before deployment.
+const store = createMemoryStore();
+const token = process.env.A423_API_TOKEN;
+const actorId = process.env.A423_AGENT_ID;
+if (!token || !actorId) throw new Error('Configure A423_API_TOKEN and A423_AGENT_ID');
+
+export const a423 = createA423Handler({
+  store,
+  authenticate(request) {
+    return request.headers.get('authorization') === `Bearer ${token}`
+      ? actorId
+      : null;
+  }
+});
+```
+
+This minimal authentication example maps one secret credential to one public actor ID. A complete workflow requires separate requester and worker credentials. The two-actor example is in `examples/nextjs/lib/a423.ts`; replace it with your own authenticated identity integration when connecting real agents.
+
+Create `app/api/a423/[...path]/route.ts`:
+
+```ts
+import { a423 } from '@/lib/a423';
+
+export const runtime = 'nodejs';
+export const GET = a423;
+export const POST = a423;
+```
+
+The `@/` import assumes your application's usual root alias; adjust it if your app uses `src/` or relative imports. This is one catch-all route, not one file per action. Do not run it in the Edge runtime. The SDK does not start a listener or publish routes on its own: Next.js exposes the route you configure.
+
+Keep credentials in server environment variables without `NEXT_PUBLIC_`. The package's client is designed for Node/server use, not for embedding worker credentials in client-side React. Your existing Next.js application supplies Next.js, React, TypeScript and `server-only`; the SDK itself does not import framework internals.
+
+## Use the typed client
+
+```ts
+import { createA423Client } from '@allorc/a423-sdk';
+
+const requester = createA423Client({
+  baseUrl: 'https://your-app.example/api/a423',
+  headers: { authorization: `Bearer ${requesterToken}` }
+});
+const worker = createA423Client({
+  baseUrl: 'https://your-app.example/api/a423',
+  headers: { authorization: `Bearer ${workerToken}` }
+});
+
+const job = await requester.offer({
+  worker_id: workerAgentId,
+  title: 'Prepare a short brief',
+  description: 'Research the topic and return a deliverable link.',
+  price: { amount_minor: 500, currency: 'USD' }
+}, { idempotencyKey: 'brief-request-001' });
+
+await worker.accept(job.id);
+await worker.submit(job.id, { deliverable: 'https://example.com/brief.md' });
+await requester.approve(job.id);
+const receipts = await requester.receipts(job.id);
+```
+
+`requesterToken`, `workerToken` and `workerAgentId` come from your application, not the SDK. The requester and worker are distinct authenticated actors. The example orchestrates both sides for demonstration; in a real integration they normally run independently.
+
+The price is an agreed term: 500 USD minor units means $5.00 when your adapter uses USD cents. Currency codes are uppercase strings of 3–12 letters/digits starting with a letter. The SDK does not calculate exchange rates, currency precision, fees or blockchain token decimals; define those semantics in your settlement integration. `amount_minor` must be a nonnegative safe integer. Zero-price jobs are allowed.
+
+A deliverable is an opaque string, such as a URL, repository reference or storage path. The SDK stores it and never downloads or executes it. It does not perform the work, evaluate quality or run an agent automatically.
+
+Client methods return `Job`, except `receipts`, which returns `Receipts`. `headers` may be an async function for fresh credentials. `fetch` can be injected for tests or custom networking. Requests default to a 30-second timeout, refuse redirects and do not retry automatically.
+
+## HTTP API
+
+Every request requires successful `authenticate(request)`. POSTs use `Content-Type: application/json`.
+
+| Method | Route | Body | Who can call |
+| --- | --- | --- | --- |
+| POST | `/api/a423/offers` | `{worker_id,title,description,price}` and `Idempotency-Key` header | Authenticated requester |
+| GET | `/api/a423/jobs/:id` | None | Requester or assigned worker |
+| POST | `/api/a423/jobs/:id/accept` | `{}` | Assigned worker |
+| POST | `/api/a423/jobs/:id/submit` | `{deliverable}` | Assigned worker |
+| POST | `/api/a423/jobs/:id/approve` | `{}` | Requester |
+| GET | `/api/a423/jobs/:id/receipts` | None | Requester or assigned worker |
+
+Offer creation returns HTTP 201 with `{job}`; an identical retry returns 200 with the existing job. Other actions return `{job}`. Receipts return `{job_id,state,settlement,events}`. Responses use `Cache-Control: no-store`. Unknown jobs and jobs belonging to other actors both return 404.
+
+External agents can use plain HTTP without installing the SDK. For example:
+
+```sh
+curl https://your-app.example/api/a423/offers \
+  -H "Authorization: Bearer $A423_REQUESTER_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: brief-request-001' \
+  -d '{"worker_id":"worker-agent-id","title":"Brief","description":"Prepare a short brief","price":{"amount_minor":500,"currency":"USD"}}'
+```
+
+Adjust `basePath` if you mount at a different URL. This initial implementation has no list/search, cancellation, disputes, amendments, webhooks, discovery endpoint, background scheduler or UI. Poll known job IDs or coordinate workers through your own queue. Authentication is mandatory; signatures and message-level cryptographic verification are not built in.
+
+## Workflow and retry behaviour
+
+A job follows `offered → accepted → submitted → completed`. With a settlement adapter it follows `submitted → settlement_pending → completed` during approval.
+
+The server checks the actor and current state before each change. Every successful change increments the job version and appends an event. Submission is immutable: retrying with the same deliverable succeeds, but replacing it is rejected. Repeating acceptance after acceptance or approval after completion returns the current job without adding a duplicate event.
+
+Offer IDs are deterministic SHA-256 values scoped by protocol version, authenticated requester ID and `Idempotency-Key`. Reuse the same key and exact logical offer when retrying after a network failure. Reusing it with different offer details returns 409. Store the key on your side; a freshly generated key means a new offer. Keys are visible ASCII without spaces, at most 200 characters, and should not contain secrets.
+
+Storage changes use compare-and-set. Concurrent writes can return 409 `CONFLICT`; reload the job and retry the intended action. The SDK does not keep an HTTP request open for the duration of a task. Worker execution and scheduling belong in your application's background jobs.
+
+## Storage adapter
+
+`store` is required. `createMemoryStore()` is only for local development/tests: it loses data on restart and is not shared across serverless instances or processes. There is no silent in-memory default.
+
+Implement the `StateStore` interface against your database:
+
+```ts
+interface StateStore {
+  get(id: string): Promise<Job | null>;
+  create(job: Job): Promise<boolean>;
+  compareAndSet(id: string, expectedVersion: number, job: Job): Promise<boolean>;
+}
+```
+
+`create` must atomically insert only if the ID is absent; enforce a unique ID constraint. `compareAndSet` must atomically update only when both ID and version match, then report whether one row changed. Store job fields and events in the same transaction. A read followed by an unconditional update is not sufficient. Return independent snapshots so caller mutations do not change stored state.
+
+For example, a relational adapter can use an ID primary key, a version column and a JSON document. Create with insert-on-conflict-do-nothing; update using `WHERE id = ? AND version = ?`. This is a contract, not a shipped SQL adapter. Durable storage must also support pending settlement recovery.
+
+## Identity and authentication
+
+`authenticate(request)` is the integration point for your identity system. It returns an authenticated actor's public agent ID or `null` to reject. It may verify a bearer credential, a session, or an externally signed request. The returned ID determines permissions; an untrusted ID in a request body/header does not.
+
+`@allorc/identity` 0.3.0 can form a public agent ID:
+
+```ts
+import { VERSION, createIdentity } from '@allorc/identity';
+
+const identity = createIdentity({
+  version: VERSION,
+  organization_public_key: 'externally-supplied-public-value',
+  agent_reference: 'worker-42',
+  agent_name: 'Alice',
+  agent_email: 'alice@example.com'
+});
+// Register identity.agent_id with your credential/authority system separately.
+```
+
+Install that optional package separately when needed. A hash match proves record consistency, not ownership or authentication. This SDK does not claim to verify the organisation behind a public key, and does not depend on the identity package to authenticate actors. Changes to that package's public ingredients change its derived agent ID; your identity integration must manage those updates.
+
+For cookie-based authentication, your integration must also enforce its CSRF/origin policy. The SDK does not configure sessions, CORS, network access, rate limits or tenant onboarding for you. The supplied example uses server-issued bearer tokens with fixed actor bindings.
+
+## Optional settlement adapter
+
+Without an adapter, approval marks the job completed with:
+
+```json
+{"status":"not_configured","reference":null}
+```
+
+**This records task approval and moves no money.** A configured adapter is called only after requester approval and after the job is persisted as `settlement_pending`:
+
+```ts
+const handler = createA423Handler({
+  store,
+  authenticate,
+  settlement: {
+    async settle({ job, idempotencyKey }) {
+      // Invoke your own escrow/payment service with this stable key.
+      // Persistently deduplicate that key, including concurrent invocations.
+      const result = await yourSettlementService.release({
+        jobId: job.id,
+        requesterId: job.requester_id,
+        workerId: job.worker_id,
+        price: job.price,
+        idempotencyKey
+      });
+      return { reference: result.receiptId };
+    }
+  }
+});
+```
+
+`yourSettlementService` is your external integration, not an included export. The SDK passes `a423:settle:<job-id>` as a stable provider idempotency key. Your adapter MUST durably deduplicate it and return the same result on retries, including simultaneous calls from multiple server instances. The SDK cannot guarantee exactly-once movement of funds across an external provider and a database transaction.
+
+On a provider error the server returns 502 and leaves the job pending; retry `approve` as the requester. If the provider succeeds but the database write fails, retrying approval uses the same key. If you run a recovery worker, route it through equivalent actor and idempotency rules. No automatic retry queue is included.
+
+This is not funded escrow: the SDK does not reserve funds at offer/acceptance, validate wallets, sign financial authorisations, collect mandates or guarantee payment. Your adapter must enforce those rules before moving funds. `settled` records the adapter's reported success, not an independently verified blockchain confirmation.
+
+## Errors and limits
+
+Errors are `{error:{code,message}}`. The client throws `A423Error` with `code` and `status` for HTTP failures. Network/timeout errors propagate from fetch. Internal exception details stay server-side; optional `onError(error)` lets your application record them.
+
+| HTTP status | Typical code |
+| --- | --- |
+| 400 | `INVALID_INPUT`, `INVALID_JSON` |
+| 401 | `UNAUTHENTICATED` |
+| 403 | `FORBIDDEN` |
+| 404 | `NOT_FOUND` |
+| 405 | `METHOD_NOT_ALLOWED` |
+| 409 | `INVALID_STATE`, `CONFLICT`, `IDEMPOTENCY_CONFLICT` |
+| 413 | `BODY_TOO_LARGE` |
+| 415 | `UNSUPPORTED_MEDIA_TYPE` |
+| 500 | `INTERNAL_ERROR` |
+| 502 | `SETTLEMENT_UNAVAILABLE` |
+
+Request bodies default to 64 KiB and are limited while streaming, even without `Content-Length`; `maxBodyBytes` can set 1 byte through 1 MiB. Description limit: 16,000 characters; deliverable: 8,000; actor IDs and titles: 256. Client response bodies are limited to 1 MiB. Bound requests at your ingress too. There is no multipart/file upload or arbitrary server-side URL fetching.
+
+## Package exports
+
+| Export | Purpose |
+| --- | --- |
+| `createA423Handler(options)` | Standard Web Request/Response handler usable in Next.js routes |
+| `createA423Client(options)` | Typed HTTP client |
+| `createMemoryStore()` | Explicit local development store |
+| `A423Error` | Structured client/protocol error |
+| `PROTOCOL_VERSION` | `a423.experimental.v1` |
+
+ESM and CommonJS expose the same names. Interfaces for `Job`, `StateStore`, `SettlementAdapter` and configuration are in `src/index.d.ts`. The handler is framework-independent at runtime, but the included integration targets Next.js App Router. Installing this SDK does not publish an API or establish protocol compatibility with other A423 implementations.
+
+## Development
+
+```sh
+npm test
+npm run pack:check
+```
+
+Tests exercise the complete workflow through actual Web Request/Response objects, permissions, malformed input, streaming limits, concurrent updates, retry semantics and settlement recovery. An additional socket-based test runs where local listeners are permitted, and explicitly skips when the execution environment blocks them. Next.js example files are templates for an existing application; they are not a standalone generated Next.js app.
+
+No runtime dependencies or build step. Before a public release, review the package allowlist, configure the repository/private security reporting channel, and verify a real Next.js deployment and durable adapter. Publication is a separate maintainer action; this package has not been published by creating these files.

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security policy
+
+Experimental SDK; no independent audit or stable support commitment. The built-in memory store and fixed bearer-token example are for development, not a production deployment.
+
+Authentication must be supplied. Never treat a public ID, public ingredients or a matching hash as evidence that a request belongs to an agent. Verify credentials/signatures using your own identity adapter; enforce session/CSRF policy when using cookies. Configure TLS, ingress limits, rate limits, CORS and durable atomic storage in your host application.
+
+Settlement adapters must durably deduplicate the SDK's stable key across retries and concurrent calls. This SDK does not fund escrow, establish mandates, custody keys or guarantee exactly-once payments. Validate recipient, amount, permission and provider status independently. Completion without an adapter explicitly means no settlement is configured.
+
+Do not include tokens, private keys, customer data or live exploit details in public reports. Use a private repository reporting channel when configured; maintainers should establish one before requesting sensitive reports. Never log credentials. No private security contact is invented by this initial package.

package/examples/client.mjs

@@ -0,0 +1,19 @@
+// Run after starting the Next.js example and setting the same server credentials.
+import { createA423Client } from '../src/index.mjs';
+import { randomUUID } from 'node:crypto';
+
+for (const name of ['A423_REQUESTER_TOKEN', 'A423_WORKER_TOKEN', 'A423_WORKER_ID']) {
+  if (!process.env[name]) throw new Error(`Set ${name} before running this example`);
+}
+const baseUrl = process.env.A423_BASE_URL || 'http://localhost:3000/api/a423';
+const requester = createA423Client({ baseUrl, headers: { authorization: `Bearer ${process.env.A423_REQUESTER_TOKEN}` } });
+const worker = createA423Client({ baseUrl, headers: { authorization: `Bearer ${process.env.A423_WORKER_TOKEN}` } });
+const job = await requester.offer({
+  worker_id: process.env.A423_WORKER_ID,
+  title: 'Prepare a short brief', description: 'Return a link to the completed brief.',
+  price: { amount_minor: 500, currency: 'USD' }
+}, { idempotencyKey: randomUUID() }); // Persist this key if retrying this logical offer.
+await worker.accept(job.id);
+await worker.submit(job.id, { deliverable: 'https://example.com/brief.md' });
+await requester.approve(job.id);
+console.log(JSON.stringify(await requester.receipts(job.id), null, 2));

package/examples/nextjs/app/api/a423/[...path]/route.ts

@@ -0,0 +1,5 @@
+import { a423 } from '@/lib/a423';
+
+export const runtime = 'nodejs';
+export const GET = a423;
+export const POST = a423;

package/examples/nextjs/lib/a423.ts

@@ -0,0 +1,31 @@
+import 'server-only';
+import { createA423Handler, createMemoryStore } from '@allorc/a423-sdk';
+
+// DEMO ONLY: replace with your database-backed StateStore before production.
+const store = createMemoryStore();
+
+const requesterToken = process.env.A423_REQUESTER_TOKEN;
+const workerToken = process.env.A423_WORKER_TOKEN;
+const requesterId = process.env.A423_REQUESTER_ID;
+const workerId = process.env.A423_WORKER_ID;
+if (!requesterToken || !workerToken || !requesterId || !workerId ||
+    requesterToken === workerToken || requesterId === workerId) {
+  throw new Error('Set distinct A423_REQUESTER_TOKEN, A423_WORKER_TOKEN, A423_REQUESTER_ID and A423_WORKER_ID server environment values');
+}
+
+export const a423 = createA423Handler({
+  store,
+  // A demo mapping from private server-issued credentials to public agent IDs.
+  // Replace with your real authentication/identity adapter. Do not expose tokens to React.
+  authenticate(request) {
+    const header = request.headers.get('authorization');
+    if (header === `Bearer ${requesterToken}`) return requesterId;
+    if (header === `Bearer ${workerToken}`) return workerId;
+    return null;
+  },
+  onError(error) {
+    // Send to your own server logger; avoid including credentials.
+    console.error('A423 server error', error instanceof Error ? error.name : 'UnknownError');
+  }
+  // No settlement adapter: completion records approval only; it moves no money.
+});

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Experimental Next.js-friendly agent job SDK with typed HTTP client and pluggable storage, authentication and settlement",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./src/index.cjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.cjs"
+    },
+    "./workflow": {
+      "types": "./src/workflow.d.ts",
+      "import": "./src/workflow.mjs",
+      "require": "./src/workflow.cjs"
+    }
+  },
+  "files": [
+    "src/index.cjs",
+    "src/index.mjs",
+    "src/index.d.ts",
+    "examples/client.mjs",
+    "examples/nextjs/lib/a423.ts",
+    "examples/nextjs/app/api/a423/*/route.ts",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "src/workflow.cjs",
+    "src/workflow.mjs",
+    "src/workflow.d.ts",
+    "INTEGRATION.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nextjs",
+    "agent",
+    "a423",
+    "sdk",
+    "experimental"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Allorc-official/A423-SDK.git"
+  },
+  "homepage": "https://github.com/Allorc-official/A423-SDK#readme",
+  "bugs": {
+    "url": "https://github.com/Allorc-official/A423-SDK/issues"
+  }
+}

package/src/index.cjs

@@ -0,0 +1,242 @@
+'use strict';
+const { createHash, randomUUID } = require('node:crypto');
+const PROTOCOL_VERSION = 'a423.experimental.v1';
+const MAX_BODY_BYTES = 65536;
+const MAX_RESULT_BYTES = 1048576;
+
+class A423Error extends Error {
+  constructor(code, message, status = 400) {
+    super(message); this.name = 'A423Error'; this.code = code; this.status = status;
+  }
+}
+function fail(code, message, status = 400) { throw new A423Error(code, message, status); }
+function object(value, required, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('INVALID_INPUT', 'Expected an object');
+  const keys = Object.keys(value);
+  if (required.some(k => !Object.hasOwn(value, k)) || keys.some(k => ![...required, ...optional].includes(k))) {
+    fail('INVALID_INPUT', `Expected fields: ${required.join(', ')}${optional.length ? `; optional: ${optional.join(', ')}` : ''}`);
+  }
+}
+function text(value, name, max = 256) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)) {
+    fail('INVALID_INPUT', `${name} must be nonempty text of at most ${max} characters`);
+  }
+  return value;
+}
+function offerInput(value) {
+  object(value, ['worker_id', 'title', 'description', 'price']);
+  object(value.price, ['amount_minor', 'currency']);
+  if (!Number.isSafeInteger(value.price.amount_minor) || value.price.amount_minor < 0) fail('INVALID_INPUT', 'amount_minor must be a nonnegative safe integer');
+  if (typeof value.price.currency !== 'string' || !/^[A-Z][A-Z0-9]{2,11}$/.test(value.price.currency)) fail('INVALID_INPUT', 'currency must be an uppercase currency code');
+  return { worker_id: text(value.worker_id, 'worker_id'), title: text(value.title, 'title'),
+    description: text(value.description, 'description', 16000), price: { amount_minor: value.price.amount_minor, currency: value.price.currency } };
+}
+function submissionInput(value) {
+  object(value, ['deliverable']);
+  return { deliverable: text(value.deliverable, 'deliverable', 8000) };
+}
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function clone(value) { return structuredClone(value); }
+function json(value, status = 200) {
+  return Response.json(value, { status, headers: { 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' } });
+}
+async function readJson(request, limit) {
+  if (!(request.headers.get('content-type') || '').split(';')[0].trim().toLowerCase().endsWith('/json')) {
+    fail('UNSUPPORTED_MEDIA_TYPE', 'Use Content-Type: application/json', 415);
+  }
+  const length = request.headers.get('content-length');
+  if (length !== null && (!/^\d+$/.test(length) || Number(length) > limit)) fail('BODY_TOO_LARGE', 'Request body exceeds the configured limit', 413);
+  if (!request.body) fail('INVALID_JSON', 'A JSON body is required');
+  const reader = request.body.getReader(); const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) { await reader.cancel(); fail('BODY_TOO_LARGE', 'Request body exceeds the configured limit', 413); }
+      chunks.push(Buffer.from(value));
+    }
+  } finally { reader.releaseLock(); }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { fail('INVALID_JSON', 'Request body must contain valid JSON'); }
+}
+/** Development only: no persistence or coordination between processes/serverless instances. */
+function createMemoryStore() {
+  const jobs = new Map();
+  return {
+    async get(id) { return jobs.has(id) ? clone(jobs.get(id)) : null; },
+    async create(job) { if (jobs.has(job.id)) return false; jobs.set(job.id, clone(job)); return true; },
+    async compareAndSet(id, expectedVersion, job) {
+      if (!jobs.has(id) || jobs.get(id).version !== expectedVersion) return false;
+      jobs.set(id, clone(job)); return true;
+    }
+  };
+}
+function createA423Handler({ store, authenticate, settlement, basePath = '/api/a423', maxBodyBytes = MAX_BODY_BYTES, onError } = {}) {
+  if (!store || ['get', 'create', 'compareAndSet'].some(k => typeof store[k] !== 'function')) throw new TypeError('Supply a store implementing get, create and atomic compareAndSet');
+  if (typeof authenticate !== 'function') throw new TypeError('Supply authenticate(request); there is no implicit anonymous access');
+  if (settlement && typeof settlement.settle !== 'function') throw new TypeError('settlement must implement settle');
+  if (typeof basePath !== 'string' || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(basePath)) throw new TypeError('basePath must be an absolute path without a trailing slash');
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || maxBodyBytes > MAX_RESULT_BYTES) throw new TypeError('maxBodyBytes must be between 1 and 1048576');
+  if (onError !== undefined && typeof onError !== 'function') throw new TypeError('onError must be a function');
+  const event = (job, type, actorId, data = {}) => ({ id: randomUUID(), sequence: job.events.length + 1, type, actor_id: actorId, at: new Date().toISOString(), data });
+  async function save(previous, next, type, actorId, data) {
+    next.version = previous.version + 1;
+    next.updated_at = new Date().toISOString();
+    next.events.push(event(next, type, actorId, data));
+    if (!await store.compareAndSet(previous.id, previous.version, next)) fail('CONFLICT', 'Job changed concurrently; reload and retry', 409);
+    return next;
+  }
+  async function load(id, actorId) {
+    const job = await store.get(id);
+    // Do not disclose a job's existence to unrelated actors.
+    if (!job || ![job.requester_id, job.worker_id].includes(actorId)) fail('NOT_FOUND', 'Job not found', 404);
+    return job;
+  }
+  return async function handler(request) {
+    try {
+      const path = new URL(request.url).pathname;
+      if (!path.startsWith(basePath + '/')) fail('NOT_FOUND', 'Route not found', 404);
+      const relative = path.slice(basePath.length);
+      const match = /^\/jobs\/([a-zA-Z0-9_-]{1,128})(?:\/(accept|submit|approve|receipts))?$/.exec(relative);
+      if (relative !== '/offers' && !match) fail('NOT_FOUND', 'Route not found', 404);
+      const expectedMethod = relative === '/offers' || (match && ['accept', 'submit', 'approve'].includes(match[2])) ? 'POST' : 'GET';
+      if (request.method !== expectedMethod) {
+        const response = json({ error: { code: 'METHOD_NOT_ALLOWED', message: `Use ${expectedMethod}` } }, 405);
+        response.headers.set('allow', expectedMethod); return response;
+      }
+      const actorId = await authenticate(request);
+      if (actorId === null || actorId === undefined) fail('UNAUTHENTICATED', 'Authentication required', 401);
+      text(actorId, 'authenticated actor ID');
+      if (relative === '/offers') {
+        const input = offerInput(await readJson(request, maxBodyBytes));
+        if (input.worker_id === actorId) fail('INVALID_INPUT', 'Requester and worker must be different actors');
+        const idempotencyKey = text(request.headers.get('idempotency-key'), 'Idempotency-Key', 200);
+        if (!/^[\x21-\x7e]+$/.test(idempotencyKey)) fail('INVALID_INPUT', 'Idempotency-Key must use visible ASCII without spaces');
+        const id = 'job_' + hash([PROTOCOL_VERSION, actorId, idempotencyKey]);
+        const requestHash = hash(input);
+        const at = new Date().toISOString();
+        const job = { protocol: PROTOCOL_VERSION, id, version: 1, state: 'offered', requester_id: actorId,
+          ...input, request_hash: requestHash, deliverable: null, settlement: null, created_at: at, updated_at: at, events: [] };
+        job.events.push(event(job, 'offered', actorId));
+        if (await store.create(job)) return json({ job }, 201);
+        const existing = await load(id, actorId);
+        if (existing.request_hash !== requestHash) fail('IDEMPOTENCY_CONFLICT', 'Idempotency-Key was already used with different offer details', 409);
+        return json({ job: existing });
+      }
+      const [, id, action] = match;
+      let job = await load(id, actorId);
+      if (action === 'receipts') return json({ job_id: job.id, state: job.state, settlement: job.settlement, events: job.events });
+      if (!action) return json({ job });
+      const body = await readJson(request, maxBodyBytes);
+      if (action === 'accept') {
+        object(body, []);
+        if (actorId !== job.worker_id) fail('FORBIDDEN', 'Only the assigned worker can accept', 403);
+        if (job.state !== 'offered') {
+          if (['accepted', 'submitted', 'settlement_pending', 'completed'].includes(job.state)) return json({ job });
+          fail('INVALID_STATE', 'Job must be offered', 409);
+        }
+        const next = clone(job); next.state = 'accepted';
+        job = await save(job, next, 'accepted', actorId);
+        return json({ job });
+      }
+      if (action === 'submit') {
+        const input = submissionInput(body);
+        if (actorId !== job.worker_id) fail('FORBIDDEN', 'Only the assigned worker can submit', 403);
+        if (job.state !== 'accepted') {
+          if (['submitted', 'settlement_pending', 'completed'].includes(job.state) && job.deliverable === input.deliverable) return json({ job });
+          fail('INVALID_STATE', 'Job must be accepted; a submitted deliverable cannot be replaced', 409);
+        }
+        const next = clone(job); next.state = 'submitted'; next.deliverable = input.deliverable;
+        return json({ job: await save(job, next, 'submitted', actorId, input) });
+      }
+      object(body, []);
+      if (actorId !== job.requester_id) fail('FORBIDDEN', 'Only the requester can approve', 403);
+      if (job.state === 'completed') return json({ job });
+      if (!['submitted', 'settlement_pending'].includes(job.state)) fail('INVALID_STATE', 'Job must be submitted before approval', 409);
+      if (!settlement) {
+        const next = clone(job); next.state = 'completed';
+        next.settlement = { status: 'not_configured', reference: null };
+        return json({ job: await save(job, next, 'completed', actorId, { settlement: next.settlement }) });
+      }
+      if (job.state === 'submitted') {
+        const next = clone(job); next.state = 'settlement_pending';
+        job = await save(job, next, 'settlement_pending', actorId);
+      }
+      // The adapter MUST deduplicate this stable key across retries/processes.
+      const idempotencyKey = `a423:settle:${job.id}`;
+      let result;
+      try {
+        result = await settlement.settle({ job: clone(job), idempotencyKey });
+        object(result, ['reference']); text(result.reference, 'settlement reference', 2048);
+      } catch (error) {
+        if (onError) { try { await onError(error); } catch {} }
+        fail('SETTLEMENT_UNAVAILABLE', 'Settlement remains pending; retry approval with the same job', 502);
+      }
+      const next = clone(job); next.state = 'completed';
+      next.settlement = { status: 'settled', reference: result.reference };
+      try { return json({ job: await save(job, next, 'completed', actorId, { settlement: next.settlement }) }); }
+      catch (error) {
+        if (error instanceof A423Error && error.code === 'CONFLICT') {
+          const latest = await load(id, actorId);
+          if (latest.state === 'completed') return json({ job: latest });
+        }
+        throw error;
+      }
+    } catch (error) {
+      if (error instanceof A423Error) return json({ error: { code: error.code, message: error.message } }, error.status);
+      if (onError) { try { await onError(error); } catch {} }
+      return json({ error: { code: 'INTERNAL_ERROR', message: 'Unable to process the request' } }, 500);
+    }
+  };
+}
+
+function createA423Client({ baseUrl, headers, fetch: fetchImpl = globalThis.fetch, timeoutMs = 30000 } = {}) {
+  const url = new URL(baseUrl);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new TypeError('baseUrl must be an HTTP(S) URL without credentials, query or fragment');
+  if (typeof fetchImpl !== 'function') throw new TypeError('Supply a fetch implementation');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new TypeError('timeoutMs must be a positive integer');
+  const base = url.href.replace(/\/$/, '');
+  async function call(path, method = 'GET', body, idempotencyKey) {
+    const supplied = typeof headers === 'function' ? await headers() : headers;
+    const requestHeaders = new Headers(supplied);
+    requestHeaders.set('accept', 'application/json');
+    if (body !== undefined) requestHeaders.set('content-type', 'application/json');
+    if (idempotencyKey !== undefined) requestHeaders.set('idempotency-key', idempotencyKey);
+    const response = await fetchImpl(base + path, { method, headers: requestHeaders, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+    const data = await readClientJson(response);
+    if (!response.ok) throw new A423Error(data?.error?.code || 'HTTP_ERROR', data?.error?.message || `HTTP ${response.status}`, response.status);
+    return data;
+  }
+  function jobPath(id) {
+    if (typeof id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new TypeError('Invalid job ID');
+    return '/jobs/' + id;
+  }
+  return {
+    async offer(input, { idempotencyKey } = {}) {
+      if (typeof idempotencyKey !== 'string' || !idempotencyKey) throw new TypeError('Supply an idempotencyKey for offer retries');
+      return (await call('/offers', 'POST', input, idempotencyKey)).job;
+    },
+    async getJob(id) { return (await call(jobPath(id))).job; },
+    async accept(id) { return (await call(jobPath(id) + '/accept', 'POST', {})).job; },
+    async submit(id, input) { return (await call(jobPath(id) + '/submit', 'POST', input)).job; },
+    async approve(id) { return (await call(jobPath(id) + '/approve', 'POST', {})).job; },
+    async receipts(id) { return call(jobPath(id) + '/receipts'); }
+  };
+}
+async function readClientJson(response) {
+  const reader = response.body?.getReader();
+  if (!reader) throw new A423Error('INVALID_RESPONSE', 'Server returned no response body', 502);
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read(); if (done) break;
+      size += value.byteLength;
+      if (size > MAX_RESULT_BYTES) { await reader.cancel(); throw new A423Error('INVALID_RESPONSE', 'Server response exceeds 1 MiB', 502); }
+      chunks.push(Buffer.from(value));
+    }
+  } finally { reader.releaseLock(); }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw new A423Error('INVALID_RESPONSE', 'Server returned invalid JSON', 502); }
+}
+module.exports = { PROTOCOL_VERSION, A423Error, createMemoryStore, createA423Handler, createA423Client };

package/src/index.d.ts

@@ -0,0 +1,67 @@
+/** Experimental A423 workflow, not a finalized interoperable protocol. Node.js 22+. */
+export const PROTOCOL_VERSION: 'a423.experimental.v1';
+export type JobState = 'offered' | 'accepted' | 'submitted' | 'settlement_pending' | 'completed';
+export interface Price { amount_minor: number; currency: string }
+export interface OfferInput { worker_id: string; title: string; description: string; price: Price }
+export interface SubmissionInput { deliverable: string }
+export interface SettlementResult { status: 'settled' | 'not_configured'; reference: string | null }
+export interface JobEvent {
+  id: string; sequence: number; type: JobState; actor_id: string;
+  at: string; data: { deliverable?: string; settlement?: SettlementResult };
+}
+export interface Job extends OfferInput {
+  protocol: typeof PROTOCOL_VERSION;
+  id: string; version: number; state: JobState; requester_id: string;
+  request_hash: string; deliverable: string | null; settlement: SettlementResult | null;
+  created_at: string; updated_at: string; events: JobEvent[];
+}
+export interface Receipts { job_id: string; state: JobState; settlement: SettlementResult | null; events: JobEvent[] }
+/** All writes must be atomic across instances. Jobs and events are saved together. */
+export interface StateStore {
+  get(id: string): Promise<Job | null>;
+  /** Atomically insert only if absent. Return true iff inserted. */
+  create(job: Job): Promise<boolean>;
+  /** Atomically replace only if version matches. Return true iff replaced. */
+  compareAndSet(id: string, expectedVersion: number, job: Job): Promise<boolean>;
+}
+export interface SettlementAdapter {
+  /** MUST persistently deduplicate idempotencyKey and return the same reference on retry. */
+  settle(input: { job: Job; idempotencyKey: string }): Promise<{ reference: string }>;
+}
+export interface HandlerOptions {
+  store: StateStore;
+  /** Return the authenticated actor's agent ID, or null to reject. Never trust a caller-supplied ID alone. */
+  authenticate(request: Request): Promise<string | null> | string | null;
+  settlement?: SettlementAdapter;
+  /** Default /api/a423; no trailing slash. */
+  basePath?: string;
+  /** Default 65536; max 1048576. Enforced while streaming, not just through Content-Length. */
+  maxBodyBytes?: number;
+  /** Receives internal errors for your server logs. Errors are not exposed in HTTP responses. */
+  onError?(error: unknown): void | Promise<void>;
+}
+export class A423Error extends Error {
+  code: string;
+  status: number;
+  constructor(code: string, message: string, status?: number);
+}
+/** Development/testing only. Does not persist across processes, restarts or serverless instances. */
+export function createMemoryStore(): StateStore;
+export function createA423Handler(options: HandlerOptions): (request: Request) => Promise<Response>;
+export interface ClientOptions {
+  /** Full API root, e.g. https://example.com/api/a423. */
+  baseUrl: string;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  fetch?: typeof globalThis.fetch;
+  /** Default 30000. No implicit retries. */
+  timeoutMs?: number;
+}
+export interface A423Client {
+  offer(input: OfferInput, options: { idempotencyKey: string }): Promise<Job>;
+  getJob(id: string): Promise<Job>;
+  accept(id: string): Promise<Job>;
+  submit(id: string, input: SubmissionInput): Promise<Job>;
+  approve(id: string): Promise<Job>;
+  receipts(id: string): Promise<Receipts>;
+}
+export function createA423Client(options: ClientOptions): A423Client;

package/src/index.mjs

@@ -0,0 +1,2 @@
+import sdk from './index.cjs';
+export const { PROTOCOL_VERSION, A423Error, createMemoryStore, createA423Handler, createA423Client } = sdk;

package/src/workflow.cjs

@@ -0,0 +1,215 @@
+'use strict';
+const { createHash, randomUUID } = require('node:crypto');
+const { A423Error } = require('./index.cjs');
+const copy = value => structuredClone(value);
+const error = (code, message, status = 409) => { throw new A423Error(code, message, status); };
+function canonical(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) throw new TypeError('Use dense JSON arrays');
+    return '[' + value.map(item => canonical(item)).join(',') + ']';
+  }
+  if (value && Object.getPrototypeOf(value) === Object.prototype) return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + canonical(value[k])).join(',') + '}';
+  throw new TypeError('Use JSON values only (no undefined, bigint, class instances or nonfinite numbers)');
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+function identifier(value) { if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) throw new TypeError('IDs must contain 1–128 letters, digits, underscores or hyphens'); return value; }
+const RULES = {
+  quote: { from: ['draft', 'quoted', 'accepted'], roles: ['requester', 'worker'], to: 'quoted' },
+  accept: { from: ['quoted'], roles: ['requester', 'worker'], to: 'quoted' },
+  fund: { from: ['accepted'], roles: ['requester'], to: 'funded', effect: true },
+  start: { from: ['funded'], roles: ['worker'], to: 'running', effect: true },
+  submit: { from: ['running'], roles: ['worker'], to: 'submitted', effect: true },
+  verify: { from: ['submitted'], roles: ['verifier'], to: 'verified', effect: true },
+  release: { from: ['verified'], roles: ['verifier'], to: 'paid', effect: true },
+  refund: { from: ['funded', 'running'], roles: ['requester'], to: 'refunded', effect: true },
+  cancel: { from: ['draft', 'quoted', 'accepted'], roles: ['requester'], to: 'cancelled' },
+  expire: { from: ['draft', 'quoted', 'accepted'], roles: ['requester', 'worker'], to: 'expired', effect: true },
+  dispute: { from: ['submitted', 'verified'], roles: ['requester', 'worker', 'verifier'], to: 'disputed' },
+  resolve: { from: ['disputed'], roles: ['verifier'], to: 'resolved', effect: true }
+};
+/** Pure canonical JSON SHA-256. This is an integrity commitment, not authentication. */
+function hashAgreement(terms) { return digest(terms); }
+function createWorkflow({ store, adapters = {}, authorize, validateTerms, transitions = {} } = {}) {
+  if (!store || ['get', 'create', 'compareAndSet'].some(k => typeof store[k] !== 'function')) throw new TypeError('Supply an atomic workflow store');
+  const rules = copy(RULES);
+  for (const [action, rule] of Object.entries(transitions)) {
+    identifier(action);
+    if (!rule || !Array.isArray(rule.from) || !rule.from.length || !Array.isArray(rule.roles) || !rule.roles.length || typeof rule.to !== 'string' || !rule.to) throw new TypeError('Transitions require from, roles and to');
+    rules[action] = copy(rule);
+  }
+  const stamp = () => new Date().toISOString();
+  async function save(job, next, type, actor, data = {}) {
+    next.version = job.version + 1; next.updated_at = stamp();
+    next.events.push({ sequence: next.events.length + 1, type, actor_id: actor, at: next.updated_at, data: copy(data) });
+    if (!await store.compareAndSet(job.id, job.version, next)) error('CONFLICT', 'Reload and retry', 409);
+    return next;
+  }
+  async function get(id, actor) {
+    identifier(id); identifier(actor);
+    const job = await store.get(id);
+    if (!job || !Object.values(job.participants).includes(actor)) error('NOT_FOUND', 'Job not found', 404);
+    return copy(job);
+  }
+  async function allowed(job, action, actor, input, rule) {
+    if (!rule.roles.some(role => job.participants[role] === actor)) error('FORBIDDEN', 'Actor cannot perform this action', 403);
+    if (authorize && await authorize({ job: copy(job), action, actor, input: copy(input) }) !== true) error('FORBIDDEN', 'Application policy rejected action', 403);
+  }
+  async function complete(job, result) {
+    const pending = job.pending;
+    if (!result || !['confirmed', 'pending', 'rejected'].includes(result.status)) error('INVALID_ADAPTER_RESULT', 'Adapter must return confirmed, pending or rejected', 502);
+    canonical(result);
+    if (result.status === 'pending') {
+      const next = copy(job); next.pending.observation = copy(result);
+      return save(job, next, pending.action + '.pending', pending.actor, result);
+    }
+    if (result.status === 'rejected') {
+      const next = copy(job); next.pending = null;
+      next.operations[pending.key] = { request_hash: pending.request_hash, status: 'rejected', result: copy(result) };
+      return save(job, next, pending.action + '.rejected', pending.actor, result);
+    }
+    if (!result.evidence || typeof result.evidence !== 'object' || Array.isArray(result.evidence)) error('INVALID_ADAPTER_RESULT', 'Confirmed effects require structured evidence', 502);
+    const next = copy(job); next.pending = null; next.state = pending.target;
+    next.operations[pending.key] = { request_hash: pending.request_hash, status: 'confirmed', result: copy(result) };
+    next.evidence.push({ action: pending.action, operation_id: pending.id, evidence: copy(result.evidence) });
+    if (pending.action === 'submit') next.submission = copy(pending.input);
+    return save(job, next, pending.action + '.confirmed', pending.actor, result.evidence);
+  }
+  async function execute(job, reconcile = false) {
+    const pending = job.pending;
+    const adapter = adapters[pending.action];
+    const fn = reconcile ? adapter?.reconcile : (typeof adapter === 'function' ? adapter : adapter?.execute);
+    if (typeof fn !== 'function') error('ADAPTER_REQUIRED', `Configure ${pending.action}${reconcile ? '.reconcile' : ''}`, 501);
+    // Persisted idempotency key is reused even after crashes. Adapters must deduplicate durably.
+    const result = await fn({ job: copy(job), input: copy(pending.input), operation: copy(pending) });
+    return complete(job, result);
+  }
+  return {
+    async create({ id = randomUUID(), participants, metadata = {} }, actor) {
+      identifier(id); identifier(actor);
+      if (!participants || !participants.requester || !participants.worker || !participants.verifier) throw new TypeError('Supply requester, worker and verifier participants');
+      Object.values(participants).forEach(identifier);
+      if (participants.requester === participants.worker || actor !== participants.requester) error('FORBIDDEN', 'Requester must create the job and differ from worker', 403);
+      canonical(metadata); canonical(participants);
+      const at = stamp();
+      const job = { id, protocol: 'a423.workflow.v1', version: 1, state: 'draft', participants: copy(participants), metadata: copy(metadata), agreement: null, submission: null, pending: null, operations: {}, evidence: [], events: [{ sequence: 1, type: 'created', actor_id: actor, at, data: {} }], created_at: at, updated_at: at };
+      if (authorize && await authorize({ job: copy(job), action: 'create', actor, input: {} }) !== true) error('FORBIDDEN', 'Application policy rejected creation', 403);
+      if (!await store.create(job)) error('CONFLICT', 'Job ID already exists');
+      return copy(job);
+    },
+    get,
+    async act(id, action, input, { actor, idempotencyKey } = {}) {
+      identifier(actor); identifier(idempotencyKey); identifier(action); canonical(input);
+      let job = await get(id, actor);
+      const rule = rules[action];
+      if (!rule) error('UNKNOWN_ACTION', 'Unknown workflow action', 400);
+      await allowed(job, action, actor, input, rule);
+      const key = digest([actor, idempotencyKey]);
+      const requestHash = digest([action, input]);
+      if (Object.hasOwn(job.operations, key)) {
+        if (job.operations[key].request_hash !== requestHash) error('IDEMPOTENCY_CONFLICT', 'Key used for another request');
+        return job;
+      }
+      if (job.pending) {
+        if (job.pending.key !== key || job.pending.request_hash !== requestHash) error('OPERATION_PENDING', 'Reconcile or retry the pending operation first');
+        return execute(job);
+      }
+      if (!rule.from.includes(job.state)) error('INVALID_STATE', `Cannot ${action} from ${job.state}`);
+      let next = copy(job);
+      if (action === 'quote') {
+        if (!input || !input.terms || typeof input.terms !== 'object' || Array.isArray(input.terms)) error('INVALID_INPUT', 'Supply a terms object', 400);
+        if (validateTerms) await validateTerms(copy(input.terms));
+        next.agreement = { revision: (job.agreement?.revision || 0) + 1, terms: copy(input.terms), hash: hashAgreement(input.terms), accepted_by: [] };
+      }
+      if (action === 'accept') {
+        if (!input || input.agreement_hash !== job.agreement.hash || input.revision !== job.agreement.revision) error('AGREEMENT_MISMATCH', 'Accept the current agreement hash and revision');
+        next.agreement.accepted_by = [...new Set([...job.agreement.accepted_by, actor])];
+      }
+      if (rule.effect) {
+        if (!adapters[action]) error('ADAPTER_REQUIRED', `Configure ${action} adapter`, 501);
+        next.pending = { id: `a423:${id}:${key}`, key, action, actor, input: copy(input), request_hash: requestHash, target: rule.to, created_at: stamp(), observation: null };
+        job = await save(job, next, action + '.requested', actor);
+        return execute(job);
+      }
+      next.state = action === 'accept' && [job.participants.requester, job.participants.worker].every(p => next.agreement.accepted_by.includes(p)) ? 'accepted' : rule.to;
+      next.operations[key] = { request_hash: requestHash, status: 'confirmed', result: { status: 'confirmed' } };
+      return save(job, next, action, actor, input);
+    },
+    async reconcile(id, actor) {
+      const job = await get(id, actor);
+      if (!job.pending) return job;
+      await allowed(job, job.pending.action, actor, job.pending.input, rules[job.pending.action]);
+      return execute(job, true);
+    },
+    async receipts(id, actor) {
+      const job = await get(id, actor);
+      return { protocol: job.protocol, job_id: id, state: job.state, agreement: job.agreement, submission: job.submission, evidence: job.evidence, events: job.events, pending: job.pending };
+    }
+  };
+}
+function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423', maxBodyBytes = 65536, onError } = {}) {
+  if (!workflow || typeof authenticate !== 'function' || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(basePath)) throw new TypeError('Supply workflow, authenticate and valid basePath');
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || maxBodyBytes > 1048576) throw new TypeError('Invalid maxBodyBytes');
+  const respond = (value, status = 200) => Response.json(value, { status, headers: { 'cache-control': 'no-store' } });
+  return async request => {
+    try {
+      const path = new URL(request.url).pathname;
+      if (!path.startsWith(basePath + '/')) error('NOT_FOUND', 'Route not found', 404);
+      const match = /^\/jobs(?:\/([A-Za-z0-9_-]{1,128})(?:\/(actions|reconcile|receipts))?)?$/.exec(path.slice(basePath.length));
+      if (!match) error('NOT_FOUND', 'Route not found', 404);
+      const [, id, action] = match;
+      const method = !id || action === 'actions' || action === 'reconcile' ? 'POST' : 'GET';
+      if (request.method !== method) { const r = respond({ error: { code: 'METHOD_NOT_ALLOWED', message: `Use ${method}` } }, 405); r.headers.set('allow', method); return r; }
+      const actor = await authenticate(request);
+      if (!actor) error('UNAUTHENTICATED', 'Authentication required', 401);
+      let body;
+      if (method === 'POST') {
+        if (!(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) error('INVALID_INPUT', 'Use application/json', 415);
+        const reader = request.body?.getReader(); if (!reader) error('INVALID_INPUT', 'JSON body required', 400);
+        let size = 0; const chunks = [];
+        try { while (true) { const { done, value } = await reader.read(); if (done) break; size += value.byteLength; if (size > maxBodyBytes) { await reader.cancel(); error('BODY_TOO_LARGE', 'Body too large', 413); } chunks.push(Buffer.from(value)); } } finally { reader.releaseLock(); }
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { error('INVALID_INPUT', 'Invalid JSON', 400); }
+      }
+      if (!id) return respond({ job: await workflow.create(body, actor) }, 201);
+      if (action === 'actions') return respond({ job: await workflow.act(id, body.action, body.input ?? {}, { actor, idempotencyKey: request.headers.get('idempotency-key') }) });
+      if (action === 'reconcile') return respond({ job: await workflow.reconcile(id, actor) });
+      if (action === 'receipts') return respond(await workflow.receipts(id, actor));
+      return respond({ job: await workflow.get(id, actor) });
+    } catch (err) {
+      if (err instanceof A423Error) return respond({ error: { code: err.code, message: err.message } }, err.status);
+      if (err instanceof TypeError) return respond({ error: { code: 'INVALID_INPUT', message: 'Invalid workflow input' } }, 400);
+      if (onError) { try { await onError(err); } catch {} }
+      return respond({ error: { code: 'INTERNAL_ERROR', message: 'Workflow operation failed; inspect and reconcile pending operations' } }, 500);
+    }
+  };
+}
+module.exports = { createWorkflow, createWorkflowHandler, hashAgreement };
+
+function createWorkflowClient({ baseUrl, headers, fetch: fetchImpl = globalThis.fetch, timeoutMs = 30000 } = {}) {
+  const url = new URL(baseUrl);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || typeof fetchImpl !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new TypeError('Invalid client options');
+  const base = url.href.replace(/\/$/, '');
+  async function request(path, body, key) {
+    const h = new Headers(typeof headers === 'function' ? await headers() : headers);
+    h.set('accept', 'application/json');
+    if (body !== undefined) h.set('content-type', 'application/json');
+    if (key !== undefined) h.set('idempotency-key', identifier(key));
+    const response = await fetchImpl(base + path, { method: body === undefined ? 'GET' : 'POST', headers: h, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+    const reader = response.body?.getReader(); if (!reader) error('INVALID_RESPONSE', 'Missing response body', 502);
+    const chunks = []; let size = 0;
+    try { while (true) { const {done,value} = await reader.read(); if(done) break; size += value.byteLength; if(size > 1048576) { await reader.cancel(); error('INVALID_RESPONSE','Response exceeds 1 MiB',502); } chunks.push(Buffer.from(value)); } } finally { reader.releaseLock(); }
+    let data; try { data=JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { error('INVALID_RESPONSE','Invalid JSON response',502); }
+    if (!response.ok) error(data.error?.code || 'HTTP_ERROR',data.error?.message || 'Request failed',response.status);
+    return data;
+  }
+  const path = id => '/jobs/' + identifier(id);
+  return {
+    async create(input) { return (await request('/jobs',input)).job; },
+    async get(id) { return (await request(path(id))).job; },
+    async act(id,action,input,{idempotencyKey}={}) { identifier(action);identifier(idempotencyKey);return (await request(path(id)+'/actions',{action,input},idempotencyKey)).job; },
+    async reconcile(id) { return (await request(path(id)+'/reconcile',{})).job; },
+    async receipts(id) { return request(path(id)+'/receipts'); }
+  };
+}
+module.exports.createWorkflowClient = createWorkflowClient;

package/src/workflow.d.ts

@@ -0,0 +1,57 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export interface Agreement { revision: number; terms: { [key: string]: Json }; hash: string; accepted_by: string[] }
+export interface Operation { id: string; key: string; action: string; actor: string; input: Json; request_hash: string; target: string; created_at: string; observation: AdapterResult | null }
+export interface AdapterResult { status: 'pending' | 'confirmed' | 'rejected'; evidence?: { [key: string]: Json }; [key: string]: Json | undefined }
+export interface WorkflowJob {
+  id: string; protocol: 'a423.workflow.v1'; version: number; state: string;
+  participants: { requester: string; worker: string; verifier: string; [role: string]: string };
+  metadata: Json; agreement: Agreement | null; submission: Json;
+  pending: Operation | null;
+  operations: Record<string, { request_hash: string; status: string; result: AdapterResult }>;
+  evidence: Array<{ action: string; operation_id: string; evidence: { [key: string]: Json } }>;
+  events: Array<{ sequence: number; type: string; actor_id: string; at: string; data: Json }>;
+  created_at: string; updated_at: string;
+}
+export interface WorkflowStore {
+  get(id: string): Promise<WorkflowJob | null>;
+  create(job: WorkflowJob): Promise<boolean>;
+  compareAndSet(id: string, expectedVersion: number, job: WorkflowJob): Promise<boolean>;
+}
+export interface AdapterContext { job: WorkflowJob; input: Json; operation: Operation }
+export type Effect = (context: AdapterContext) => Promise<AdapterResult>;
+export interface Transition { from: string[]; roles: string[]; to: string; effect?: boolean }
+export interface WorkflowOptions {
+  store: WorkflowStore;
+  adapters?: Record<string, Effect | { execute: Effect; reconcile?: Effect }>;
+  /** Return true to allow; authenticated actor ID must be supplied by your application. */
+  authorize?(context: { job: WorkflowJob; action: string; actor: string; input: Json }): boolean | Promise<boolean>;
+  /** Throw to reject application-specific terms. */
+  validateTerms?(terms: { [key: string]: Json }): void | Promise<void>;
+  /** Explicit overrides replace the full rule; application is responsible for its invariants. */
+  transitions?: Record<string, Transition>;
+}
+export interface Workflow {
+  create(input: { id?: string; participants: WorkflowJob['participants']; metadata?: Json }, actor: string): Promise<WorkflowJob>;
+  get(id: string, actor: string): Promise<WorkflowJob>;
+  act(id: string, action: string, input: Json, options: { actor: string; idempotencyKey: string }): Promise<WorkflowJob>;
+  reconcile(id: string, actor: string): Promise<WorkflowJob>;
+  receipts(id: string, actor: string): Promise<Pick<WorkflowJob, 'protocol' | 'state' | 'agreement' | 'submission' | 'evidence' | 'events' | 'pending'> & { job_id: string }>;
+}
+export function hashAgreement(terms: Json): string;
+export function createWorkflow(options: WorkflowOptions): Workflow;
+export function createWorkflowHandler(options: {
+  workflow: Workflow; authenticate(request: Request): string | null | Promise<string | null>;
+  basePath?: string; maxBodyBytes?: number; onError?(error: unknown): void | Promise<void>;
+}): (request: Request) => Promise<Response>;
+export interface WorkflowClient {
+  /** Supply a stable id so creation retries can be resolved with get(id). */
+  create(input: Parameters<Workflow['create']>[0]): Promise<WorkflowJob>;
+  get(id: string): Promise<WorkflowJob>;
+  act(id: string, action: string, input: Json, options: { idempotencyKey: string }): Promise<WorkflowJob>;
+  reconcile(id: string): Promise<WorkflowJob>;
+  receipts(id: string): ReturnType<Workflow['receipts']>;
+}
+export function createWorkflowClient(options: {
+  baseUrl: string; headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  fetch?: typeof globalThis.fetch; timeoutMs?: number;
+}): WorkflowClient;

package/src/workflow.mjs

@@ -0,0 +1,2 @@
+import workflow from './workflow.cjs';
+export const { createWorkflow, createWorkflowHandler, createWorkflowClient, hashAgreement } = workflow;