Write testing
Status: DRAFT test design. Artifact checks validate contracts, schemas, links, and examples; they do not establish deployed Write behaviour.
Verification boundary
Section titled “Verification boundary”The repository validator can check requirement structure, local references, operation identifiers, the unified OpenAPI schema, example validity, and declared identity and version handoffs across combined Read and Write fixtures. It cannot prove current authorisation, commit atomicity, strong preconditions, idempotent replay, protected existence, workflow separation, source behaviour, concurrency, or crash recovery in a deployment.
The cases below are normative verification targets for the selected DRAFT options. Their runtime status is pending implementation conformance test unless a future evidence record identifies the implementation, version, environment, fixtures, requests, responses, source observations, and result. Schema-valid examples are not recorded as runtime passes.
Applicability and fixtures
Section titled “Applicability and fixtures”Before executing a runtime case, record:
- the specification and contract version, selected Write options, Registry, Collection, and operation grants;
- the implementation and deployment version, service metadata, source arrangement, and declared component boundary;
- synthetic permitted, denied, unknown, protected, stale, conflicting, and concurrently changed fixtures;
- the trusted actor and purpose contexts, with secrets and personal data excluded from retained evidence;
- the idempotency retention, precondition mechanism, audit scope, request-list bounds, and, where asynchronous execution is offered, Operation retention; and
- which optional facilities are offered, including preview, withdrawal, request listing, asynchronous processing, and separately declared compound guarantees.
An inapplicable optional facility is recorded as not applicable with its contract basis. It is not counted as a pass and does not weaken another applicable requirement.
Requirement traceability
Section titled “Requirement traceability”Pending runtime case matrix
Section titled “Pending runtime case matrix”| Case | Boundary under test | Required observation | Runtime status |
|---|---|---|---|
| Create commit | Direct Create and source | Acknowledgement, authoritative Record, source write count, and audit correlation agree. | Pending implementation conformance test. |
| Update conflict | Direct Update and source | Two writers using one starting guard produce one commit and one explicit stale-precondition outcome. | Pending implementation conformance test. |
| Transition conflict | Direct Transition and source policy | Invalid source state and a losing concurrent transition produce no authoritative effect. | Pending implementation conformance test. |
| Synchronous-only Write | Selected direct and governed operations | Selected operations declare no 202 outcome, no Operation resource is required, and synchronous success is returned only after the declared commit or request creation completes. | Pending implementation conformance test. |
| Submit request | Change Request intake | 201 identifies one immutable non-authoritative request and the Registry Record remains unchanged. A pending review creates no Operation merely because review will happen later. | Pending implementation conformance test. |
| Approve request | Review decision and optional triggered application | Review-only approval returns the Change Request, such as 200 approved with application not started. Where the review operation also triggers background application, 202 identifies a separate Operation while the Change Request retains the review and application state. | Pending implementation conformance test. |
| Apply request | Application and source | A separate authorised application rechecks current conditions and alone produces the authoritative effect. | Pending implementation conformance test. |
| Rejected or withdrawn request | Workflow and source | Rejection, and withdrawal where offered, cannot mutate authoritative state or be applied later. | Pending implementation conformance test. |
| Permission change after approval | Workflow and current policy | Revoked application permission produces an unapplied outcome without weakening the decision record. | Pending implementation conformance test. |
| Source change after approval | Workflow and source precondition | A stale approved proposal fails at commit and does not overwrite the intervening source change. | Pending implementation conformance test. |
| Idempotent replay after response loss | Client, service, and source | Same actor, key, and content recover one result and one effect. | Pending implementation conformance test. |
| Idempotency mismatch | Client and service | Reuse under changed content, target, actor, operation, or purpose fails explicitly. | Pending implementation conformance test. |
| Crash before commit | Service and source | Recovery exposes no authoritative effect and no false committed acknowledgement. | Pending implementation conformance test. |
| Crash after commit before response | Service and source | Retry recovers the durable committed result without a second effect. | Pending implementation conformance test. |
| Crash during asynchronous work | Operation worker and source, where offered | Operation status reaches one honest terminal outcome and correlates with authoritative state without replacing the Change Request’s review or application state. | Pending implementation conformance test. |
| Protected-resource comparison | Access policy and protocol | Unknown and protected fixtures remain indistinguishable at the declared generic 404 boundary. | Pending implementation conformance test. |
| Preview followed by source change | Preview and commit | Preview has no side effect, and commit uses current source and policy rather than previewed assumptions. | Pending implementation conformance test. |
| Request-list source change | Listing and request store | Results follow declared live consistency and bounds without an undeclared exhaustive or snapshot guarantee. | Pending implementation conformance test. |
| Declared compound failure | Write component and declared external components | Every claimed compound guarantee holds at each injected boundary, or the service reports the declared non-atomic outcome. | Pending implementation conformance test. |
Runtime companion-guard procedure
Section titled “Runtime companion-guard procedure”Use this procedure for every selected Update and Transition companion read. Record the Registry, Collection, target Record, mutation operation, companion operation and view, declared companion-currency condition, and the effective authorisation and disclosure, purpose, and field selection. Use synthetic source fixtures and retain authoritative before-and-after evidence.
- Obtain the permitted companion body and opaque strong ETag from one current
authoritative guard evaluation. Change authoritative state through a second
authorised path, then submit the earlier ETag in
If-Match. If an ordinary read is intentionally lagged, record it separately and do not use its token as companion evidence. The mutation must atomically return the generic412response and leave the intervening authoritative state unchanged. - Obtain a fresh companion body and ETag. Change a source field or condition
that affects this mutation’s validation, mapping, or committed effect but is
not disclosed in the permitted body. Under the identical effective context,
retrieve again and record an equal body with a different opaque ETag. A
mutation using the prior token must return generic
412, disclose neither the changed condition nor a replacement token, and have no authoritative effect. An unrelated hidden change is not required to invalidate the tag. - Perform a successful mutation and retain its success ETag. With no intervening mutation-relevant change, wait until the declared companion currency is satisfied, then retrieve the exact committed guard state under the identical effective context. Only this case may require equality between the success ETag and the later companion ETag. Repeat after changing the effective authorisation or disclosure, purpose, or field selection, and do not infer equality merely because the view name is unchanged.
For each case, retain the exact requests and responses, trusted context record, source setup and observations, authoritative write count, and audit correlation. The repository fixture declares the intended relationships but does not execute this procedure or prove runtime concurrency behaviour.
Artifact checks
Section titled “Artifact checks”Artifact validation should confirm that:
- each Write option resolves its exact primary
operationIdin the unifiedapi/openapi.yamlcontract, whileapi/write.openapi.yamlremains only a compatibility alias; - each SERVICE_API requirement resolves its operation in its own declared contract;
- OpenAPI request and response examples validate against their referenced schemas;
- primary and supporting operations use consistent Registry, Collection, broad Record identity, restricted workflow identity, error, idempotency, precondition, and acknowledgement definitions;
Idempotency-Keyis required for mutation operations and is not imposed on read-only POST Lookup or Search;- Update and Transition identify one companion Retrieve operation and view; fixture-only guard evaluation identifiers keep each request, response, and ETag handoff internally coherent; companion guards declare a current authoritative body-and-ETag evaluation; later equality additionally requires the exact committed guard state, no intervening mutation-relevant change, settled companion currency, and identical effective authorisation and disclosure, purpose, and field selection;
- the conditional journey rejects a lagged companion declaration and includes a hidden mutation-relevant source change whose unchanged permitted body receives a different opaque guard ETag, while the prior token produces generic
412without a replacement ETag; - synchronous Create
Location, returnedcollectionIdandrecordId, responseETag, and bodyetagagree, including deployments with a declared base path and encoded one-segment identifiers; - operation-specific declaration and correction inputs remain typed, every accepted field maps to authoritative state, retained provenance, or workflow-only context, and no check assumes that Write input equals Consultation
Record.data; - caller discovery can describe caller-visible Read, independently granted Write, and supporting workflow operations without treating discovery as authority;
api/examples/combined-journeys.jsoncovers Create then Retrieve, conditional companion Retrieve then Update then companion Retrieve plus stale and hidden-relevant-changeIf-Matchrejections, Transition then companion Retrieve, asynchronous completion then Retrieve, and governed submission and approval with no effect before authoritative application and Retrieve; Operation polling and Change Request review/application retain their original workflow identities and immutable proposal;- local links and all
write-1throughwrite-19anchors resolve; and - non-normative domain examples do not introduce a domain-schema dependency into the shared contract or requirements.
Run uv run python tools/validate_write.py for the command-line artifact gate and uv run python -m unittest tools.test_write for its unit, contract-integration, negative-mutation, and end-to-end artifact regressions.
Passing these checks is artifact evidence only. They validate declared exchanges and handoffs without sending HTTP requests or observing a deployed source, Adapter, workflow worker, or Registry. They do not require one retained history revision for each Write. Record runtime results separately, including failures and not-applicable cases, and do not convert a schema-valid trace into an implementation pass.
Unofficial preview · 3.0.0-alpha.2 · Source revision 2350fdf8.
Content snapshot 5e66af7b9724.