[ACIR/JIT][v0.3] 建立参数化高层积木、SimQueue ABI 与双后端 Provider specialization

[zhoubot]

目标

在 v0.2 Queue/Var 基础上建立 v0.3 的参数化高层积木体系：Python 和 frozen ACIR 只表达官方、可复用的高层硬件积木；所有积木之间只通过现有 !ac.queue<T> SSA operand/result 通信；每个积木绑定经过优化且语义等价的 gfsim C++ 与 Verilog Provider。

Python 使用 ac.const 参数和 JIT elaboration 产生具体 specialization。端口数量、payload 类型、结构参数和策略必须在发布 frozen ACIR 前完全常量化。运行时不得发现 Provider、改变 topology 或解释 Python/MLIR。

用户模型

import agentic_circuit as ac


@ac.config
class CoreConfig:
    engines: int
    issue_entries: int
    issue_width: int
    rob_entries: int


@ac.system
def davinci(cfg: ac.const[CoreConfig]) -> None:
    inst = ac.source(PTOInst, rate=cfg.issue_width)

    with ac.scope("decode"):
        inst = ac.compute(
            inst,
            lambda x: x.with_fields(
                engine=decode_engine(x.opcode),
                cycles=decode_latency(x.opcode),
            ),
        )

    with ac.scope("dispatch"):
        lanes = ac.route(
            inst,
            by=PTOInst.engine,
            outputs=cfg.engines,
        )

    with ac.scope("issue"):
        issued = ac.issue(
            lanes,
            entries=cfg.issue_entries,
            width=cfg.issue_width,
            policy=ac.oldest,
        )

    with ac.scope("execute"):
        completed = ac.engine(issued, lanes=cfg.engines)

    with ac.scope("retire"):
        retired = ac.reorder(
            completed,
            entries=cfg.rob_entries,
            width=cfg.issue_width,
            by=PTOInst.sequence,
        )

    ac.sink(retired)


model = ac.jit(
    davinci,
    cfg=CoreConfig(
        engines=4,
        issue_entries=16,
        issue_width=4,
        rob_entries=64,
    ),
)

系统函数仍不声明运行时输入输出。所有函数参数必须是 ac.const[...]；Queue 边界和 scope I/O 继续由 source/sink 与 lexical def-use 推导。

高层积木边界

公开名字保持简短，并按公共硬件语义定义：

boundary:       source, sink, observe
compute:        compute, pipeline
transport:      queue, route, merge, fork, join, crossbar
synchronization: barrier
storage:        memory, table, pool
resource:       credit
scheduling:     issue, reorder
execution:      engine
adaptation:     adapt, cdc

• decode、dispatch、rename、execute、retire 是 scope 或高层积木组合，不是应用专用 opcode。
• Rule、State、ready/valid 和 raw register 不进入 Python 公共积木层。
• 用户不能定义私有 opcode、C++ Provider、Verilog Provider 或注入 raw backend code。

最终闭集与每个积木的精确名字由本 Issue 冻结；应优先复用现有名字，删除重叠或只反映实现细节的别名。

SimQueue-only 接口

积木动态输入输出必须继续使用现有 IR：

inputs  = Variadic<!ac.queue<T>> operands
outputs = Variadic<!ac.queue<U>> results

端口数量和类型从 operand/result 列表直接推导，不额外存储可能不一致的 input_count 或 output_count。

具有多组可变端口的积木使用 named operand/result segments。例如：

