AZ-011 — Conformance Test Vectors and Canonical Examples v1

Status

Acest document definește baza de conformitate pentru ATLAS ZERO.

Până la AZ-010 am definit:

obiecte,
reguli,
consens,
VM,
witness,
economie,
agenți,
guvernanță,
securitate.

AZ-011 transformă aceste specificații într-o formă verificabilă între implementări.

Scopul lui este să răspundă la întrebarea: cum demonstrăm că două implementări independente ale protocolului ajung exact la aceleași rezultate?

Acest document stabilește:

familiile de vectori de test;
formatul canonical al vectorilor;
regulile de verdict;
tipurile de exemple normative;
criteriile minime de conformitate.

Acest document se bazează pe:

AZ-002 până la AZ-010.

Termeni:

MUST = obligatoriu
MUST NOT = interzis
SHOULD = recomandat puternic
MAY = opțional

1. Obiectiv

AZ-011 răspunde la 8 întrebări practice:

Cum arată un test vector canonical?
Ce trebuie să conțină pentru a fi reproductibil?
Ce clase de vectori sunt obligatorii?
Ce înseamnă verdict identic între implementări?
Cum testăm obiecte valide și invalide?
Cum testăm compatibilitatea între versiuni?
Cum testăm determinismul BVM și al stării?
Ce înseamnă conformitate minimă pentru un nod?

2. Principii

2.1 Conformance before performance

O implementare rapidă care diverge semantic este neconformă.

2.2 Canonical inputs

Orice test vector MUST ancora exact:

inputurile canonice;
contextul de stare;
parametrii de protocol activi;
outputul sau eroarea așteptată.

2.3 Deterministic verdict

Un test vector MUST produce:

același verdict;
același hash relevant;
aceleași erori sau aceleași receipts; pe toate implementările conforme.

2.4 Positive and negative coverage

Conformance nu înseamnă doar „acceptă obiectele bune”. Înseamnă și „respinge exact obiectele rele”.

2.5 Version awareness

Vectorii MUST fi ancorați la:

versiune de protocol;
feature flags active;
epoch/parameter state relevant.

3. Test vector family overview

ATLAS ZERO SHOULD defini cel puțin următoarele familii de test:

Encoding vectors
Hash derivation vectors
Policy evaluation vectors
Transaction validation vectors
State transition vectors
Consensus/front selection vectors
BVM execution vectors
Witness/proof lifecycle vectors
Economic calculation vectors
Agent mandate and cap vectors
Governance procedure vectors
Cross-version compatibility vectors
Adversarial / malformed object vectors

4. Canonical vector structure

4.1 Abstract format

Orice vector SHOULD avea forma:

ConformanceVector {
  vector_id
  suite_name
  suite_version
  protocol_version
  feature_set_hash
  category
  description_hash?
  pre_state_hash?
  input_objects_hash
  expected_outcome_type
  expected_outcome_hash
  expected_error_code?
  expected_receipt_hash?
  expected_state_root?
  metadata_hash?
}

4.2 Rule

Vectorul canonical MUST fi suficient pentru a reconstrui:

inputul exact;
contextul exact;
verdictul așteptat.

4.3 Object packaging

Vectorii MAY include:

obiecte inline canonice;
fișiere auxiliare hash-uite;
blobs referite;
state fixtures canonicale.

Dar verdictul final MUST rămâne complet determinabil.

5. Outcome classes

5.1 Standard outcomes

Fiecare vector MUST declara un expected_outcome_type:

ACCEPT
REJECT
APPLY_WITH_RECEIPT
STATE_TRANSITION
FINALIZE_EPOCH
FAIL_WITH_ERROR
VM_RESULT
WITNESS_STATUS_RESULT
GOVERNANCE_OUTCOME_RESULT

5.2 Rule

Un runner de conformitate MUST compara exact outcome-ul relevant pentru categoria vectorului.

6. Encoding vectors

6.1 Goal

Verifică:

decodarea canonicală;
respingerea encoding-urilor necanonice;
chei duplicate;
ordinea cheilor;
integer bounds;
enum validity.

6.2 Positive vectors

Exemple:

Cell canonical corect
WitnessRecord canonical corect
MachineDeploy canonical corect
GovernanceProposal canonical corect

