Skip to content

PARSER_CANONICAL_AST_SCHEMA.md

Latest commit

 

History

History
106 lines (75 loc) · 2.96 KB

PARSER_CANONICAL_AST_SCHEMA.md

File metadata and controls

106 lines (75 loc) · 2.96 KB

Parser Canonical AST Schema Contract

This document freezes the parser canonical AST schema + hash contract for bd-2mds.1.1.2.

Contract IDs (v1)

  • contract_version: franken-engine.parser-ast.contract.v1
  • schema_version: franken-engine.parser-ast.schema.v1
  • hash_algorithm: sha256
  • hash_prefix: sha256:

Source of truth: crates/franken-engine/src/ast.rs constants:

  • CANONICAL_AST_CONTRACT_VERSION
  • CANONICAL_AST_SCHEMA_VERSION
  • CANONICAL_AST_HASH_ALGORITHM
  • CANONICAL_AST_HASH_PREFIX

Canonical Encoding Rules

Canonical AST bytes are produced by:

  1. SyntaxTree::canonical_value()
  2. deterministic_serde::encode_value(...)

deterministic_serde contract (v1):

  • map key ordering is lexicographic (BTreeMap)
  • arrays preserve insertion order
  • typed tags are stable (U64, I64, Bool, String, Array, Map, Null)
  • no optional-field omission inside canonical values

Hash contract (v1):

  • canonical_hash = "sha256:" + hex(sha256(canonical_bytes))

Canonical AST Shape (v1)

SyntaxTree canonical map keys:

  • goal ("script" or "module")
  • body (Array<Statement>)
  • span (SourceSpan)

Statement canonical map keys:

  • kind ("import" | "export" | "expression")
  • payload (kind-specific node)
  • span (SourceSpan)

SourceSpan canonical map keys:

  • start_offset
  • end_offset
  • start_line
  • start_column
  • end_line
  • end_column

Expression canonical map keys:

  • kind (identifier|string|numeric|boolean|null|undefined|await|raw)
  • value (typed value by expression variant)

Compatibility Policy

  • v1 is fail-closed for drift in:
    • contract constants,
    • canonical encoding algorithm,
    • hash prefix/algorithm,
    • pinned compatibility vectors.
  • Any incompatible change requires:
    1. new version constants (...v2),
    2. new compatibility vectors,
    3. migration note in this doc and parser verification docs.

Compatibility Checks

Pinned by tests:

  • crates/franken-engine/tests/parser_trait_ast.rs
    • contract constants/accessors are stable
    • hash vectors:
      • -7 (script) -> sha256:d959b7cbce9a409871d9a288d6feb3c043bdf3ce6ee54ff39051909db432adc4
      • import dep from "pkg" (module) -> sha256:6f9b81a8dfbaad70c345e5508dd1fae29d3d6cfdc1d18954d3486abd00d75f6c
      • export default true (module) -> sha256:ebb993de589945a2cf22f17db58200599ae3e1e6c21cd33a0fc59eab99fd8ef6
  • crates/franken-engine/tests/ast_integration.rs
    • contract constants/accessors and hash prefix checks

Replay Commands

Use rch for heavy runs:

rch exec -- env RUSTUP_TOOLCHAIN=nightly \
  CARGO_TARGET_DIR=/tmp/rch_target_franken_engine_parser_ast_contract \
  cargo test -p frankenengine-engine --test parser_trait_ast --test ast_integration

Parser phase0 gate (includes parser trait vectors):

./scripts/run_parser_phase0_gate.sh ci