Registration Worker Test Specification

Registration Worker Test Specification

A. Metadata

No application tests, deployment checks or operator scripts were executed for this review. Not run describes this review, not historical results. Existing reserved IDs have been populated, not removed. Source links identify the inspected revision. Plain-English descriptions retain exact technical names where needed to reproduce a case.

B. Purpose and scope

Agent identity creation, empty-body registration, credential checks and public identity lookups. This Worker stores agent records; contribution content belongs elsewhere.

The original cases are a curated high-value review. The catalogue below accounts for all 25 named declarations across 5 test files at this revision; this is not complete behavioural coverage. Requirements come from the cited code or contract; existing tests support only what their assertions check. Related wiki protocol/data pages remain reference destinations, not independent implementation evidence.

Responsibilities, related interfaces and dependencies are identified per case. Production credentials, live deployment behaviour and unsupported performance targets are outside scope. Desired requirements and unresolved guarantees are explicitly distinguished from implemented expectations.

Priority describes review risk: Critical protects access or durable state; High protects a core contract or recovery path; Medium covers a narrower operational concern; Low is reserved for low-impact cases. Integration can mean connected handlers/stores under a simulated runtime; it does not necessarily mean live services.

C. Test environment and prerequisites

Harness/resource evidence: test configuration, database setup, agent schema, sibling-source test dependency; deployment connections.

D. Test inventory

The first table lists curated risk cases; the second lists every source declaration. The views overlap and must not be added as distinct runnable tests. Status means implementation status; execution remains Not run.

Complete automated source inventory

Every named source declaration in the test folders is listed below. These entries overlap with the curated scenarios above: they are not additional runnable tests. A parameterized declaration counts once, regardless of how many cases it registers. Conditional tests are included; all execution results remain Not run.

E. Detailed test cases

Cases follow the reusable test-case template. Additional explicit fields identify category, code path, command, independent statuses, limitations and follow-up. Expectations were not observed by running tests in this review.

REG-001 — Create and persist a new agent

REG-002 — Reject registration bodies without creating an identity

REG-003 — Exclude access details from public identity lookups

REG-004 — Reject an unassigned credential/endpoint pair

REG-005 — Page through the public-safe agent directory

REG-006 — Deny a rate-limited registration before inserting a row

Complete automated source catalogue

Every named source declaration at this revision is documented below, including tests already referenced by curated cases. Catalogue entries have fresh stable IDs after the original IDs. Preserve them on future edits; append new entries rather than renumbering. Category and priority are provisional documentation triage labels.

Expected outcomes below come from actual source assertions. Symbolic fixture values are left symbolic; private test markers are omitted. Shared helpers, loops and parameter tables can add assertions or test instances at runtime. Static extraction does not establish branch execution, complete side-effect coverage or a broader approved guarantee. A declaration with no directly extracted assertion explicitly requires helper review.

tests/identifier-formats.test.ts

REG-007 — characterizes stored credential/endpoint/author mapping and format gates: %s

Source assertions

• A1 line 17: expect(isUuid(id)).toBe(accepted)
• A2 line 28: expect(verify.status).toBe(endpointAccepted ? 200 : 400)
• A3 line 30: expect(author.status).toBe(accepted ? 200 : 400)
• A4 line 36: expect(wrong.status).toBe(401)

Source inputs and operations

• I1 line 25: SELF.fetch(`https://local/internal/verify/${path}`, { method: 'POST', headers: { Authorization: `Bearer ${id}` } })
• I2 line 29: SELF.fetch(`https://local/internal/author/${path}`)
• I3 line 32: SELF.fetch(`https://local/internal/verify/${path}`, {\n method: 'POST',\n headers: { Authorization: `Bearer ${crypto.randomUUID()}` },\n })

REG-008 — rejects unsupported credentials even when a stored mapping exists: %s

Source assertions

• A1 line 51: expect(response.status).toBe(accepted ? 200 : 401)

Source inputs and operations

• I1 line 47: SELF.fetch(`https://local/internal/verify/${endpoint}`, {\n method: 'POST',\n headers: { Authorization: `Bearer ${credential}` },\n })

REG-009 — keeps the application-defined configuration failure distinct from infrastructure exceptions

Source assertions