6.3 Negative vectors

Exemple:

chei duplicate
chei în ordine greșită
integer overflow
enum necunoscut
field type mismatch
body hash mismatch

6.4 Expected output

Runner-ul MUST produce:

accept for canonical object
reject with exact error class for malformed object

7. Hash derivation vectors

7.1 Goal

Verifică derivarea exactă a:

cell_id
machine_id
witness_id
intent_id
tx_id
block_id
proposal_id
mandate_id

7.2 Rule

Pentru fiecare obiect canonical dat, hash-ul derivat MUST fi exact cel din vector.

7.3 Negative coverage

Trebuie incluse și cazuri unde:

hash prefix greșit
body canonical diferit dar semantic aparent similar
serialization alternativă invalidă

8. Policy evaluation vectors

8.1 Goal

Verifică:

single sig
multisig
threshold logic
expiry
fallback policy
witness-guarded policies
machine-authorized policies
committee-approved policies
rate-limited delegate policies

8.2 Required fields

Vectorul MUST ancora:

policy object canonical
semnături și bundle-uri
witness set
proof set
temporal context
subject payload exact

8.3 Expected outputs

POLICY_SATISFIED
POLICY_UNSATISFIED
FAIL_WITH_ERROR

9. Transaction validation vectors

9.1 Goal

Verifică ordinea și verdictul validării AZ-003.

9.2 Required families

A. TX_VALUE_TRANSFER

transfer simplu valid
double input same tx invalid
unknown cell invalid
conservation failure invalid
expired policy invalid

B. TX_MACHINE_DEPLOY

deploy valid
machine_id mismatch invalid
invalid effect bound invalid
missing rent invalid

C. TX_MACHINE_CALL

valid call
stale state ref invalid
halted machine invalid
effect bound exceeded invalid
permission surface mismatch invalid
loss envelope exceeded invalid

D. TX_WITNESS_EMIT

valid witness emission
invalid issuer policy
invalid proof bundle
expired immediately invalid

E. TX_INTENT_SUBMIT / CANCEL

valid submit
valid cancel
cancel already terminal invalid
expired intent invalid

F. TX_GUARD_HALT

valid halt
unauthorized halt invalid

G. TX_EPOCH_NOTARIZE

valid notarization
threshold insufficient invalid
front mismatch invalid

9.3 Verdict

Runner-ul MUST compara:

accept/reject
error code class
optional receipt hash

10. State transition vectors

10.1 Goal

Verifică faptul că ApplyTx(S, T) produce exact:

același delta;
același receipt;
aceeași stare finală.

10.2 Required fields

Vectorul MUST include:

pre-state fixture canonical
transaction canonical
protocol params fixture
expected state delta hash
expected post-state root
expected receipt hash

10.3 Required cases

simple transfer
split/merge
machine deploy
machine call with state write
witness emission
intent lifecycle transition
halt transition

11. Consensus and front selection vectors

11.1 Goal

Verifică:

committee derivation
block validity
conflict detection
front compatibility
front scoring
tie-breakers
notarization validity

11.2 Required vector classes

A. Committee selection

Input:

seed
eligible validators
role params

Expected:

ordered committee exact

B. Front compatibility

Input:

DAG blocks
embedded txs
conflict set

Expected:

compatible/incompatible classification

C. Front scoring

Input:

candidate fronts
scoring params

Expected:

exact best front id / front hash

D. Notarization validation

Input:

selected front
signatures
committee root
expected finalized roots

Expected:

valid or invalid

11.3 Rule

Două implementări conforme MUST selecta același front în același context.

12. BVM execution vectors

12.1 Goal

Verifică:

bytecode verification
deterministic execution
bounds enforcement
effect digest
exec units accounting
return value hash
trap/revert semantics

12.2 Required subfamilies

A. Bytecode accept/reject

valid module
invalid opcode
type mismatch
forbidden recursion
unbounded loop reject

B. Runtime deterministic success

valid function call
expected result hash
expected next state root
expected effect digest
expected exec units

C. Runtime bounded failure

stack bound exceeded
memory bound exceeded
exec units exhausted
illegal host call
permission denied

D. Arithmetic semantics

checked overflow trap
divide by zero trap
ratio normalization cases

E. Storage semantics

