Quality Strategy

Generated from QUALITY-STRATEGY.md. Edit the canonical source file, not this page.

Strategy: Assurance-Driven Protocol Development
Status: Required foundation before production implementation
Applies to: protocol specifications, schemas, conformance suites, reference broker, clients, adapters and release artifacts

1. Quality objective

Absolute certainty is not an honest engineering claim. OpenFreytProtocol instead requires 100% traceability of every critical claim and invariant to executable evidence.

Every critical capability follows this chain:

Risk
  → Requirement
    → Normative specification clause
      → Invariant or acceptance criterion
        → Automated verification
          → Durable release evidence

A feature is not considered safe because code coverage is high or a happy-path test passes. A release is justified only when its relevant safety, security, compatibility and recovery claims have current evidence.

2. Non-negotiable principles

Specify observable behaviour before implementation.
Use test-driven development for domain and application behaviour.
Keep domain rules independent from frameworks and infrastructure.
Treat the public specification and conformance suite as the product.
Formally model the small set of distributed state transitions that can produce invalid commitments or data leakage.
Verify every critical invariant with multiple complementary techniques.
Test real persistence and network boundaries; do not mock away operational risk.
Require an independent implementation for interoperability proof.
Preserve immutable verification and release evidence.
Never waive a failing or flaky test silently.

3. Uncle Bob practices

3.1 Test-driven development

Use the red-green-refactor cycle:

Write the smallest failing test demonstrating the missing behaviour.
Write only enough production code to pass.
Refactor while the suite remains green.
Start every defect fix with a reproducing test.

Tests describe externally meaningful behaviour. They must not be coupled to private methods, framework internals or incidental call order.

3.2 Clean Architecture

Implementation dependencies point inward:

Domain
  Pure state, matching, authorization and evidence rules

Application
  Commands, policies and use cases

Ports
  Persistence, event publication, identity, clock and routing abstractions

Adapters
  HTTP, database, queue, TMS and external-format integrations

The domain must not depend on HTTP frameworks, databases, cloud SDKs, Freyt internals or adapter-specific models.

3.3 Humble adapters

Adapters validate, translate and delegate. Business decisions remain in the domain or application core. Prefer in-memory implementations for application tests and use mocks only at actual process or network boundaries.

TDD and Clean Architecture are necessary but not sufficient. Distributed retries, concurrency, authorization and compatibility also require formal, model-based, integration, security and resilience verification.

4. Executable specification first

Before implementing a production endpoint, define:

stable requirement IDs;
RFC 2119/RFC 8174 MUST, SHOULD and MAY clauses;
glossary and canonical field meanings;
JSON Schemas;
state-transition tables;
command preconditions and outcomes;
authorization matrix;
idempotency and concurrency behaviour;
event ordering and delivery guarantees;
compatibility rules;
valid and invalid examples;
stable error codes.

The reference implementation is not normative. Normative behaviour comes from the specification, schemas and conformance suite.

Schemas, examples and conformance checks must run in CI before the first broker implementation exists.

5. Requirements and traceability

Maintain machine-readable registries:

requirements/requirements.yaml
requirements/invariants.yaml
requirements/traceability.yaml

Every requirement contains:

stable ID;
risk or user need;
normative statement;
owner;
criticality;
affected resources and operations;
acceptance criteria;
test/evidence references;
lifecycle status.

CI fails when:

a critical requirement has no test reference;
a normative schema or operation has no requirement;
a removed test leaves an active requirement unverified;
a release contains stale evidence.

Target 100% requirement, invariant, lifecycle-transition and authorization-matrix coverage.

6. Formal model of critical state

Use a focused TLA+/PlusCal model for:

offer and request lifecycle;
proposal creation;
concurrent accept, reject, withdrawal and expiry;
duplicate commands;
stale resource versions;
duplicate and out-of-order events;
restart/recovery boundaries;
execution-evidence deduplication.

Required safety properties include:

No commitment without every decision required by policy.

No commitment after a valid withdrawal or expiry.

One idempotency key cannot produce two different effects.