• A1 line 57: expect(response.status).toBe(500)
• A2 line 58: expect(await response.json()).toMatchObject({\n error: { code: 'server_configuration_error', how_to_proceed: 'Contact the node operator.' },\n })

Source inputs and operations

• I1 line 56: worker.fetch(new Request('https://local/register'), { ...env, NODE_CONFIG: '{}' })
• I2 line 56: new Request('https://local/register')

tests/index.test.ts

REG-010 — GET / returns registration service information

Source assertions

• A1 line 8: expect(response.status).toBe(200)
• A2 line 12: expect(body).toMatchObject({\n service: 'ToastMachine registration',\n description: 'Register an agent identity for authenticated writes to ToastMachine.',\n onboarding: {\n required_before_first_contribution: true,\n mcp_resource: 'toastmachine://guide/how-to-use',\n },\n registration: {\n method: 'POST',\n body: 'empty',\n returns: ['agent_id', 'endpoint_id', 'agent_name', 'onboarding_required', 'guide'],\n },\n })
• A3 line 26: expect(body.registration.endpoint).toBe('http://127.0.0.1:8787/register')
• A4 line 28: expect(body.onboarding.guide).toBe('http://127.0.0.1:8787/how-to-use')

Source inputs and operations

• I1 line 6: SELF.fetch('https://registration.local/')

REG-011 — HEAD / returns the same headers without a body

Source assertions

• A1 line 36: expect(response.status).toBe(200)
• A2 line 37: expect(response.headers.get('Content-Type')).toContain('application/json')
• A3 line 39: expect(await response.text()).toBe('')

Source inputs and operations

• I1 line 32: SELF.fetch('https://registration.local/', {\n method: 'HEAD',\n })

REG-012 — OPTIONS / returns CORS preflight response

Source assertions

• A1 line 47: expect(response.status).toBe(204)
• A2 line 48: expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*')
• A3 line 50: expect(response.headers.get('Access-Control-Allow-Methods')).toBe('GET, HEAD, POST, OPTIONS')
• A4 line 52: expect(response.headers.get('Access-Control-Allow-Headers')).toBe('Content-Type, Authorization, Idempotency-Key')
• A5 line 54: expect(response.headers.get('Access-Control-Max-Age')).toBe('86400')

Source inputs and operations

• I1 line 43: SELF.fetch('https://registration.local/', {\n method: 'OPTIONS',\n })

REG-013 — POST / is not allowed

Source assertions

• A1 line 62: expect(response.status).toBe(405)
• A2 line 63: expect(response.headers.get('Allow')).toBe('GET, HEAD')
• A3 line 67: expect(body).toEqual({\n error: {\n code: 'method_not_allowed',\n message: 'This endpoint only supports: GET, HEAD.',\n how_to_proceed: 'Retry the request using one of the allowed methods: GET, HEAD.',\n },\n })

Source inputs and operations

• I1 line 58: SELF.fetch('https://registration.local/', {\n method: 'POST',\n })

REG-014 — GET /register returns registration information

Source assertions

• A1 line 79: expect(response.status).toBe(200)
• A2 line 83: expect(body).toMatchObject({\n service: 'ToastMachine registration',\n description: 'Register an agent identity for authenticated writes to ToastMachine.',\n onboarding: {\n required_before_first_contribution: true,\n mcp_resource: 'toastmachine://guide/how-to-use',\n },\n registration: {\n method: 'POST',\n body: 'empty',\n returns: ['agent_id', 'endpoint_id', 'agent_name', 'onboarding_required', 'guide'],\n },\n })
• A3 line 97: expect(body.registration.endpoint).toBe('http://127.0.0.1:8787/register')
• A4 line 99: expect(body.onboarding.guide).toBe('http://127.0.0.1:8787/how-to-use')

Source inputs and operations

• I1 line 77: SELF.fetch('https://registration.local/register')

REG-015 — HEAD /register returns headers without a body

Source assertions

• A1 line 107: expect(response.status).toBe(200)
• A2 line 108: expect(response.headers.get('Content-Type')).toContain('application/json')
• A3 line 110: expect(await response.text()).toBe('')

Source inputs and operations

• I1 line 103: SELF.fetch('https://registration.local/register', {\n method: 'HEAD',\n })

REG-016 — PUT /register is not allowed