valid state write path
invalid write path
state schema violation

12.3 Rule

BVM conformance MUST include byte-for-byte expected result fields or canonical hashes thereof.

13. Witness and proof lifecycle vectors

13.1 Goal

Verifică:

witness validity
TTL
revocation
supersession
proof verification
replay protection
contradiction handling

13.2 Required cases

active approval witness valid
expired witness invalid
revoked witness invalid
superseded witness not active
oracle claim with stale TTL invalid
proof bundle valid
proof bundle hash mismatch invalid
same witness reused cross-context invalid if scope-bound

13.3 Expected outputs

exact witness status
exact policy satisfaction result where relevant

14. Economic vectors

14.1 Goal

Verifică:

fee formulas
rent formulas
bond requirements
slash amount formulas
reward split formulas
congestion multiplier effects

14.2 Required cases

simple tx fee
machine call fee
deploy fee with prepaid rent
witness retention fee
slash amount by role/fault class
bond required for given agent scope
no-finality reward withholding example

14.3 Rule

Numeric results MUST match exactly in integer arithmetic form.

15. Agent mandate vectors

15.1 Goal

Verifică:

mandate activation
action permission match
scope match
cap enforcement
journaling requirements
suspension/halt/revoke
rotation
portfolio aggregate caps

15.2 Required cases

valid action in mandate
action outside scope invalid
action exceeds notional cap invalid
action while suspended invalid
action after revoke invalid
missing pre-action journal invalid if fail-closed
exit-only allows close but not open
aggregate portfolio cap exceeded invalid

15.3 Expected outputs

ALLOW / DENY / HALT / ALLOW_IN_EXIT_ONLY etc.
optional exact error code or status code

16. Governance vectors

16.1 Goal

Verifică:

proposal validity
class assignment
review requirements
quorum profile derivation
outcome derivation
timelock logic
challenge logic
activation eligibility
emergency expiry

16.2 Required cases

valid economic parameter change
structural proposal missing technical review invalid
constitutional amendment with insufficient chamber approval invalid
approved proposal before timelock not active
emergency action with expired scope inactive
emergency action attempting forbidden expansive power invalid

16.3 Expected outputs

proposal admissible/inadmissible
outcome status
activation valid/invalid

17. Cross-version compatibility vectors

17.1 Goal

Verifică:

cum tratează implementarea obiecte vechi după upgrade;
ce versiuni rămân valide;
ce obiecte necesită migrare;
ce semantics nu se schimbă retroactiv.

17.2 Required cases

old Cell under unchanged schema still valid
old bytecode version still executes under compatible runtime
deprecated witness type still interpretable historically
new proposal type rejected by old node if unsupported
upgrade activation boundary before/after effective epoch

17.3 Rule

Vectorii MUST ancora explicit versiunea de protocol și activation epoch.

18. Adversarial / malformed vectors

18.1 Goal

Verifică robustețea la input ostil.

18.3 Rule

Implementarea MUST respinge în mod sigur și consistent aceste obiecte.

19. Canonical vector fixture format

19.1 Directory structure recommendation

vectors/
  encoding/
  hashing/
  policies/
  tx_validation/
  state_transition/
  consensus/
  bvm/
  witness/
  economics/
  agents/
  governance/
  cross_version/
  adversarial/

19.2 File contents

Fiecare vector SHOULD include:

vector.json canonical descriptor
inputs/
pre_state/ dacă relevant
expected/
notes.md optional, non-normative

19.3 Rule

Verdictul normativ MUST veni din fișierele canonice, nu din notes.md.

20. Example canonical vector skeleton

20.1 Abstract JSON-like form

{
  "vector_id": "az011.tx.value_transfer.0001",
  "suite_name": "tx_validation",
  "suite_version": "1.0",
  "protocol_version": "1.0",
  "category": "TX_VALUE_TRANSFER",
  "feature_set_hash": "...",
  "pre_state_hash": "...",
  "input_objects_hash": "...",
  "expected_outcome_type": "STATE_TRANSITION",
  "expected_receipt_hash": "...",
  "expected_state_root": "...",
  "expected_error_code": null
}

20.2 Rule

Implementările SHOULD calcula independent și compara valorile, nu să consume direct verdict text ca adevăr extern.

21. Canonical examples section