%issued:4 = ac.issue
  enqueue(%in0, %in1, %in2, %in3)
  wakeup(%done0, %done1, %done2, %done3)
  {entries = 16, width = 4, policy = #ac.policy<oldest>}
  : (...) -> (...)

使用 operand_segment_sizes / result_segment_sizes 或等价的 ODS variadic segment contract 区分 enqueue、wakeup、issued 等端口组。

必须区分：

• port arity：独立 SimQueue 的数量；
• Queue rate：单条 SimQueue 每 epoch 最多传输的 token 数量；
• payload shape：单个 token 内部的结构、array 或 packet。

三者都是 frozen specialization 的一部分，但语义不能混用。

Static parameter 与 C++ template 映射

每个积木参数必须声明分类和 backend 映射：

参数类别	ACIR 表达	C++	Verilog
payload/type	Queue element type 或 TypeAttr	template type	parameter type/packed layout
port shape	operand/result arity	template pack/non-type template	interface array/generate
structural	integer/bool attribute	non-type template	integer parameter
policy	enum/SymbolRefAttr	policy template type	enum parameter/generate
instance constant	typed attribute	constexpr/constructor constant	parameter/localparam
compute function	pure ACIR region	generated functor	generated combinational logic

沿用 schemas/component.schema.json 已有的：

template_argument
constexpr_argument
constructor_constant

结构布局、端口数量、entry 数、lane 数、issue width 和实现策略优先成为 template/non-type-template 参数。只影响实例数值且不改变布局的参数可以是 constexpr/constructor constant，但仍必须进入 specialization identity。

Compute 是唯一 lambda 积木

ac.compute 可以携带一个或多个纯组合 lambda region：

• lambda 参数和临时值全部是 ac.var<T>；
• 只能捕获 closed ac.const；
• 只能使用受支持的纯计算、字段读取和 immutable update；
• 禁止 Queue effect、跨周期状态、任意 Python runtime、I/O 和 mutable capture；
• JIT 后 lambda 必须完全降低为 canonical ac.var.* region；
• specialization hash 使用 canonical region，不使用原始 Python 文本。

其他积木不接受任意 lambda。它们通过类型化 field descriptor 或 policy 参数选择字段：

ac.route(inst, by=PTOInst.engine, outputs=4)
ac.reorder(done, by=PTOInst.sequence, entries=64)

field descriptor 在 ACIR 中成为稳定的字段符号/路径，C++ 映射为 typed accessor，Verilog 映射为冻结 packed layout 中的 bit slice。

Const-only JIT specialization

ac.jit(system, **constants) 必须执行以下流程：

validate closed const values
  -> execute static Python elaboration
  -> infer Queue types, scope I/O and port arity
  -> emit ACIR operands/results + canonical attributes
  -> lower compute lambda to Var regions
  -> canonicalize and constant-fold
  -> compute block specialization identities
  -> bind backend Providers
  -> compile only cache misses
  -> publish frozen artifacts and manifest

允许的 const 值必须是封闭、可规范化的 bool、bounded integer、enum、type、field descriptor、tuple/array/map 及 @ac.config immutable record。不允许 Python object identity、open callable、mutable collection 或 runtime Queue handle 进入 specialization input。

frozen ACIR 之后不得依赖 Python。所有 const conditional、const loop、静态 collection shape 和端口数量必须已经消失或展开。

Specialization identity 与缓存

每个 Provider specialization 的 content-addressed identity 至少包含：

• opcode、version 和 contract epoch；
• BlockSpec/schema fingerprint；
• Provider implementation fingerprint；
• input/output Queue element types 与 canonical layout；
• operand/result segment shape；
• canonical static parameter dictionary；
• canonical compute region hash（仅 compute）；
• backend、target triple、compiler 和 toolchain identity。

沿用现有 SpecializationInput、ComponentSpecialization、build fingerprint 和 manifest 体系。相同 specialization 必须命中同一缓存 artifact；不同 checkout root、Python hash seed 和进程不得改变 identity。

C++ 第一阶段采用按需生成 template-instantiation translation unit、优化编译并写入内容寻址缓存的方式。无需第一阶段直接实现 LLVM ORC C++ template frontend。

Verilog Provider 使用常量化 wrapper、parameter 和 generate；PYC/CIRCT/Verilator elaboration 后形成专用模块。参数化 source 与 specialization manifest 必须可复现。

BlockSpec 单一事实源

合并当前并行存在的 Queue opcode catalog、QueueBlockContract 与 schemas/stdlib/*.json component schema。每个官方积木只保留一个版本化 BlockSpec，并由它生成：

• ACIR ODS declaration/metadata；
• Python API metadata；
• opcode catalog；
• verifier 和参数约束；
• C++ Provider binding；
• Verilog/PYC Provider binding；
• refinement observation contract；
• specialization schema、文档表格和 capability inventory。

BlockSpec 必须声明 variadic port groups、payload relation、static parameters、parameter mapping、state/effect、timing、backpressure、Provider identity 和 refinement observations。

Provider ABI

gfsim C++

• Parent scope/topology 物理拥有所有 SimQueue<T> interconnect。
• 积木只借用 typed Queue reference/pointer/span，不拥有兄弟 interconnect。
• hot path 不执行字符串 opcode 查找、schema walk、RTTI dispatch 或 plugin discovery。
• specialization 直接实例化优化 template/provider，例如：

using Issue4 = gfsim::Issue<
    PTOInst,
    16,
    4,
    4,
    4,
    ac::Oldest>;

Verilog/PYC

• 逻辑 SimQueue 降低为 typed data/valid/ready interface 和显式 Queue storage。
• Queue depth、latency、rate 和 domain 由 interconnect owner 实现，不由相邻积木私自复制。
• Provider 可以按参数选择 register、SRAM、banked 或 pipelined implementation，但必须满足同一 BlockSpec。
• 同一 frozen ACIR 的 gfsim 与 Verilog Provider 比较声明的 Queue transaction、architectural state、completion/retirement 和 failure observations。

交付内容

• const-only @ac.system 参数和 ac.jit specialization API。
• @ac.config closed canonical config model。
• 统一 BlockSpec schema、catalog generator 和 Provider registry。
• ACIR high-level parameter attributes、field descriptor 和 variadic port segments。
• 简化后的官方积木闭集及 Python API。
• optimized gfsim C++ Provider bindings。
• optimized PYC/Verilog Provider bindings。
• specialization compiler/cache、manifest 和 deterministic publication。
• DavinciOO 4-wide reference specialization，包括 route、issue、engine、reorder 的 parameterized multi-port graph。

验收标准

• @ac.system 只接受 ac.const 参数；运行时参数和 Queue 参数被确定性拒绝。
• JIT 后 frozen ACIR 不包含 Python config object、动态端口数量或未常量化模板参数。
• Queue 输入输出只使用现有 !ac.queue<T> operands/results 表达。
• variadic port groups、heterogeneous payload 和 segment verifier 有正反测试。
• 类型和端口数量从 IR 推导，不存在重复且可能冲突的 count 属性。
• 只有 compute 接受 lambda；非法 capture、Queue effect 和 stateful lambda 被拒绝。
• field descriptor 在 C++ 和 Verilog 中映射到同一 canonical payload field。
• 每个 design-role 高层积木同时具有 gfsim 与 PYC/Verilog Provider。
• C++ template specialization 至少验证 cache miss、cache hit、跨路径复用和完整 fingerprint 失效。
• Verilog parameter/generate specialization 通过 lint、compile 和 backend equivalence。
• BlockSpec 可生成 ODS/catalog/provider inventory，删除并行手写事实源。
• DavinciOO 4-wide specialization 生成静态 SimQueue graph，并验证依赖发射、乱序完成和顺序退休。
• Debug、Release、ASan、UBSan、lit、CTest、Python、Verilator 和 determinism gates 全部通过。

非目标

• 不支持运行时动态 topology、动态 Queue port count 或 Queue handle escape。
• 不把 Rule/State/ready-valid 暴露为 Python 公共积木。
• 不允许用户自定义 opcode 或 backend Provider。
• 不在运行时解释 Python、MLIR、BlockSpec 或 schema。
• 不要求 C++ 与 Verilog 内部数据结构或未声明的内部 cycle 完全相同。
• 不把架构阶段名称直接做成无法复用的专用 opcode。

关联

• [ACPy][v0.2 hard break] 将高级串行 Python 编译为隐式 Queue/Var ACIR agentic-circuit#9：高级串行 Python 与隐式 Queue/Var frontend。
• [ACIR/gfsim][v0.2] 建立 Queue/Var 中间层优化与类型化 C++ 模型生成 agentic-circuit#10：Queue/Var ACIR、官方 opcode catalog 与 typed gfsim backend。
• [PYC/RTL][v0.2] 实现 ACIR→PYC IR→Verilog 的硬件 refinement 后端 agentic-circuit#11：ACIR→PYC IR→Verilog refinement backend。

本 Issue 是上述 v0.2 闭环之后的高层积木/JIT specialization 升级。

[zhoubot]

已启动实现，当前第一条 v0.3 纵向链路已推送到 codex/v0.3-parameterized-blocks-jit。\n\n已完成：\n- @ac.config、ac.const[...]、ac.jit(...)，JIT 不执行 system body；\n- const 参数 canonicalization、specialization fingerprint；\n- compute/route/merge/fork/barrier/table/issue/engine/reorder 简单高层积木；\n- 只有 compute 接受 lambda，其余积木使用 typed field descriptor；\n- Queue SSA operand/result 继续承载所有动态接口；\n- v0.3 BlockSpec schema/catalog 与 agentic-circuit schema block discovery；\n- gfsim C++ 按需编译与 content-addressed cache；\n- PYC C++/Verilog bundle cache，包含 C++ syntax 和 Verilator lint；\n- Issue/Engine/Reorder/Table non-type-template Provider，把 entries/resources/lanes/start/init 固化进 C++ 类型；\n- v0.3 DavinciOO JIT 示例。\n\n验证：Python frontend 106 tests、contracts/CLI 28 tests、lit 124/124、CTest 14/14；锁定 pyCircuit/LLVM 19 + Verilator 的 v0.3 bundle miss→hit 通过；v0.2 feedback PYC C++/Verilog cycle-equivalence 回归通过。\n\n剩余：真正的 multi-rate/multi-port Queue contract、pool/adapt/cdc/crossbar/pipeline 等 BlockSpec/Provider、显式 wakeup issue window，以及 DavinciOO 4-wide 精确闭环。\n\nCommits: dcb9945, d8a0da5.

[zhoubot]

继续实现进展：\n\n- 修正了早期纵向切片中的语义问题：原 issue 复用 ac.dependency 已包含执行 countdown，再串接 engine 会重复计算 cost。该组合积木现更名为 schedule；真正的 issue 名保留给后续显式 wakeup Queue 的多端口窗口。\n- JIT specialization fingerprint 现贯穿 Python specialization、frozen ACIR module attr、QueueGraph JSON 和 generated C++。\n- 新增独立 gfsim::Compute<..., Rate, Policy> 与 gfsim::Pipeline<T, Stages, Rate> template Provider。\n- 新增 SimQueue rate：每 epoch push/pop proposal 上限、peekProposable()、rate/depth 一致性校验。\n- QueueGraph plan/canonical JSON/native C++ generator 已保留 rate；gfsim compute 可在一个 epoch 原子处理多个 token。\n- PYC 对 rate>1 当前明确失败 requires explicit lane lowering。这是刻意的安全门禁：不能把一个共享有序 FIFO 错误拆成互不相关的 lane。BlockSpec 对应参数标记为 requires_lane_lowering。\n- 新增 examples/v03/multirate_compute.py。\n\n新增 commits：b56a9bc, 4ae9b88, d8920d4, 490cdb8, 72501a0。\n\n验证：GfsimTests、CodeGenTests、Python frontend 107 tests、contracts 24 tests 全绿；rate=4 frozen ACIR/QueueGraph/native C++ 通过，PYC negative gate 命中预期诊断。

[zhoubot]

DavinciOO reference fidelity gap audit

结论

当前 v0.3 生成模型已经覆盖 DavinciOO 的高层执行骨架，但仍是 contract-level behavioral projection，不是内部微架构等价实现。

已对齐的核心语义包括：静态 SimQueue 拓扑、四类执行资源、确定性调度、乱序完成、顺序退休、Work/Xfer 分离，以及 JIT 后的 C++ template specialization。

仍未对齐的主要部分是：完整 PTO 指令 ABI、tile rename、多输入 readiness/wakeup、显式 per-engine issue queue、由 opcode/shape/dtype 推导的 Engine cost、完整 ROB 状态机、4-wide lowering，以及 v0.3 同 trace 的 cycle-level oracle。

当前结构差异

维度	v0.3 generated gfsim	Frozen DavinciOO reference	Gap
Pipeline	compute -> pipeline -> route/merge -> schedule -> reorder	Frontend -> ROB -> Rename -> Dispatch -> ReadyTable -> IQ -> Engine -> ROB	中间微架构状态被折叠
Physical queues	10 个 SimQueue	默认四个 Engine 时约 22 个实体 Queue	缺少 rename、ready、wakeup、IQ/Engine 边界
Instruction payload	sequence/waits_for/engine/cycles/value	opcode、tile/scalar operands、shape、dtype、layout、tags、ROB/Engine identity、stage timestamps	payload ABI 差异大
Dependency	单一 waits_for predecessor	多 tile 输入、SMAP physical tag、ReadyTable	无法表达一般 PTO dataflow
Scheduling	schedule 合并 dependency、resource reservation 和 countdown	每 Engine 独立 IQ，显式 wakeup，oldest-ready arbitration	committed order 可近似，内部状态不可比较
Execution cost	packet 预先携带 cycles	Engine 根据 opcode、shape、dtype、带宽和 cost config 计算	latency source 未对齐
Retirement	reorder 只恢复 sequence order	ROB alloc/issue/completion/exception/retire + rename-tag recycle	ROB pressure/exception/recycle 未建模
Width	示例当前是单 token rate	fetch/alloc/issue/rename/dispatch width 可配置	4-wide 尚未闭环
Observation	Queue result/manifest	ROB、scheduler、per-stage timestamp 和 pipe view	缺少结构化对比点

Evidence:

• Generated frontend: examples/v03/davincioo_jit.py
• Reference topology: core.hpp, core.cpp
• Reference payload ABI: pto_inst.hpp
• Reference rename/readiness/IQ/ROB: rename.cpp, ready_table.cpp, issue_queue.cpp, rob.cpp

Implementation gaps

P0 — 建立 v0.3 同 trace oracle

• 让 v0.3 specialization 直接消费 canonical PTO trace，而不是手工构造简化 packet。
• 冻结并比较 record count、opcode count、architectural values、completion order、retirement order 和声明为 observable 的 timestamps。
• 保留现有 15-record softmax / 453-cycle contract，去除只能由手工 projection 提供的参数。
• 输出结构化差异报告；失败时指出首个 instruction/stage/cycle divergence。

P0 — 扩展 typed PTO payload ABI

• 用 @ac.struct 表达 opcode、engine kind、sequence/block identity、tile/scalar operands、dtype、layout 和 compile-time-bounded shape。
• 支持多个 tile inputs/outputs，而不是单一 waits_for。
• 区分 architectural fields 与 provider-local runtime state；runtime tag、ROB slot 和 timestamps 不暴露为 Python 手工维护字段。
• 冻结 C++ layout 与 Verilog packed layout，并加入 cross-backend field mapping tests。

P0 — 将 schedule provider 升级为完整 OoO scheduling specialization

Python/ACIR 继续保持一个高层 schedule 积木；不要把 rename、ready_table 或 raw wakeup wires 暴露成应用层 opcode。优化后的 provider 内部需要实现：

• SMAP/free-tag rename 与 retirement recycle。
• 多输入 tag readiness 和 completion wakeup broadcast。
• per-resource/per-engine bounded issue windows。
• deterministic oldest-ready arbitration。
• 独立资源并发、有限 Engine capacity 和 backpressure。
• 可声明的 enqueue/wakeup/completion observation points，用于 refinement comparison。

当显式 Queue 边界对于组合或复用确有必要时，再冻结 issue/engine BlockSpec；否则优先把它们保留为 schedule provider 的内部优化结构。

P1 — 将 reorder provider 升级为 ROB specialization

• 实现 alloc/issued/completed/exception/free 状态迁移。
• 实现有限 entry pressure、head/tail wraparound 和 in-order retirement。
• completion 通过稳定 identity 匹配 ROB entry。
• retirement 触发 rename-tag recycle。
• 定义 exception 的 architectural observation；不要求 gfsim/Verilog 使用相同内部容器。

P1 — Engine latency policy specialization

• 从 opcode、tile shape、dtype/layout 和 static cost config 推导 latency。
• Scalar/Vector/Cube/TMA 使用独立、版本化的 policy/provider identity。
• cost policy 的所有静态参数进入 specialization fingerprint。
• trace 中的 cycles 仅可作为 oracle/debug metadata，不能作为最终模型的权威执行成本。

P1 — 4-wide / multi-rate lowering

• 冻结 port arity、Queue rate 和 payload shape 的独立语义。
• 生成 4-wide fetch/alloc/rename/dispatch/issue specialization。
• 为共享有序 FIFO 实现显式 lane lowering；禁止将其错误拆成四条互不相关的 Queue。
• gfsim 和 PYC/Verilog 对同一个 frozen ACIR specialization 给出等价 committed Queue transactions。

P2 — Observation and deterministic diagnostics

• 统一 instruction identity、scope path、provider path 和 cycle timestamp schema。
• 提供 ROB occupancy、issue-window occupancy、resource utilization 和 queue occupancy observations。
• 保证结果不依赖 pointer、allocation order、Python hash seed、checkout root 或 host scheduling。
• 支持将 generated 与 reference trace 输出交给同一个 comparator。

建议实现顺序

canonical PTO trace adapter
  -> rich bounded PTOInst schema
  -> schedule v2 (rename + ready + IQ + engines)
  -> reorder v2 (ROB + recycle)
  -> 4-wide lane lowering
  -> v0.3 reference comparator
  -> PYC C++ / Verilog refinement closure

Gap closure acceptance criteria

• 同一 frozen PTO trace 可以同时运行 reference 和 generated v0.3 model。
• 两侧 record/opcode count、architectural values、completion order 和 retirement order 一致。
• 所有声明为 committed observation 的 stage timestamps 满足同一 cycle contract；任何边界补偿必须版本化并显式记录。
• Generated model 保留静态 Queue ownership、deterministic arbitration 和 Work/Xfer separation。
• schedule 覆盖多输入依赖、rename、wakeup、oldest-ready 和有限资源，不要求 Python 暴露底层 RTL wires。
• reorder 覆盖完整 ROB pressure、completion、exception 和 retirement contract。
• 4-wide gfsim specialization 通过 native tests；同一 frozen ACIR 的 PYC C++/Verilog 通过声明 observation 的 refinement tests。
• 通过 Python、contracts、GfsimTests、CodeGenTests、lit、CTest、Verilator、ASan/UBSan 和 determinism gates。

Scope clarification

目标是 semantic and observable equivalence，不是复制 reference 的文件名、类名或容器实现，也不要求 byte-identical C++。Python frontend 仍保持高层串行表达；微架构细节由版本化 BlockSpec 和优化 provider 承担。