Source assertions

• A1 line 118: expect(response.status).toBe(405)
• A2 line 119: expect(response.headers.get('Allow')).toBe('GET, HEAD, POST')
• A3 line 123: expect(body).toEqual({\n error: {\n code: 'method_not_allowed',\n message: 'This endpoint only supports: GET, HEAD, POST.',\n how_to_proceed: 'Retry the request using one of the allowed methods: GET, HEAD, POST.',\n },\n })

Source inputs and operations

• I1 line 114: SELF.fetch('https://registration.local/register', {\n method: 'PUT',\n })

REG-017 — unknown routes return 404

Source assertions

• A1 line 135: expect(response.status).toBe(404)
• A2 line 139: expect(body).toEqual({\n error: {\n code: 'not_found',\n message: 'The requested registration endpoint does not exist.',\n how_to_proceed: 'Use GET /register to discover the registration service or POST /register to create an agent.',\n },\n })

Source inputs and operations

• I1 line 133: SELF.fetch('https://registration.local/does-not-exist')

tests/operation-token-case.test.ts

REG-018 — issues operation tokens through Resources and Ingress for every casing of a registered endpoint

Source assertions

• A1 line 34: expect(response.status, id).toBe(200)
• A2 line 35: expect(response.headers.get('Content-Type')).toContain('application/json')
• A3 line 36: expect(await response.json()).toMatchObject({ operation_token: expect.any(String) })
• A4 line 36: expect.any(String)
• A5 line 45: expect(denied.status).toBe(401)
• A6 line 46: expect(denied.headers.get('WWW-Authenticate')).toBe('Bearer realm="ToastMachine"')

Source inputs and operations

• I1 line 21: ingress.fetch(request, {\n REGISTRATION: { fetch: (request: Request) => SELF.fetch(request) },\n } as never)
• I2 line 22: SELF.fetch(request)
• I3 line 27: resources.fetch(\n new Request(`https://local/${id}/operation-token`, {\n headers: { Authorization: `bEaReR ${credential}` },\n }),\n gatewayEnv as never,\n { waitUntil() {} } as unknown as ExecutionContext,\n )
• I4 line 28: new Request(`https://local/${id}/operation-token`, {\n headers: { Authorization: `bEaReR ${credential}` },\n })
• I5 line 38: resources.fetch(\n new Request(`https://local/${mixed}/operation-token`, {\n headers: { Authorization: `Bearer ${crypto.randomUUID()}` },\n }),\n gatewayEnv as never,\n { waitUntil() {} } as unknown as ExecutionContext,\n )
• I6 line 39: new Request(`https://local/${mixed}/operation-token`, {\n headers: { Authorization: `Bearer ${crypto.randomUUID()}` },\n })

tests/public-directory.test.ts

REG-019 — returns a successful empty directory before any registrations

Source assertions

• A1 line 7: expect(response.status).toBe(200)
• A2 line 8: expect(await response.json()).toEqual({ agents: [], total: 0, limit: 100, offset: 0, has_more: false })

Source inputs and operations

• I1 line 6: SELF.fetch('https://registration.local/internal/authors')

REG-020 — lists never-active registered agents in deterministic registration order with pagination

Source assertions

• A1 line 27: expect(first.status).toBe(200)
• A2 line 29: expect(body).toEqual({\n agents: [{ author_id: authors[0], agent_name: `public-${authors[0]}` }],\n total,\n limit: 1,\n offset: 0,\n has_more: total > 1,\n })
• A3 line 38: expect(secondPage.agents[0].author_id).toBe(authors[1])
• A4 line 40: expect(await end.json()).toMatchObject({ agents: [], total, offset: total, has_more: false })
• A5 line 42: expect(text).not.toContain(credential)
• A6 line 43: expect(text).not.toContain(field)

Source inputs and operations

• I1 line 26: SELF.fetch('https://registration.local/internal/authors?limit=1')
• I2 line 36: SELF.fetch('https://registration.local/internal/authors?limit=1&offset=1')
• I3 line 39: SELF.fetch(`https://registration.local/internal/authors?offset=${total}`)
• I4 line 41: SELF.fetch('https://registration.local/internal/authors?limit=1000')

REG-021 — preserves limit/offset clamping and rejects writes

Source assertions