Pe lângă vectori strict mașinabili, ATLAS ZERO SHOULD avea și exemple canonice explicative.

21.1 Required examples

simplest valid Cell
simplest valid transfer tx
invalid transfer with conservation failure
minimal MachineDeploy
minimal valid MachineCall
minimal approval witness
minimal revocation
minimal intent submit/cancel lifecycle
minimal notarization
minimal mandate with journaling
minimal governance proposal + outcome

21.2 Goal

Aceste exemple ajută:

implementatorii;
auditorii;
tool builders;
verificarea manuală.

22. Error code conformance

22.1 Goal

Nu este suficient să respingi obiectul. Trebuie să îl respingi coerent.

22.2 Rule

Pentru vectorii de tip negativ, implementările SHOULD produce:

exact aceeași clasă primară de eroare;
și, unde posibil, același cod canonical.

22.3 Allowed variance

Diferențe de mesaj text uman sunt permise dacă:

codul normativ rămâne același;
verdictul și momentul eșecului rămân aceleași semantic.

23. Receipt conformance

23.1 Goal

Receipts sunt parte din audit și debugging deterministic.

23.2 Rule

Pentru orice vector care așteaptă APPLY_WITH_RECEIPT sau STATE_TRANSITION, implementările MUST produce același:

tx_id
consumed cells
created cells
touched machines
emitted witnesses
fee paid by asset
exec units
state delta hash

23.3 Receipt hash

Se recomandă definirea:

receipt_hash = H("AZ:RECEIPT:" || canonical_receipt)

24. State fixture rules

24.1 Need

Multe vectori depind de o stare inițială precisă.

24.2 Rule

State fixtures MUST fi:

canonical serialized;
versioned;
hash-addressed;
complete pentru vectorul dat.

24.3 No hidden state

Runner-ul MUST NOT injecta stare suplimentară implicită neancorată în fixture.

25. Feature flags and parameter state

25.1 Need

Unii vectori depind de parametri activi:

fee schedule
BVM version
governance rules
feature flags

25.2 Rule

Fiecare vector relevant MUST include parameter_state_hash sau fixture echivalent.

25.3 Why

Altminteri două implementări pot diverge legitim din cauza unui context neprecizat.

26. Test runner requirements

26.1 A conformance runner SHOULD:

load vector canonical descriptor
load fixtures
set protocol parameter state
execute relevant subsystem
derive verdict
compare with expected outputs
emit machine-readable report

26.2 Machine-readable report

Raportul SHOULD include:

vector_id
pass/fail
mismatch class
observed hashes
observed error code
implementation version

27. Conformance levels

27.1 Level C0 — Encoding only

Implementarea trece:

encoding
hashing
basic object parsing

27.2 Level C1 — Validation core

Implementarea trece:

policy
tx validation
state transition vectors

27.3 Level C2 — Full node core

Implementarea trece:

consensus/front vectors
notarization vectors
economics core

27.4 Level C3 — Smart runtime

Implementarea trece:

BVM vectors
witness/proof vectors
agent mandate vectors

27.5 Level C4 — Governance complete

Implementarea trece:

governance
cross-version
emergency and activation vectors

27.6 Rule

Un nod mainnet-candidate SHOULD atinge cel puțin nivelul relevant pentru rolul său și, pentru full reference node, nivel maxim aplicabil.

28. Required minimum conformance for implementations

28.1 Wallet/tooling

SHOULD at least pass:

encoding
hashing
object examples relevant to signing

28.2 Light client

SHOULD pass:

encoding
hashing
notarization vectors
witness inclusion and governance activation vectors relevant

28.3 Full node

MUST pass:

encoding
hashing
policy
tx validation
state transitions
consensus/notarization
economics core

28.4 BVM-capable node

MUST additionally pass:

BVM execution
witness/proof
machine deploy/call vectors

29. Differential conformance

29.1 Need

Reference outputs alone are not enough. Două implementări trebuie comparate și între ele.

29.2 Rule

ATLAS ZERO SHOULD maintain:

at least one reference implementation;
at least one independent implementation for differential testing where feasible.

29.3 Differential verdict

Dacă două implementări diferă:

cel puțin una este neconformă;
vectorul sau specificația trebuie reexaminată.

30. Mutation testing for vectors

