schema
The optimization plan and report files, as typed models with JSON schemas.
<prefix>_plan.json is normative: the resolved choice of every knob for
every operator, what was requested and by which rule, the choices that are not
knobs yet, and the identity of the model and target the plan belongs to. It is
what an optimizer rewrites and what heliaAOT will reproduce.
<prefix>_report.json is non-normative: MACs, alternatives and whether they
apply, measurements, constant placement facts and the hints the results print.
Its content may change between releases, and a plan reader ignores it.
Versioning: both files carry schema_version. Adding an optional field, a
knob, a knob value or an enum member keeps the version; renaming or removing a
field, or changing what a field means, bumps it. The plan’s schedule
section is applied: a field added there keeps the version, and a release
reading the plan as input rejects a field it does not know there. A derived or
explanatory fact is added outside schedule. An applied field added outside
schedule bumps the version.
The models read a file the way that rule needs: they ignore a field they do
not know, keep a knob, knob value or member they do not know as the string
written, and reject only a schema_version other than their own. So a
release reads the files of every release that writes the same
schema_version, older or newer. Validating with context=APPLIED, as
optimization.plan does, rejects an unknown field under schedule as
well. Validating with context=THIS_RELEASE checks a file as this release
writes it instead: no unknown field, only the knobs and values of the
registry (KNOBS), only the listed members, one measurement entry per
setting, and the reserved slots empty. The converter checks every file it
writes that way. The exported JSON schemas state the same rules, so they
belong to the release that produced a file (generator.helia_aot), and a
consumer validates against that release’s schema rather than pinning one
across releases.
Some members and fields are reserved and never written today: plan as a
knob source, resolved_by and set_by (a choice taken from an input
plan), auto_heuristic as resolved_by (auto consulting the operator
or target rather than the goal table) and model-level optimization.knobs.
The plan’s schedule section is the transfer schedule of RFC 0005: a
conversion reads it from the plan optimization.plan names, checks it
against the conversion and writes it back with its derived fields. Fields
marked input come from the plan; a derived field stated differently in the
input is rejected, except units[].source_offset, which a planner backend
decides and the input may state freely. Every field of the section is one this
release applies, checks, or reads and ignores.
The report’s per-operator constants[] and its stream_pool memory,
bytes and alignment are the planner facts of RFC 0005: they are stable
within report schema version 1, the one exception to the report’s “may change
in any release” rule.
Copyright 2025 Ambiq. All Rights Reserved.
Each symbol here has its own page: ConstantPlacement, FoldedVariable, Fp16Overflow, Hint, KnobChoice, KnobSource, MeasurementRecord, ModuleKernelCall, ModuleKernelCalls, OptimizationPlan, OptimizationReport, PlanOperator, RuleRef.