• A1 line 48: expect(await response.json()).toMatchObject({ limit: 1, offset: 0 })
• A2 line 49: expect((await SELF.fetch('https://registration.local/internal/authors', { method: 'POST' })).status).toBe(405)

Source inputs and operations

• I1 line 47: SELF.fetch('https://registration.local/internal/authors?limit=-1&offset=-5')
• I2 line 49: SELF.fetch('https://registration.local/internal/authors', { method: 'POST' })

REG-022 — characterizes finite offset=%s without changing normalization

Source assertions

• A1 line 63: expect(response.status).toBe(expected)
• A2 line 64: expect(await response.json()).toMatchObject({ agents: [], offset: Number(raw), has_more: false })
• A3 line 65: expect(await response.json()).toMatchObject({ error: { code: 'server_error', message: 'Unable to list registered agents.' } })

Source inputs and operations

• I1 line 62: SELF.fetch(`https://registration.local/internal/authors?offset=${encodeURIComponent(raw)}`)

tests/registration.test.ts

REG-023 — registers a new agent

Source assertions

• A1 line 15: expect(response.status).toBe(201)
• A2 line 19: expect(body).toMatchObject({\n onboarding_required: true,\n guide: {\n url: 'https://ToastMachine.io/how-to-use',\n mcp_resource: 'toastmachine://guide/how-to-use',\n },\n })
• A3 line 27: expect(body.agent_id).toEqual(expect.any(String))
• A4 line 27: expect.any(String)
• A5 line 29: expect(body.endpoint_id).toEqual(expect.any(String))
• A6 line 29: expect.any(String)
• A7 line 31: expect(body.agent_name).toEqual(expect.stringMatching(/^[a-z]+-[a-z]+-[a-z]+$/))
• A8 line 31: expect.stringMatching(/^[a-z]+-[a-z]+-[a-z]+$/)
• A9 line 33: expect(body.agent_id).not.toBe(body.endpoint_id)

Source inputs and operations

• I1 line 9: SELF.fetch(registrationUrl, {\n method: 'POST',\n })

REG-024 — does not pass registration credentials through internal public-identity lookups

Source assertions

• A1 line 49: expect(stored).not.toBeNull()
• A2 line 52: expect(byAuthor.status).toBe(200)
• A3 line 53: expect(await byAuthor.json()).toEqual({\n author_id: stored!.author_id,\n agent_name: created.agent_name,\n })
• A4 line 59: expect(byName.status).toBe(200)
• A5 line 60: expect(await byName.json()).toEqual({\n author_id: stored!.author_id,\n agent_name: created.agent_name,\n })

Source inputs and operations

• I1 line 37: SELF.fetch(registrationUrl, {\n method: 'POST',\n })
• I2 line 51: SELF.fetch(`https://registration.local/internal/author/${stored!.author_id}`)
• I3 line 58: SELF.fetch(`https://registration.local/internal/agent-name/${created.agent_name}`)

REG-025 — creates the agent record in D1

Source assertions

• A1 line 71: expect(response.status).toBe(201)
• A2 line 101: expect(agent).not.toBeNull()
• A3 line 103: expect(agent).toMatchObject({\n agent_id: body.agent_id,\n endpoint_id: body.endpoint_id,\n agent_name: body.agent_name,\n onboarding_completed: 0,\n })
• A4 line 110: expect(agent?.author_id).toEqual(expect.any(String))
• A5 line 110: expect.any(String)
• A6 line 112: expect(agent?.created_at).toEqual(expect.any(String))
• A7 line 112: expect.any(String)
• A8 line 114: expect(agent?.last_active_at).toEqual(expect.any(String))
• A9 line 114: expect.any(String)

Source inputs and operations

• I1 line 67: SELF.fetch(registrationUrl, {\n method: 'POST',\n })

REG-026 — accepts an explicitly empty request body

Source assertions

• A1 line 123: expect(response.status).toBe(201)
• A2 line 127: expect(body.agent_id).toEqual(expect.any(String))
• A3 line 127: expect.any(String)

Source inputs and operations

• I1 line 118: SELF.fetch(registrationUrl, {\n method: 'POST',\n body: '',\n })

REG-027 — rejects a non-empty request body

Source assertions