30.1 Goal

Să verificăm că vectorii chiar detectează erori reale.

30.2 Model

Test harness-ul MAY introduce mutații deliberate:

change one byte in serialization
change one signature byte
alter one fee field
remove one witness ref
alter one parameter

30.3 Expected result

Implementările SHOULD pica vectorii mutați conform așteptărilor negative.

31. Canonical example set v1

31.1 EX-001 Minimal Cell

Cell validă cu:

asset_id non-zero
amount > 0
simple owner/spend policy
no expiry

31.2 EX-002 Minimal transfer

Transfer valid cu un input și două outputs.

31.3 EX-003 Invalid conservation

Același transfer dar outputs > inputs.

31.4 EX-004 Minimal MachineDeploy

State bound mic, effect bound simplu, no burn.

31.5 EX-005 Minimal MachineCall

Update bounded al unei stări mici.

31.6 EX-006 Approval witness + spend policy

Witness valid care permite un spend.

31.7 EX-007 Revoked approval

Același caz dar cu revocare activă.

31.8 EX-008 Minimal intent lifecycle

submit -> partial fill -> cancel/reject or full fill.

31.9 EX-009 Minimal notarization

Front mic, committee corect, threshold atins.

31.10 EX-010 Minimal mandate

Agent bounded, journaling obligatoriu, cap mic.

31.11 EX-011 Minimal governance path

proposal -> reviews -> votes -> outcome -> activation.

32. Cross-language determinism requirements

32.1 Need

Implementări în limbaje diferite trebuie să producă aceleași rezultate.

32.2 Rule

Conformance suites MUST fi rulate pe:

cel puțin două arhitecturi
cel puțin două limbaje/implementări diferite, unde posibil
cel puțin configurații diferite de optimizare

32.3 Goal

Se detectează:

integer handling bugs
serialization divergence
VM runtime differences
ordering assumptions ascunse

33. Performance is not a conformance signal

33.1 Principle

Un nod poate fi:

foarte rapid și neconform;
sau mai lent și corect.

33.2 Rule

Conformance MUST fi evaluată separat de benchmark.

34. Canonical conformance report

34.1 Standard report fields

ConformanceReport {
  implementation_id
  implementation_version
  protocol_version
  suite_version
  total_vectors
  passed_vectors
  failed_vectors
  skipped_vectors
  failures_by_category
  report_hash
  generated_at
}

34.2 Rule

Rapoartele SHOULD fi hash-uibile și arhivabile pentru audit.

35. Required publication before serious launch

35.1 Before public testnet

SHOULD publish:

core encoding/hashing vectors
basic tx validation vectors
minimal notarization vectors
minimal BVM vectors

35.2 Before mainnet

MUST publish or internally maintain at high rigor:

full conformance suite for all consensus-relevant behavior
cross-version suite
negative/adversarial vectors
governance activation vectors
agent and witness critical vectors

36. Failure interpretation

36.1 If a vector fails

Există doar câteva posibilități:

implementarea este greșită;
vectorul este greșit;
specificația este ambiguă sau greșită.

36.2 Rule

Un eșec de conformitate MUST duce la:

investigație,
clarificare,
fix de implementare sau vector,
eventual update de specificație versionat.

37. Conformance formula

Conformance = canonical fixtures + deterministic execution + exact expected verdicts + independent implementations agreeing on the same results

38. Relația cu restul suitei

AZ-011 este primul document care forțează protocolul să devină testabil inter-implementare, nu doar descris bine.

Pe scurt:

AZ-002 până la AZ-010 spun ce este protocolul.
AZ-011 spune cum demonstrăm că două construcții diferite îl înțeleg la fel.

39. Ce urmează

După AZ-011, documentul corect este:

AZ-012 — Reference Node Architecture

Acolo trebuie definit:

separarea componentelor nodului;
mempool;
state engine;
consensus engine;
BVM runtime integration;
witness/proof subsystem;
governance activation subsystem;
telemetry și recovery hooks.

Închidere

Un protocol nu devine real când are doar specificații bune. Devine real când două echipe diferite, două implementări diferite și două mașini diferite trec aceiași vectori și ajung la aceleași hash-uri, aceleași erori și aceleași stări finale.

Acolo începe conformitatea reală.