An unauthorized organization never observes a protected resource.

Duplicate or reordered events cannot regress resource state.

One accepted exchange cannot produce contradictory execution outcomes.

Corrections cannot erase historical decisions or evidence.

Formal modeling is deliberately restricted to distributed lifecycle invariants. It is not required for simple CRUD or presentation behaviour.

7. Independent reference model

Build a pure deterministic reference model independently from the broker. It accepts commands such as:

RequestRelationship
ActivateRelationship
PublishOffer
PublishLoadRequest
ProposeMatch
AcceptMatch
RejectMatch
WithdrawOffer
ExpireProposal
RecordExecution
RecordEvidence
CorrectEvidence

Model-based tests generate command sequences and compare:

expected model state;
broker state;
emitted events;
visible projections;
audit history.

Randomized failures always report and preserve their seed.

8. Verification layers

8.1 Static verification

Run on every change:

strict compilation;
formatter and linter;
JSON Schema validation;
OpenAPI and AsyncAPI linting;
broken-reference detection;
generated-artifact drift detection;
breaking-change detection;
dependency and license policy;
secret scanning;
static security analysis.

8.2 Domain unit tests

Fast, pure tests cover:

lifecycle transitions;
authorization decisions;
capacity compatibility;
matching reason codes;
distance and evidence calculations;
decision policy;
correction and supersession.

These tests do not start a database, queue or web server.

8.3 Property-based tests

Generate and shrink cases involving:

timestamp and time-zone boundaries;
malformed and extreme capacity values;
invalid or boundary geometry;
corridor overlap;
duplicate identifiers;
stale versions;
arbitrary valid and invalid transition sequences;
unit conversion and numerical rounding;
Unicode and hostile external-reference values.

8.4 Mutation tests

Mutation testing measures whether assertions detect broken logic. Critical modules require no unexplained surviving mutation. Examples include removing an authorization check, changing > to >=, skipping a version check or reversing a terminal transition.

Equivalent mutations may be waived only with a reviewed explanation stored as evidence.

8.5 Schema and contract tests

For every resource and operation, maintain:

valid golden examples;
invalid examples for each validation rule;
request and response conformance;
event conformance;
unknown-field behaviour;
enum compatibility behaviour;
stable RFC 9457 error responses.

The suite must run against any implementation without importing Freyt code.

8.6 Persistence integration tests

Use the real database technology to verify:

unique and foreign-key constraints;
transaction boundaries;
optimistic concurrency;
idempotency records;
append-only decisions and evidence;
transactional outbox behaviour;
organization isolation;
migration and restart recovery.

Do not replace persistence behaviour with mocks.

8.7 End-to-end tests

Exercise only public interfaces. Cover complete success and rejection paths:

relationship → offer/request → proposal → decisions
→ execution → evidence → audit retrieval

Include withdrawal, expiry, stale decisions, cancellation and evidence correction.

8.8 Independent interoperability

A stable release requires:

one reference broker;
the Freyt reference client;
one independently implemented client or simulator;
preferably an implementation in another programming language.

Every implementation runs the same black-box conformance suite. Shared implementation libraries must not hide interoperability defects.

8.9 Resilience and recovery

Inject failures at every distributed boundary:

database unavailable;
event transport unavailable;
timeout after commit but before response;
duplicate delivery;
out-of-order delivery;
expired credentials;
unavailable webhook;
restart during acceptance;
adapter partial failure;
clock skew.

Verify state, retry safety, operator diagnostics and eventual recovery.

8.10 Security and privacy

Maintain a threat model and test:

organization and object-level isolation;
field-level disclosure;
token audience and scopes;
replay resistance;
webhook authentication;
resource enumeration resistance;
injection and hostile references;
oversized payload handling;
sensitive log redaction;
retention and deletion;
software-supply-chain risk.

Use the OWASP API Security Top 10 as a required release checklist. No unresolved critical or high finding is releasable without an explicit, time-bounded risk acceptance.

8.11 Performance and longevity

Define service-level targets before running tests:

expected and 10× resource/event volume;
API latency percentiles;
matching deadline;
replay and recovery time;
evidence-report time;
retention volume;
backpressure behaviour.

Use sustained load and soak tests in addition to short peak tests.

9. Coverage policy

Line coverage is a diagnostic, not the quality goal.

Required coverage:

100% active requirement coverage;
100% documented invariant coverage;
100% state-transition coverage;
100% authorization-matrix coverage;
100% branch coverage for critical domain modules;
no unreviewed mutation survivors in critical modules;
zero skipped, focused or quarantined tests;
zero accepted flaky tests.

Critical modules include partner authorization, visibility, state transitions, idempotency, commitment creation, event ordering and execution-outcome deduplication.

10. Continuous-integration gates

Every pull request

specification and schema validation;
canonical-content policy and generated documentation drift checks;
static documentation-site type check and production build;
strict type checking;
linting and formatting;
unit and property tests;
schema and contract tests;
database integration tests;
compatibility diff;
security/static analysis;
affected-code mutation testing;
traceability validation;
no skipped tests;
independent review.

Nightly

full mutation suite;
long-running property-based tests;
fuzzing;
concurrency stress;
restart and fault-injection suite;
complete dependency and license scan;
performance regression tests.

Release candidate

A release is blocked unless:

every critical requirement has current evidence;
all applicable conformance profiles pass;
two independent clients interoperate;
all supported prior client versions pass compatibility tests;
migrations pass from every supported version;
rollback or forward recovery has been rehearsed;
threat model and authorization matrix are current;
no unresolved critical/high security finding remains;
performance and recovery targets pass;
schemas, release artifacts and SBOM are signed;
the versioned website is generated from the exact release revision;
release evidence is archived.

11. Repository quality structure

/
├── README.md
├── CONTEXT.md
├── QUALITY-STRATEGY.md
├── CONTRIBUTING.md
├── astro.config.mjs
├── scripts/
│   ├── check-content.mjs
│   └── sync-docs.mjs
├── src/content/docs/     Generated website content plus landing page
├── requirements/
│   ├── requirements.yaml
│   ├── invariants.yaml
│   └── traceability.yaml
├── specification/
│   ├── protocol.md
│   ├── glossary.md
│   ├── state-machines/
│   ├── schemas/
│   ├── openapi/
│   ├── events/
│   └── errors/
├── examples/
│   ├── valid/
│   ├── invalid/
│   └── scenarios/
├── conformance/
│   ├── reference-model/
│   ├── provider-suite/
│   ├── consumer-suite/
│   └── evidence-suite/
├── formal/
│   └── tla/
├── implementations/
│   ├── reference-broker/
│   ├── freyt-client/
│   └── independent-client/
├── adapters/
├── security/
│   ├── threat-model.md
│   ├── authorization-matrix.md
│   └── abuse-cases.md
├── verification/
│   ├── performance/
│   ├── resilience/
│   └── releases/
└── docs/
    ├── adr/
    ├── rfcs/
    └── research/

Because the root DECISIONS.md is locally ignored, durable normative architecture decisions must be stored as tracked ADRs under docs/adr/ before implementation begins.

12. Definition of Done

A capability is done only when:

its requirement and risk are identified;
normative semantics are documented;
security and privacy impact are assessed;
a failing acceptance or domain test preceded implementation;
positive, negative and boundary tests pass;
property/model tests cover relevant behaviour;
integration and conformance tests pass;
failure and recovery behaviour is verified;
observability and redaction are verified;
compatibility impact is recorded;
traceability evidence is current;
an independent reviewer approves it.

13. Foundation gate before production code

No production broker or SDK implementation should begin until these artifacts exist and pass validation:

quality charter and contribution policy;
requirement and invariant registries;
glossary;
state-transition specifications;
authorization matrix;
initial threat model and abuse cases;
conformance-test skeleton;
CI checks for schema, traceability and breaking changes;
release-evidence format;
tracked ADRs for all normative architecture choices.

The first implementation milestone is therefore not an API endpoint. It is an executable assurance foundation.