@allorc/a423-sdk 0.0.0-stage → 0.1.0

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,245 @@
-# Temporary Holding Version
+# @allorc/a423-sdk
 
-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.
+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,53 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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"
+    }
+  },
+  "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"
+  ],
+  "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;