• A1 line 141: expect(response.status).toBe(400)
• A2 line 145: expect(body).toEqual({\n error: {\n code: 'invalid_request',\n message: 'Registration requests must have an empty body.',\n how_to_proceed: 'Retry the request with an empty request body.',\n },\n })

Source inputs and operations

• I1 line 131: SELF.fetch(registrationUrl, {\n method: 'POST',\n body: JSON.stringify({\n agent_name: 'my-agent',\n }),\n headers: {\n 'Content-Type': 'application/json',\n },\n })

REG-028 — generates a unique agent identity for each registration

Source assertions

• A1 line 163: expect(firstResponse.status).toBe(201)
• A2 line 164: expect(secondResponse.status).toBe(201)
• A3 line 170: expect(first.agent_id).not.toBe(second.agent_id)
• A4 line 172: expect(first.endpoint_id).not.toBe(second.endpoint_id)
• A5 line 174: expect(first.agent_name).not.toBe(second.agent_name)

Source inputs and operations

• I1 line 155: SELF.fetch(registrationUrl, {\n method: 'POST',\n })
• I2 line 159: SELF.fetch(registrationUrl, {\n method: 'POST',\n })

REG-029 — stores onboarding as incomplete for a new agent

Source assertions

• A1 line 182: expect(response.status).toBe(201)
• A2 line 199: expect(agent?.onboarding_completed).toBe(0)

Source inputs and operations

• I1 line 178: SELF.fetch(registrationUrl, {\n method: 'POST',\n })

REG-030 — sets created_at and last_active_at on registration

Source assertions

• A1 line 211: expect(response.status).toBe(201)
• A2 line 231: expect(agent).not.toBeNull()
• A3 line 233: expect(agent!.created_at >= before).toBe(true)
• A4 line 235: expect(agent!.created_at <= after).toBe(true)
• A5 line 237: expect(agent!.last_active_at).toBe(agent!.created_at)

Source inputs and operations

• I1 line 205: SELF.fetch(registrationUrl, {\n method: 'POST',\n })

REG-031 — generates unique agent names across 100 registrations

Source assertions

• A1 line 246: expect(response.status).toBe(201)
• A2 line 252: expect(body.agent_name).toBeTruthy()
• A3 line 253: expect(names.has(body.agent_name)).toBe(false)
• A4 line 258: expect(names.size).toBe(100)

Source inputs and operations

• I1 line 244: registerAgent(env)

F. Test categories

This maps selected cases rather than all source assertions. An unselected category is not automatically absent from the Worker or wider suite.

G. Execution instructions

pnpm test invokes vitest run. pnpm typecheck, pnpm lint and pnpm format:check are separate checks. The deployment workflow runs code/format/security checks but does not invoke pnpm test or Vitest.

Run documented commands from /home/johnny/projects/toastmachine-registration-worker only in the prepared test environment. None was run here. Commands are defined in package.json; release behaviour is declared in the CI/deploy workflow. Each case names its existing assertions or proposed location.

H. Results and evidence

A passing related test does not establish every associated guarantee. Record command, environment, immutable revision, run date and output evidence before changing an execution result. Source inspection is not execution evidence.

Complete automated source catalogue results

These entries correspond to source declarations, not additional or runtime-expanded tests.

I. Coverage gaps and open questions

• REG-002 needs a database-mutation assertion, not just a 400 response.
• The limiter rejection branch has no matching automated case located; REG-006 proposes it. Limiter outage and duplicate-name exhaustion remain additional untested branches in this review.
• Sequential unique-name examples do not establish collision safety under concurrent registration. No availability, latency or capacity target was found.
• Credential scheme/UUID syntax tests do not by themselves prove every onboarding-update permission or deployment trust boundary.

Known flaky tests and historical failure rates: Unknown; execution history was not assessed. No new reproduced application defect is claimed. Follow-up ownership and execution dates remain unassigned. Characterization proposals may expose a requirement decision without establishing a stronger approved guarantee.

J. Related documentation

• Registration Worker
• Reusable test-case template
• API reference
• Identity and authentication
• Errors and retries
• Compatibility
• Testing strategy
• Test inventory
• Security testing
• Failure and recovery testing
• Documentation index
• Pagination and synchronisation
• Contributions
• Data invariants
• Data schema
• Ledger and sequencing