Skip to content

Write testing

Status: DRAFT test design. Artifact checks validate contracts, schemas, links, and examples; they do not establish deployed Write behaviour.

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.

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 anchorApplies whenExerciseExpected evidence
write-1Create selectedSubmit valid, invalid, denied, duplicate, and concurrently conflicting Create inputs through every declared synchronous and asynchronous path.One valid authorised attempt reaches one complete authoritative Record. Each acknowledgement honestly identifies committed or asynchronous status. Rejections and failed work create no Record or partial component.
write-2Update selectedUpdate permitted and forbidden fields with matching, omitted, malformed, and stale preconditions, including two concurrent writers and every declared asynchronous path.Only a currently authorised, valid input with a matching commit-time guard changes the declared fields atomically. Accepted work is not reported as committed, and no intervening change is overwritten.
write-3Transition selectedApply every declared transition from valid and invalid source states, then submit an undeclared transition and concurrent attempts through every declared asynchronous path.Only a permitted transition from its declared current state commits atomically. Accepted work is not reported as committed, and invalid, undeclared, stale, and losing concurrent attempts have no authoritative effect.
write-4Change Requests selectedSubmit valid, invalid, denied, duplicate, and conflicting proposals for each supported proposal kind.Submission creates one immutable non-authoritative request and no authoritative Record change. Review and application remain separately governed.
write-5Any Write option selectedResolve every selected operation from metadata and inspect its typed input, result, Registry, Collection, grant, and mapping into authoritative state or retained provenance. Exercise declaration, correction, evidence, and reason fields where supported.Declarations are machine-readable, versioned, unambiguous, mutually consistent, and complete for every accepted input. Write input need not equal a Consultation view, and publication does not grant authority.
write-6Any Write option selectedInject failures before validation, persistence, commit, acknowledgement, and each separately declared integration boundary.The operation’s own component is all or nothing. Cross-component atomicity passes only where separately declared and exercised.
write-7Any Write option selectedReplay the same key before, during, and after commit; change content, operation, target, actor, purpose, permissions, and retention state.One bound request causes at most one committed effect. Mismatched reuse conflicts, current policy is rechecked, and key expiry creates no false retry guarantee.
write-8Update, Transition, or Change Requests selectedExercise omitted, malformed, matching, and stale guards; race two writers; change a target after request approval.The strong target guard is evaluated atomically at commit. At most one competing attempt commits, without requiring published history.
write-9Any Write option selectedUse read-only, Write-only, combined, and unprivileged actors across operations and targets; where purpose is enforced, vary trusted purpose context.Read and Write permissions remain independent. Every selected grant and target is checked, and only a declared trusted purpose binding supplies purpose.
write-10Any Write option selectedInject actor, reviewer, purpose, approved, applied, and equivalent control fields and flags at every accepted nesting level.Published schema handling is explicit, and no client field bypasses trusted authentication, authorisation, review, or application controls.
write-11Any Write option selectedCorrelate body-bearing and bodyless success, rejection, replay, asynchronous work, review, and failure before and after commit across protocol responses, state, and audit evidence.Status, schema, request URI, Location, or validator identifies the target, created resource, or Operation as declared and distinguishes committed, non-authoritative, and asynchronous outcomes. Correlation and provenance cover the declared scope without an invented response body, correlation identifier, or timestamp.
write-12Protected existence appliesCompare unknown and protected Records, Collections, requests, Operations, and operation availability under the same caller context.Each pair receives the same generic 404 security outcome without resource-specific content or distinguishable workflow, count, or continuation information.
write-13Preview or validation is offeredPreview valid and invalid changes, alter source state and permissions, then attempt the Write.Preview is read-only and visibly non-authoritative, allocates no authoritative identity, advances no workflow, and grants no later commit right.
write-14Change Requests selectedChange proposal content, target, source guard, version, submitter context, and digest before and after a decision; replay the decision elsewhere.Review and decisions remain bound to the exact immutable request version and content. Altered or cross-request application fails without authoritative effect.
write-15Change Requests selectedObserve authoritative state while a request is pending, rejected, approved without application, approved with triggered application where offered, processing, applied successfully, blocked, or failed; include withdrawal where offered.Pending, rejected, and supported withdrawn states have no authoritative effect. Decision and application outcomes remain distinct even in one response, and only successful application changes state.
write-16Change Requests selectedExercise submit-only, review-only, apply-only, combined, and denied actors at every workflow stage.Submission, review, and application each evaluate their own permission and trusted actor context. No stage or approval silently grants another.
write-17Change Requests selectedAfter approval, revoke permission, change purpose, protect or remove the target, change source state, invalidate input, and change transition policy.Application rechecks every current condition atomically with commit. Failure records an explicit unapplied outcome and leaves authoritative state unchanged.
write-18Any Write option selectedExercise a synchronous-only deployment without 202 or getOperation; synchronous creation and commit; Change Request submission awaiting review; review-only approval; and, where offered, asynchronous acceptance, processing success and failure, and Operation expiry.Synchronous-only Write needs no Operation resource. 201 identifies a created Record or Change Request. A pending review is not background work. Review-only approval uses the declared Change Request response, such as 200 approved with application not started. 202 identifies retrievable execution work and never substitutes for review state or implies commit, approval, or application.
write-19Change Request listing offeredTraverse zero, one, and multiple Pages; change bound context and permissions; tamper with and expire cursors; exercise limits, timeout, protected-only matches, and source changes.Pages are permitted, deterministic, bounded, advancing, reauthorised, and explicit at termination. Invalid continuation never restarts or discloses protected requests.
CaseBoundary under testRequired observationRuntime status
Create commitDirect Create and sourceAcknowledgement, authoritative Record, source write count, and audit correlation agree.Pending implementation conformance test.
Update conflictDirect Update and sourceTwo writers using one starting guard produce one commit and one explicit stale-precondition outcome.Pending implementation conformance test.
Transition conflictDirect Transition and source policyInvalid source state and a losing concurrent transition produce no authoritative effect.Pending implementation conformance test.
Synchronous-only WriteSelected direct and governed operationsSelected 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 requestChange Request intake201 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 requestReview decision and optional triggered applicationReview-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 requestApplication and sourceA separate authorised application rechecks current conditions and alone produces the authoritative effect.Pending implementation conformance test.
Rejected or withdrawn requestWorkflow and sourceRejection, and withdrawal where offered, cannot mutate authoritative state or be applied later.Pending implementation conformance test.
Permission change after approvalWorkflow and current policyRevoked application permission produces an unapplied outcome without weakening the decision record.Pending implementation conformance test.
Source change after approvalWorkflow and source preconditionA stale approved proposal fails at commit and does not overwrite the intervening source change.Pending implementation conformance test.
Idempotent replay after response lossClient, service, and sourceSame actor, key, and content recover one result and one effect.Pending implementation conformance test.
Idempotency mismatchClient and serviceReuse under changed content, target, actor, operation, or purpose fails explicitly.Pending implementation conformance test.
Crash before commitService and sourceRecovery exposes no authoritative effect and no false committed acknowledgement.Pending implementation conformance test.
Crash after commit before responseService and sourceRetry recovers the durable committed result without a second effect.Pending implementation conformance test.
Crash during asynchronous workOperation worker and source, where offeredOperation 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 comparisonAccess policy and protocolUnknown and protected fixtures remain indistinguishable at the declared generic 404 boundary.Pending implementation conformance test.
Preview followed by source changePreview and commitPreview has no side effect, and commit uses current source and policy rather than previewed assumptions.Pending implementation conformance test.
Request-list source changeListing and request storeResults follow declared live consistency and bounds without an undeclared exhaustive or snapshot guarantee.Pending implementation conformance test.
Declared compound failureWrite component and declared external componentsEvery claimed compound guarantee holds at each injected boundary, or the service reports the declared non-atomic outcome.Pending implementation conformance test.

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.

  1. 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 generic 412 response and leave the intervening authoritative state unchanged.
  2. 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.
  3. 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 validation should confirm that:

  • each Write option resolves its exact primary operationId in the unified api/openapi.yaml contract, while api/write.openapi.yaml remains 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-Key is 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 412 without a replacement ETag;
  • synchronous Create Location, returned collectionId and recordId, response ETag, and body etag agree, 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.json covers Create then Retrieve, conditional companion Retrieve then Update then companion Retrieve plus stale and hidden-relevant-change If-Match rejections, 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-1 through write-19 anchors 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.

MetadataAuthorsNavigation source