diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 1f379810..47f5b5a5 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -7,3 +7,8 @@
/CONTRIBUTING.md @PTO-ISA/pycircuit-maintainers
/SECURITY.md @PTO-ISA/pycircuit-maintainers
/CODE_OF_CONDUCT.md @PTO-ISA/pycircuit-maintainers
+
+# Agentic Circuit remains a separate semantic and package boundary in the
+# shared repository, but follows the same maintainer review authority.
+/components/agentic-circuit/ @PTO-ISA/pycircuit-maintainers
+/docs/acir/ @PTO-ISA/pycircuit-maintainers
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f9449c64..4889a1d3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -6,24 +6,27 @@ repos:
- id: check-yaml
args: [--unsafe]
- id: end-of-file-fixer
+ exclude: ^components/agentic-circuit/
- id: trailing-whitespace
+ exclude: ^components/agentic-circuit/
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.11.8
hooks:
- id: ruff
- exclude: ^(designs/XiangShan-pyc/|designs/outerCube/|designs/BypassUnit/|designs/RegisterFile/)
+ exclude: ^(components/agentic-circuit/|designs/XiangShan-pyc/|designs/outerCube/|designs/BypassUnit/|designs/RegisterFile/)
- repo: https://github.com/psf/black
rev: 24.10.0
hooks:
- id: black
+ exclude: ^components/agentic-circuit/
- repo: https://github.com/DavidAnson/markdownlint-cli2
rev: v0.18.1
hooks:
- id: markdownlint-cli2
- exclude: ^(docs/gates/logs/|designs/outerCube/.*\.md$|designs/XiangShan-pyc/docs/design_hierarchy_plan\.md$|docs/cycle_balance_improvement.*\.md$)
+ exclude: ^(components/agentic-circuit/|docs/gates/logs/|designs/outerCube/.*\.md$|designs/XiangShan-pyc/docs/design_hierarchy_plan\.md$|docs/cycle_balance_improvement.*\.md$)
- repo: local
hooks:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 35439be0..d05b1662 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -6,6 +6,8 @@ include(GNUInstallDirs)
option(PYC_BUILD_MLIR_TOOLS "Build MLIR-based pyc tools" ON)
option(PYC_BUILD_RUNTIME_LIB "Build pyc6 runtime library" ON)
+option(PYC_BUILD_AGENTIC_CIRCUIT "Build the integrated Agentic Circuit component" OFF)
+option(PYC_BUILD_AGENTIC_CIRCUIT_TESTS "Build Agentic Circuit tests" OFF)
option(PYC_RUNTIME_ENABLE_ZLIB_TRACE "Enable gzip trace output in runtime (optional)" OFF)
option(PYC_RUNTIME_BUILD_SHARED "Build shared pyc6 runtime library" OFF)
option(PYC_INSTALL_TEMPLATES "Install runtime template libraries" ON)
@@ -34,6 +36,13 @@ if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")
endif()
endif()
+if(PYC_BUILD_AGENTIC_CIRCUIT)
+ # Discover LLVM/MLIR in the common parent scope so the PYC and ACIR sibling
+ # subprojects share one imported target graph.
+ find_package(LLVM 22.1.8 EXACT CONFIG REQUIRED)
+ find_package(MLIR 22.1.8 EXACT CONFIG REQUIRED)
+endif()
+
if(PYC_BUILD_MLIR_TOOLS)
add_subdirectory(compiler/mlir)
endif()
@@ -42,6 +51,17 @@ if(PYC_BUILD_RUNTIME_LIB)
add_subdirectory(runtime/cpp)
endif()
+if(PYC_BUILD_AGENTIC_CIRCUIT)
+ if(NOT PYC_BUILD_MLIR_TOOLS OR NOT PYC_BUILD_RUNTIME_LIB)
+ message(FATAL_ERROR
+ "PYC_BUILD_AGENTIC_CIRCUIT requires PYC_BUILD_MLIR_TOOLS=ON and "
+ "PYC_BUILD_RUNTIME_LIB=ON so ACIR-to-PYC uses the repo-local pyc6 toolchain")
+ endif()
+ set(ACIR_BUILD_TESTING "${PYC_BUILD_AGENTIC_CIRCUIT_TESTS}" CACHE BOOL
+ "Build Agentic Circuit tests" FORCE)
+ add_subdirectory(components/agentic-circuit)
+endif()
+
if(PYC_INSTALL_TEMPLATES)
install(
DIRECTORY runtime/cpp
diff --git a/LICENSE b/LICENSE
index ea8f6036..cc7bc6d7 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
BSD 3-Clause License
-Copyright (c) 2026, Kevin Zhou
+Copyright (c) 2026, PTO-ISA
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
diff --git a/README.md b/README.md
index 39935770..ef29d0ab 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
# pyCircuit 6
-
+
@@ -9,12 +9,15 @@
-pyCircuit is a Python hardware construction language. It lowers cycle-aware
-designs to a verified MLIR dialect, then emits synthesizable Verilog and a C++
-cycle model from the same IR.
+pyCircuit is a Python hardware construction and architecture-modeling
+repository. The `pycircuit` frontend lowers cycle-aware designs to verified PYC
+MLIR and emits synthesizable Verilog and a C++ cycle model. The retained
+`agentic_circuit` frontend lowers architecture/process/queue descriptions to
+ACIR, then targets either ACSim/gfsim or the pyCircuit 6 hardware flow.
[`PTO-ISA/pyCircuit`](https://github.com/PTO-ISA/pyCircuit) is the canonical
-repository, release authority, and only source of truth.
+repository, release authority, and only active source of truth for both
+pyCircuit and Agentic Circuit.
[`LinxISA/pyCircuit`](https://github.com/LinxISA/pyCircuit) is its downstream
fork for Linx integration work.
@@ -43,6 +46,14 @@ pre-commit install
bash flows/scripts/pyc build
```
+The Agentic Circuit frontend remains a separate distribution and Python
+namespace in the same source repository:
+
+```bash
+python3 -m pip install -e components/agentic-circuit
+agentic-circuit --help
+```
+
Release wheels, once published, use the distribution name `pycircuit-hisi`;
the Python import remains `pycircuit`. The repository does not claim a PyPI
release until the corresponding PTO-ISA release workflow has completed.
@@ -51,6 +62,24 @@ The staged compiler is installed under
`.pycircuit_out/toolchain/install/`. Set `PYC_TOOLCHAIN_ROOT` to that directory
when running end-to-end builds from a source checkout.
+## Agentic Circuit and ACIR
+
+ACIR remains an independent, upper-level MLIR dialect. It is not folded into
+the PYC dialect and does not replace the Cycle-Aware Signal model:
+
+```text
+agentic_circuit frontend -> ACPy 0.3 -> ACIR
+ |-> ACSim -> gfsim
+ `-> PYC -> pycc -> pyc6 C++ / Verilog
+
+pycircuit frontend -> Cycle-Aware Signal -> PYC -> pycc -> pyc6 C++ / Verilog
+```
+
+The public `agentic_circuit` import and `agentic-circuit` CLI remain distinct
+from `pycircuit`. AC symbols are not re-exported from `pycircuit.__init__`.
+See the [ACIR architecture overview](docs/acir/index.md) and
+[migration record](docs/acir/migration.md).
+
## First cycle-aware design
```python
@@ -108,6 +137,15 @@ bash flows/scripts/run_examples.sh
bash flows/scripts/run_sims.sh
```
+Run the Agentic Circuit frontend and contract lane:
+
+```bash
+PYTHONPATH=components/agentic-circuit/src \
+python3 -m unittest discover \
+ -s components/agentic-circuit/tests \
+ -p 'test_*.py'
+```
+
System tests require a built toolchain and Verilator:
```bash
@@ -124,12 +162,16 @@ pytest tests/system -m system
- [IR specification](docs/IR_SPEC.md)
- [pyCircuit 6 decisions](docs/rfcs/pyc6-decisions.md)
- [pyCircuit 6 evolution plan](docs/pyc6-plan.md)
+- [ACIR architecture and frontend](docs/acir/index.md)
+- [Agentic Circuit migration](docs/acir/migration.md)
## Repository governance
-PTO-ISA owns product decisions, releases, package publication, and the default
-branch. Linx integration changes should be developed so they can be reviewed
-upstream; the LinxISA fork follows the upstream default branch.
+PTO-ISA owns product decisions, both Python distributions, releases, package
+publication, and the default branch. Linx integration changes should be
+developed so they can be reviewed upstream; the LinxISA fork follows the
+upstream default branch. The former standalone Agentic Circuit repository is
+retired only after both AC and PYC closure gates pass.
- [Contribution workflow](docs/development/contributing-workflow.md)
- [Testing and gates](docs/development/testing-and-gates.md)
@@ -146,6 +188,7 @@ trace, and gate contracts use `libpyc6_runtime`, `PYC6TRC3`, and
pyCircuit/
├── compiler/frontend/pycircuit/ # Python language frontend
├── compiler/mlir/ # pyc dialect, passes, pycc, and emitters
+├── components/agentic-circuit/ # AC frontend, ACIR/ACSim, gfsim, and AC tools
├── runtime/ # C++ simulation and Verilog primitives
├── designs/examples/ # Supported product examples
├── flows/ # Build and validation orchestration
@@ -155,4 +198,6 @@ pyCircuit/
## License
-pyCircuit is licensed under the MIT License. See [LICENSE](LICENSE).
+pyCircuit, including the integrated Agentic Circuit sources, is licensed under
+the BSD 3-Clause License. See [LICENSE](LICENSE) and the
+[relicensing record](docs/legal/AC-RELICENSE-BSD-3-CLAUSE.md).
diff --git a/components/agentic-circuit/.clang-format b/components/agentic-circuit/.clang-format
new file mode 100644
index 00000000..9b3aa8b7
--- /dev/null
+++ b/components/agentic-circuit/.clang-format
@@ -0,0 +1 @@
+BasedOnStyle: LLVM
diff --git a/components/agentic-circuit/.clang-tidy b/components/agentic-circuit/.clang-tidy
new file mode 100644
index 00000000..784da8f0
--- /dev/null
+++ b/components/agentic-circuit/.clang-tidy
@@ -0,0 +1,47 @@
+# clang-tidy gate for Agentic Circuit owned sources.
+#
+# The gate enforces the static analyzer plus high-signal bugprone/performance
+# checks that hold across the entire owned tree. Noise-heavy checks whose
+# findings are dominated by MLIR/gtest idioms (macro parentheses, optional
+# access heuristics, generated enum sizing, gtest static initialization) are
+# intentionally out of scope for the CI gate.
+Checks: >
+ -*,
+ clang-analyzer-*,
+ bugprone-assert-side-effect,
+ bugprone-bool-pointer-implicit-conversion,
+ bugprone-dangling-handle,
+ bugprone-exception-escape,
+ bugprone-implicit-widening-of-multiplication-result,
+ bugprone-inc-dec-in-conditions,
+ bugprone-inaccurate-erase,
+ bugprone-infinite-loop,
+ bugprone-misplaced-operator-in-strlen-in-alloc,
+ bugprone-misplaced-widening-cast,
+ bugprone-not-null-terminated-result,
+ bugprone-optional-value-conversion,
+ bugprone-posix-return,
+ bugprone-string-constructor,
+ bugprone-stringview-nullptr,
+ bugprone-suspicious-missing-comma,
+ bugprone-suspicious-realloc-usage,
+ bugprone-suspicious-string-compare,
+ bugprone-swapped-arguments,
+ bugprone-undelegated-constructor,
+ bugprone-undefined-memory-manipulation,
+ bugprone-unhandled-self-assignment,
+ bugprone-use-after-move,
+ bugprone-virtual-near-miss,
+ performance-faster-string-find,
+ performance-implicit-conversion-in-loop,
+ performance-inefficient-algorithm,
+ performance-inefficient-string-concatenation,
+ performance-move-const-arg,
+ performance-no-automatic-move,
+ performance-no-int-to-ptr,
+ performance-trivially-destructible,
+ performance-type-promotion-in-math-fn,
+ performance-unnecessary-copy-initialization,
+ -clang-analyzer-core.StackAddressEscape
+WarningsAsErrors: '*'
+HeaderFilterRegex: '.*agentic-circuit/(include|lib|tools|unittests)/.*'
diff --git a/components/agentic-circuit/.editorconfig b/components/agentic-circuit/.editorconfig
new file mode 100644
index 00000000..2e0d78c1
--- /dev/null
+++ b/components/agentic-circuit/.editorconfig
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab
diff --git a/components/agentic-circuit/.gitattributes b/components/agentic-circuit/.gitattributes
new file mode 100644
index 00000000..f9080a8d
--- /dev/null
+++ b/components/agentic-circuit/.gitattributes
@@ -0,0 +1,9 @@
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+references/davincioo-gfsim/upstream/** whitespace=-trailing-space
diff --git a/components/agentic-circuit/.github/dependabot.yml b/components/agentic-circuit/.github/dependabot.yml
new file mode 100644
index 00000000..3b5ca194
--- /dev/null
+++ b/components/agentic-circuit/.github/dependabot.yml
@@ -0,0 +1,10 @@
+version: 2
+updates:
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "monthly"
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "monthly"
diff --git a/components/agentic-circuit/.github/workflows/ci.yml b/components/agentic-circuit/.github/workflows/ci.yml
new file mode 100644
index 00000000..fe833dca
--- /dev/null
+++ b/components/agentic-circuit/.github/workflows/ci.yml
@@ -0,0 +1,327 @@
+name: CI
+
+on:
+ push:
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ python-frontend:
+ runs-on: ubuntu-24.04
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.11", "3.12", "3.13"]
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+ - name: Set up Python
+ uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: "pip"
+ cache-dependency-path: requirements-dev.lock
+
+ - name: Install locked development requirements
+ run: python -m pip install --disable-pip-version-check -r requirements-dev.lock
+
+ - name: Run Python frontend contracts
+ env:
+ PYTHONPATH: src
+ run: |
+ python -m unittest discover -s tests/python_frontend -v
+ python -m unittest \
+ tests.cli.test_cli_parser.CliParserTest.test_exact_command_inventory \
+ tests.cli.test_cli_parser.CliParserTest.test_aliases_and_repeated_singleton_options_are_rejected \
+ tests.cli.test_all_commands -v
+ PYTHONHASHSEED=1 python -m unittest tests.python_frontend.test_determinism -v
+ PYTHONHASHSEED=99 python -m unittest tests.python_frontend.test_determinism -v
+
+ contracts-and-configure:
+ runs-on: ubuntu-24.04
+ env:
+ LLVM_RELEASE: "22.1.8"
+ LLVM_SOURCE_SHA256: "922f1817a0df7b1489272d18134ee0087a8b068828f87ac63b9861b1a9965888"
+ LLVM_SOURCE_URL: "https://github.com/llvm/llvm-project/releases/download/llvmorg-22.1.8/llvm-project-22.1.8.src.tar.xz"
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+ - name: Set up Python
+ uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38
+ with:
+ python-version: "3.12"
+ cache: "pip"
+ cache-dependency-path: requirements-dev.lock
+
+ - name: Install locked development requirements
+ run: python -m pip install --disable-pip-version-check -r requirements-dev.lock
+
+ - name: Install native test dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install --yes --no-install-recommends libgtest-dev
+
+ - name: Run repository contracts
+ run: python -m unittest tests.contracts.test_contracts -v
+
+ - name: Run IR coverage gate
+ run: |
+ python -m unittest tests.contracts.test_ir_coverage -v
+ python scripts/check-ir-coverage.py
+
+ - name: Check clang-format on owned sources
+ run: |
+ git ls-files "*.cpp" "*.h" ":!references/**" |
+ xargs clang-format --dry-run --Werror
+
+ - name: Cache content-addressed LLVM source archive
+ uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
+ with:
+ path: .cache/llvm-project-22.1.8.src.tar.xz
+ key: llvm-${{ runner.os }}-${{ runner.arch }}-${{ env.LLVM_SOURCE_SHA256 }}-${{ hashFiles('toolchains/llvm.lock.json') }}
+
+ - name: Fetch and verify locked LLVM source
+ run: |
+ mkdir -p .cache
+ if [[ ! -f .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz ]]; then
+ curl --fail --location --proto '=https' --tlsv1.2 \
+ --output .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz \
+ "${LLVM_SOURCE_URL}"
+ fi
+ echo "${LLVM_SOURCE_SHA256} .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz" | sha256sum --check --strict
+ tar -C .cache -xf .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz
+
+ - name: Compute LLVM build fingerprint
+ id: llvm-build-fingerprint
+ run: |
+ {
+ pwd -P
+ command -v c++
+ c++ --version
+ cmake --version
+ ninja --version
+ uname -m
+ ldd --version 2>&1 | head -n 1
+ } | sha256sum | awk '{print "value=" $1}' >> "${GITHUB_OUTPUT}"
+
+ - name: Restore exact LLVM build outputs
+ id: llvm-build-cache
+ uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684
+ with:
+ path: .cache/llvm-build
+ key: llvm-build-${{ runner.os }}-${{ runner.arch }}-${{ env.LLVM_SOURCE_SHA256 }}-${{ hashFiles('toolchains/llvm.lock.json', 'scripts/ci-build-llvm.sh') }}-${{ steps.llvm-build-fingerprint.outputs.value }}
+
+ - name: Build locked MLIR package
+ id: llvm-build
+ if: steps.llvm-build-cache.outputs.cache-hit != 'true'
+ run: bash scripts/ci-build-llvm.sh
+
+ - name: Save exact LLVM build outputs
+ # Save even when later steps fail: the LLVM build takes over an hour
+ # and must never be rebuilt just because a test regressed. Only save
+ # a fully built tree, never a partial one.
+ if: always() && steps.llvm-build-cache.outputs.cache-hit != 'true' && steps.llvm-build.conclusion == 'success'
+ uses: actions/cache/save@5a3ec84eff668545956fd18022155c47e93e2684
+ with:
+ path: .cache/llvm-build
+ key: llvm-build-${{ runner.os }}-${{ runner.arch }}-${{ env.LLVM_SOURCE_SHA256 }}-${{ hashFiles('toolchains/llvm.lock.json', 'scripts/ci-build-llvm.sh') }}-${{ steps.llvm-build-fingerprint.outputs.value }}
+
+ - name: Verify exact LLVM build outputs
+ run: |
+ test -x .cache/llvm-build/bin/mlir-opt
+ test -x .cache/llvm-build/bin/FileCheck
+ test -x .cache/llvm-build/bin/not
+ test -x .cache/llvm-build/bin/split-file
+ test -x .cache/llvm-build/bin/count
+ test -f .cache/llvm-build/lib/cmake/llvm/LLVMConfigVersion.cmake
+ test -f .cache/llvm-build/lib/cmake/mlir/MLIRConfigVersion.cmake
+ .cache/llvm-build/bin/mlir-opt --version | grep -F "LLVM version ${LLVM_RELEASE}"
+ grep -F "set(PACKAGE_VERSION \"${LLVM_RELEASE}\")" .cache/llvm-build/lib/cmake/llvm/LLVMConfigVersion.cmake
+ grep -F "set(PACKAGE_VERSION \"${LLVM_RELEASE}\")" .cache/llvm-build/lib/cmake/mlir/MLIRConfigVersion.cmake
+ grep -F "CMAKE_HOME_DIRECTORY:INTERNAL=${GITHUB_WORKSPACE}/.cache/llvm-project-${LLVM_RELEASE}.src/llvm" .cache/llvm-build/CMakeCache.txt
+ grep -F "CMAKE_CACHEFILE_DIR:INTERNAL=${GITHUB_WORKSPACE}/.cache/llvm-build" .cache/llvm-build/CMakeCache.txt
+
+ - name: Configure development preset
+ env:
+ LLVM_PREFIX: "${{ github.workspace }}/.cache/llvm-build"
+ run: cmake --preset dev-llvm22 -DMLIR_DIR="${LLVM_PREFIX}/lib/cmake/mlir" -DACIR_ENABLE_ASSERTIONS=ON
+
+ - name: Build development preset with assertions
+ run: cmake --build --preset dev-llvm22
+
+ - name: Run lit and FileCheck suite
+ # Run lit directly with -v so failed tests print their command output;
+ # the add_lit_testsuite default is succinct and hides failure bodies.
+ run: |
+ cmake --build --preset dev-llvm22 --target acir-opt acir-opt-internal
+ lit -v build/dev-llvm22/test
+
+ - name: Run unit tests with assertions
+ run: ctest --test-dir build/dev-llvm22 --output-on-failure
+
+ - name: Run public CLI and Python frontend tests
+ env:
+ PYTHONPATH: src:${{ github.workspace }}/build/dev-llvm22/python
+ run: |
+ python -m unittest discover -s tests/cli -v
+ python -m unittest discover -s tests/python_frontend -v
+
+ - name: Run workspace tool and end-to-end tests
+ env:
+ PYTHONPATH: src:${{ github.workspace }}/build/dev-llvm22/python
+ run: |
+ python -m unittest discover -s tests/tools -v
+ python -m unittest \
+ tests.e2e.test_workspace_examples \
+ tests.e2e.test_workspace_npu -v
+
+ - name: Audit workspace determinism and generated dependencies
+ env:
+ PYTHONPATH: src:${{ github.workspace }}/build/dev-llvm22/python
+ RUNS: "2"
+ run: scripts/audit-workspace-determinism.sh
+
+ - name: Install clang-tidy
+ run: sudo apt-get install --yes --no-install-recommends clang-tidy
+
+ - name: Run clang-tidy gate on owned sources
+ run: |
+ git ls-files "lib/*.cpp" "tools/*.cpp" "unittests/*.cpp" |
+ xargs -P 4 -I {} clang-tidy -p build/dev-llvm22 \
+ --config-file=.clang-tidy \
+ --header-filter='.*agentic-circuit/(include|lib|tools|unittests)/.*' \
+ {}
+
+ - name: Configure release preset
+ env:
+ LLVM_PREFIX: "${{ github.workspace }}/.cache/llvm-build"
+ run: cmake --preset release-llvm22 -DMLIR_DIR="${LLVM_PREFIX}/lib/cmake/mlir"
+
+ - name: Build release preset
+ run: cmake --build --preset release-llvm22
+
+ - name: Run release test suites
+ run: |
+ cmake --build --preset release-llvm22 --target check-acir
+ ctest --test-dir build/release-llvm22 --output-on-failure
+
+ - name: Install to a temporary prefix
+ run: cmake --install build/release-llvm22 --prefix "${RUNNER_TEMP}/acir-prefix"
+
+ - name: Build and run the installed-tree consumer
+ env:
+ LLVM_PREFIX: "${{ github.workspace }}/.cache/llvm-build"
+ run: |
+ cmake -S tests/install-consumer -B "${RUNNER_TEMP}/acir-consumer" \
+ -GNinja -DCMAKE_BUILD_TYPE=Release \
+ -DAgenticCircuit_DIR="${RUNNER_TEMP}/acir-prefix/lib/cmake/AgenticCircuit" \
+ -DLLVM_DIR="${LLVM_PREFIX}/lib/cmake/llvm" \
+ -DMLIR_DIR="${LLVM_PREFIX}/lib/cmake/mlir"
+ cmake --build "${RUNNER_TEMP}/acir-consumer"
+ "${RUNNER_TEMP}/acir-consumer/process-state-plan-consumer"
+
+ - name: Check whitespace
+ run: git diff --check
+
+ sanitizers:
+ name: ${{ matrix.preset }}
+ needs: contracts-and-configure
+ runs-on: ubuntu-24.04
+ env:
+ LLVM_RELEASE: "22.1.8"
+ LLVM_SOURCE_SHA256: "922f1817a0df7b1489272d18134ee0087a8b068828f87ac63b9861b1a9965888"
+ LLVM_SOURCE_URL: "https://github.com/llvm/llvm-project/releases/download/llvmorg-22.1.8/llvm-project-22.1.8.src.tar.xz"
+ strategy:
+ fail-fast: false
+ matrix:
+ preset: ["asan-llvm22", "ubsan-llvm22"]
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+ - name: Set up Python
+ uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38
+ with:
+ python-version: "3.12"
+ cache: "pip"
+ cache-dependency-path: requirements-dev.lock
+
+ - name: Install locked development requirements
+ run: python -m pip install --disable-pip-version-check -r requirements-dev.lock
+
+ - name: Install native test dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install --yes --no-install-recommends libgtest-dev
+
+ - name: Cache content-addressed LLVM source archive
+ uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
+ with:
+ path: .cache/llvm-project-22.1.8.src.tar.xz
+ key: llvm-${{ runner.os }}-${{ runner.arch }}-${{ env.LLVM_SOURCE_SHA256 }}-${{ hashFiles('toolchains/llvm.lock.json') }}
+
+ - name: Fetch and verify locked LLVM source
+ run: |
+ mkdir -p .cache
+ if [[ ! -f .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz ]]; then
+ curl --fail --location --proto '=https' --tlsv1.2 \
+ --output .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz \
+ "${LLVM_SOURCE_URL}"
+ fi
+ echo "${LLVM_SOURCE_SHA256} .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz" | sha256sum --check --strict
+ tar -C .cache -xf .cache/llvm-project-${LLVM_RELEASE}.src.tar.xz
+
+ - name: Compute LLVM build fingerprint
+ id: llvm-build-fingerprint
+ run: |
+ {
+ pwd -P
+ command -v c++
+ c++ --version
+ cmake --version
+ ninja --version
+ uname -m
+ ldd --version 2>&1 | head -n 1
+ } | sha256sum | awk '{print "value=" $1}' >> "${GITHUB_OUTPUT}"
+
+ - name: Restore exact LLVM build outputs
+ uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684
+ with:
+ path: .cache/llvm-build
+ key: llvm-build-${{ runner.os }}-${{ runner.arch }}-${{ env.LLVM_SOURCE_SHA256 }}-${{ hashFiles('toolchains/llvm.lock.json', 'scripts/ci-build-llvm.sh') }}-${{ steps.llvm-build-fingerprint.outputs.value }}
+ fail-on-cache-miss: true
+
+ - name: Verify cached LLVM package
+ run: |
+ test -x .cache/llvm-build/bin/mlir-opt
+ test -f .cache/llvm-build/lib/cmake/llvm/LLVMConfigVersion.cmake
+ test -f .cache/llvm-build/lib/cmake/mlir/MLIRConfigVersion.cmake
+ .cache/llvm-build/bin/mlir-opt --version | grep -F "LLVM version ${LLVM_RELEASE}"
+
+ - name: Configure sanitizer preset
+ env:
+ LLVM_PREFIX: "${{ github.workspace }}/.cache/llvm-build"
+ run: >-
+ cmake --preset "${{ matrix.preset }}"
+ -DMLIR_DIR="${LLVM_PREFIX}/lib/cmake/mlir"
+
+ - name: Build sanitizer targets
+ run: >-
+ cmake --build --preset "${{ matrix.preset }}"
+ --target GfsimTests CodeGenTests
+
+ - name: Run sanitizer tests
+ env:
+ ASAN_OPTIONS: "detect_leaks=1:strict_string_checks=1:check_initialization_order=1:allow_user_poisoning=0:halt_on_error=1"
+ UBSAN_OPTIONS: "print_stacktrace=1:halt_on_error=1"
+ run: >-
+ ctest --test-dir "build/${{ matrix.preset }}"
+ --output-on-failure -R '^(GfsimTests|CodeGenTests)$'
diff --git a/components/agentic-circuit/.gitignore b/components/agentic-circuit/.gitignore
new file mode 100644
index 00000000..10e8e12a
--- /dev/null
+++ b/components/agentic-circuit/.gitignore
@@ -0,0 +1,12 @@
+.DS_Store
+.worktrees/
+.venv/
+build/
+cmake-build-*/
+compile_commands.json
+__pycache__/
+*.py[cod]
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
diff --git a/components/agentic-circuit/CHANGELOG.md b/components/agentic-circuit/CHANGELOG.md
new file mode 100644
index 00000000..05418ff8
--- /dev/null
+++ b/components/agentic-circuit/CHANGELOG.md
@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to Agentic Circuit will be documented here. The project
+follows Keep a Changelog and will use Semantic Versioning after its first
+release.
+
+## Unreleased
+
+### Added
+
+- Reproducible LLVM/MLIR 22.1.8 repository and development-toolchain baseline.
+- A strict repository-local DavinciOO JSONL adapter that emits canonical,
+ validated `pto-trace@0.1` documents without widening the simulator input
+ contract.
+- Committed runtime statistics and Chrome Trace Event JSONL, plus a
+ deterministic repository-local Perfetto packer.
+- Six complete golden workspaces covering queueing,
+ backpressure, request/response memory, nested arrays, time-domain bridging,
+ and suspended processes.
+- A hierarchical superscalar NPU showcase with typed decode, dependency-aware
+ oldest-ready issue, four finite execution-engine classes, memory behavior,
+ completion, and in-order retirement.
+- Workspace replay, equivalent-root, legal Work-permutation, dependency-scan,
+ installation, sanitizer, and end-to-end CI gates.
+- A provenance-locked DavinciOO gfsim C++ reference model under
+ `references`, with an executable smoke trace and an explicit
+ ACIR-to-gfsim generation boundary.
diff --git a/components/agentic-circuit/CMakeLists.txt b/components/agentic-circuit/CMakeLists.txt
new file mode 100644
index 00000000..eb581a93
--- /dev/null
+++ b/components/agentic-circuit/CMakeLists.txt
@@ -0,0 +1,215 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(AgenticCircuit VERSION 0.1.0 LANGUAGES C CXX)
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
+include(cmake/LLVMToolchain.cmake)
+acir_configure_llvm()
+
+function(acir_append_llvm_link_flag flag)
+ set_property(GLOBAL APPEND PROPERTY ACIR_LLVM_LINK_FLAGS_PROPERTY "${flag}")
+endfunction()
+
+function(acir_collect_llvm_link_target target)
+ get_property(_visited GLOBAL PROPERTY ACIR_LLVM_LINK_TARGETS_PROPERTY)
+ if("${target}" IN_LIST _visited)
+ return()
+ endif()
+ set_property(GLOBAL APPEND PROPERTY ACIR_LLVM_LINK_TARGETS_PROPERTY "${target}")
+
+ get_target_property(_location "${target}" IMPORTED_LOCATION)
+ if(NOT _location OR _location MATCHES "-NOTFOUND$")
+ get_target_property(_configurations "${target}" IMPORTED_CONFIGURATIONS)
+ foreach(_configuration IN LISTS _configurations)
+ string(TOUPPER "${_configuration}" _configuration_upper)
+ get_target_property(
+ _candidate "${target}" "IMPORTED_LOCATION_${_configuration_upper}"
+ )
+ if(_candidate AND NOT _candidate MATCHES "-NOTFOUND$")
+ set(_location "${_candidate}")
+ break()
+ endif()
+ endforeach()
+ endif()
+ if(_location AND NOT _location MATCHES "-NOTFOUND$")
+ acir_append_llvm_link_flag("${_location}")
+ endif()
+
+ get_target_property(_dependencies "${target}" INTERFACE_LINK_LIBRARIES)
+ if(NOT _dependencies OR _dependencies MATCHES "-NOTFOUND$")
+ return()
+ endif()
+ foreach(_dependency IN LISTS _dependencies)
+ if(_dependency MATCHES "^\\$]+)>$")
+ set(_dependency "${CMAKE_MATCH_1}")
+ elseif(_dependency MATCHES "^\\$<")
+ message(FATAL_ERROR
+ "unsupported LLVM link dependency expression: ${_dependency}"
+ )
+ endif()
+ if(TARGET "${_dependency}")
+ acir_collect_llvm_link_target("${_dependency}")
+ elseif(IS_ABSOLUTE "${_dependency}" OR _dependency MATCHES "^-")
+ acir_append_llvm_link_flag("${_dependency}")
+ else()
+ acir_append_llvm_link_flag("-l${_dependency}")
+ endif()
+ endforeach()
+endfunction()
+
+set_property(GLOBAL PROPERTY ACIR_LLVM_LINK_FLAGS_PROPERTY "")
+set_property(GLOBAL PROPERTY ACIR_LLVM_LINK_TARGETS_PROPERTY "")
+if(TARGET LLVM)
+ acir_collect_llvm_link_target(LLVM)
+else()
+ acir_collect_llvm_link_target(LLVMSupport)
+endif()
+get_property(ACIR_LLVM_LINK_FLAGS GLOBAL PROPERTY ACIR_LLVM_LINK_FLAGS_PROPERTY)
+
+list(APPEND CMAKE_MODULE_PATH "${LLVM_DIR}" "${MLIR_DIR}")
+include(TableGen)
+include(AddLLVM)
+include(AddMLIR)
+include(AddACIR)
+
+set(_ACIR_BUILD_TESTING_DEFAULT "${PROJECT_IS_TOP_LEVEL}")
+if(DEFINED BUILD_TESTING)
+ set(_ACIR_BUILD_TESTING_DEFAULT "${BUILD_TESTING}")
+endif()
+option(ACIR_BUILD_TESTING "Build Agentic Circuit tests"
+ "${_ACIR_BUILD_TESTING_DEFAULT}")
+unset(_ACIR_BUILD_TESTING_DEFAULT)
+if(ACIR_BUILD_TESTING)
+ include(CTest)
+ enable_testing()
+ find_package(Python3 3.11 REQUIRED COMPONENTS Interpreter)
+ find_program(ACIR_LIT_EXECUTABLE NAMES llvm-lit lit
+ HINTS "${CMAKE_CURRENT_SOURCE_DIR}/.venv/bin"
+ REQUIRED
+ )
+ set(LLVM_EXTERNAL_LIT "${ACIR_LIT_EXECUTABLE}" CACHE FILEPATH
+ "lit executable used by Agentic Circuit tests" FORCE
+ )
+endif()
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+
+include_directories(SYSTEM ${LLVM_INCLUDE_DIRS} ${MLIR_INCLUDE_DIRS})
+include_directories(
+ "${CMAKE_CURRENT_SOURCE_DIR}/include"
+ "${CMAKE_CURRENT_BINARY_DIR}/include"
+)
+add_definitions(${LLVM_DEFINITIONS})
+
+option(ACIR_ENABLE_ASSERTIONS "Keep C/C++ assertions enabled" OFF)
+option(
+ ACIR_BUILD_REFERENCE_MODELS
+ "Build non-installed reference models used as code-generation baselines"
+ ${ACIR_BUILD_TESTING}
+)
+
+add_library(acir_project_options INTERFACE)
+add_library(AgenticCircuit::ProjectOptions ALIAS acir_project_options)
+set_target_properties(acir_project_options PROPERTIES EXPORT_NAME ProjectOptions)
+target_compile_features(acir_project_options INTERFACE cxx_std_20)
+if(ACIR_ENABLE_ASSERTIONS)
+ if(MSVC)
+ target_compile_options(acir_project_options INTERFACE /UNDEBUG)
+ else()
+ target_compile_options(acir_project_options INTERFACE -UNDEBUG)
+ endif()
+endif()
+
+include(CMakePackageConfigHelpers)
+configure_package_config_file(
+ cmake/AgenticCircuitConfig.cmake.in
+ "${CMAKE_CURRENT_BINARY_DIR}/AgenticCircuitConfig.cmake"
+ INSTALL_DESTINATION lib/cmake/AgenticCircuit
+)
+write_basic_package_version_file(
+ "${CMAKE_CURRENT_BINARY_DIR}/AgenticCircuitConfigVersion.cmake"
+ VERSION "${PROJECT_VERSION}"
+ COMPATIBILITY ExactVersion
+)
+
+install(
+ FILES
+ "${CMAKE_CURRENT_BINARY_DIR}/AgenticCircuitConfig.cmake"
+ "${CMAKE_CURRENT_BINARY_DIR}/AgenticCircuitConfigVersion.cmake"
+ DESTINATION lib/cmake/AgenticCircuit
+)
+install(TARGETS acir_project_options EXPORT AgenticCircuitTargets)
+install(
+ EXPORT AgenticCircuitTargets
+ FILE AgenticCircuitTargets.cmake
+ NAMESPACE AgenticCircuit::
+ DESTINATION lib/cmake/AgenticCircuit
+)
+install(FILES cmake/modules/AddACIR.cmake DESTINATION lib/cmake/AgenticCircuit/modules)
+install(DIRECTORY include/acir DESTINATION include)
+install(DIRECTORY include/gfsim DESTINATION include)
+install(DIRECTORY resources/pyc_runtime DESTINATION share/AgenticCircuit)
+install(
+ DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/include/acir"
+ DESTINATION include
+ FILES_MATCHING
+ PATTERN "*.h.inc"
+)
+
+# The Python bridge locates the same installed-style runtime surface in the
+# build tree, keeping native compilation independent of source-tree paths.
+file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/include/gfsim"
+ DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/include")
+add_custom_target(acir_runtime_headers
+ COMMAND "${CMAKE_COMMAND}" -E copy_directory
+ "${CMAKE_CURRENT_SOURCE_DIR}/include/gfsim"
+ "${CMAKE_CURRENT_BINARY_DIR}/include/gfsim"
+ COMMENT "Synchronizing gfsim runtime headers"
+)
+
+add_subdirectory(include)
+add_subdirectory(lib)
+add_subdirectory(python)
+add_subdirectory(tools)
+if(ACIR_BUILD_REFERENCE_MODELS)
+ add_subdirectory(references/davincioo-gfsim)
+endif()
+if(ACIR_BUILD_TESTING)
+ add_subdirectory(test)
+ add_subdirectory(unittests)
+ add_test(
+ NAME WorkspaceE2ETests
+ COMMAND "${Python3_EXECUTABLE}" -m unittest tests.e2e.test_workspace_examples -v
+ )
+ set_tests_properties(WorkspaceE2ETests PROPERTIES
+ WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+ TIMEOUT 300
+ LABELS "e2e;workspace"
+ ENVIRONMENT "AGENTIC_CIRCUIT_TEST_BUILD_DIR=${CMAKE_BINARY_DIR}"
+ )
+ add_test(
+ NAME DavinciOOTraceTests
+ COMMAND "${Python3_EXECUTABLE}" -m unittest
+ tests.e2e.test_davincioo_trace -v
+ )
+ set_tests_properties(DavinciOOTraceTests PROPERTIES
+ WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+ TIMEOUT 60
+ LABELS "e2e;davincioo"
+ )
+ add_test(
+ NAME PycVerilogBackendTests
+ COMMAND "${Python3_EXECUTABLE}" -m unittest
+ tests.tools.test_pyc_verilog_backend -v
+ )
+ set_tests_properties(PycVerilogBackendTests PROPERTIES
+ WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+ TIMEOUT 30
+ LABELS "pyc;verilog"
+ )
+endif()
diff --git a/components/agentic-circuit/CMakePresets.json b/components/agentic-circuit/CMakePresets.json
new file mode 100644
index 00000000..54334543
--- /dev/null
+++ b/components/agentic-circuit/CMakePresets.json
@@ -0,0 +1,92 @@
+{
+ "version": 7,
+ "cmakeMinimumRequired": {
+ "major": 3,
+ "minor": 25,
+ "patch": 0
+ },
+ "configurePresets": [
+ {
+ "name": "llvm22-base",
+ "hidden": true,
+ "generator": "Ninja",
+ "binaryDir": "${sourceDir}/build/${presetName}",
+ "cacheVariables": {
+ "CMAKE_EXPORT_COMPILE_COMMANDS": true,
+ "MLIR_DIR": "$env{LLVM_PREFIX}/lib/cmake/mlir"
+ }
+ },
+ {
+ "name": "dev-llvm22",
+ "displayName": "Development with LLVM 22.1.8",
+ "inherits": "llvm22-base",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Debug",
+ "ACIR_ENABLE_ASSERTIONS": true
+ },
+ "environment": {
+ "LLVM_PREFIX": "/opt/homebrew/opt/llvm"
+ }
+ },
+ {
+ "name": "release-llvm22",
+ "displayName": "Release with LLVM 22.1.8",
+ "inherits": "llvm22-base",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Release",
+ "ACIR_ENABLE_ASSERTIONS": false
+ },
+ "environment": {
+ "LLVM_PREFIX": "/opt/homebrew/opt/llvm"
+ }
+ },
+ {
+ "name": "asan-llvm22",
+ "displayName": "ASAN with LLVM 22.1.8",
+ "inherits": "llvm22-base",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Debug",
+ "ACIR_ENABLE_ASSERTIONS": true,
+ "CMAKE_CXX_FLAGS": "-fsanitize=address -fno-omit-frame-pointer",
+ "CMAKE_C_FLAGS": "-fsanitize=address -fno-omit-frame-pointer",
+ "CMAKE_EXE_LINKER_FLAGS": "-fsanitize=address"
+ },
+ "environment": {
+ "LLVM_PREFIX": "/opt/homebrew/opt/llvm"
+ }
+ },
+ {
+ "name": "ubsan-llvm22",
+ "displayName": "UBSAN with LLVM 22.1.8",
+ "inherits": "llvm22-base",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Debug",
+ "ACIR_ENABLE_ASSERTIONS": true,
+ "CMAKE_CXX_FLAGS": "-fsanitize=undefined -fno-omit-frame-pointer",
+ "CMAKE_C_FLAGS": "-fsanitize=undefined -fno-omit-frame-pointer",
+ "CMAKE_EXE_LINKER_FLAGS": "-fsanitize=undefined"
+ },
+ "environment": {
+ "LLVM_PREFIX": "/opt/homebrew/opt/llvm"
+ }
+ }
+ ],
+ "buildPresets": [
+ {
+ "name": "dev-llvm22",
+ "configurePreset": "dev-llvm22"
+ },
+ {
+ "name": "release-llvm22",
+ "configurePreset": "release-llvm22"
+ },
+ {
+ "name": "asan-llvm22",
+ "configurePreset": "asan-llvm22"
+ },
+ {
+ "name": "ubsan-llvm22",
+ "configurePreset": "ubsan-llvm22"
+ }
+ ]
+}
diff --git a/components/agentic-circuit/CODE_OF_CONDUCT.md b/components/agentic-circuit/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..87ca1918
--- /dev/null
+++ b/components/agentic-circuit/CODE_OF_CONDUCT.md
@@ -0,0 +1,28 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Agentic Circuit a harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity,
+sex characteristics, gender identity and expression, level of experience,
+education, socioeconomic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Positive behavior includes empathy, constructive feedback, respect for
+different viewpoints, and taking responsibility for mistakes. Unacceptable
+behavior includes harassment, sexualized language or imagery, personal or
+political attacks, trolling, insulting comments, and publishing another
+person's private information without permission.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, and
+other contributions that do not align with this Code of Conduct. Instances of
+abusive, harassing, or otherwise unacceptable behavior may be reported using
+the private process in `SECURITY.md`. Maintainers will respect the privacy and
+security of reporters and will apply corrective action fairly.
+
+This Code of Conduct applies in all project spaces and whenever an individual
+is officially representing the project.
diff --git a/components/agentic-circuit/CONTRIBUTING.md b/components/agentic-circuit/CONTRIBUTING.md
new file mode 100644
index 00000000..87e5a7bb
--- /dev/null
+++ b/components/agentic-circuit/CONTRIBUTING.md
@@ -0,0 +1,20 @@
+# Contributing to Agentic Circuit
+
+Thank you for helping improve Agentic Circuit. Contributions must preserve the
+exact global contract epoch and the reproducible LLVM toolchain boundary.
+
+## Development setup
+
+1. Run `scripts/bootstrap-dev.sh` to create `.venv` and install the locked
+ development requirements.
+2. Activate `.venv`.
+3. Run `python -m unittest tests.contracts.test_contracts -v`.
+4. Configure with `cmake --preset dev-llvm22`.
+
+Before submitting a change, run the contract tests, the relevant build and
+tests, and `git diff --check`. Changes to a public contract must update every
+affected normative specification and machine-readable schema in the same
+change.
+
+By contributing, you agree that your contribution is licensed under the
+BSD 3-Clause License and that you will follow the Code of Conduct.
diff --git a/components/agentic-circuit/LICENSE b/components/agentic-circuit/LICENSE
new file mode 100644
index 00000000..cc7bc6d7
--- /dev/null
+++ b/components/agentic-circuit/LICENSE
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, PTO-ISA
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/components/agentic-circuit/README.md b/components/agentic-circuit/README.md
new file mode 100644
index 00000000..fc941fdb
--- /dev/null
+++ b/components/agentic-circuit/README.md
@@ -0,0 +1,66 @@
+# Agentic Circuit
+
+Agentic Circuit is a Python and MLIR-based architecture construction system
+that generates a structured, pure C++ graph-flow simulator named `gfsim`.
+It also emits canonical PYC IR for downstream C++ and Verilog generation.
+
+The source tree is intentionally release-neutral: product versions belong to
+Git tags and GitHub Releases, not directory names, filenames, symbols, or test
+names. Serialized artifacts still carry an exact contract epoch because that
+field is part of their wire-format compatibility contract.
+
+## Development baseline
+
+The repository is locked to LLVM/MLIR 22.1.8. On Apple Silicon, the default
+prefix is `/opt/homebrew/opt/llvm`. On another supported host, pass the
+equivalent package explicitly with
+`-DMLIR_DIR=/path/to/llvm/lib/cmake/mlir`.
+
+```sh
+scripts/bootstrap-dev.sh
+source .venv/bin/activate
+python -m unittest tests.contracts.test_contracts -v
+cmake --preset dev-llvm22
+cmake --build --preset dev-llvm22
+```
+
+Use `release-llvm22` for a release configuration. The exact upstream release,
+commit, archive digest, supported host triples, and version policy are recorded
+in `toolchains/llvm.lock.json`.
+
+## Documentation
+
+- [Specification index](docs/spec/README.md)
+- [Agentic Circuit specification manual](docs/spec/agentic-circuit.md)
+- [Agentic Circuit 团队 Specification 手册](docs/spec/agentic-circuit.zh-CN.md)
+- [NDF release-layout decision](docs/spec/decisions/D-RELEASE-LAYOUT-001.md)
+- [Historical specification reference](docs/spec/refs/history.md)
+- [Examples by semantic role](examples/README.md)
+
+Canonical machine-readable schemas:
+
+- [ACPy](schemas/acpy.schema.json)
+- [Capabilities](schemas/capabilities.schema.json)
+- [ComponentSchema](schemas/component.schema.json)
+- [Official opcode catalog schema](schemas/opcode-catalog.schema.json)
+- [Official Queue building-block catalog](schemas/opcodes.json)
+- [PTO trace](schemas/pto-trace.schema.json)
+- [Build manifest](schemas/build-manifest.schema.json)
+- [Run manifest](schemas/run-manifest.schema.json)
+- [Run result](schemas/run-result.schema.json)
+- [Diagnostic](schemas/diagnostic.schema.json)
+- [ACSim binding](schemas/acsim-binding.schema.json)
+- [ACIR process-state plan](schemas/acir-process-state-plan.schema.json)
+
+The repository uses a hard-break layout. Removed implementation-phase and
+product-version paths have no aliases or compatibility symlinks. Historical
+documents remain recoverable from the Git revision recorded by the NDF
+historical reference.
+
+## Project policies
+
+Agentic Circuit is distributed as part of pyCircuit under the
+[BSD 3-Clause License](LICENSE). See
+[Contributing](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md),
+[Security policy](SECURITY.md), and [Support policy](SUPPORT.md) before opening
+a change or report.
diff --git a/components/agentic-circuit/SECURITY.md b/components/agentic-circuit/SECURITY.md
new file mode 100644
index 00000000..9538777e
--- /dev/null
+++ b/components/agentic-circuit/SECURITY.md
@@ -0,0 +1,14 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use GitHub's private
+security advisory reporting for this repository and include affected versions,
+reproduction steps, impact, and any proposed mitigation.
+
+Maintainers will acknowledge a report within seven days, coordinate validation
+and remediation privately, and publish an advisory after a fix is available.
+Please allow a reasonable remediation window before public disclosure.
+
+Only the current development branch is supported until the project publishes
+its first release.
diff --git a/components/agentic-circuit/SUPPORT.md b/components/agentic-circuit/SUPPORT.md
new file mode 100644
index 00000000..dabe4d95
--- /dev/null
+++ b/components/agentic-circuit/SUPPORT.md
@@ -0,0 +1,9 @@
+# Support
+
+Use GitHub Discussions for design and usage questions. Use GitHub Issues for a
+reproducible defect or a scoped feature proposal. Include the host triple,
+LLVM/MLIR version, configure preset, command output, and a minimal reproducer.
+
+Security reports must follow `SECURITY.md` and must not be filed publicly.
+The project is maintained on a best-effort basis and does not provide a service
+level agreement.
diff --git a/components/agentic-circuit/cmake/AgenticCircuitConfig.cmake.in b/components/agentic-circuit/cmake/AgenticCircuitConfig.cmake.in
new file mode 100644
index 00000000..62a0cfd7
--- /dev/null
+++ b/components/agentic-circuit/cmake/AgenticCircuitConfig.cmake.in
@@ -0,0 +1,18 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(LLVM 22.1.8 EXACT CONFIG)
+find_dependency(MLIR 22.1.8 EXACT CONFIG)
+
+include("${CMAKE_CURRENT_LIST_DIR}/AgenticCircuitTargets.cmake")
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/modules")
+include(AddACIR)
+
+set(AgenticCircuit_EXECUTABLE "${PACKAGE_PREFIX_DIR}/bin/agentic-circuit")
+if(NOT EXISTS "${AgenticCircuit_EXECUTABLE}")
+ set(AgenticCircuit_FOUND FALSE)
+ set(AgenticCircuit_NOT_FOUND_MESSAGE
+ "Agentic Circuit executable is missing: ${AgenticCircuit_EXECUTABLE}")
+endif()
+
+check_required_components(AgenticCircuit)
diff --git a/components/agentic-circuit/cmake/LLVMToolchain.cmake b/components/agentic-circuit/cmake/LLVMToolchain.cmake
new file mode 100644
index 00000000..6e2edf3a
--- /dev/null
+++ b/components/agentic-circuit/cmake/LLVMToolchain.cmake
@@ -0,0 +1,43 @@
+include_guard(GLOBAL)
+
+set(ACIR_REQUIRED_LLVM_VERSION "22.1.8")
+
+function(acir_configure_llvm)
+ if(TARGET MLIRIR)
+ if(NOT LLVM_PACKAGE_VERSION)
+ message(FATAL_ERROR
+ "the parent project supplied LLVM targets without LLVM_PACKAGE_VERSION")
+ endif()
+ message(STATUS
+ "Reusing parent LLVM/MLIR ${LLVM_PACKAGE_VERSION} targets for Agentic Circuit")
+ else()
+ if(NOT MLIR_DIR)
+ message(FATAL_ERROR "MLIR_DIR is required and must select MLIR 22.1.8")
+ endif()
+
+ get_filename_component(_llvm_cmake_dir "${MLIR_DIR}/../llvm" ABSOLUTE)
+ if(NOT LLVM_DIR)
+ set(LLVM_DIR "${_llvm_cmake_dir}" CACHE PATH "LLVM CMake package directory")
+ endif()
+
+ find_package(LLVM ${ACIR_REQUIRED_LLVM_VERSION} EXACT CONFIG REQUIRED)
+ find_package(MLIR ${ACIR_REQUIRED_LLVM_VERSION} EXACT CONFIG REQUIRED)
+ endif()
+
+ if(NOT LLVM_PACKAGE_VERSION STREQUAL ACIR_REQUIRED_LLVM_VERSION)
+ message(FATAL_ERROR
+ "LLVM ${ACIR_REQUIRED_LLVM_VERSION} is required; found ${LLVM_PACKAGE_VERSION}"
+ )
+ endif()
+
+ foreach(_package_variable
+ LLVM_DEFINITIONS
+ LLVM_INCLUDE_DIRS
+ LLVM_TOOLS_BINARY_DIR
+ MLIR_INCLUDE_DIRS
+ MLIR_TABLEGEN_EXE)
+ set(${_package_variable} "${${_package_variable}}" PARENT_SCOPE)
+ endforeach()
+ message(STATUS "Using LLVM ${LLVM_PACKAGE_VERSION} from ${LLVM_DIR}")
+ message(STATUS "Using MLIR ${ACIR_REQUIRED_LLVM_VERSION} from ${MLIR_DIR}")
+endfunction()
diff --git a/components/agentic-circuit/cmake/modules/AddACIR.cmake b/components/agentic-circuit/cmake/modules/AddACIR.cmake
new file mode 100644
index 00000000..430025a2
--- /dev/null
+++ b/components/agentic-circuit/cmake/modules/AddACIR.cmake
@@ -0,0 +1,19 @@
+include_guard(GLOBAL)
+
+function(add_acir_library target)
+ cmake_parse_arguments(ARG "" "" "SOURCES;LINK_LIBRARIES" ${ARGN})
+ if(NOT ARG_SOURCES)
+ message(FATAL_ERROR "add_acir_library(${target}) requires SOURCES")
+ endif()
+
+ add_library(${target} ${ARG_SOURCES})
+ target_compile_features(${target} PUBLIC cxx_std_20)
+ set_target_properties(${target} PROPERTIES CXX_EXTENSIONS OFF)
+ target_link_libraries(
+ ${target}
+ PUBLIC
+ AgenticCircuit::ProjectOptions
+ MLIRIR
+ ${ARG_LINK_LIBRARIES}
+ )
+endfunction()
diff --git a/components/agentic-circuit/contracts/acir.yaml b/components/agentic-circuit/contracts/acir.yaml
new file mode 100644
index 00000000..0ad4bceb
--- /dev/null
+++ b/components/agentic-circuit/contracts/acir.yaml
@@ -0,0 +1,130 @@
+# Normative ACIR public inventory.
+#
+# This manifest is the contract-side source of truth for the public ACIR
+# surface. scripts/check-ir-coverage.py requires the ODS definitions to
+# match these lists exactly: any added, renamed, or removed public operation
+# or type must be reflected here in the same commit, and every entry must
+# have observable lit coverage.
+schema: acir-ir-inventory
+contract_epoch: "0.3"
+dialect: acir
+operations:
+ - ac.system
+ - ac.type_scope
+ - ac.type_alias
+ - ac.module
+ - ac.module.extern
+ - ac.module.generated
+ - ac.instance
+ - ac.array
+ - ac.instances
+ - ac.view
+ - ac.port
+ - ac.return
+ - ac.queue
+ - ac.event_queue
+ - ac.resource
+ - ac.address_space
+ - ac.address_map
+ - ac.time_domain
+ - ac.struct
+ - ac.enum
+ - ac.union
+ - ac.packet
+ - ac.transaction
+ - ac.interface
+ - ac.protocol
+ - ac.role
+ - ac.state
+ - ac.event
+ - ac.transition
+ - ac.guarantee
+ - ac.process
+ - ac.record.create
+ - ac.record.get
+ - ac.record.with
+ - ac.var.constant
+ - ac.var.add
+ - ac.var.sub
+ - ac.var.mul
+ - ac.var.cmp
+ - ac.var.get
+ - ac.var.with
+ - ac.var.popcount
+ - ac.packet.serialize
+ - ac.packet.deserialize
+ - ac.transform
+ - ac.transform.yield
+ - ac.source
+ - ac.sink
+ - ac.observe
+ - ac.expect
+ - ac.expect.yield
+ - ac.broadcast
+ - ac.fork
+ - ac.route
+ - ac.route.yield
+ - ac.select
+ - ac.select.yield
+ - ac.merge
+ - ac.barrier
+ - ac.credit
+ - ac.credit.yield
+ - ac.dependency
+ - ac.dependency.yield
+ - ac.memory.instance
+ - ac.memory.request
+ - ac.memory.yield
+ - ac.reorder
+ - ac.reorder.yield
+ - ac.feedback
+ - ac.feedback.yield
+ - ac.scope
+ - ac.scope.yield
+ - ac.firing
+ - ac.firing.yield
+ - ac.queue.peek
+ - ac.queue.pop
+ - ac.queue.push
+ - ac.try_send
+ - ac.try_recv
+ - ac.schedule
+ - ac.wait_until
+ - ac.wait_for
+ - ac.await_event
+ - ac.yield_sim
+ - ac.trace.open
+ - ac.trace.next
+ - ac.trace.decode
+ - ac.trace.eof
+ - ac.trace.position
+ - ac.require
+ - ac.ensure
+ - ac.assert
+ - ac.probe
+ - ac.stat
+ - ac.stat.add
+ - ac.instrumentation
+types:
+ - struct
+ - packet
+ - transaction
+ - enum
+ - union
+ - optional
+ - list
+ - vector
+ - var
+ - queue
+ - array
+ - map
+ - set
+ - flow
+ - endpoint
+ - resource_ref
+ - channel
+ - duration
+ - rate
+ - event
+ - address
+ - resource_token
diff --git a/components/agentic-circuit/contracts/acsim.yaml b/components/agentic-circuit/contracts/acsim.yaml
new file mode 100644
index 00000000..83d526f6
--- /dev/null
+++ b/components/agentic-circuit/contracts/acsim.yaml
@@ -0,0 +1,48 @@
+# Normative ACSim v0.1 public inventory.
+#
+# This manifest is the contract-side source of truth for the public ACSim
+# surface. The acsim.type inventory includes the closed optional runtime
+# metadata contract for time_domain realizations: period, phase, tick_scale,
+# and paired parent/bridge attributes. scripts/check-ir-coverage.py requires
+# the ODS definitions to
+# match these lists exactly: any added, renamed, or removed public operation
+# or type must be reflected here in the same commit, and every entry must
+# have observable lit coverage.
+schema: acir-ir-inventory
+contract_epoch: "0.3"
+dialect: acsim
+operations:
+ - acsim.model
+ - acsim.type
+ - acsim.binding
+ - acsim.module
+ - acsim.instance
+ - acsim.array
+ - acsim.element
+ - acsim.port
+ - acsim.resource
+ - acsim.bind
+ - acsim.inline
+ - acsim.process
+ - acsim.live.load
+ - acsim.live.store
+ - acsim.invoke
+ - acsim.continue
+ - acsim.suspend
+ - acsim.terminate
+ - acsim.export
+ - acsim.dispatch
+ - acsim.activate
+ - acsim.return
+types:
+ - value
+ - expr
+ - owner
+ - ref
+ - port
+ - resource
+ - array
+ - object_id
+ - activation_id
+ - pc
+ - wake
diff --git a/components/agentic-circuit/docs/spec/00-charter/scope.md b/components/agentic-circuit/docs/spec/00-charter/scope.md
new file mode 100644
index 00000000..4ed3156b
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/00-charter/scope.md
@@ -0,0 +1,26 @@
+# Repository and release charter
+
+## Release tags own product versions {#ARC-RELEASE-001}
+
+
+The checked-out source tree describes one current product. Git releases and
+tags assign product versions. Source paths, public type names, test names, and
+example groups do not encode a product version or implementation phase.
+
+Serialized documents may retain their own schema version, and dependency locks
+retain exact external tool versions. Those values version protocols and
+dependencies, not repository layouts.
+
+## Current source uses semantic partitions {#ARC-LAYOUT-001}
+
+
+Current source is partitioned by responsibility: specifications under
+`docs/spec`, public examples under `examples`, imported upstream material under
+`references`, and test-owned golden data under `tests/goldens`.
+
+## Historical design remains in Git history {#ARC-HISTORY-001}
+
+
+Completed plans, superseded proposals, and release audits are not duplicated in
+the current tree. [[REF-HISTORY-001]] pins the last pre-migration tree so each
+historical document remains reproducible through Git.
diff --git a/components/agentic-circuit/docs/spec/50-verification/ir-coverage.md b/components/agentic-circuit/docs/spec/50-verification/ir-coverage.md
new file mode 100644
index 00000000..bb852c01
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/50-verification/ir-coverage.md
@@ -0,0 +1,179 @@
+# ACIR / ACSim coverage ledger
+
+
+
+acir_contract_epoch: 0.3
+acsim_contract_epoch: 0.3
+
+## acir operations (96)
+
+| operation | source symbol | positive coverage | negative coverage |
+| --- | --- | --- | --- |
+| ac.system | ACIR_SystemOp | test/ACIR/collections-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/Analysis/process-state-pass.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-empty.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/CodeGen/arbiter-verilog.mlir
test/CodeGen/arbiter.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Conversion/atomic-failure.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/collections-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir
test/Conversion/process-invalid.mlir |
+| ac.type_scope | ACIR_TypeScopeOp | test/ACIR/address-selectors-valid.mlir
test/ACIR/declarations-valid.mlir
test/ACIR/memory.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/select.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/records-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| ac.type_alias | ACIR_TypeAliasOp | test/ACIR/declarations-valid.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir |
+| ac.module | ACIR_ModuleOp | test/ACIR/address-map-canonical-order.mlir
test/ACIR/address-selectors-valid.mlir
test/ACIR/address-time-valid.mlir
test/ACIR/canonical-entrypoint.mlir
test/ACIR/collections-valid.mlir
test/ACIR/contracts-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/trace-valid.mlir
test/ACIR/view-provenance.mlir
test/Analysis/process-state-pass.mlir
test/Analysis/process-state-verifier.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-empty.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/atomic-failure.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/address-time-invalid.mlir
test/ACIR/collections-invalid.mlir
test/ACIR/contracts-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/runtime-references-invalid.mlir
test/ACIR/trace-invalid.mlir
test/Conversion/bindings-invalid.mlir
test/Conversion/process-invalid.mlir |
+| ac.module.extern | ACIR_ModuleExternOp | test/ACIR/canonical-entrypoint.mlir
test/ACIR/hierarchy-valid.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/bindings.mlir
test/Conversion/pure-results.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/verify-model.mlir | test/ACIR/collections-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| ac.module.generated | ACIR_ModuleGeneratedOp | test/ACIR/hierarchy-valid.mlir | test/ACIR/hierarchy-invalid.mlir |
+| ac.instance | ACIR_InstanceOp | test/ACIR/address-time-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/view-provenance.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/bindings.mlir
test/Conversion/hierarchy.mlir
test/Conversion/pure-results.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/address-time-invalid.mlir
test/ACIR/collections-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/ACIR/process-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| ac.array | ACIR_ArrayOp | test/ACIR/collections-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/Conversion/collections.mlir
test/Conversion/whole-model.mlir | test/ACIR/collections-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| ac.instances | ACIR_InstancesOp | test/ACIR/collections-valid.mlir
test/ACIR/hierarchy-valid.mlir | test/ACIR/collections-invalid.mlir |
+| ac.view | ACIR_ViewOp | test/ACIR/collections-valid.mlir
test/ACIR/view-provenance.mlir | test/ACIR/collections-invalid.mlir |
+| ac.port | ACIR_PortOp | test/ACIR/interfaces-valid.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/resources-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir |
+| ac.return | ACIR_ReturnOp | test/ACIR/address-map-canonical-order.mlir
test/ACIR/address-selectors-valid.mlir
test/ACIR/address-time-valid.mlir
test/ACIR/canonical-entrypoint.mlir
test/ACIR/collections-valid.mlir
test/ACIR/contracts-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/trace-valid.mlir
test/ACIR/view-provenance.mlir
test/Analysis/process-state-pass.mlir
test/Analysis/process-state-verifier.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-empty.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/atomic-failure.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/address-time-invalid.mlir
test/ACIR/collections-invalid.mlir
test/ACIR/contracts-invalid.mlir
test/ACIR/hierarchy-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/runtime-references-invalid.mlir
test/ACIR/trace-invalid.mlir
test/Conversion/bindings-invalid.mlir
test/Conversion/process-invalid.mlir |
+| ac.queue | ACIR_QueueOp | test/ACIR/contracts-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.event_queue | ACIR_EventQueueOp | test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir | test/ACIR/resources-invalid.mlir |
+| ac.resource | ACIR_ResourceOp | test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/resources-invalid.mlir |
+| ac.address_space | ACIR_AddressSpaceOp | test/ACIR/address-map-canonical-order.mlir
test/ACIR/address-selectors-valid.mlir
test/ACIR/address-time-valid.mlir | test/ACIR/address-time-invalid.mlir |
+| ac.address_map | ACIR_AddressMapOp | test/ACIR/address-map-canonical-order.mlir
test/ACIR/address-selectors-valid.mlir
test/ACIR/address-time-valid.mlir | test/ACIR/address-time-invalid.mlir |
+| ac.time_domain | ACIR_TimeDomainOp | test/ACIR/address-time-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir | test/ACIR/address-time-invalid.mlir
test/ACIR/resources-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| ac.struct | ACIR_StructOp | test/ACIR/declarations-valid.mlir
test/ACIR/memory.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/select.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/review-r1-invalid.mlir |
+| ac.enum | ACIR_EnumOp | test/ACIR/declarations-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/declarations-invalid.mlir |
+| ac.union | ACIR_UnionOp | test/ACIR/declarations-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| ac.packet | ACIR_PacketOp | test/ACIR/declarations-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| ac.transaction | ACIR_TransactionOp | test/ACIR/address-selectors-valid.mlir
test/ACIR/declarations-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/records-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| ac.interface | ACIR_InterfaceOp | test/ACIR/interfaces-valid.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/types-invalid.mlir |
+| ac.protocol | ACIR_ProtocolOp | test/ACIR/contracts-valid.mlir
test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/process-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/guarantees-review-r1-invalid.mlir
test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.role | ACIR_RoleOp | test/ACIR/contracts-valid.mlir
test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/process-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.state | ACIR_StateOp | test/ACIR/contracts-valid.mlir
test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/process-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/guarantees-review-r1-invalid.mlir
test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.event | ACIR_EventOp | test/ACIR/contracts-valid.mlir
test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/process-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.transition | ACIR_TransitionOp | test/ACIR/contracts-valid.mlir
test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/process-valid.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.guarantee | ACIR_GuaranteeOp | test/ACIR/interfaces-valid.mlir
test/ACIR/ownership-order-review-r2.mlir
test/ACIR/protocols-valid.mlir
test/ACIR/resources-valid.mlir | test/ACIR/guarantees-review-r1-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/protocols-review-r1-invalid.mlir
test/ACIR/resources-forward-malformed-invalid.mlir
test/ACIR/resources-invalid.mlir |
+| ac.process | ACIR_ProcessOp | test/ACIR/contracts-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir
test/Analysis/process-state-pass.mlir
test/Analysis/process-state-verifier.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-empty.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/atomic-failure.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/runtime-references-invalid.mlir
test/ACIR/trace-invalid.mlir
test/Conversion/bindings-invalid.mlir
test/Conversion/process-invalid.mlir |
+| ac.record.create | ACIR_RecordCreateOp | test/ACIR/protocols-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| ac.record.get | ACIR_RecordGetOp | test/ACIR/protocols-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir |
+| ac.record.with | ACIR_RecordWithOp | test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir |
+| ac.var.constant | ACIR_VarConstantOp | test/ACIR/control-feedback.mlir
test/ACIR/dependency.mlir
test/ACIR/expect.mlir
test/ACIR/var-expressions.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/control-feedback-invalid.mlir
test/ACIR/credit-invalid.mlir
test/ACIR/dependency-invalid.mlir
test/ACIR/expect-invalid.mlir
test/ACIR/reorder-invalid.mlir
test/ACIR/select-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| ac.var.add | ACIR_VarAddOp | test/ACIR/control-feedback.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/atomic-transform.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.var.sub | ACIR_VarSubOp | test/ACIR/var-expressions.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.var.mul | ACIR_VarMulOp | test/ACIR/var-expressions.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.var.cmp | ACIR_VarCmpOp | test/ACIR/expect.mlir
test/ACIR/var-expressions.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.var.get | ACIR_VarGetOp | test/ACIR/memory.mlir
test/ACIR/select.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/memory-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| ac.var.with | ACIR_VarWithOp | test/ACIR/var-expressions.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.var.popcount | ACIR_VarPopcountOp | test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir | test/ACIR/var-expressions-invalid.mlir |
+| ac.packet.serialize | ACIR_PacketSerializeOp | test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| ac.packet.deserialize | ACIR_PacketDeserializeOp | test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| ac.transform | ACIR_TransformOp | test/ACIR/scope.mlir
test/ACIR/transform.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir | test/ACIR/transform-invalid.mlir |
+| ac.transform.yield | ACIR_TransformYieldOp | test/ACIR/scope.mlir
test/ACIR/transform.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir | test/ACIR/transform-invalid.mlir |
+| ac.source | ACIR_SourceOp | test/ACIR/barrier.mlir
test/ACIR/broadcast.mlir
test/ACIR/control-feedback.mlir
test/ACIR/credit.mlir
test/ACIR/dependency.mlir
test/ACIR/expect.mlir
test/ACIR/fork.mlir
test/ACIR/memory.mlir
test/ACIR/observe.mlir
test/ACIR/reorder.mlir
test/ACIR/route.mlir
test/ACIR/scope.mlir
test/ACIR/select.mlir
test/ACIR/source-sink.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/arbiter-verilog.mlir
test/CodeGen/arbiter.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/barrier-invalid.mlir
test/ACIR/broadcast-invalid.mlir
test/ACIR/control-feedback-invalid.mlir
test/ACIR/credit-invalid.mlir
test/ACIR/dependency-invalid.mlir
test/ACIR/expect-invalid.mlir
test/ACIR/fork-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/observe-invalid.mlir
test/ACIR/reorder-invalid.mlir
test/ACIR/route-invalid.mlir
test/ACIR/scope-invalid.mlir
test/ACIR/select-invalid.mlir
test/ACIR/source-sink-invalid.mlir |
+| ac.sink | ACIR_SinkOp | test/ACIR/barrier.mlir
test/ACIR/broadcast.mlir
test/ACIR/control-feedback.mlir
test/ACIR/credit.mlir
test/ACIR/dependency.mlir
test/ACIR/expect.mlir
test/ACIR/fork.mlir
test/ACIR/memory.mlir
test/ACIR/observe.mlir
test/ACIR/reorder.mlir
test/ACIR/route.mlir
test/ACIR/scope.mlir
test/ACIR/select.mlir
test/ACIR/source-sink.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/arbiter-verilog.mlir
test/CodeGen/arbiter.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/memory-invalid.mlir
test/ACIR/source-sink-invalid.mlir |
+| ac.observe | ACIR_ObserveOp | test/ACIR/observe.mlir | test/ACIR/observe-invalid.mlir |
+| ac.expect | ACIR_ExpectOp | test/ACIR/expect.mlir | test/ACIR/expect-invalid.mlir |
+| ac.expect.yield | ACIR_ExpectYieldOp | test/ACIR/expect.mlir | test/ACIR/expect-invalid.mlir |
+| ac.broadcast | ACIR_BroadcastOp | test/ACIR/broadcast.mlir | test/ACIR/broadcast-invalid.mlir |
+| ac.fork | ACIR_ForkOp | test/ACIR/fork.mlir | test/ACIR/fork-invalid.mlir |
+| ac.route | ACIR_RouteOp | test/ACIR/route.mlir | test/ACIR/route-invalid.mlir |
+| ac.route.yield | ACIR_RouteYieldOp | test/ACIR/route.mlir | test/ACIR/route-invalid.mlir |
+| ac.select | ACIR_SelectOp | test/ACIR/select.mlir | test/ACIR/select-invalid.mlir |
+| ac.select.yield | ACIR_SelectYieldOp | test/ACIR/select.mlir | test/ACIR/select-invalid.mlir |
+| ac.merge | ACIR_MergeOp | test/ACIR/control-feedback.mlir
test/CodeGen/arbiter-verilog.mlir
test/CodeGen/arbiter.mlir | test/ACIR/control-feedback-invalid.mlir |
+| ac.barrier | ACIR_BarrierOp | test/ACIR/barrier.mlir | test/ACIR/barrier-invalid.mlir |
+| ac.credit | ACIR_CreditOp | test/ACIR/credit.mlir | test/ACIR/credit-invalid.mlir |
+| ac.credit.yield | ACIR_CreditYieldOp | test/ACIR/credit.mlir | test/ACIR/credit-invalid.mlir |
+| ac.dependency | ACIR_DependencyOp | test/ACIR/dependency.mlir | test/ACIR/dependency-invalid.mlir |
+| ac.dependency.yield | ACIR_DependencyYieldOp | test/ACIR/dependency.mlir | test/ACIR/dependency-invalid.mlir |
+| ac.memory.instance | ACIR_MemoryInstanceOp | test/ACIR/memory.mlir | test/ACIR/memory-invalid.mlir |
+| ac.memory.request | ACIR_MemoryRequestOp | test/ACIR/memory.mlir | test/ACIR/memory-invalid.mlir |
+| ac.memory.yield | ACIR_MemoryYieldOp | test/ACIR/memory.mlir | test/ACIR/memory-invalid.mlir |
+| ac.reorder | ACIR_ReorderOp | test/ACIR/reorder.mlir | test/ACIR/reorder-invalid.mlir |
+| ac.reorder.yield | ACIR_ReorderYieldOp | test/ACIR/reorder.mlir | test/ACIR/reorder-invalid.mlir |
+| ac.feedback | ACIR_FeedbackOp | test/ACIR/control-feedback.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/control-feedback-invalid.mlir |
+| ac.feedback.yield | ACIR_FeedbackYieldOp | test/ACIR/control-feedback.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/control-feedback-invalid.mlir |
+| ac.scope | ACIR_ScopeOp | test/ACIR/memory.mlir
test/ACIR/scope.mlir | test/ACIR/memory-invalid.mlir
test/ACIR/scope-invalid.mlir |
+| ac.scope.yield | ACIR_ScopeYieldOp | test/ACIR/memory.mlir
test/ACIR/scope.mlir | test/ACIR/memory-invalid.mlir
test/ACIR/scope-invalid.mlir |
+| ac.firing | ACIR_FiringOp | test/ACIR/firing.mlir | test/ACIR/firing-invalid.mlir |
+| ac.firing.yield | ACIR_FiringYieldOp | test/ACIR/firing.mlir | test/ACIR/firing-invalid.mlir |
+| ac.queue.peek | ACIR_QueuePeekOp | test/ACIR/firing.mlir | test/ACIR/firing-invalid.mlir |
+| ac.queue.pop | ACIR_QueuePopOp | test/ACIR/firing.mlir | test/ACIR/firing-invalid.mlir |
+| ac.queue.push | ACIR_QueuePushOp | test/ACIR/firing.mlir | test/ACIR/firing-invalid.mlir |
+| ac.try_send | ACIR_TrySendOp | test/ACIR/process-valid.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.try_recv | ACIR_TryRecvOp | test/ACIR/process-valid.mlir | test/ACIR/process-invalid.mlir |
+| ac.schedule | ACIR_ScheduleOp | test/ACIR/process-valid.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.wait_until | ACIR_WaitUntilOp | test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir
test/Analysis/process-state-pass.mlir
test/Analysis/process-state-verifier.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/whole-model.mlir | test/ACIR/process-invalid.mlir |
+| ac.wait_for | ACIR_WaitForOp | test/ACIR/process-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/runtime-references-invalid.mlir |
+| ac.await_event | ACIR_AwaitEventOp | test/ACIR/process-valid.mlir | test/ACIR/process-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.yield_sim | ACIR_YieldSimOp | test/ACIR/contracts-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir
test/Analysis/process-state-pass.mlir
test/Analysis/process-state-verifier.mlir
test/Bindings/resolve-ambiguous.mlir
test/Bindings/resolve-empty.mlir
test/Bindings/resolve-missing.mlir
test/Bindings/resolve-valid.mlir
test/Conversion/atomic-failure.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Python/frontend-lowering.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir
test/Transforms/zero-delay-cycles.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/runtime-references-invalid.mlir
test/ACIR/trace-invalid.mlir
test/Conversion/bindings-invalid.mlir
test/Conversion/process-invalid.mlir |
+| ac.trace.open | ACIR_TraceOpenOp | test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir
test/Transforms/freeze-topology.mlir | test/ACIR/trace-invalid.mlir |
+| ac.trace.next | ACIR_TraceNextOp | test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir | test/ACIR/trace-invalid.mlir |
+| ac.trace.decode | ACIR_TraceDecodeOp | test/ACIR/process-valid.mlir
test/ACIR/trace-valid.mlir | test/ACIR/trace-invalid.mlir |
+| ac.trace.eof | ACIR_TraceEofOp | test/ACIR/trace-valid.mlir | test/ACIR/trace-invalid.mlir |
+| ac.trace.position | ACIR_TracePositionOp | test/ACIR/trace-valid.mlir | test/ACIR/trace-invalid.mlir |
+| ac.require | ACIR_RequireOp | test/ACIR/contracts-valid.mlir
test/Transforms/freeze-topology.mlir | test/ACIR/contracts-invalid.mlir |
+| ac.ensure | ACIR_EnsureOp | test/ACIR/contracts-valid.mlir
test/Transforms/freeze-topology.mlir | test/ACIR/contracts-invalid.mlir |
+| ac.assert | ACIR_AssertOp | test/ACIR/contracts-valid.mlir
test/ACIR/process-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/credit-invalid.mlir
test/ACIR/dependency-invalid.mlir
test/ACIR/firing-invalid.mlir
test/ACIR/reorder-invalid.mlir
test/ACIR/transform-invalid.mlir |
+| ac.probe | ACIR_ProbeOp | test/ACIR/contracts-valid.mlir
test/ACIR/trace-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.stat | ACIR_StatOp | test/ACIR/contracts-valid.mlir
test/ACIR/trace-valid.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/freeze-topology.mlir
test/Transforms/verify-model.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/runtime-references-invalid.mlir |
+| ac.stat.add | ACIR_StatAddOp | test/ACIR/contracts-valid.mlir
test/ACIR/trace-valid.mlir
test/Transforms/freeze-topology.mlir | test/ACIR/runtime-references-invalid.mlir |
+| ac.instrumentation | ACIR_InstrumentationOp | test/ACIR/contracts-valid.mlir
test/ACIR/hierarchy-valid.mlir
test/Transforms/freeze-topology.mlir | test/ACIR/contracts-invalid.mlir
test/ACIR/hierarchy-invalid.mlir |
+
+## acir types (22)
+
+| type | source symbol | positive coverage | negative coverage |
+| --- | --- | --- | --- |
+| !ac.struct | ACIR_StructType | test/ACIR/declarations-valid.mlir
test/ACIR/memory.mlir
test/ACIR/queue-var-types.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/select.mlir
test/ACIR/types-valid.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/deterministic-canonicalization.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/types-invalid.mlir |
+| !ac.packet | ACIR_PacketType | test/ACIR/declarations-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir |
+| !ac.transaction | ACIR_TransactionType | test/ACIR/protocols-valid.mlir
test/ACIR/records-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/declarations-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| !ac.enum | ACIR_EnumType | test/ACIR/declarations-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/declarations-invalid.mlir |
+| !ac.union | ACIR_UnionType | test/ACIR/declarations-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/types-invalid.mlir |
+| !ac.optional | ACIR_OptionalType | test/ACIR/types-valid.mlir | test/ACIR/review-r2-invalid.mlir
test/ACIR/route-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/types-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| !ac.list | ACIR_ListType | test/ACIR/review-r1-valid.mlir
test/ACIR/types-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/queue-var-types-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir |
+| !ac.vector | ACIR_VectorType | test/ACIR/records-valid.mlir
test/ACIR/review-r1-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/records-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/review-r2-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/types-invalid.mlir |
+| !ac.var | ACIR_VarType | test/ACIR/control-feedback.mlir
test/ACIR/credit.mlir
test/ACIR/dependency.mlir
test/ACIR/expect.mlir
test/ACIR/firing.mlir
test/ACIR/memory.mlir
test/ACIR/queue-var-types.mlir
test/ACIR/reorder.mlir
test/ACIR/route.mlir
test/ACIR/scope.mlir
test/ACIR/select.mlir
test/ACIR/transform.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/control-feedback-invalid.mlir
test/ACIR/credit-invalid.mlir
test/ACIR/dependency-invalid.mlir
test/ACIR/expect-invalid.mlir
test/ACIR/firing-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/queue-var-types-invalid.mlir
test/ACIR/reorder-invalid.mlir
test/ACIR/route-invalid.mlir
test/ACIR/select-invalid.mlir
test/ACIR/transform-invalid.mlir
test/ACIR/var-expressions-invalid.mlir |
+| !ac.queue | ACIR_QueueType | test/ACIR/barrier.mlir
test/ACIR/broadcast.mlir
test/ACIR/control-feedback.mlir
test/ACIR/credit.mlir
test/ACIR/dependency.mlir
test/ACIR/expect.mlir
test/ACIR/firing.mlir
test/ACIR/fork.mlir
test/ACIR/memory.mlir
test/ACIR/observe.mlir
test/ACIR/queue-var-types.mlir
test/ACIR/reorder.mlir
test/ACIR/route.mlir
test/ACIR/scope.mlir
test/ACIR/select.mlir
test/ACIR/source-sink.mlir
test/ACIR/transform.mlir
test/ACIR/var-expressions.mlir
test/CodeGen/arbiter-verilog.mlir
test/CodeGen/arbiter.mlir
test/CodeGen/atomic-transform.mlir
test/CodeGen/popcount-verilog.mlir
test/CodeGen/popcount.mlir
test/Transforms/queue-var-cse.mlir | test/ACIR/barrier-invalid.mlir
test/ACIR/broadcast-invalid.mlir
test/ACIR/control-feedback-invalid.mlir
test/ACIR/credit-invalid.mlir
test/ACIR/dependency-invalid.mlir
test/ACIR/expect-invalid.mlir
test/ACIR/firing-invalid.mlir
test/ACIR/fork-invalid.mlir
test/ACIR/memory-invalid.mlir
test/ACIR/observe-invalid.mlir
test/ACIR/queue-var-types-invalid.mlir
test/ACIR/reorder-invalid.mlir
test/ACIR/route-invalid.mlir
test/ACIR/scope-invalid.mlir
test/ACIR/select-invalid.mlir
test/ACIR/source-sink-invalid.mlir
test/ACIR/transform-invalid.mlir |
+| !ac.array | ACIR_ArrayType | test/ACIR/queue-var-types.mlir | test/ACIR/queue-var-types-invalid.mlir |
+| !ac.map | ACIR_MapType | test/ACIR/queue-var-types.mlir | test/ACIR/queue-var-types-invalid.mlir |
+| !ac.set | ACIR_SetType | test/ACIR/queue-var-types.mlir | test/ACIR/queue-var-types-invalid.mlir |
+| !ac.flow | ACIR_FlowType | test/ACIR/protocols-valid.mlir
test/ACIR/types-valid.mlir
test/Transforms/verify-model.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/types-invalid.mlir |
+| !ac.endpoint | ACIR_EndpointType | test/ACIR/interfaces-valid.mlir
test/ACIR/types-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/protocols-invalid.mlir
test/ACIR/resources-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir |
+| !ac.resource_ref | ACIR_ResourceRefType | test/ACIR/types-valid.mlir | test/ACIR/topology-review-r1-invalid.mlir |
+| !ac.channel | ACIR_ChannelType | test/ACIR/interfaces-valid.mlir
test/ACIR/port-mapping-review-r2.mlir
test/ACIR/resources-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir
test/Transforms/deterministic-canonicalization.mlir | test/ACIR/interfaces-invalid.mlir
test/ACIR/interfaces-review-r1-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir
test/ACIR/types-invalid.mlir |
+| !ac.duration | ACIR_DurationType | test/ACIR/types-valid.mlir | test/ACIR/types-invalid.mlir |
+| !ac.rate | ACIR_RateType | test/ACIR/types-valid.mlir | test/ACIR/types-invalid.mlir |
+| !ac.event | ACIR_EventType | test/ACIR/process-valid.mlir
test/ACIR/resources-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/resources-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir |
+| !ac.address | ACIR_AddressType | test/ACIR/types-valid.mlir | test/ACIR/types-invalid.mlir |
+| !ac.resource_token | ACIR_ResourceTokenType | test/ACIR/process-valid.mlir
test/ACIR/types-valid.mlir | test/ACIR/hierarchy-invalid.mlir
test/ACIR/process-invalid.mlir
test/ACIR/review-r1-invalid.mlir
test/ACIR/topology-review-r1-invalid.mlir |
+
+## acsim operations (22)
+
+| operation | source symbol | positive coverage | negative coverage |
+| --- | --- | --- | --- |
+| acsim.model | ACSim_ModelOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/driver-errors.mlir
test/CodeGen/driver-stages.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/structure.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.type | ACSim_TypeOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/process-basic.mlir
test/Conversion/structure.mlir
test/Conversion/time-domains.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| acsim.binding | ACSim_BindingOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/Conversion/bindings.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.module | ACSim_ModuleOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/driver-errors.mlir
test/CodeGen/driver-stages.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| acsim.instance | ACSim_InstanceOp | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/extension-provider.mlir
test/Conversion/bindings.mlir
test/Conversion/hierarchy.mlir
test/Conversion/typed-graph.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.array | ACSim_ArrayOp | test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/multidimensional-array.mlir
test/Conversion/collections.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.element | ACSim_ElementOp | test/ACSim/ops-valid.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.port | ACSim_PortOp | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/Conversion/typed-graph.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.resource | ACSim_ResourceOp | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.bind | ACSim_BindOp | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.inline | ACSim_InlineOp | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/Conversion/process-live-values.mlir
test/Conversion/pure-results.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| acsim.process | ACSim_ProcessOp | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/structure.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/process-invalid.mlir |
+| acsim.live.load | ACSim_LiveLoadOp | test/ACSim/ops-valid.mlir
test/Conversion/process-live-values.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.live.store | ACSim_LiveStoreOp | test/ACSim/ops-valid.mlir
test/Conversion/process-live-values.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.invoke | ACSim_InvokeOp | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/process-basic.mlir
test/Conversion/structure.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.continue | ACSim_ContinueOp | test/ACSim/ops-valid.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.suspend | ACSim_SuspendOp | test/ACSim/ops-valid.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/process-basic.mlir
test/Conversion/process-control-flow.mlir
test/Conversion/process-live-values.mlir
test/Conversion/structure.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.terminate | ACSim_TerminateOp | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.export | ACSim_ExportOp | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/Conversion/pure-results.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.dispatch | ACSim_DispatchOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/process-basic.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| acsim.activate | ACSim_ActivateOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/structure.mlir
test/Conversion/typed-graph.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+| acsim.return | ACSim_ReturnOp | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/CodeGen/driver-errors.mlir
test/CodeGen/driver-stages.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir
test/Conversion/pure-results.mlir
test/Conversion/structure.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir |
+
+## acsim types (11)
+
+| type | source symbol | positive coverage | negative coverage |
+| --- | --- | --- | --- |
+| !acsim.value | ACSim_ValueType | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir | test/ACSim/ops-invalid.mlir |
+| !acsim.expr | ACSim_ExprType | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir
test/Conversion/pure-results.mlir | test/ACSim/ops-invalid.mlir
test/Conversion/bindings-invalid.mlir |
+| !acsim.owner | ACSim_OwnerType | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/ACSim/types-valid.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/Conversion/bindings.mlir
test/Conversion/collections.mlir
test/Conversion/hierarchy.mlir | test/ACSim/ops-invalid.mlir
test/ACSim/types-invalid.mlir |
+| !acsim.ref | ACSim_RefType | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir | test/ACSim/ops-invalid.mlir
test/ACSim/types-invalid.mlir |
+| !acsim.port | ACSim_PortType | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir
test/Conversion/whole-model.mlir | test/ACSim/ops-invalid.mlir
test/ACSim/types-invalid.mlir |
+| !acsim.resource | ACSim_ResourceType | test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir | test/ACSim/ops-invalid.mlir
test/ACSim/types-invalid.mlir |
+| !acsim.array | ACSim_ArrayType | test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/ACSim/types-valid.mlir
test/CodeGen/multidimensional-array.mlir
test/Conversion/collections.mlir | test/ACSim/ops-invalid.mlir
test/ACSim/types-invalid.mlir |
+| !acsim.object_id | ACSim_ObjectIdType | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/ACSim/types-valid.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/structure.mlir | test/ACSim/ops-invalid.mlir |
+| !acsim.activation_id | ACSim_ActivationIdType | test/ACSim/generated-call-contract.mlir
test/ACSim/generated-wrapper-activation.mlir
test/ACSim/ops-valid.mlir
test/ACSim/reusable-modules.mlir
test/ACSim/types-valid.mlir
test/CodeGen/extension-provider.mlir
test/CodeGen/multidimensional-array.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/structure.mlir | test/ACSim/ops-invalid.mlir |
+| !acsim.pc | ACSim_PcType | test/ACSim/generated-call-contract.mlir
test/ACSim/types-valid.mlir | test/ACSim/types-invalid.mlir |
+| !acsim.wake | ACSim_WakeType | test/ACSim/generated-call-contract.mlir
test/ACSim/ops-valid.mlir
test/ACSim/types-valid.mlir
test/CodeGen/process-control-flow.mlir
test/Conversion/process-basic.mlir
test/Conversion/structure.mlir | test/ACSim/ops-invalid.mlir |
diff --git a/components/agentic-circuit/docs/spec/50-verification/pyc-verilog-backend.md b/components/agentic-circuit/docs/spec/50-verification/pyc-verilog-backend.md
new file mode 100644
index 00000000..50f1f558
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/50-verification/pyc-verilog-backend.md
@@ -0,0 +1,63 @@
+# In-tree PYC-to-Verilog bridge
+
+## Verify the integrated Verilog bridge {#VER-PYC-VERILOG-001}
+
+
+The `acir-queue-veriloggen.py` entrypoint closes the first integrated backend
+slice without introducing a second ACIR lowering:
+
+```text
+frozen ACIR
+ -> acir-queue-pycgen
+ -> canonical textual PYC IR
+ -> PYC compatibility emitter
+ -> self-contained Verilog (PYC runtime modules embedded)
+```
+
+The runtime modules under `resources/pyc_runtime/verilog/` are the small
+cycle-level primitives migrated from pyCircuit's runtime surface: `pyc_fifo`,
+`pyc_reg`, `pyc_popcount`, and `pyc_rr_arbiter`. The bridge currently covers
+the operations needed by the golden Popcount and round-robin Queue slices:
+FIFO, register, wiring, constants, mux/boolean/integer expressions, concat,
+extract, Popcount, and round-robin Arbiter. Unsupported PYC operations fail
+explicitly instead of silently producing incomplete RTL.
+
+Pure Python compute regions spell population count as `ac.popcount(value)`.
+The bridge also preserves canonical `pyc.assert` operations as simulation-only
+Verilog checks guarded by synthesis translation directives; failure semantics
+are not silently removed from Verilator runs.
+
+Example:
+
+```bash
+python tools/acir-queue-veriloggen.py test/CodeGen/arbiter-verilog.mlir \
+ --pycgen build/dev-llvm22/bin/acir-queue-pycgen \
+ --emit-pyc /tmp/arbiter.pyc.mlir \
+ --output /tmp/arbiter.v
+```
+
+For a constrained WSL host, build only the producer needed by this bridge and
+keep Ninja single-threaded:
+
+```bash
+cmake --build build/dev-llvm22 --target acir-queue-pycgen -j1
+python tools/acir-queue-veriloggen.py test/CodeGen/arbiter-verilog.mlir \
+ --pycgen build/dev-llvm22/bin/acir-queue-pycgen --timeout 120 \
+ --output /tmp/arbiter.v
+```
+
+The timeout guards against an accidentally started full build or malformed
+input keeping the lowering process alive. It does not start a compiler build;
+the bridge consumes an already-built `acir-queue-pycgen` executable.
+
+The generated Verilog is self-contained, so Verilator/Yosys can consume one
+file. This is an integration bridge, not yet the generic registry-driven
+`pycc` replacement. The next step is to replace the textual compatibility
+emitter with the shared PYC MLIR dialect/emitter once the repositories agree on
+one LLVM/MLIR toolchain.
+
+The same path is covered by `test/CodeGen/popcount-verilog.mlir`; the
+fixture exercises packed-field extraction (`i12` to `i8`) before the qualified
+`pyc.popcount` primitive. `test/CodeGen/pyc-primitives-smoke.sv` provides a
+bounded N=2/N=3/N=4 arbitration, popcount, and FIFO simulation. The smoke is
+part of `PycVerilogBackendTests` whenever Verilator is available.
diff --git a/components/agentic-circuit/docs/spec/50-verification/repository-layout.md b/components/agentic-circuit/docs/spec/50-verification/repository-layout.md
new file mode 100644
index 00000000..26022e30
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/50-verification/repository-layout.md
@@ -0,0 +1,9 @@
+# Repository layout verification
+
+## Enforce the release-owned layout {#VER-LAYOUT-001}
+
+
+`scripts/check-release-layout.py` rejects tracked product-version and phase
+paths and checks the required semantic roots. `scripts/check-ndf.py` validates
+clause metadata, stable IDs, relationship targets, and L1 verification
+coverage. Repository contract tests execute both gates.
diff --git a/components/agentic-circuit/docs/spec/README.md b/components/agentic-circuit/docs/spec/README.md
new file mode 100644
index 00000000..063c88a3
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/README.md
@@ -0,0 +1,45 @@
+# Agentic Circuit Specifications
+
+This directory contains the human-readable contracts for Agentic Circuit.
+Machine-readable schemas under [`schemas`](../../schemas) and MLIR ODS
+definitions under [`include/acir`](../../include/acir) remain the executable
+sources of truth.
+
+The generated [official Queue building-block catalog](../../schemas/opcodes.json)
+records the closed opcode roles, arity, constants, backend realizations, and
+refinement observations.
+
+## Current manuals
+
+- [Agentic Circuit Specification Manual](agentic-circuit.md) defines the
+ implementation-facing serial Python, ACIR, gfsim, PYC, and refinement
+ contract.
+- [Agentic Circuit 团队 Specification 手册](agentic-circuit.zh-CN.md)
+ provides a Chinese teammate-facing overview, common patterns, executable
+ examples, backend differences, and troubleshooting guidance.
+
+## NDF decision spine
+
+The repository follows the restricted NDF profile declared in
+[`ndf.yaml`](ndf.yaml). Stable clause IDs connect the current architecture,
+decisions, historical evidence, and verification:
+
+- [`ARC-RELEASE-001`, `ARC-LAYOUT-001`, and `ARC-HISTORY-001`](00-charter/scope.md)
+ define release ownership, semantic source partitions, and history policy.
+- [`D-RELEASE-LAYOUT-001`](decisions/D-RELEASE-LAYOUT-001.md) records the
+ hard-break release-neutral layout decision.
+- [`D-BLOCK-MODEL-001`](decisions/D-BLOCK-MODEL-001.md) records the current
+ Queue/Var building-block model.
+- [`REF-HISTORY-001`](refs/history.md) pins removed historical specifications
+ to an immutable Git revision.
+- [`VER-LAYOUT-001`](50-verification/repository-layout.md) binds these rules to
+ executable repository checks.
+- [`VER-PYC-VERILOG-001`](50-verification/pyc-verilog-backend.md) records the
+ integrated PYC-to-Verilog bridge and its executable fixtures.
+- [IR coverage ledger](50-verification/ir-coverage.md) is generated from the
+ current ACIR/ACSim manifests and lit coverage.
+
+Product releases are represented by Git tags and GitHub Releases. The source
+tree does not retain product-version or implementation-phase paths, aliases,
+or compatibility symlinks. Serialized contract epochs and external dependency
+pins remain versioned where interoperability and reproducibility require them.
diff --git a/components/agentic-circuit/docs/spec/agentic-circuit.md b/components/agentic-circuit/docs/spec/agentic-circuit.md
new file mode 100644
index 00000000..31e22192
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/agentic-circuit.md
@@ -0,0 +1,1412 @@
+# Agentic Circuit Specification Manual
+
+| Field | Value |
+| --- | --- |
+| Specification | Serial Python, Queue/Var ACIR, typed gfsim, and PYC refinement |
+| Target contract epoch | `0.3` |
+| Status | Current implementation contract; serialized epoch `0.3` is active on `main` |
+| Public namespace | `ac` |
+| Audience | Frontend, compiler, simulator, and RTL contributors |
+| Design background | [NDF block-model decision](decisions/D-BLOCK-MODEL-001.md) |
+| Executable examples | [Pipeline examples](../../examples/pipelines/README.md) |
+
+## Purpose
+
+Agentic Circuit lets an author describe a static circuit as serial-looking
+Python. The author names values and lexical scopes; the compiler infers queue
+connections, scope boundaries, typed payloads, and common hardware building
+blocks. The same frozen ACIR graph can generate:
+
+- a deterministic typed gfsim C++ model built around `SimQueue`; and
+- canonical PYC IR that external pinned `pycc` lowers to PYC C++ and Verilog.
+
+This manual is the implementation-facing specification for teammates. It
+defines the supported programming model, ACIR contracts, backend obligations,
+examples, and current limitations. The NDF
+[block-model decision](decisions/D-BLOCK-MODEL-001.md) records the architectural
+rationale; this document records the executable contract.
+
+
+
+The editable diagram source is
+[`agentic-circuit-pipeline.drawio`](images/agentic-circuit-pipeline.drawio).
+
+## Status and authority
+
+The words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are
+normative requirements for the current contract.
+
+Producers emit exact serialized epoch `0.3`; consumers reject other epochs
+before interpreting the artifact. The toolchain provides no compatibility
+alias or best-effort conversion.
+
+When this manual and implementation disagree, use the following authority
+order:
+
+1. machine-readable schema and MLIR ODS definitions;
+2. verifier and conformance tests;
+3. this manual;
+4. NDF decisions and references.
+
+The principal machine-readable and executable sources are:
+
+- [`ACIRTypes.td`](../../include/acir/Dialect/ACIR/ACIRTypes.td) for Queue, Var,
+ and collection types;
+- [`ACIROps.td`](../../include/acir/Dialect/ACIR/ACIROps.td) for operation
+ signatures;
+- [`ACIROps.cpp`](../../lib/Dialect/ACIR/ACIROps.cpp) for semantic verification;
+- [`QueueGraphPlan.cpp`](../../lib/CodeGen/QueueGraphPlan.cpp) for the frozen
+ backend plan;
+- [`opcodes.json`](../../schemas/opcodes.json) for the closed official
+ building-block catalog and backend availability;
+- [`queue.h`](../../include/gfsim/queue.h) and
+ [`queue_blocks.h`](../../include/gfsim/queue_blocks.h) for gfsim behavior;
+- [`test_queue_frontend.py`](../../tests/python_frontend/test_queue_frontend.py)
+ for accepted and rejected Python syntax;
+- [`test/ACIR`](../../test/ACIR) for ACIR conformance tests.
+
+The executable conformance suites and generated
+[IR coverage ledger](50-verification/ir-coverage.md) track the live
+requirement-by-requirement status.
+
+## Core mental model
+
+### Serial Python elaborates a static graph
+
+An `@ac.system` body is not an imperative program that runs once per simulated
+cycle. The frontend parses its Python AST and treats statements as graph
+construction in source order.
+
+```python
+@ac.system
+def pipeline() -> None:
+ incoming = ac.source(int)
+ adjusted = incoming.apply(lambda item: item + 1)
+ ac.sink(adjusted)
+```
+
+This source creates two Queue values and one persistent transform block:
+
+```text
+incoming Queue -> transform(item + 1) -> adjusted Queue -> sink
+```
+
+The frontend does not require explicit module input or output declarations.
+`ac.source(...)` and `ac.sink(...)` define the current executable boundary, and
+lexical uses determine scope inputs and outputs.
+
+### Queue is state; Var is combinational value
+
+`!ac.queue` is a finite, typed, stateful FIFO channel. It has positive depth,
+positive latency, occupancy, backpressure, stable identity, and commit-time
+effects.
+
+`!ac.var` is an immutable, zero-latency value. It has no occupancy, capacity,
+push, pop, or independent runtime identity. Lambda arguments, constants,
+arithmetic results, comparisons, field projections, and immutable field updates
+are Vars.
+
+```text
+!ac.queue stateful channel
+!ac.var combinational scalar
+!ac.queue> stateful typed channel
+!ac.var> immutable token value
+```
+
+A Queue MUST have latency of at least one. A zero-latency Queue is invalid;
+zero-latency logic belongs in a Var region.
+
+### Mutable channel, immutable token
+
+Queue state changes at commit. Token payloads do not mutate in place.
+
+```python
+# Valid: creates a new immutable token value.
+next_item = item.with_fields(remaining=item.remaining - 1)
+
+# Invalid: mutates the input object.
+item.remaining -= 1
+```
+
+The frontend and backends MAY copy or move an immutable token internally, but
+they MUST NOT expose mutable aliases that change a token already stored in a
+Queue.
+
+### Opcodes are common building blocks
+
+The public `ac.*` inventory is closed and repository-owned. Users compose
+common transport, computation, state, boundary, and observation blocks. They
+MUST NOT define private opcodes, C++ providers, PYC providers, or raw Verilog
+providers.
+
+Application stages such as `decode`, `rename`, `dispatch`, and `retire` are
+scope names or compositions. They are not generic ACIR opcodes.
+
+Generate the canonical catalog directly from the shared backend contract table:
+
+```sh
+build/dev-llvm22/bin/acir-opcode-catalog
+agentic-circuit schema opcode ac.transform
+```
+
+## Python authoring contract
+
+### System declaration
+
+A Queue/Var system uses `@ac.system` and takes no parameters. Inputs and outputs
+are inferred from the body.
+
+```python
+import agentic_circuit as ac
+
+
+@ac.system
+def pipeline() -> None:
+ value = ac.source(int)
+ ac.sink(value)
+```
+
+The source file is compiled through AST capture. The queue primitives inside
+the system body are syntax markers; ordinary Python execution of the body is
+not the compilation path.
+
+### Payload structures
+
+Use `@ac.struct` to define a compile-time token layout.
+
+```python
+@ac.struct
+class WorkItem:
+ value: ac.u32
+ route: ac.u2
+ remaining: ac.u16
+ valid: bool
+```
+
+The current frontend accepts these scalar field spellings:
+
+| Python spelling | ACIR element type |
+| --- | --- |
+| `bool` | `i1` |
+| `int` | `i64` |
+| `ac.u1`, `ac.u2`, `ac.u4` | `i1`, `i2`, `i4` |
+| `ac.u8`, `ac.u16`, `ac.u32`, `ac.u64` | corresponding integer width |
+| `ac.s8`, `ac.s16`, `ac.s32`, `ac.s64` | corresponding integer width |
+
+Field order is declaration order. Fields MUST be unique and annotated. The
+current ACIR integer type freezes width but not signedness as a distinct type;
+do not rely on unsigned comparison semantics until the signedness contract is
+made explicit.
+
+### Source and sink
+
+`ac.source(T, depth=N, latency=L)` creates a Queue boundary with payload `T`.
+`depth` and `latency` default to one and MUST be positive compile-time integers.
+
+```python
+incoming = ac.source(WorkItem, depth=8, latency=1)
+ac.sink(incoming)
+```
+
+`ac.sink(queue)` consumes tokens from a Queue. A system MUST contain at least
+one source Queue and at least one sink.
+
+### Transform with `apply`
+
+`queue.apply(lambda item: expression, depth=N, latency=L)` creates an
+`ac.transform` block and one output Queue.
+
+```python
+updated = incoming.apply(
+ lambda item: item.with_fields(
+ value=(item.value + 1) * 2,
+ remaining=item.remaining - 1,
+ ),
+ depth=4,
+ latency=2,
+)
+```
+
+The current lambda subset supports:
+
+- the lambda parameter itself;
+- integer and Boolean constants;
+- structure field reads;
+- `+`, `-`, and `*` over identical Var types;
+- `==`, `!=`, `<`, `<=`, `>`, and `>=`;
+- immutable `with_fields(...)` updates.
+
+The lambda MUST take exactly one argument and MUST return the Queue payload
+type. Function calls other than `with_fields`, mutation, I/O, allocation,
+ambient state access, and arbitrary Python expressions are rejected.
+
+### Lexical scope and inferred boundaries
+
+`with ac.scope("name"):` defines ownership and hierarchy. It does not declare
+ports.
+
+```python
+incoming = ac.source(int)
+
+with ac.scope("frontend"):
+ adjusted = incoming.apply(lambda item: item + 1)
+ with ac.scope("inner"):
+ completed = adjusted.apply(lambda item: item * 2)
+
+ac.sink(completed)
+```
+
+The compiler infers:
+
+- `incoming` as a borrowed input of `/frontend`;
+- `adjusted` as a Queue owned inside `/frontend`;
+- `completed` as an exported output of `/frontend/inner` and `/frontend`;
+- parent ownership for an interconnect at the lowest common lexical ancestor.
+
+Scope names MUST be non-empty, and one lexical path MUST NOT be declared twice.
+
+### Multiple consuming uses
+
+Queue consumption is destructive. If one Queue variable feeds multiple
+`apply` statements, the frontend inserts `ac.broadcast` at the lexical lowest
+common ancestor.
+
+```python
+incoming = ac.source(int)
+left = incoming.apply(lambda item: item + 1)
+right = incoming.apply(lambda item: item + 2)
+```
+
+The inserted broadcast is strict and atomic: it pops the input only when every
+output can accept the token. It has no hidden per-output progress state.
+
+### Explicit decoupled fork
+
+Use `fork` when outputs may accept the token on different cycles.
+
+```python
+left, right = incoming.fork(outputs=2, depth=2, latency=1)
+```
+
+`ac.fork` retains one token and a per-output delivered mask until every output
+has accepted that token. Each output receives the token exactly once. The input
+is popped only after delivery to all outputs completes.
+
+This distinction is normative:
+
+| Block | Acceptance rule | Hidden progress state |
+| --- | --- | --- |
+| `ac.broadcast` | all outputs accept in one atomic firing | none |
+| `ac.fork` | outputs may accept independently | per-token delivered mask |
+
+### Route
+
+`route` sends one token to exactly one statically declared output.
+
+```python
+scalar, vector, cube, tma = prepared.route(
+ outputs=4,
+ key=lambda item: item.route,
+ depth=2,
+ latency=1,
+)
+```
+
+The output tuple arity MUST equal `outputs`. The selector lambda returns an
+integer or enum-like Var. A selector outside `[0, outputs)` is a deterministic
+runtime failure named `route_selector_out_of_range`; it is not wrapped or
+clamped.
+
+### Merge
+
+`merge` combines two or more Queues with identical payload types.
+
+```python
+completed = scalar_done.merge(
+ vector_done,
+ cube_done,
+ tma_done,
+ policy="round_robin",
+ depth=8,
+ latency=1,
+)
+```
+
+Supported policies are:
+
+- `priority`: select the first ready input in source order;
+- `round_robin`: begin from a committed cursor and advance the cursor after a
+ successful transfer.
+
+The output Queue applies ordinary capacity and latency rules.
+
+### Dependency scheduling
+
+`depend` is the generic bounded dependency window. It admits typed tokens,
+starts a token when its predecessor is complete, counts its declared execution
+cost, and emits tokens in completion order.
+
+```python
+completed = issued.depend(
+ key=lambda item: item.sequence_id,
+ waits_for=lambda item: item.waits_for,
+ resource=lambda item: item.route,
+ cost=lambda item: item.cycles,
+ capacity=8,
+ resources=4,
+ no_dependency=255,
+ depth=8,
+ latency=1,
+)
+```
+
+The three lambdas are pure Var regions. `key` and `waits_for` MUST return the
+same integer Var type, no wider than 64 bits. `no_dependency` MUST fit that
+type. `resource` selects one of the statically declared resources; each resource
+admits at most one executing token at a time. `cost` MUST return a positive
+integer at runtime. Dependencies refer to tokens retained in the bounded
+window; a missing predecessor blocks the token and can participate in deadlock
+diagnostics.
+
+### Credit scheduling
+
+`credit` is a bounded parallel completion window. It admits at most `credits`
+tokens, evaluates a pure per-token cost, advances every occupied slot once per
+epoch, and returns the slot when the completed token transfers to the output
+Queue.
+
+```python
+completed = issued.credit(
+ cost=lambda item: item.cycles,
+ credits=2,
+ depth=4,
+ latency=1,
+)
+```
+
+`credits`, output `depth`, and output `latency` are positive compile-time
+constants. The cost lambda MUST return an integer Var no wider than 64 bits.
+Every accepted runtime cost MUST be positive; zero or negative cost produces
+the deterministic `credit_nonpositive_cost` failure/assertion.
+
+Each slot counts down independently, so completion order may differ from input
+order. When multiple slots are complete, the block chooses the lowest canonical
+slot index and emits at most one token per epoch. Admission and retirement may
+occur in the same epoch when they use different committed slots. A slot retired
+in the current Xfer is not reused until a later epoch.
+
+### Barrier synchronization
+
+`barrier` synchronizes two or more Queue heads and publishes a positionally
+matching output tuple as one atomic firing. Input payload types may differ.
+
+```python
+left_ready, right_ready = left.barrier(
+ right,
+ depth=2,
+ latency=1,
+)
+```
+
+All input Queues MUST be distinct. The output count MUST equal the input count,
+and each output payload type MUST match its corresponding input. The barrier
+waits until every input can pop and every output can accept; then all pops and
+pushes commit together. Before that Xfer, it publishes no partial result.
+
+The output Queues are ordinary independent Queues after the atomic transfer.
+Downstream consumers may therefore drain them on different later epochs without
+changing the barrier firing contract.
+
+### Typed memory
+
+`memory` declares a physical single-read/single-write state instance. One or
+more logical request endpoints connect to it; requests and responses use one
+shared structure type. Three pure lambdas select the address, write enable, and
+write data; `result_field` names the response field replaced with old data.
+
+```python
+@ac.struct
+class MemoryRequest:
+ address: ac.u4
+ write: ac.u1
+ data: ac.u16
+ tag: ac.u8
+
+
+sram = ac.memory(ac.u16, entries=16, init=0, latency=3)
+requests = ac.source(MemoryRequest, depth=4, latency=1)
+responses = sram.request(
+ requests,
+ address=lambda item: item.address,
+ write=lambda item: item.write,
+ data=lambda item: item.data,
+ result_field="data",
+ depth=4,
+)
+ac.sink(responses)
+```
+
+`entries`, `init`, instance `latency`, `result_field`, and `depth` are
+compile-time constants. `entries`, `depth`, and instance `latency` MUST be
+positive. The response Queue has fixed latency one. The address MUST
+be an integer Var no wider than 64 bits and wide enough to represent every
+entry. The write policy MUST return `!ac.var`. The data policy and result
+field MUST have the same integer type, no wider than 64 bits. The current contract supports
+deterministic zero initialization only, so `init` MUST equal zero.
+
+Every accepted request performs a read. A request accepted in cycle `T` can
+offer its response no earlier than `T + latency`; the instance remains busy
+throughout that interval and while the response Queue is blocked. A response
+preserves the request's other fields and replaces `result_field` with the
+pre-transfer memory value. A
+write commits at Xfer. Therefore a read and write to the same address in one
+request returns old data and makes the new data visible to a later request.
+
+### Reorder
+
+`reorder` accepts out-of-order completions and releases them in monotonically
+increasing key order. It is the generic ordering primitive used to compose a
+ROB-like retirement path; `retire` itself remains an application scope.
+
+```python
+retired = completed.reorder(
+ key=lambda item: item.sequence_id,
+ capacity=64,
+ start=0,
+ depth=8,
+ latency=1,
+)
+```
+
+The key lambda MUST return an integer Var no wider than 64 bits. `capacity`,
+`start`, output `depth`, and output `latency` are compile-time constants. The
+non-negative `start` value MUST fit the key width. The
+block backpressures when every entry is occupied and emits only the token whose
+key equals the committed next key. Duplicate, negative, or already retired keys
+are invalid.
+
+### Observation
+
+`ac.observe(queue)` reads the committed Queue head without consuming it and
+without participating in backpressure.
+
+```python
+ac.observe(completed)
+ac.sink(completed)
+```
+
+An observation-only use does not cause broadcast insertion. Observations may
+record a new head when the token or committed pop count changes, but MUST NOT
+alter functional state.
+
+### Verification expectation
+
+`ac.expect` is a non-consuming verification leaf for gfsim and PYC testbench
+boundaries.
+
+```python
+ac.expect(
+ completed,
+ predicate=lambda item: item.value > 0,
+ message="value must be positive",
+)
+```
+
+The predicate MUST be pure and return bool. gfsim evaluates each new committed
+head and reports `expectation_failed` without consuming or backpressuring the
+Queue. `ac.expect` is verification-role, not design-role: PYC design emission
+rejects it with an explicit instruction to place the check at the testbench
+boundary. `ac.observe` remains observation-role and may enter design lowering
+because it cannot change functional state.
+
+### Atomic group
+
+Each ordinary `apply` is an atomic input-pop/output-push firing. Use
+`with ac.atomic():` to group at least two independent direct Queue transforms.
+
+```python
+left = ac.source(int)
+right = ac.source(int)
+
+with ac.atomic():
+ left_next = left.apply(lambda item: item + 1)
+ right_next = right.apply(lambda item: item * 2)
+```
+
+All input Queues in the group MUST be unique. The grouped transform fires only
+when every input can pop and every output can push; all effects commit or none
+commit.
+
+### Explicit Python firing effects
+
+Use `firing` when a low-level algorithm is clearer as explicit `peek`, `pop`,
+and `push` effects while keeping the destination Queue implicit.
+
+```python
+outgoing = incoming.firing(
+ lambda queue: queue.push(
+ queue.pop().with_fields(
+ value=queue.peek().value + 1,
+ )
+ )
+)
+```
+
+One Python firing MUST contain exactly one `pop` and one outer `push`; it MAY
+contain repeated non-consuming `peek` calls. `peek` and `pop` return immutable
+token Vars, and `push` requires the unchanged Queue payload type. Queue effects
+are rejected inside ordinary `apply` lambdas.
+
+The frontend normalizes this one-input/one-output form to the standard atomic
+`ac.transform` building block. The lower-level `ac.firing` and
+`ac.queue.peek/pop/push` operations remain the normative ACIR effect contract
+for future multi-Queue/state-effect normalization; generated hot paths do not
+interpret Python effect objects.
+
+### Bounded feedback
+
+The current runtime-loop form is one Queue rebinding through one `apply`.
+
+```python
+current = ac.source(WorkItem)
+
+while current.remaining > 0:
+ current = current.apply(
+ lambda item: item.with_fields(
+ value=item.value + 1,
+ remaining=item.remaining - 1,
+ ),
+ depth=2,
+ latency=1,
+ )
+
+ac.sink(current)
+```
+
+The frontend lowers this form to `ac.feedback` with a stateful feedback Queue.
+The current compiler freezes `max_iterations = 1024`. When the condition is
+false, the current token exits unchanged. When it is true, the immutable update
+is recirculated. Exceeding the bound reports `feedback_iteration_limit`.
+
+A bounded loop may place one runtime `break` guard before its Queue update and
+one runtime `continue` guard at the tail:
+
+```python
+while current.remaining > 0:
+ if current.stop:
+ break
+ current = current.apply(step)
+ if current.skip:
+ continue
+```
+
+The leading `break` becomes part of the explicit feedback continuation
+condition; a matching token exits unchanged. A tail `continue` targets the same
+feedback edge as normal loop fallthrough and is normalized to that edge. Other
+statement placement, loop `else`, and more than one Queue update remain
+deterministic errors.
+
+### Static collections
+
+Queue collections have compile-time shape and membership.
+
+```python
+lanes = ac.array(
+ 2,
+ lambda lane: ac.source(int, depth=lane + 1),
+)
+named = ac.map({"right": lanes[1], "left": lanes[0]})
+active = ac.set({named["right"], named["left"]})
+
+for lane in active:
+ ac.sink(lane)
+```
+
+Runtime selection from a flat Queue collection uses one explicit control Queue
+and lowers to the official `ac.select` mux. It never creates a runtime Queue
+handle.
+
+```python
+control = ac.source(SelectControl)
+lanes = ac.array(2, lambda index: ac.source(int))
+selected = lanes.select(
+ control,
+ key=lambda item: item.route,
+)
+ac.sink(selected)
+```
+
+The control token and exactly one selected data token transfer atomically. An
+out-of-range selector produces `select_selector_out_of_range`. Nested
+collections MUST first be statically flattened to a flat collection.
+
+The current frontend supports:
+
+- `ac.array(extent, lambda index: ...)` with positive static extent;
+- `ac.map({...})` with unique compile-time `bool`, `int`, or non-empty `str`
+ keys;
+- `ac.set({...})` over unique Queue or nested collection members;
+- nested collections;
+- static indexing;
+- compile-time iteration over a collection.
+
+Map keys and set members are canonicalized. Frozen QueueGraph planning flattens
+collections into statically named Queue members; it never creates a runtime
+Queue pointer or host-order container dependency.
+
+### Static control
+
+`if True` and `if False` are elaborated statically. `for` over
+`range(constant)` or a static Queue collection is expanded at compile time.
+
+```python
+if True:
+ selected = incoming.apply(lambda item: item + 1)
+
+for index in range(2):
+ ac.sink(lanes[index])
+```
+
+One structurally decreasing Queue helper may recurse at compile time:
+
+```python
+def add_stages(queue, count):
+ if count == 0:
+ return queue
+ return add_stages(
+ queue.apply(lambda item: item + 1),
+ count - 1,
+ )
+
+outgoing = add_stages(incoming, 3)
+```
+
+The helper MUST have exactly one Queue parameter and one integer count, a
+`count == 0` identity base case, and one self-call whose count is `count - 1`.
+The call-site depth MUST be a compile-time integer in `[0, 1024]`. The frontend
+expands the helper before ACIR publication; no recursion, call stack, or dynamic
+module creation remains in either backend.
+
+A runtime Queue condition may use the symmetric form below. The condition MUST
+lower to `ac.var`, both branches MUST consume the same Queue through one
+`apply`, and both branches MUST assign the same fresh result name.
+
+```python
+if incoming.route == 0:
+ selected = incoming.apply(
+ lambda item: item.with_fields(value=item.value + 10)
+ )
+else:
+ selected = incoming.apply(
+ lambda item: item.with_fields(value=item.value + 20)
+ )
+```
+
+The frontend lowers this statement to an official two-way `ac.route`, two
+branch transforms, and a mutually exclusive priority `ac.merge`. More complex
+runtime Queue control remains explicit through `route`/`merge`. Runtime topology
+allocation is forbidden.
+
+## ACIR type contract
+
+### Immutable payload types
+
+`!ac.var` and `!ac.queue` require an immutable ACIR payload type. They
+MUST NOT recursively carry Queue, mutable list, function, channel, endpoint, or
+other runtime-reference types.
+
+Valid examples:
+
+```mlir
+!ac.var
+!ac.queue
+!ac.var>
+!ac.queue>
+```
+
+Invalid examples:
+
+```mlir
+!ac.queue>
+!ac.var>
+!ac.queue>
+!ac.queue<(i32) -> i32>
+```
+
+### Static collection types
+
+ACIR provides statically shaped collection types:
+
+```mlir
+!ac.array<4 x !ac.queue>
+!ac.map<["cube", "scalar", "vector"], !ac.queue>
+!ac.set<4 x !ac.var>
+```
+
+Array and set lengths MUST be positive. ACIR map keys are non-empty unique
+strings in strict lexicographic order. Collection elements MUST be Queue, Var,
+or another supported static collection with a valid fixed shape.
+
+## ACIR operation contract
+
+### Implemented common building blocks
+
+The official graph-level catalog contains exactly these operations. Every
+design entry has both a typed gfsim realization and a PYC realization;
+verification entries declare their permitted boundary explicitly.
+
+| Operation | Role | Queue arity | Static parameters | Core behavior |
+| --- | --- | --- | --- | --- |
+| `ac.source` | design | none to one | `depth`, `latency` | boundary producer |
+| `ac.sink` | design | one to none | none | consuming boundary |
+| `ac.observe` | observation | one to none | `name` | non-consuming, non-backpressuring probe |
+| `ac.expect` | verification | one to none | `message` | non-consuming predicate check; PYC testbench only |
+| `ac.transform` | design | one or more to one or more | output depths and latencies | pure Var region plus atomic Queue transfer |
+| `ac.broadcast` | design | one to two or more | output depths and latencies | strict atomic fanout |
+| `ac.fork` | design | one to two or more | output depths and latencies | decoupled exactly-once fanout |
+| `ac.route` | design | one to two or more | output depths and latencies | selector-controlled demultiplexing |
+| `ac.select` | design | one control plus two or more data inputs to one | `depth`, `latency` | selector-controlled data Queue mux |
+| `ac.merge` | design | two or more to one | `policy`, `depth`, `latency` | priority or round-robin arbitration |
+| `ac.barrier` | design | two or more to the same count | output depths and latencies | positionally typed atomic synchronization |
+| `ac.credit` | design | one to one | `credits`, `depth`, `latency` | bounded parallel cost countdown and completion |
+| `ac.memory.instance` / `ac.memory.request` | design | shared instance, one-to-one endpoint | instance identity, ordinal, `entries`, `init`, instance `latency`, `result_field`, `depth` | fixed-priority single-outstanding old-data memory |
+| `ac.dependency` | design | one to one | `capacity`, `resources`, `no_dependency`, `depth`, `latency` | bounded predecessor tracking, resource reservation, and execution countdown |
+| `ac.reorder` | design | one to one | `capacity`, `start`, `depth`, `latency` | bounded key-ordered retirement |
+| `ac.feedback` | design | one to one | `depth`, `latency`, `max_iterations` | bounded stateful loop |
+| `ac.scope` | design | variadic to variadic | symbol name | hierarchy boundary; PYC elaboration flattens it |
+
+`ac.firing`, `ac.queue.peek`, `ac.queue.pop`, and `ac.queue.push` are lower-level
+transactional primitives. They are normative ACIR operations, but they are not
+independent QueueGraph building blocks and therefore do not appear in the
+graph-level opcode catalog.
+
+The closed inventory will grow with other common hardware blocks. New
+application-specific opcodes and private provider identities are not an
+extension mechanism.
+
+### Transform example
+
+The following excerpt is the canonical shape produced for a structure update:
+
+```mlir
+%output = ac.transform %input depths [2] latencies [1] {
+^transform(%item: !ac.var>):
+ %value = ac.var.get %item field "value"
+ : !ac.var> -> !ac.var
+ %one = ac.var.constant 1 : i64 as !ac.var
+ %next_value = ac.var.add %value, %one : !ac.var
+ %next = ac.var.with %item, %next_value field "value"
+ : !ac.var>, !ac.var
+ -> !ac.var>
+ ac.transform.yield %next : !ac.var>
+} {ac.name = "output"}
+ : (!ac.queue>)
+ -> !ac.queue>
+```
+
+The region MUST have one Var block argument for each input Queue. All body
+operations before `ac.transform.yield` MUST be pure. Yielded Var types MUST
+match the payload types of the corresponding output Queues.
+
+Input and output arity are independent. This two-input, one-output transform
+consumes both heads and publishes the sum as one atomic transaction:
+
+```mlir
+%sum = ac.transform %left, %right depths [2] latencies [1] {
+^transform(%left_item: !ac.var, %right_item: !ac.var):
+ %value = ac.var.add %left_item, %right_item : !ac.var
+ ac.transform.yield %value : !ac.var
+} {ac.output_names = ["sum"]}
+ : (!ac.queue, !ac.queue) -> !ac.queue
+```
+
+Neither backend may consume only one input or publish a partial output set.
+The transform fires only when every input is valid and every output can accept
+its corresponding result.
+
+### Credit example
+
+The Python credit call lowers to one stateful `ac.credit` and one pure cost
+region.
+
+```mlir
+%completed = ac.credit %issued credits 2 depth 4 latency 1 cost {
+^cost(%item: !ac.var>):
+ %cycles = ac.var.get %item field "cycles"
+ : !ac.var> -> !ac.var
+ ac.credit.yield %cycles : !ac.var
+} : !ac.queue>
+ -> !ac.queue>
+```
+
+The cost region MUST contain one argument matching the Queue payload, contain
+only pure Var operations, and terminate with exactly one `ac.credit.yield`.
+
+### Barrier example
+
+The barrier has no Var policy region. Its positional Queue types and static
+output parameters completely define the operation.
+
+```mlir
+%left_ready, %right_ready = ac.barrier %left, %right
+ depths [2, 2] latencies [1, 1]
+ : (!ac.queue, !ac.queue)
+ -> (!ac.queue, !ac.queue)
+```
+
+The input operands MUST be unique. Output depth and latency arrays MUST match
+the output count and contain only positive values.
+
+### Memory example
+
+The declaration lowers to `ac.memory.instance`; every endpoint lowers to an
+`ac.memory.request` with a frozen ordinal and three pure policy regions.
+
+```mlir
+ac.memory.instance @sram data i16 entries 16 init 0 latency 3
+ owner "/" stable_id "memory/sram"
+%response = ac.memory.request @sram, %request ordinal 0
+ result_field "data" depth 4
+ address {
+ ^address(%item: !ac.var>):
+ %address = ac.var.get %item field "address"
+ : !ac.var> -> !ac.var
+ ac.memory.yield %address : !ac.var
+} write {
+ ^write(%item: !ac.var>):
+ %write = ac.var.get %item field "write"
+ : !ac.var> -> !ac.var
+ ac.memory.yield %write : !ac.var
+} data {
+ ^data(%item: !ac.var>):
+ %data = ac.var.get %item field "data"
+ : !ac.var> -> !ac.var
+ ac.memory.yield %data : !ac.var
+} {ac.endpoint_path = "/response", ac.name = "response"}
+ : !ac.queue>
+ -> !ac.queue>
+```
+
+The three regions MUST each contain one block argument matching the request
+payload, contain only pure Var operations, and terminate with exactly one
+`ac.memory.yield`.
+
+An instance is visible only from its declaration scope and descendants. Its
+endpoints use fixed ordinal priority. While one transaction is outstanding all
+request endpoints are backpressured; `busy` is released only when the selected
+response Queue accepts the response, and no request is reaccepted in that same
+epoch. Every backend realizes exactly one physical memory per instance.
+
+The Python frontend may statically elaborate a homogeneous memory array without
+adding a frozen operation. `banks.select(requests, key=...).request(...)`
+lowers to one `ac.route`, one ordinary memory instance and request per bank,
+and one response `ac.merge`. The route key selects exactly one bank. Banks have
+independent outstanding state, so responses from different banks may be
+reordered; callers that require request order retain a tag and use `reorder`.
+Memory arrays are one-dimensional in epoch 0.3 and require identical data type,
+entry count, and initialization across all banks.
+
+### Explicit firing example
+
+Low-level Queue effects are legal only inside `ac.firing`.
+
+```mlir
+ac.firing(%input, %output) {
+ %head = ac.queue.peek %input
+ : !ac.queue -> !ac.var
+ %value = ac.queue.pop %input
+ : !ac.queue -> !ac.var
+ ac.queue.push %output, %value
+ : !ac.queue, !ac.var
+ ac.firing.yield
+} : (!ac.queue, !ac.queue)
+```
+
+Firing Queue operands MUST be unique. Every Queue effect MUST reference a
+listed operand. One Queue may be popped at most once and pushed at most once in
+one firing. A firing MUST contain at least one pop or push. `peek` reads the
+same committed head without consuming it.
+
+### Frozen logical identity
+
+Every Queue-producing operation MUST carry exact frozen logical output names
+before QueueGraph extraction:
+
+- one result uses non-empty `ac.name`;
+- multiple results use exact `ac.output_names` in result order;
+- names are unique across the system;
+- each Queue records payload type, scope path, depth, and latency.
+
+The canonical QueueGraph JSON uses schema
+`agentic-circuit-queue-graph-plan`, version `0.2`. Its ordering and bytes MUST
+not depend on host addresses, hash iteration, allocation order, or checkout
+path.
+
+### Queue graph verification
+
+A backend-ready Queue graph MUST satisfy:
+
+- every Queue has exactly one producer;
+- every Queue has exactly one consuming block;
+- `ac.observe` does not count as a consuming block;
+- fanout is represented by `ac.broadcast` or `ac.fork`;
+- merge is represented by `ac.merge`, not multiple producers on one Queue;
+- key-ordered retirement is represented by bounded `ac.reorder` state;
+- every Queue depth and latency is positive;
+- Queue logical identities are non-empty and unique;
+- every block input and output references a known Queue identity;
+- raw QueueGraph cycles are rejected; a stateful loop MUST use `ac.feedback`;
+- every Var region uses only supported pure operations and structured yields;
+- topology and collection shape are compile-time fixed.
+
+An otherwise unused Queue is a static no-progress risk and is rejected with an
+actionable `connect ac.sink` diagnostic. The same verifier runs after ACIR
+extraction and again at both backend entry points, so hand-constructed plans
+cannot bypass the producer, consumer, reference, or cycle checks.
+
+## Runtime execution contract
+
+### Snapshot, proposal, arbitration, and Xfer
+
+At one active epoch, gfsim follows this state discipline:
+
+1. blocks read committed Queue state;
+2. blocks propose pushes and pops without publishing them;
+3. Queue-local arbitration resolves deterministic FIFO proposals;
+4. Xfer commits accepted changes;
+5. consumers observe committed results no earlier than the required later
+ epoch.
+
+One block MUST NOT observe another block's uncommitted proposal in the same
+epoch. Independent Work order MUST NOT change architectural results,
+diagnostics, committed statistics, or refinement observations.
+
+### Capacity and latency
+
+`SimQueue` counts committed entries, delayed entries, and push proposals
+against capacity. It rejects a push proposal that would exceed entry or byte
+capacity.
+
+Latency is exact and positive. A token accepted at epoch `t` by a Queue with
+latency `L` becomes visible to downstream committed-state reads no earlier than
+the boundary corresponding to `t + L`. Latency one is still stateful; it is not
+a combinational wire.
+
+### Atomic transfer
+
+A transform fires only when all required input pops and output pushes can be
+proposed. It computes output Vars from immutable input heads, proposes every
+output, proposes every input pop, and commits the complete transaction through
+Xfer.
+
+No legal lowering may commit an input pop while a required output push is
+rejected.
+
+### Credit transfer
+
+Credit admission pops one input token into a free committed slot. Active slots
+decrement at Xfer, and a zero-remaining slot may propose one output token. The
+slot becomes free only when that output push commits. Output backpressure keeps
+the completed token and its credit occupied.
+
+The gfsim and PYC implementations use the same lowest-slot tie break, the same
+one-admission/one-completion bandwidth, and the same no-same-Xfer slot reuse
+rule. Refinement compares accepted and completed transactions and derives the
+active credit count from their committed difference.
+
+### Barrier transfer
+
+A barrier reads every committed input head, checks every output proposal slot,
+and proposes the complete positional transfer. If any precondition fails, it
+proposes no pop or push. Xfer commits all accepted Queue effects together.
+
+gfsim implements this as `QueueBarrier>`. PYC implements the
+same contract with an all-input-valid conjunction, per-input ready gating, and
+per-output valid gating; no backend retains a dynamic Queue pointer.
+
+### Memory transfer
+
+Memory reads observe committed state before the current Xfer. The memory block
+stages an optional write only after its response push and request pop are both
+accepted. Xfer commits the staged write and the Queue effects together. A
+rejected response push MUST leave the request and memory unchanged.
+
+Model construction and replay start from the deterministic zero image.
+gfsim `reset()` restores that image so the same model instance can replay
+deterministically. The raw PYC primitive does not clear memory on its reset
+port, so mid-run reset of memory contents is outside the shared refinement
+contract; a PYC replay MUST instantiate a fresh model.
+
+## Typed gfsim C++ lowering
+
+The C++ backend MUST generate statically typed, queue-wired code.
+
+```cpp
+struct WorkItem {
+ std::uint32_t value;
+ std::uint8_t route;
+ std::uint16_t remaining;
+};
+
+gfsim::SimQueue input_queue_;
+gfsim::SimQueue output_queue_;
+```
+
+The generated system owns interconnect Queues. Child scope modules and common
+blocks borrow typed Queue references. Sibling blocks MUST NOT own duplicate
+instances of the same interconnect.
+
+The implementation currently provides reusable templates for transform,
+atomic transform, sink, observe, broadcast, fork, route, merge, barrier, credit,
+memory, dependency, reorder, and feedback.
+Generated dispatch is static; generated runtime code MUST NOT discover opcodes
+by strings, walk schemas, construct topology dynamically, or depend on Python
+or MLIR libraries.
+
+## PYC and Verilog lowering
+
+Agentic Circuit owns `frozen ACIR -> canonical PYC IR`. A pinned external
+`pycc` owns PYC verification, C++ emission, and Verilog emission. The pin is
+recorded in [`pyc.lock.json`](../../toolchains/pyc.lock.json).
+
+The current hardware lowering maps:
+
+| ACIR concept | PYC/RTL realization |
+| --- | --- |
+| scalar or structure Var | combinational value or packed bundle |
+| Queue | valid/data/ready channel with fixed storage |
+| Queue depth and latency | fixed register/FIFO stages |
+| transform | combinational data logic plus atomic handshakes |
+| broadcast | all-output ready conjunction |
+| fork | delivered-mask registers and independent output handshakes |
+| route | selector decoder, valid demultiplexing, ready multiplexing |
+| select | selector mux, selected-input ready, and control/data atomic handshake |
+| priority merge | fixed-priority selection |
+| round-robin merge | selection plus committed cursor register |
+| barrier | all-input-valid/all-output-ready atomic handshake |
+| credit | fixed slot register bank, parallel countdown, and deterministic completion selection |
+| memory | `pyc.sync_mem` plus an aligned pending request/valid register |
+| dependency | fixed register window, predecessor wakeup, countdown, and resource grants |
+| reorder | fixed register window and committed next-key register |
+| bounded feedback | committed valid/data/iteration registers and limit assertion |
+| scope | static module hierarchy |
+| observe | non-functional probe boundary |
+| expect | rejected in design hierarchy; permitted only at the PYC testbench boundary |
+
+PYC C++ and Verilog generated from the same PYC IR MUST be cycle equivalent.
+Memory uses the PYC synchronous 1R1W primitive. The lowering retains the
+request until its registered read data is aligned and accepted, drives writes
+only when the request handshake fires, and enables every byte lane of the
+integer data word. The primitive's read-during-write rule is old data.
+Feedback uses explicit sequential state in PYC IR; it is not a combinational
+unroll or a backend-specific loop.
+
+Before lowering, role placement is checked against the shared opcode catalog.
+A verification-only leaf in the design graph fails deterministically; an
+observation leaf remains non-state-changing and cannot affect ready/valid.
+
+## Cross-backend refinement
+
+Typed gfsim and PYC/Verilog have different internal IR and may have different
+internal cycle structures. Cross-backend validation compares a declared
+semantic projection, including:
+
+- input transaction sequence;
+- accepted and completed transaction identities;
+- output transaction sequence;
+- architectural state and memory-visible effects when present;
+- declared assertions and runtime failures.
+
+Cross-backend refinement does not require equality of:
+
+- internal Queue implementation;
+- gfsim deltas;
+- PYC registers and wires;
+- every internal stage cycle;
+- abstract versus detailed pipeline latency that is outside the declared
+ observation contract.
+
+## End-to-end example
+
+The executable
+[`davincioo_queue_model.py`](../../examples/pipelines/davincioo_queue_model.py)
+uses only serial Python and common building blocks.
+
+```python
+import agentic_circuit as ac
+
+
+@ac.struct
+class WorkItem:
+ value: int
+ route: int
+ remaining: int
+
+
+@ac.system
+def davincioo_queue_model() -> None:
+ trace = ac.source(WorkItem, depth=8, latency=1)
+
+ with ac.scope("frontend"):
+ prepared = trace.apply(
+ lambda item: item.with_fields(value=item.value + 1),
+ depth=4,
+ latency=1,
+ )
+
+ with ac.scope("dispatch"):
+ scalar, vector, cube, tma = prepared.route(
+ outputs=4,
+ key=lambda item: item.route,
+ depth=2,
+ latency=1,
+ )
+
+ scalar_done = scalar.apply(lambda item: item.with_fields(value=item.value + 1))
+ vector_done = vector.apply(lambda item: item.with_fields(value=item.value + 2))
+ cube_done = cube.apply(lambda item: item.with_fields(value=item.value + 3))
+ tma_done = tma.apply(lambda item: item.with_fields(value=item.value + 4))
+
+ completed = scalar_done.merge(
+ vector_done,
+ cube_done,
+ tma_done,
+ policy="round_robin",
+ depth=8,
+ latency=1,
+ )
+
+ ac.sink(completed)
+```
+
+The checked-in executable adds explicit engine and retirement scopes. The
+inferred graph is:
+
+```text
+trace -> frontend transform -> four-way route
+ | scalar engine
+ | vector engine
+ | cube engine
+ | tma engine
+ round-robin merge -> retire -> sink
+```
+
+### Generate canonical ACIR, QueueGraph JSON, and gfsim C++
+
+Configure and build the native tools first:
+
+```sh
+scripts/bootstrap-dev.sh
+cmake --preset dev-llvm22
+cmake --build --preset dev-llvm22
+```
+
+Generate all canonical Queue artifacts:
+
+```sh
+PYTHONPATH=src .venv/bin/python tools/ac-queue-cxxgen.py \
+ examples/pipelines/davincioo_queue_model.py \
+ --system davincioo_queue_model \
+ --acir-output build/davincioo_queue_model.ac.mlir \
+ --plan-output build/davincioo_queue_model.queue-plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output build/davincioo_queue_model.cpp
+```
+
+Check that the generated C++ is valid for the local compiler:
+
+```sh
+c++ -std=c++20 -I include -fsyntax-only build/davincioo_queue_model.cpp
+```
+
+### Generate PYC, PYC C++, and Verilog
+
+Use the exact pyCircuit commit and LLVM version in the toolchain lock. Given a
+matching local pyCircuit installation, run the canonical bundle command:
+
+```sh
+PYC_TOOLCHAIN_ROOT=/path/to/pycircuit/toolchain/install
+
+.venv/bin/python tools/ac-queue-pyc-build.py \
+ build/davincioo_queue_model.ac.mlir \
+ --pycgen-tool build/dev-llvm22/bin/acir-queue-pycgen \
+ --pycc "$PYC_TOOLCHAIN_ROOT/bin/pycc" \
+ --toolchain-lock toolchains/pyc.lock.json \
+ --toolchain-metadata \
+ "$PYC_TOOLCHAIN_ROOT/share/pycircuit/toolchain-metadata.json" \
+ --cxx "$(command -v c++)" \
+ --verilator "$(command -v verilator)" \
+ --pyc-output build/davincioo_queue_model.pyc \
+ --cpp-output-dir build/davincioo_queue_model-pyc-cpp \
+ --verilog-output-dir build/davincioo_queue_model-verilog \
+ --manifest build/davincioo_queue_model-pyc-manifest.json
+```
+
+The command validates the toolchain lock, emits PYC C++ and Verilog, runs C++
+syntax checking and Verilator lint, and records deterministic artifact hashes.
+Output paths MUST not already exist.
+
+## Rejected examples
+
+### Explicit system ports
+
+```python
+@ac.system
+def illegal(input_queue):
+ ...
+```
+
+Queue/Var system boundaries are inferred. A system with parameters is rejected.
+
+### Zero-latency Queue
+
+```python
+incoming = ac.source(int, latency=0)
+```
+
+Use Var computation inside a lambda for latency-zero logic.
+
+### Runtime topology
+
+```python
+for _ in range(item.value):
+ queues.append(ac.source(int))
+```
+
+Queue count and collection shape MUST be known during AST elaboration.
+
+### Runtime Queue condition
+
+```python
+if incoming:
+ selected = incoming.apply(lambda item: item + 1)
+```
+
+Use `route` for runtime token selection.
+
+### Dynamic Queue handle
+
+```python
+selected_queue = queues[item.route]
+```
+
+Runtime selection MUST lower to `route`, select, or arbitration logic. It MUST
+NOT materialize a runtime Queue pointer.
+
+### Private opcode or backend
+
+```python
+@ac.opcode
+def private_scheduler(...):
+ ...
+
+ac.raw_verilog("assign ...")
+```
+
+Both forms are forbidden. Add a reusable common building block to the
+repository-owned inventory with ACIR, gfsim, PYC, and conformance definitions.
+
+## Diagnostics
+
+Frontend Queue diagnostics use the `ACPY-QUEUE-*` family. They SHOULD identify
+the source construct, violated static rule, and repair. Important current codes
+include:
+
+| Code | Meaning |
+| --- | --- |
+| `ACPY-QUEUE-001` | invalid system, assignment, statement, or positive constant |
+| `ACPY-QUEUE-002` | unsupported payload or structure declaration |
+| `ACPY-QUEUE-003` | invalid lambda or Var expression |
+| `ACPY-QUEUE-004` | duplicate scope path |
+| `ACPY-QUEUE-005` | invalid static collection or reference |
+| `ACPY-QUEUE-006` | invalid route declaration |
+| `ACPY-QUEUE-007` | invalid bounded feedback loop |
+| `ACPY-QUEUE-008` | invalid merge |
+| `ACPY-QUEUE-009` | invalid atomic group |
+| `ACPY-QUEUE-010` | forbidden user opcode or backend provider |
+| `ACPY-QUEUE-011` | runtime `if` is not a symmetric Boolean Queue branch |
+| `ACPY-QUEUE-012` | invalid fork |
+
+Native QueueGraph/backend diagnostics use the `ACLOWER-QUEUE-*` family and
+MUST reject an invalid graph before emitting partial backend artifacts.
+
+## Determinism requirements
+
+Canonical ACIR, QueueGraph JSON, generated C++, PYC IR, manifests, and
+observations MUST NOT depend on:
+
+- Python hash iteration order;
+- host pointer values or allocation order;
+- unordered C++ traversal order;
+- ambient checkout path;
+- process ID or wall-clock time;
+- runtime plugin discovery;
+- arbitrary Python or Verilog execution.
+
+Canonical ordering uses source occurrence, static collection order, frozen
+logical identity, and declared arbitration policy.
+
+## Current implementation boundary
+
+The following slices are implemented and tested:
+
+- AST-based serial Python capture;
+- immutable scalar and structure payloads;
+- Queue/Var types and pure Var expressions;
+- scopes with inferred Queue boundaries;
+- transform, strict broadcast, decoupled fork, route, merge, atomic barrier,
+ bounded credit, typed memory, dependency, reorder, observe, sink, explicit
+ atomic transform, and bounded feedback;
+- static arrays, maps, sets, runtime flat-collection selection, static `if`,
+ static loops, and symmetric runtime Queue `if` lowering through
+ route/transform/merge;
+- canonical QueueGraph extraction;
+- typed gfsim C++ generation;
+- PYC/Verilog lowering for transform, broadcast, fork, route, select, merge,
+ atomic barrier, bounded credit, typed synchronous memory, dependency,
+ reorder, bounded feedback, elaboration-time scope flattening, packed
+ structures, atomic handshakes, and exact Queue latency;
+- PYC C++ versus Verilog cycle equivalence and gfsim/PYC projected transaction
+ comparison.
+
+Issues [#9](https://github.com/PTO-ISA/agentic-circuit/issues/9),
+[#10](https://github.com/PTO-ISA/agentic-circuit/issues/10), and
+[#11](https://github.com/PTO-ISA/agentic-circuit/issues/11) are closed. The
+requirement matrix contains no partial or missing rows. Future public
+building blocks, richer signedness semantics, and additional refinement
+projections are new contract work rather than incomplete requirements of these
+issues.
+
+The checked-in DavinciOO-like model now proves topology, typed payloads, finite
+Queues, backpressure, deterministic C++ generation, the 15-record softmax
+opcode/completion/retirement projection, and the 453-cycle bounded oracle. The
+same frozen ACIR produces PYC C++ and Verilog with cycle-identical hardware
+observations and the same projected output transactions. Dependency readiness
+resource reservation, and execution countdown are now explicit `ac.dependency`
+state, while bounded parallel in-flight work is explicit `ac.credit` state. The
+projection
+retains only a fixed 5-cycle ingress and 4-cycle drain compensation for the
+different model boundaries. The checked occupancy projection records dependency
+window peak 8, per-resource executing peaks `[1, 1, 0, 1]`, and reorder window
+peak 8 through stable generated-model accessors.
+
+## Contributor checklist
+
+A change to the public contract is complete only when it updates all
+affected layers:
+
+- Python accepted and rejected syntax;
+- ACIR ODS type or operation definition;
+- verifier and diagnostic;
+- QueueGraph canonical plan;
+- gfsim runtime semantics and typed C++ emission;
+- PYC lowering or an explicit backend rejection;
+- positive, negative, determinism, and round-trip tests;
+- this manual and the relevant machine-readable schema;
+- exact contract epoch and capability declarations when public syntax changes.
+
+Do not document a backend-specific behavior as shared ACIR semantics. Do not
+add a compatibility alias for removed public source surfaces. Git history,
+release tags, and [`REF-HISTORY-001`](refs/history.md) preserve prior contracts.
diff --git a/components/agentic-circuit/docs/spec/agentic-circuit.zh-CN.md b/components/agentic-circuit/docs/spec/agentic-circuit.zh-CN.md
new file mode 100644
index 00000000..93dcd44f
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/agentic-circuit.zh-CN.md
@@ -0,0 +1,685 @@
+# Agentic Circuit 团队 Specification 手册
+
+| 字段 | 内容 |
+| --- | --- |
+| 目标版本 | Explicit Memory contract epoch `0.3` |
+| 状态 | 已在 `main` 实现;本文是团队阅读入口 |
+| 适用读者 | Python 前端、ACIR、gfsim、PYC/Verilog 和模型验证开发者 |
+| 规范主文档 | [Agentic Circuit Specification Manual](agentic-circuit.md) |
+| 机器可读清单 | [`opcodes.json`](../../schemas/opcodes.json) |
+| 可执行示例 | [`examples/pipelines`](../../examples/pipelines/README.md) |
+
+## 文档定位
+
+本文帮助团队成员快速理解和使用 Agentic Circuit。它解释编程模型、
+常用积木、后端差异、验证方法和常见错误,并给出与仓内测试一致的示例。
+
+本文不复制所有 ODS 签名和 verifier 条件。发生差异时,按以下顺序判断:
+
+1. JSON Schema、opcode catalog 和 MLIR ODS;
+2. verifier 与 conformance test;
+3. [英文规范](agentic-circuit.md);
+4. 本文和设计提案。
+
+规范中的 **MUST**、**MUST NOT**、**SHOULD**、**SHOULD NOT** 和 **MAY**
+具有 RFC 风格的约束含义。本文使用“必须”“禁止”“应该”和“可以”表达同一
+含义。
+
+## 一句话理解
+
+用户编写串行风格的 Python。编译器读取 AST,把 Python 变量解释成静态连接的
+`ac.queue`,把 lambda 内的值解释成零延迟 `ac.var`,再从同一份冻结 ACIR
+生成两种内部结构不同的后端:
+
+```text
+串行 Python
+ |
+ v
+AST capture / ACPy
+ |
+ v
+Queue/Var ACIR
+ |
+ +------------------------------+
+ | |
+ v v
+typed gfsim C++ canonical PYC IR
+SimQueue 模型 |
+ v
+ pinned pycc
+ | |
+ v v
+ PYC C++ Verilog
+```
+
+Python 看起来按顺序书写,但运行时不是逐行解释 Python。系统体只在编译期完成
+拓扑 elaboration;生成的 Queue、积木和作用域在运行期保持静态。
+
+## 核心对象
+
+### Queue 是带时序的状态
+
+`ac.queue` 是有限深度、带类型、带反压的 FIFO 通道。它具有:
+
+- 编译期确定的 payload 类型 `T`;
+- 正数 `depth` 和正数 `latency`;
+- 稳定的逻辑身份和层级路径;
+- `peek`、`pop`、`push` 和 commit-time 状态变化;
+- gfsim 中的 `SimQueue` 实例;
+- PYC/RTL 中的 valid/data/ready 与固定存储。
+
+Queue 的 latency 禁止为零。需要零延迟组合逻辑时使用 Var 表达式。
+
+### Var 是不可变组合值
+
+`ac.var` 没有容量、占用率和运行时对象身份。以下对象都属于 Var:
+
+- lambda 参数;
+- 常量和算术结果;
+- 结构体字段投影;
+- 比较结果;
+- `with_fields(...)` 产生的新 token。
+
+Queue 可以改变占用状态,Queue 中的 token 不可原地修改。
+
+```python
+# 正确:创建一个新 token。
+next_item = item.with_fields(remaining=item.remaining - 1)
+
+# 错误:原地修改输入 token。
+item.remaining -= 1
+```
+
+### Opcode 是公共硬件积木
+
+公开积木统一使用 `ac.*` 命名空间。不存在 `ac.std.*`,也不允许用户定义私有
+opcode、C++ provider、PYC provider 或直接插入 Verilog。
+
+`decode`、`dispatch`、`rename`、`retire` 等名称属于具体架构的 scope 或积木组合,
+不是通用 opcode。公共积木描述的是 transform、route、merge、memory、barrier、
+credit、dependency 和 reorder 等可复用硬件行为。
+
+查看当前闭集:
+
+```bash
+build/dev-llvm22/bin/acir-opcode-catalog
+agentic-circuit schema opcode ac.transform
+```
+
+## 最小示例
+
+下面的系统没有显式输入输出声明。`source` 和 `sink` 定义可执行边界,变量的定义和
+使用关系定义 Queue 连接。
+
+```python
+import agentic_circuit as ac
+
+
+@ac.system
+def pipeline() -> None:
+ incoming = ac.source(int, depth=4, latency=1)
+ outgoing = incoming.apply(
+ lambda item: item + 1,
+ depth=2,
+ latency=1,
+ )
+ ac.sink(outgoing)
+```
+
+它 elaboration 成:
+
+```text
+incoming Queue -> ac.transform(item + 1) -> outgoing Queue -> ac.sink
+```
+
+系统函数必须无参数。`source`、`apply` 和 `sink` 是 AST marker,不能通过普通
+Python 调用系统体来模拟电路。
+
+## 定义结构化 payload
+
+使用 `@ac.struct` 冻结字段顺序、位宽和结构身份。
+
+```python
+import agentic_circuit as ac
+
+
+@ac.struct
+class WorkItem:
+ sequence: ac.u64
+ value: ac.u32
+ route: ac.u2
+ remaining: ac.u16
+ valid: bool
+
+
+@ac.system
+def pipeline() -> None:
+ incoming = ac.source(WorkItem)
+ updated = incoming.apply(
+ lambda item: item.with_fields(
+ value=item.value + 1,
+ remaining=item.remaining - 1,
+ )
+ )
+ ac.sink(updated)
+```
+
+当前常用字段类型包括 `bool`、`int`、`ac.u1/u2/u4/u8/u16/u32/u64` 和
+`ac.s8/s16/s32/s64`。当前 ACIR 契约已冻结整数宽度,但尚未把有符号性作为完全独立的
+类型语义;不要假设所有比较都自动采用 Python 的有符号规则。
+
+可执行示例:
+[`pyc_struct_pipeline.py`](../../examples/pipelines/pyc_struct_pipeline.py)。
+
+## 使用 scope 表达层级
+
+`with ac.scope("name"):` 表达所有权和层级,不声明端口。编译器根据跨 scope 的
+def-use 自动推导输入、输出和 interconnect 所属的最低公共祖先。
+
+```python
+@ac.system
+def pipeline() -> None:
+ incoming = ac.source(int)
+
+ with ac.scope("frontend"):
+ prepared = incoming.apply(lambda item: item + 1)
+
+ with ac.scope("backend"):
+ completed = prepared.apply(lambda item: item * 2)
+
+ ac.sink(completed)
+```
+
+scope 名必须非空,同一路径不能重复声明。跨 scope 的 Queue 不会被两个子模块重复
+拥有;生成系统拥有 interconnect,子模块只借用类型化 Queue 引用。
+
+## 数据通路积木
+
+### Transform
+
+`apply` 生成一个 `ac.transform`。一次 firing 原子地 pop 输入并 push 输出。
+
+```python
+updated = incoming.apply(
+ lambda item: item.with_fields(value=(item.value + 1) * 2),
+ depth=4,
+ latency=2,
+)
+```
+
+lambda 必须是纯 Var 表达式,且返回类型与输出 Queue payload 一致。当前支持字段读取、
+常量、`+`、`-`、`*`、比较和不可变 `with_fields(...)` 更新。
+
+### Broadcast 与 Fork
+
+同一 Queue 被多个消费点使用时,前端自动插入严格原子的 `ac.broadcast`:所有输出
+必须在同一 firing 接收 token。
+
+需要各输出在不同 cycle 接收时,显式使用 `fork`:
+
+```python
+left, right = incoming.fork(outputs=2, depth=2, latency=1)
+```
+
+`fork` 为当前 token 保存 delivered mask,每个输出恰好收到一次,全部完成后才 pop
+输入。两者不能互换,因为反压和内部状态不同。
+
+可执行示例:
+[`pyc_broadcast_pipeline.py`](../../examples/pipelines/pyc_broadcast_pipeline.py) 和
+[`pyc_fork_pipeline.py`](../../examples/pipelines/pyc_fork_pipeline.py)。
+
+### Route 与 Merge
+
+`route` 根据一个 Var selector 把 token 发送到一个静态输出,`merge` 把同类型 Queue
+合并回来。
+
+```python
+scalar, vector = prepared.route(
+ outputs=2,
+ key=lambda item: item.route,
+ depth=2,
+ latency=1,
+)
+
+scalar_done = scalar.apply(lambda item: item.with_fields(value=item.value + 1))
+vector_done = vector.apply(lambda item: item.with_fields(value=item.value + 2))
+
+completed = scalar_done.merge(
+ vector_done,
+ policy="round_robin",
+ depth=4,
+ latency=1,
+)
+```
+
+selector 越界产生确定性 `route_selector_out_of_range` 失败,不会回绕。merge policy
+仅支持 `priority` 和 `round_robin`。
+
+可执行示例:
+[`pyc_route_merge_pipeline.py`](../../examples/pipelines/pyc_route_merge_pipeline.py)。
+
+## 静态集合与运行时选择
+
+Queue 和 Var 可以放入编译期确定形状的 array、map 和 set。
+
+```python
+lanes = ac.array(4, lambda index: ac.source(int, depth=index + 1))
+named = ac.map({"scalar": lanes[0], "vector": lanes[1]})
+active = ac.set({named["scalar"], named["vector"]})
+```
+
+静态索引和编译期遍历会被展开。运行时从 flat Queue collection 选择一个成员时,必须
+提供显式 control Queue;编译器生成 `ac.select`,而不是动态 Queue 指针。
+
+```python
+@ac.struct
+class Control:
+ route: ac.u2
+
+
+@ac.system
+def selected_pipeline() -> None:
+ control = ac.source(Control)
+ lanes = ac.array(4, lambda index: ac.source(int))
+ selected = lanes.select(
+ control,
+ key=lambda item: item.route,
+ depth=2,
+ latency=1,
+ )
+ ac.sink(selected)
+```
+
+control token 与被选中的 data token 原子传输。越界产生
+`select_selector_out_of_range`。嵌套集合必须先静态展开,不能在运行时保存或返回
+Queue handle。
+
+可执行示例:
+[`pyc_select_pipeline.py`](../../examples/pipelines/pyc_select_pipeline.py)。
+
+## 状态和调度积木
+
+### Typed Memory
+
+`memory` 是单读单写的类型化状态积木。一次请求总会读取;写入在 Xfer commit;同一
+请求对同地址读写时返回旧值,新值对后续请求可见。
+
+```python
+@ac.struct
+class Request:
+ address: ac.u8
+ write: bool
+ data: ac.u16
+
+
+@ac.system
+def memory_pipeline() -> None:
+ sram = ac.memory(ac.u16, entries=16, init=0, latency=3)
+ requests = ac.source(Request)
+ responses = sram.request(
+ requests,
+ address=lambda item: item.address,
+ write=lambda item: item.write,
+ data=lambda item: item.data,
+ result_field="data",
+ depth=4,
+ )
+ ac.sink(responses)
+```
+
+只允许 `init=0`,实例 `latency` 必须为正数。周期 `T` 接受的请求最早在
+`T + latency` 提交响应;request 的 response Queue latency 固定为 1。一个实例可以
+连接多个逻辑 endpoint,但只有一个物理端口和一个 outstanding request。endpoint 按
+冻结 ordinal 固定优先级仲裁;访问延迟期间及 response Queue 阻塞时全部反压,直到
+选中 response Queue 接纳响应。PYC 每个实例只生成一个 `pyc.sync_mem`。
+
+Python 前端允许用同构 `ac.array` 静态声明 memory banks,并以
+`banks.select(requests, key=...).request(...)` 明确选择 bank。该写法只在前端展开:
+冻结 ACIR 包含一个 `ac.route`、每个 bank 各一个普通 memory instance/request,以及
+一个 response `ac.merge`,不会引入新的 primitive。各 bank 的 outstanding 状态独立,
+因此跨 bank response 可能乱序;需要保序时应在 payload 中保留 tag 并显式接
+`reorder`。epoch 0.3 仅支持一维、data type、entries、init 和 latency 完全相同的 memory
+array。
+
+可执行示例:
+[`pyc_memory_pipeline.py`](../../examples/pipelines/pyc_memory_pipeline.py)。
+
+### Credit
+
+`credit` 表达固定数量的并行 in-flight slot。每个 slot 独立倒计时,完成顺序可以和
+输入顺序不同。
+
+```python
+completed = issued.credit(
+ cost=lambda item: item.cycles,
+ credits=4,
+ depth=4,
+ latency=1,
+)
+```
+
+`credits` 必须为正,运行时 cost 必须为正。多个 slot 同时完成时,选择最低 canonical
+slot index,并且每个 epoch 最多输出一个 token。
+
+可执行示例:
+[`pyc_credit_pipeline.py`](../../examples/pipelines/pyc_credit_pipeline.py)。
+
+### Barrier
+
+`barrier` 等待所有输入可 pop 且所有输出可 push,然后一次性提交所有效果。各输入
+payload 类型可以不同,但输出必须按位置匹配。
+
+```python
+left_ready, right_ready = left.barrier(
+ right,
+ depth=2,
+ latency=1,
+)
+```
+
+输入 Queue 必须互不相同。barrier firing 前禁止发布部分结果。
+
+可执行示例:
+[`pyc_barrier_pipeline.py`](../../examples/pipelines/pyc_barrier_pipeline.py)。
+
+### Dependency 与 Reorder
+
+`depend` 表达有界依赖窗口、资源占用和执行 cost;`reorder` 按连续 key 恢复顺序。
+它们可以组合成 issue/execute/retire 风格架构,但这些应用阶段仍是 scope,而不是新
+opcode。
+
+```python
+completed = issued.depend(
+ key=lambda item: item.sequence,
+ waits_for=lambda item: item.waits_for,
+ resource=lambda item: item.route,
+ cost=lambda item: item.cycles,
+ capacity=16,
+ resources=4,
+ no_dependency=255,
+ depth=8,
+ latency=1,
+)
+
+retired = completed.reorder(
+ key=lambda item: item.sequence,
+ capacity=16,
+ start=0,
+ depth=4,
+ latency=1,
+)
+```
+
+完整参考:
+[`davincioo_queue_model.py`](../../examples/pipelines/davincioo_queue_model.py)。该模型用公共
+积木构造 DavinciOO-like 拓扑,并验证 15 条记录、out-of-order completion、in-order
+retirement、Queue occupancy 和 453-cycle 投影。
+
+## 串行控制流
+
+### 编译期控制
+
+`if True/False`、`range(constant)`、静态集合遍历和结构递减的有限递归在编译期展开。
+
+```python
+def add_stages(queue, count):
+ if count == 0:
+ return queue
+ return add_stages(
+ queue.apply(lambda item: item + 1),
+ count - 1,
+ )
+
+
+@ac.system
+def recursive_pipeline() -> None:
+ incoming = ac.source(int)
+ outgoing = add_stages(incoming, 3)
+ ac.sink(outgoing)
+```
+
+递归深度必须是 `[0, 1024]` 范围内的编译期整数。后端中不会留下递归或动态模块创建。
+
+可执行示例:
+[`pyc_recursive_pipeline.py`](../../examples/pipelines/pyc_recursive_pipeline.py)。
+
+### 运行时 if
+
+当前高层语法支持对同一 Queue 的对称二分支更新。它会 lowering 成 route、两个
+transform 和互斥 priority merge。
+
+```python
+if incoming.route == 0:
+ selected = incoming.apply(
+ lambda item: item.with_fields(value=item.value + 10)
+ )
+else:
+ selected = incoming.apply(
+ lambda item: item.with_fields(value=item.value + 20)
+ )
+```
+
+两个分支必须消费同一 Queue、各执行一次 apply,并赋值给同一新变量。更复杂的控制
+使用显式 route/merge 组合。
+
+可执行示例:
+[`pyc_conditional_pipeline.py`](../../examples/pipelines/pyc_conditional_pipeline.py)。
+
+### 有界 while
+
+Queue rebinding 的串行 `while` lowering 成带状态 feedback Queue 的 `ac.feedback`。
+
+```python
+while current.remaining > 0:
+ if current.stop:
+ break
+ current = current.apply(
+ lambda item: item.with_fields(remaining=item.remaining - 1)
+ )
+ if current.skip:
+ continue
+```
+
+当前允许 update 前一个 break guard 和尾部一个 continue guard。最大迭代次数为
+1024,超出时产生 `feedback_iteration_limit`。
+
+可执行示例:
+[`pyc_feedback_pipeline.py`](../../examples/pipelines/pyc_feedback_pipeline.py) 和
+[`pyc_loop_control_pipeline.py`](../../examples/pipelines/pyc_loop_control_pipeline.py)。
+
+## 显式 Queue effect
+
+需要强调 pop 的副作用和 peek 的非消费读取时,使用 `firing`:
+
+```python
+outgoing = incoming.firing(
+ lambda queue: queue.push(
+ queue.pop().with_fields(
+ value=queue.peek().value + 1,
+ )
+ )
+)
+```
+
+一次 Python firing 必须恰好包含一次 `pop` 和一次最外层 `push`,可以重复 `peek`。
+`peek` 和 `pop` 返回不可变 Var。当前单输入单输出形式会规范化为标准
+`ac.transform`,不会在生成的 hot path 中解释 Python effect 对象。
+
+可执行示例:
+[`pyc_firing_pipeline.py`](../../examples/pipelines/pyc_firing_pipeline.py)。
+
+## Observation 与 Verification
+
+`ac.observe(queue)` 非消费地观察 committed head,不参与反压,可以进入设计 lowering。
+
+`ac.expect(...)` 也是非消费 leaf,但角色是 verification:
+
+```python
+ac.expect(
+ completed,
+ predicate=lambda item: item.value > 0,
+ message="value must be positive",
+)
+```
+
+gfsim 对每个新 committed head 检查 predicate,失败时报告 `expectation_failed`。
+PYC design hierarchy 明确拒绝 `ac.expect`;对应检查必须放到 PYC testbench boundary。
+这不是后端缺失,而是 design role 与 verification role 的边界。
+
+可执行示例:
+[`gfsim_expect_pipeline.py`](../../examples/pipelines/gfsim_expect_pipeline.py)。
+
+## gfsim 与 PYC/Verilog 的差异
+
+两种后端共享冻结 ACIR 语义,但内部 IR 和状态结构不要求相同。
+
+| 方面 | typed gfsim | PYC/Verilog |
+| --- | --- | --- |
+| Queue | `SimQueue` 对象 | valid/data/ready + FIFO/register |
+| Var | C++ 局部值或纯表达式 | wire、packed value、组合 op |
+| 层级 | `gfsim::Module` 对象层级 | 静态 module hierarchy |
+| 调度 | snapshot/proposal/Xfer/commit | 时钟边沿和 ready/valid handshake |
+| Memory | 类型化 QueueMemory 状态 | `pyc.sync_mem` + 对齐寄存器 |
+| Verification | `ac.expect` 可执行 | design 中拒绝,testbench 中实现 |
+| 输出 | 类型化 C++ simulator | PYC C++ 与 Verilog |
+
+跨后端 refinement 比较声明过的语义投影:输入/输出 transaction、接受与完成身份、
+架构状态、memory-visible effect 和明确的 assertion。它不比较 gfsim delta、内部 Queue
+布局、PYC 寄存器名称或每个未声明的内部 cycle。
+
+同一 PYC IR 生成的 PYC C++ 和 Verilog 必须 cycle equivalent。gfsim 与 PYC 可以有
+不同内部 latency,但必须满足选定的 observation/refinement contract。
+
+## 编译和验证示例
+
+先配置 LLVM 22.1.8 开发环境:
+
+```bash
+scripts/bootstrap-dev.sh
+source .venv/bin/activate
+cmake --preset dev-llvm22
+cmake --build --preset dev-llvm22
+```
+
+生成 frozen ACIR、QueueGraph plan 和 typed gfsim C++:
+
+```bash
+PYTHONPATH=src .venv/bin/python tools/ac-queue-cxxgen.py \
+ examples/pipelines/davincioo_queue_model.py \
+ --system davincioo_queue_model \
+ --acir-output build/davincioo_queue_model.ac.mlir \
+ --plan-output build/davincioo_queue_model.queue-plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output build/davincioo_queue_model.cpp
+```
+
+验证生成 C++:
+
+```bash
+c++ -std=c++20 -I include -fsyntax-only build/davincioo_queue_model.cpp
+```
+
+使用锁定的 pyCircuit toolchain 生成 PYC C++ 与 Verilog:
+
+```bash
+PYC_TOOLCHAIN_ROOT=/path/to/pycircuit/toolchain/install
+
+.venv/bin/python tools/ac-queue-pyc-build.py \
+ build/davincioo_queue_model.ac.mlir \
+ --pycgen-tool build/dev-llvm22/bin/acir-queue-pycgen \
+ --pycc "$PYC_TOOLCHAIN_ROOT/bin/pycc" \
+ --toolchain-lock toolchains/pyc.lock.json \
+ --toolchain-metadata \
+ "$PYC_TOOLCHAIN_ROOT/share/pycircuit/toolchain-metadata.json" \
+ --cxx "$(command -v c++)" \
+ --verilator "$(command -v verilator)" \
+ --pyc-output build/davincioo_queue_model.pyc \
+ --cpp-output-dir build/davincioo_queue_model-pyc-cpp \
+ --verilog-output-dir build/davincioo_queue_model-verilog \
+ --manifest build/davincioo_queue_model-pyc-manifest.json
+```
+
+命令会检查 [`pyc.lock.json`](../../toolchains/pyc.lock.json),执行 PYC
+verification、C++ syntax check、Verilator lint,并记录确定性 artifact hash。目标输出
+路径必须不存在,防止覆盖旧证据。
+
+## 明确禁止的写法
+
+### 显式系统端口
+
+```python
+# 禁止:系统边界由 source/sink 和 def-use 推导。
+@ac.system
+def pipeline(input_queue, output_queue):
+ ...
+```
+
+### 零延迟 Queue
+
+```python
+# 禁止:Queue latency 必须为正。
+incoming = ac.source(int, latency=0)
+```
+
+### 运行时拓扑和动态 Queue handle
+
+```python
+# 禁止:运行时不能构造、保存或返回 Queue 指针。
+selected_queue = lanes[token.route]
+```
+
+应改用 `lanes.select(control, key=...)`。
+
+### 私有 opcode 或后端代码
+
+```python
+# 禁止:用户不能从 Python 注册私有实现。
+ac.register_opcode("my.dispatch", cpp_provider=..., verilog=...)
+```
+
+需要新能力时,先把它定义成通用硬件积木,并同步更新 Python、ACIR、verifier、
+QueueGraph、gfsim、PYC、测试和 opcode catalog。
+
+## 常见问题
+
+| 现象 | 原因 | 处理方法 |
+| --- | --- | --- |
+| Queue 被两个消费者使用 | pop 是消费 effect | 需要原子复制时依赖自动 broadcast;需要解耦时显式 fork |
+| `latency=0` 被拒绝 | Queue 是状态,不是 wire | 把逻辑写入 lambda,让它 lowering 成 Var |
+| selector 越界 | route/select 拓扑是静态闭集 | 修正 selector 位宽或在上游保证合法范围 |
+| loop 被拒绝 | 不是受支持的单 Queue 有界 feedback 形状 | 简化为一次 Queue update,或显式组合 route/merge/feedback |
+| PYC 拒绝 `ac.expect` | verification leaf 不能进入 design | 把 assertion 放入 PYC testbench boundary |
+| 后端结果内部 cycle 不同 | gfsim 与 RTL IR 不同 | 比较声明的 transaction/state/refinement projection |
+| artifact epoch 不匹配 | serialized epoch 是 hard break | 重新生成 exact epoch `0.3` artifact,不使用兼容 shim |
+
+## 修改公共契约的完成条件
+
+新增或修改一个公共积木时,必须同步完成:
+
+- Python 正向和拒绝语法;
+- ACIR ODS 类型或 operation;
+- verifier、错误码和诊断文本;
+- QueueGraph canonical plan;
+- gfsim runtime 语义与类型化 C++ 生成;
+- PYC lowering,或明确的 backend-role 拒绝;
+- 正向、负向、determinism、round-trip 和 cross-backend 测试;
+- [`opcodes.json`](../../schemas/opcodes.json);
+- [英文规范](agentic-circuit.md) 和本文对应入口。
+
+不要把某个后端的实现细节提升成共享 ACIR 语义,也不要为已移除的公共表面增加兼容
+别名。旧契约由 Git 历史、release tag 和
+[`REF-HISTORY-001`](refs/history.md) 保存。
+
+## 推荐阅读顺序
+
+新同学可以按以下顺序阅读和动手:
+
+1. 本文的“核心对象”和“最小示例”;
+2. [`examples/pipelines/README.md`](../../examples/pipelines/README.md);
+3. [`davincioo_queue_model.py`](../../examples/pipelines/davincioo_queue_model.py);
+4. [英文规范](agentic-circuit.md);
+5. [`opcodes.json`](../../schemas/opcodes.json) 和
+ [`test/ACIR`](../../test/ACIR);
+6. [NDF 仓库布局验证](50-verification/repository-layout.md)。
diff --git a/components/agentic-circuit/docs/spec/decisions/D-BLOCK-MODEL-001.md b/components/agentic-circuit/docs/spec/decisions/D-BLOCK-MODEL-001.md
new file mode 100644
index 00000000..6d59fa7e
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/decisions/D-BLOCK-MODEL-001.md
@@ -0,0 +1,15 @@
+# Queue and block model
+
+## Use one current compositional block model {#D-BLOCK-MODEL-001}
+
+
+**Context.** Queue/Var, explicit memory, parameterized blocks, and end-to-end
+workspaces were developed in successive release phases. Keeping those phase
+names in source paths made them look like competing APIs.
+
+**Decision.** `ac.queue`, `ac.var`, explicit memory, parameterized blocks, and
+workspace examples form one current model. Examples are grouped by purpose:
+pipelines, memory, blocks, architecture models, and complete workspaces.
+
+**Consequence.** New work extends the existing semantic group. It does not add
+a versioned or phase-numbered sibling.
diff --git a/components/agentic-circuit/docs/spec/decisions/D-RELEASE-LAYOUT-001.md b/components/agentic-circuit/docs/spec/decisions/D-RELEASE-LAYOUT-001.md
new file mode 100644
index 00000000..4f743a91
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/decisions/D-RELEASE-LAYOUT-001.md
@@ -0,0 +1,16 @@
+# Release-owned repository layout
+
+## Remove product versions and phases from source paths {#D-RELEASE-LAYOUT-001}
+
+
+**Context.** Versioned directories caused several generations of examples,
+tests, and contracts to appear active at the same time. Phase plans and current
+implementation documentation were also indistinguishable.
+
+**Decision.** The repository uses semantic paths only. Releases identify
+versions. A new release changes files in place and does not create a parallel
+versioned source tree. The migration is a hard break: old paths have no aliases,
+redirect files, or compatibility symlinks.
+
+**Consequence.** Consumers must use the paths shipped by the selected release.
+Repository gates reject new product-version or phase tokens in tracked paths.
diff --git a/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.drawio b/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.drawio
new file mode 100644
index 00000000..25c016c6
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.drawio
@@ -0,0 +1,136 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.svg b/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.svg
new file mode 100644
index 00000000..98dd1073
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/images/agentic-circuit-pipeline.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/components/agentic-circuit/docs/spec/ndf.yaml b/components/agentic-circuit/docs/spec/ndf.yaml
new file mode 100644
index 00000000..e18a2727
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/ndf.yaml
@@ -0,0 +1,5 @@
+project: agentic-circuit
+release_model: git-release
+layers: L0,L1,L2,L3
+clause_heading: "## Title {#CLAUSE-ID}"
+metadata_comment: ""
diff --git a/components/agentic-circuit/docs/spec/refs/history.md b/components/agentic-circuit/docs/spec/refs/history.md
new file mode 100644
index 00000000..fbbfd03d
--- /dev/null
+++ b/components/agentic-circuit/docs/spec/refs/history.md
@@ -0,0 +1,12 @@
+# Historical source reference
+
+## Pre-migration plans and audits {#REF-HISTORY-001}
+
+
+
+Commit `5514f886f9967d3f06551f030b74d1fcaccd383e` is the final tree before
+the release-layout hard break. It contains the complete dated implementation
+plans, superseded design proposals, phase audits, and their original paths.
+
+NDF clauses in the current tree retain stable decisions and verification
+relationships. Git history retains the full historical prose.
diff --git a/components/agentic-circuit/examples/README.md b/components/agentic-circuit/examples/README.md
new file mode 100644
index 00000000..bad3ccce
--- /dev/null
+++ b/components/agentic-circuit/examples/README.md
@@ -0,0 +1,13 @@
+# Examples
+
+Examples are grouped by purpose. Product releases version the repository; the
+source tree does not keep parallel versioned or phase-numbered example sets.
+
+- [`pipelines`](pipelines/README.md): Queue/Var composition and control flow.
+- [`memory`](memory/README.md): explicit memory, banking, latency, and DMA.
+- [`blocks`](blocks/README.md): parameterized reusable building blocks.
+- [`architecture`](architecture/README.md): complete generated architecture models.
+- [`workspaces`](workspaces/README.md): CLI build/run/replay workspaces with goldens.
+
+Imported upstream source is not an example. It lives under [`references`](../references/README.md).
+Test-owned generated output lives under [`tests/goldens`](../tests/goldens/README.md).
diff --git a/components/agentic-circuit/examples/architecture/README.md b/components/agentic-circuit/examples/architecture/README.md
new file mode 100644
index 00000000..ae6c4c74
--- /dev/null
+++ b/components/agentic-circuit/examples/architecture/README.md
@@ -0,0 +1,9 @@
+# Architecture models
+
+This directory contains complete architecture-scale inputs and native harnesses.
+`davincioo_jit.py` specializes the current block catalog for the canonical
+DavinciOO trace, while `davincioo_trace_harness.cpp` executes the generated
+gfsim model.
+
+Byte-exact reports and visual goldens belong to
+[`tests/goldens/davincioo`](../../tests/goldens/davincioo/README.md).
diff --git a/components/agentic-circuit/examples/architecture/davincioo_jit.py b/components/agentic-circuit/examples/architecture/davincioo_jit.py
new file mode 100644
index 00000000..0105c031
--- /dev/null
+++ b/components/agentic-circuit/examples/architecture/davincioo_jit.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import agentic_circuit as ac
+
+
+@ac.config
+class CoreConfig:
+ engines: int
+ schedule_entries: int
+ rob_entries: int
+
+
+@ac.struct
+class PTOInst:
+ sequence: ac.u8
+ waits_for: ac.u8
+ engine: ac.u2
+ cycles: ac.u16
+ value: ac.u32
+
+
+@ac.system
+def davincioo(cfg: ac.const[CoreConfig]) -> None:
+ incoming = ac.source(PTOInst, depth=4, latency=1)
+
+ with ac.scope("decode"):
+ decoded = ac.compute(
+ incoming,
+ lambda item: item.with_fields(value=item.value + 1),
+ depth=4,
+ latency=1,
+ )
+
+ with ac.scope("pipeline"):
+ pipelined = ac.pipeline(decoded, stages=2, depth=4)
+
+ with ac.scope("dispatch"):
+ scalar, vector, cube, tma = ac.route(
+ pipelined,
+ by=PTOInst.engine,
+ outputs=cfg.engines,
+ depth=8,
+ latency=1,
+ )
+ dispatched = ac.merge(
+ scalar,
+ vector,
+ cube,
+ tma,
+ policy=ac.round_robin,
+ depth=8,
+ latency=1,
+ )
+
+ with ac.scope("schedule"):
+ completed = ac.schedule(
+ dispatched,
+ by=PTOInst.sequence,
+ waits_for=PTOInst.waits_for,
+ resource=PTOInst.engine,
+ cost=PTOInst.cycles,
+ entries=cfg.schedule_entries,
+ resources=cfg.engines,
+ no_dependency=255,
+ depth=16,
+ latency=1,
+ )
+
+ with ac.scope("retire"):
+ retired = ac.reorder(
+ completed,
+ by=PTOInst.sequence,
+ entries=cfg.rob_entries,
+ start=0,
+ depth=8,
+ latency=1,
+ )
+
+ ac.observe(retired)
+ ac.sink(retired)
+
+
+specialization = ac.jit(
+ davincioo,
+ cfg=CoreConfig(
+ engines=4,
+ schedule_entries=16,
+ rob_entries=64,
+ ),
+)
diff --git a/components/agentic-circuit/examples/architecture/davincioo_trace_harness.cpp b/components/agentic-circuit/examples/architecture/davincioo_trace_harness.cpp
new file mode 100644
index 00000000..3a6286f2
--- /dev/null
+++ b/components/agentic-circuit/examples/architecture/davincioo_trace_harness.cpp
@@ -0,0 +1,200 @@
+#include "davincioo.generated.cpp"
+#include "davincioo_trace_fixture.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+namespace {
+
+struct Span {
+ std::size_t sequence = 0;
+ std::string stage;
+ std::uint64_t begin = 0;
+ std::uint64_t end = 0;
+};
+
+class Tracker {
+public:
+ explicit Tracker(std::size_t count)
+ : current_(count, "source_wait"), begin_(count, 0), seen_(count, false),
+ completionSeen_(count, false), retirementSeen_(count, false) {}
+
+ void transition(std::size_t sequence, std::string_view stage,
+ std::uint64_t cycle) {
+ if (sequence >= current_.size() || current_[sequence] == stage)
+ return;
+ close(sequence, cycle);
+ current_[sequence] = stage;
+ begin_[sequence] = cycle;
+ seen_[sequence] = true;
+ }
+
+ void infer(std::size_t sequence, std::uint64_t cycle) {
+ if (!seen_[sequence])
+ return;
+ const std::string &stage = current_[sequence];
+ if (stage == "completed" || stage == "rob_wait")
+ transition(sequence, "rob_wait", cycle);
+ else if (stage == "dispatched" || stage == "schedule_execute")
+ transition(sequence, "schedule_execute", cycle);
+ }
+
+ void completion(std::size_t sequence) {
+ if (sequence < completionSeen_.size() && !completionSeen_[sequence]) {
+ completionSeen_[sequence] = true;
+ completionOrder_.push_back(sequence);
+ }
+ }
+
+ void retirement(std::size_t sequence) {
+ if (sequence < retirementSeen_.size() && !retirementSeen_[sequence]) {
+ retirementSeen_[sequence] = true;
+ retirementOrder_.push_back(sequence);
+ }
+ }
+
+ bool isRetired(std::size_t sequence) const {
+ return sequence < retirementSeen_.size() && retirementSeen_[sequence];
+ }
+
+ void finish(std::uint64_t cycle) {
+ for (std::size_t sequence = 0; sequence < current_.size(); ++sequence)
+ close(sequence, cycle);
+ }
+
+ const std::vector &spans() const { return spans_; }
+ const std::vector &completionOrder() const {
+ return completionOrder_;
+ }
+ const std::vector &retirementOrder() const {
+ return retirementOrder_;
+ }
+
+private:
+ void close(std::size_t sequence, std::uint64_t cycle) {
+ if (current_[sequence] != "done" && cycle > begin_[sequence])
+ spans_.push_back({sequence, current_[sequence], begin_[sequence], cycle});
+ }
+
+ std::vector current_;
+ std::vector begin_;
+ std::vector seen_;
+ std::vector completionSeen_;
+ std::vector retirementSeen_;
+ std::vector completionOrder_;
+ std::vector retirementOrder_;
+ std::vector spans_;
+};
+
+template
+void observeQueue(const Queue &queue, std::string_view stage,
+ std::vector> &observed,
+ Tracker *tracker = nullptr, bool completion = false,
+ bool retirement = false) {
+ for (const auto &item : queue.committedValues()) {
+ const std::size_t sequence = item.sequence;
+ if (sequence >= observed.size())
+ continue;
+ observed[sequence] = std::string(stage);
+ if (tracker && completion)
+ tracker->completion(sequence);
+ if (tracker && retirement)
+ tracker->retirement(sequence);
+ }
+}
+
+void printOrder(std::string_view name, const std::vector &order) {
+ std::cout << name;
+ for (std::size_t sequence : order)
+ std::cout << ' ' << sequence;
+ std::cout << '\n';
+}
+
+} // namespace
+
+int main() {
+ ac_generated::Davincioo model;
+ auto rows = model.dispatch_rows();
+ Tracker tracker(davincioo_fixture::kTokens.size());
+ std::size_t nextInput = 0;
+ std::uint64_t cycles = 0;
+
+ for (std::uint64_t tick = 0; tick < 4096; ++tick) {
+ while (nextInput < davincioo_fixture::kTokens.size() &&
+ model.incoming().canProposePush()) {
+ if (!model.incoming().proposePush(davincioo_fixture::kTokens[nextInput]))
+ break;
+ ++nextInput;
+ }
+
+ const gfsim::Epoch epoch{tick, 0};
+ for (auto &row : rows)
+ row.work(row.object, epoch);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Arbitrate);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Commit);
+
+ std::vector> observed(
+ davincioo_fixture::kTokens.size());
+ observeQueue(model.incoming(), "incoming", observed);
+ observeQueue(model.decoded(), "decoded", observed);
+ observeQueue(model.pipelined(), "pipelined", observed);
+ observeQueue(model.scalar(), "dispatch_scalar", observed);
+ observeQueue(model.vector(), "dispatch_vector", observed);
+ observeQueue(model.cube(), "dispatch_cube", observed);
+ observeQueue(model.tma(), "dispatch_tma", observed);
+ observeQueue(model.dispatched(), "dispatched", observed);
+ observeQueue(model.completed(), "completed", observed, &tracker, true);
+ for (const auto &item : model.retired().committedValues()) {
+ if (item.sequence >= observed.size())
+ continue;
+ const bool alreadyRetired = tracker.isRetired(item.sequence);
+ tracker.retirement(item.sequence);
+ observed[item.sequence] = alreadyRetired ? "done" : "retired";
+ }
+ for (const auto &item : model.sink_0_values()) {
+ if (item.sequence < observed.size()) {
+ const bool alreadyRetired = tracker.isRetired(item.sequence);
+ tracker.retirement(item.sequence);
+ observed[item.sequence] = alreadyRetired ? "done" : "retired";
+ }
+ }
+
+ for (std::size_t sequence = 0; sequence < observed.size(); ++sequence) {
+ if (observed[sequence])
+ tracker.transition(sequence, *observed[sequence], tick);
+ else
+ tracker.infer(sequence, tick);
+ }
+
+ if (model.sink_0_values().size() == davincioo_fixture::kTokens.size()) {
+ cycles = tick + 1;
+ break;
+ }
+ }
+
+ if (cycles == 0)
+ return 2;
+ tracker.finish(cycles);
+
+ std::cout << "SUMMARY " << cycles << ' ' << model.sink_0_values().size()
+ << '\n';
+ printOrder("COMPLETION", tracker.completionOrder());
+ printOrder("RETIREMENT", tracker.retirementOrder());
+ std::cout << "VALUES";
+ for (const auto &item : model.sink_0_values())
+ std::cout << ' ' << item.value;
+ std::cout << '\n';
+ for (const Span &span : tracker.spans())
+ std::cout << "SPAN " << span.sequence << ' '
+ << davincioo_fixture::kOpcodes[span.sequence] << ' ' << span.stage
+ << ' ' << span.begin << ' ' << span.end << '\n';
+ return 0;
+}
diff --git a/components/agentic-circuit/examples/blocks/README.md b/components/agentic-circuit/examples/blocks/README.md
new file mode 100644
index 00000000..206ff344
--- /dev/null
+++ b/components/agentic-circuit/examples/blocks/README.md
@@ -0,0 +1,5 @@
+# Parameterized blocks
+
+This directory contains small examples of reusable, statically specialized
+building blocks. `multirate_compute.py` demonstrates a compute block with a
+compile-time rate and latency contract.
diff --git a/components/agentic-circuit/examples/blocks/multirate_compute.py b/components/agentic-circuit/examples/blocks/multirate_compute.py
new file mode 100644
index 00000000..c4e5f1f6
--- /dev/null
+++ b/components/agentic-circuit/examples/blocks/multirate_compute.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import agentic_circuit as ac
+
+
+@ac.config
+class Config:
+ rate: int
+
+
+@ac.system
+def multirate_compute(cfg: ac.const[Config]) -> None:
+ incoming = ac.source(int, depth=8, rate=cfg.rate)
+ computed = ac.compute(
+ incoming,
+ lambda item: item + 1,
+ depth=8,
+ rate=cfg.rate,
+ )
+ pipelined = ac.pipeline(
+ computed,
+ stages=2,
+ depth=8,
+ rate=cfg.rate,
+ )
+ ac.sink(pipelined)
+
+
+specialization = ac.jit(multirate_compute, cfg=Config(rate=4))
diff --git a/components/agentic-circuit/examples/memory/README.md b/components/agentic-circuit/examples/memory/README.md
new file mode 100644
index 00000000..db5512ef
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/README.md
@@ -0,0 +1,216 @@
+# Agentic Circuit memory examples
+
+## Parameterized high-level blocks
+
+`davincioo_jit.py` keeps every dynamic connection as a typed Queue SSA edge,
+freezes `CoreConfig` through `ac.jit`, and uses the simple high-level block
+names `compute`, `route`, `pipeline`, `merge`, `schedule`, and `reorder`.
+Only `compute` carries a lambda; other blocks select typed payload fields with
+compile-time descriptors and bind optimized gfsim and PYC/Verilog providers.
+
+```bash
+PYTHONPATH=src python - <<'PY'
+from examples.architecture.davincioo_jit import specialization
+
+open("build/davincioo.ac.mlir", "w").write(specialization.lower_acir())
+open("build/davincioo.cpp", "w").write(specialization.lower_cpp())
+PY
+
+c++ -std=c++20 -I include -fsyntax-only build/davincioo.cpp
+```
+
+`specialization.materialize_cpp(cache_root)` compiles the generated C++ on
+first use and returns the content-addressed cached object later.
+`materialize_pyc(...)` publishes the corresponding PYC/C++/Verilog bundle.
+
+`multirate_compute.py` freezes `rate=4` into the Queue and C++ template
+identities. Native QueueGraph/gfsim supports it; PYC deliberately rejects
+`rate>1` until shared ordered FIFO lane lowering is implemented.
+
+### DavinciOO canonical PTO trace
+
+The trace runner converts the locked DavinciOO JSONL trace to canonical PTO
+trace JSON, specializes the high-level Python model, compiles generated gfsim,
+and checks completion order, retirement order, architectural values, and the
+453-cycle reference contract. It also emits a deterministic instruction
+swimlane.
+
+```bash
+.venv/bin/python tools/run-davincioo.py
+```
+
+Checked-in evidence:
+
+- [`davincioo-softmax-run.json`](../../tests/goldens/davincioo/davincioo-softmax-run.json)
+- [`davincioo-softmax-swimlane.svg`](../../tests/goldens/davincioo/davincioo-softmax-swimlane.svg)
+
+## Explicit memory (epoch 0.3)
+
+`memory_simple.py` declares one root-owned, 16-entry `u16` memory and connects
+two typed logical endpoints from child scopes. Writer endpoint ordinal 0 has
+fixed priority over reader endpoint ordinal 1.
+
+The harness makes both endpoints valid together. Two writes to address `3`
+return old values `0` and `42`; only after those responses complete can the
+reader run, and it observes the final value `99`. This exercises:
+
+- one physical memory shared by multiple logical request endpoints;
+- root-to-descendant scope visibility;
+- canonical fixed-priority arbitration;
+- one outstanding request and global busy backpressure;
+- endpoint-specific write policies and response demultiplexing;
+- old-data write responses.
+
+From the repository root:
+
+```bash
+PYTHONPATH=src \
+ .venv/bin/python \
+ tools/ac-queue-cxxgen.py examples/memory/memory_simple.py \
+ --system memory_simple \
+ --acir-output /tmp/memory_simple.mlir \
+ --plan-output /tmp/memory_simple.plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output examples/memory/memory_simple.generated.cpp
+
+c++ \
+ -std=c++20 -Iinclude -Iexamples/memory \
+ examples/memory/memory_simple_harness.cpp \
+ -o /tmp/memory_simple_sim
+
+/tmp/memory_simple_sim
+```
+
+Expected output:
+
+```text
+cycles=8 write_old_values=0,42 read_after_priority=99
+```
+
+The generated `memory_simple.generated.cpp` is a build artifact and is not
+checked in.
+
+## Statically expanded memory banks
+
+`memory_banks.py` uses a homogeneous `ac.array` of four memories. The
+Python-only `banks.select(...).request(...)` expansion makes bank selection
+explicit while lowering entirely to the existing `ac.route`, four
+`ac.memory.instance`/`ac.memory.request` pairs, and one `ac.merge`. Each bank
+has independent storage and one outstanding request; responses from different
+banks may be reordered, so the harness checks them by tag.
+
+```bash
+PYTHONPATH=src \
+ .venv/bin/python \
+ tools/ac-queue-cxxgen.py examples/memory/memory_banks.py \
+ --system memory_banks \
+ --acir-output /tmp/memory_banks.mlir \
+ --plan-output /tmp/memory_banks.plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output examples/memory/memory_banks.generated.cpp
+
+c++ \
+ -std=c++20 -Iinclude -Iexamples/memory \
+ examples/memory/memory_banks_harness.cpp \
+ -o /tmp/memory_banks_sim
+
+/tmp/memory_banks_sim
+```
+
+Expected output has the following values; the cycle count is deterministic but
+is intentionally not part of the example contract:
+
+```text
+cycles= bank0=41 bank1=91 bank2_initial=0
+```
+
+## Single-memory busy backpressure
+
+`memory_busy.py` uses `ac.memory(..., latency=3)` and issues two reads at
+different simulated times. Its harness prints the public request Queue
+occupancy after every epoch: the second request remains queued throughout the
+physical access latency, then is accepted only after the first response
+releases `busy`.
+
+```bash
+PYTHONPATH=src \
+ .venv/bin/python \
+ tools/ac-queue-cxxgen.py examples/memory/memory_busy.py \
+ --system memory_busy \
+ --acir-output /tmp/memory_busy.mlir \
+ --plan-output /tmp/memory_busy.plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output examples/memory/memory_busy.generated.cpp
+
+c++ \
+ -std=c++20 -Iinclude -Iexamples/memory \
+ examples/memory/memory_busy_harness.cpp \
+ -o /tmp/memory_busy_sim
+
+/tmp/memory_busy_sim
+```
+
+Expected output:
+
+```text
+epoch req_q received event
+ 0 1 0 request A queued
+ 1 1 0 A accepted; request B queued
+ 2 1 0 B blocked by memory latency
+ 3 1 0 B blocked by memory latency
+ 4 1 0 A response accepted; busy released
+ 5 0 1 B accepted
+ 6 0 1 B response pending
+ 7 0 1 B response pending
+ 8 0 1 B response accepted; busy released
+ 9 0 2 sink received B
+latency_blocked=1 accepted_after_release=1 responses=2
+```
+
+## DMA-style DRAM-to-SRAM copy
+
+`dma.py` declares root-owned DRAM and SRAM instances. Inside
+`with ac.scope("dma")`, the DRAM response Queue directly drives an SRAM write
+endpoint. The harness first seeds `DRAM[5]` with `0x1234`, runs one DMA copy to
+`SRAM[3]`, then reads SRAM back to verify the transferred value.
+
+```bash
+PYTHONPATH=src \
+ .venv/bin/python \
+ tools/ac-queue-cxxgen.py examples/memory/dma.py \
+ --system dma \
+ --acir-output /tmp/dma.mlir \
+ --plan-output /tmp/dma.plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ --output examples/memory/dma.generated.cpp
+
+c++ \
+ -std=c++20 -Iinclude -Iexamples/memory \
+ examples/memory/dma_harness.cpp \
+ -o /tmp/dma_sim
+
+/tmp/dma_sim
+```
+
+Expected output:
+
+```text
+seed_tick=5 copy_tick=14 verify_tick=19 dram_value=0x1234 copy_old_sram=0
+```
+
+## Current boundary
+
+The 0.3 contract intentionally supports one physical port and one outstanding
+request per memory instance. It does not provide true multi-port access,
+round-robin fairness, response reordering, byte enables, or non-zero
+initialization. A continuously valid higher-priority endpoint can starve lower
+ordinals. All endpoints of an instance must use the same payload struct and
+the memory data/address widths are limited to 64 bits.
diff --git a/components/agentic-circuit/examples/memory/dma.py b/components/agentic-circuit/examples/memory/dma.py
new file mode 100644
index 00000000..021631ab
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/dma.py
@@ -0,0 +1,75 @@
+"""DMA-style DRAM-to-SRAM copy built from explicit memory endpoints.
+
+The memories are owned by the root scope. The ``dma`` scope connects a
+request Queue to a DRAM read endpoint and feeds that response Queue directly
+into an SRAM write endpoint:
+
+ requests -> DRAM read -> dram_responses -> SRAM write -> copy_responses
+
+Each DMA token carries both addresses. The DRAM response replaces ``data``
+with the value read from DRAM; the following SRAM endpoint uses that value as
+its write data. The SRAM response contains SRAM old-data, as required by the
+memory contract.
+"""
+
+import agentic_circuit as ac
+
+
+@ac.struct
+class DmaRequest:
+ dram_address: ac.u4
+ sram_address: ac.u4
+ data: ac.u16
+ tag: ac.u8
+
+
+@ac.system
+def dma() -> None:
+ dram = ac.memory(ac.u16, entries=16, init=0, latency=3)
+ sram = ac.memory(ac.u16, entries=16, init=0, latency=2)
+
+ # Test/host endpoint used by the harness to put non-zero data in DRAM.
+ with ac.scope("host"):
+ dram_seed = ac.source(DmaRequest, depth=2, latency=1)
+ dram_seed_responses = dram.request(
+ dram_seed,
+ address=lambda request: request.dram_address,
+ write=lambda request: True,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ )
+ ac.sink(dram_seed_responses)
+
+ with ac.scope("dma"):
+ requests = ac.source(DmaRequest, depth=4, latency=1)
+ dram_responses = dram.request(
+ requests,
+ address=lambda request: request.dram_address,
+ write=lambda request: False,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ )
+ copy_responses = sram.request(
+ dram_responses,
+ address=lambda response: response.sram_address,
+ write=lambda response: True,
+ data=lambda response: response.data,
+ result_field="data",
+ depth=2,
+ )
+ ac.sink(copy_responses)
+
+ # Independent read endpoint used to verify the copied SRAM value.
+ with ac.scope("check"):
+ sram_reads = ac.source(DmaRequest, depth=2, latency=1)
+ sram_read_responses = sram.request(
+ sram_reads,
+ address=lambda request: request.sram_address,
+ write=lambda request: False,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ )
+ ac.sink(sram_read_responses)
diff --git a/components/agentic-circuit/examples/memory/dma_harness.cpp b/components/agentic-circuit/examples/memory/dma_harness.cpp
new file mode 100644
index 00000000..550aff0d
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/dma_harness.cpp
@@ -0,0 +1,69 @@
+#include "dma.generated.cpp"
+
+#include
+#include
+#include
+
+namespace {
+
+void step(ac_generated::Dma &model, std::size_t tick) {
+ const gfsim::Epoch epoch{tick, 0};
+ auto rows = model.dispatch_rows();
+ for (auto &row : rows)
+ row.work(row.object, epoch);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Arbitrate);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Commit);
+}
+
+template
+std::size_t runUntil(ac_generated::Dma &model, std::size_t &nextTick,
+ Done done) {
+ while (nextTick < 64) {
+ const std::size_t current = nextTick++;
+ step(model, current);
+ if (done())
+ return current;
+ }
+ return 64;
+}
+
+} // namespace
+
+int main() {
+ ac_generated::Dma model;
+ std::size_t nextTick = 0;
+
+ // Host writes 0x1234 to DRAM[5].
+ if (!model.dram_seed().proposePush({5, 3, 0x1234, 1}))
+ return 1;
+ const std::size_t seedTick = runUntil(
+ model, nextTick, [&] { return model.sink_0_values().size() == 1; });
+ if (seedTick == 64 || model.sink_0_values()[0].data != 0)
+ return 2;
+
+ // DMA reads DRAM[5] and writes the returned value into SRAM[3].
+ if (!model.requests().proposePush({5, 3, 0, 2}))
+ return 3;
+ const std::size_t copyTick = runUntil(
+ model, nextTick, [&] { return model.sink_1_values().size() == 1; });
+ if (copyTick == 64 || model.sink_1_values()[0].tag != 2 ||
+ model.sink_1_values()[0].data != 0)
+ return 4;
+
+ // Read SRAM[3]. The response proves that the DMA copied the DRAM value.
+ if (!model.sram_reads().proposePush({0, 3, 0, 3}))
+ return 5;
+ const std::size_t verifyTick = runUntil(
+ model, nextTick, [&] { return model.sink_2_values().size() == 1; });
+ if (verifyTick == 64 || model.sink_2_values()[0].tag != 3 ||
+ model.sink_2_values()[0].data != 0x1234)
+ return 6;
+
+ std::cout << "seed_tick=" << seedTick << " copy_tick=" << copyTick
+ << " verify_tick=" << verifyTick << " dram_value=0x" << std::hex
+ << model.sink_2_values()[0].data << std::dec
+ << " copy_old_sram=" << model.sink_1_values()[0].data << "\n";
+ return 0;
+}
diff --git a/components/agentic-circuit/examples/memory/memory_banks.py b/components/agentic-circuit/examples/memory/memory_banks.py
new file mode 100644
index 00000000..278d45d0
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_banks.py
@@ -0,0 +1,66 @@
+"""Statically expanded banked-memory example for contract epoch 0.3.
+
+The companion harness injects five requests before tick 0:
+
+ tag operation
+ 1 bank0[3] = 41 (returns old data 0)
+ 2 bank1[3] = 91 (returns old data 0)
+ 3 read bank0[3] (returns 41)
+ 4 read bank1[3] (returns 91)
+ 5 read bank2[3] (returns 0)
+
+Current gfsim event pipeline (R=route, A=bank accept, P=bank response,
+M=priority merge, S=sink):
+
+ tick 0 1 2 3 4 5 6 7 8 9 10 11
+ input t1 Q R A . P M S . . . . .
+ input t2 Q . R A . P M S . . . .
+ input t3 Q . . R W A . P M S . .
+ input t4 Q . . . R W A . P M S .
+ input t5 Q . . . . R A . P W M S
+
+Q commits the initially injected token, and W marks waiting caused by either
+a busy bank or priority-merge serialization. Notice that bank1 accepts tag 2
+while bank0 is still processing tag 1, and bank1/bank2 accept tags 4/5 in the
+same tick. Requests to one bank remain single-outstanding.
+"""
+
+import agentic_circuit as ac
+
+
+@ac.struct
+class BankRequest:
+ bank: ac.u2
+ offset: ac.u4
+ write: ac.u1
+ data: ac.u16
+ tag: ac.u8
+
+
+@ac.system
+def memory_banks() -> None:
+ requests = ac.source(BankRequest, depth=8, latency=1)
+
+ with ac.scope("sram"):
+ banks = ac.array(
+ 4,
+ lambda _: ac.memory(ac.u16, entries=16, init=0, latency=2),
+ )
+ selected = banks.select(
+ requests,
+ key=lambda request: request.bank,
+ depth=2,
+ latency=1,
+ )
+ responses = selected.request(
+ address=lambda request: request.offset,
+ write=lambda request: request.write,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ merge_policy="priority",
+ merge_depth=2,
+ merge_latency=1,
+ )
+
+ ac.sink(responses)
diff --git a/components/agentic-circuit/examples/memory/memory_banks_harness.cpp b/components/agentic-circuit/examples/memory/memory_banks_harness.cpp
new file mode 100644
index 00000000..31acbeb5
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_banks_harness.cpp
@@ -0,0 +1,55 @@
+#include "memory_banks.generated.cpp"
+
+#include
+#include
+#include
+#include
+
+int main() {
+ ac_generated::MemoryBanks model;
+ const std::array requests{{
+ ac_generated::BankRequest{0, 3, 1, 41, 1},
+ ac_generated::BankRequest{1, 3, 1, 91, 2},
+ ac_generated::BankRequest{0, 3, 0, 0, 3},
+ ac_generated::BankRequest{1, 3, 0, 0, 4},
+ ac_generated::BankRequest{2, 3, 0, 0, 5},
+ }};
+
+ for (const auto &request : requests)
+ if (!model.requests().proposePush(request))
+ return 1;
+
+ auto rows = model.dispatch_rows();
+ std::size_t cycles = 0;
+ for (std::size_t tick = 0; tick < 64; ++tick) {
+ const gfsim::Epoch epoch{tick, 0};
+ for (auto &row : rows)
+ row.work(row.object, epoch);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Arbitrate);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Commit);
+ if (model.sink_0_values().size() == requests.size()) {
+ cycles = tick + 1;
+ break;
+ }
+ }
+
+ std::array oldDataByTag{};
+ const auto &responses = model.sink_0_values();
+ if (responses.size() != requests.size())
+ return 2;
+ for (const auto &response : responses) {
+ if (response.tag == 0 || response.tag >= oldDataByTag.size())
+ return 3;
+ oldDataByTag[response.tag] = response.data;
+ }
+ if (oldDataByTag[1] != 0 || oldDataByTag[2] != 0 || oldDataByTag[3] != 41 ||
+ oldDataByTag[4] != 91 || oldDataByTag[5] != 0)
+ return 4;
+
+ std::cout << "cycles=" << cycles << " bank0=" << oldDataByTag[3]
+ << " bank1=" << oldDataByTag[4]
+ << " bank2_initial=" << oldDataByTag[5] << "\n";
+ return 0;
+}
diff --git a/components/agentic-circuit/examples/memory/memory_busy.py b/components/agentic-circuit/examples/memory/memory_busy.py
new file mode 100644
index 00000000..fbeba17b
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_busy.py
@@ -0,0 +1,42 @@
+"""Single-memory busy/backpressure example for contract epoch 0.3.
+
+The companion harness injects read A (tag 1) before tick 0 and read B (tag 2)
+before tick 1. Both access zero-initialized locations through one memory with
+``latency=3``.
+
+Current gfsim event pipeline (Q=request Queue commit, A=memory accept,
+W=waiting while the memory is busy, P=response Queue commit/busy release,
+S=sink):
+
+ tick 0 1 2 3 4 5 6 7 8 9
+ read A Q A . . P S . . . .
+ read B . Q W W W A . . P S
+
+Read B remains at the head of the request Queue while A is outstanding. A's
+response releases ``busy`` at tick 4, but the no-same-epoch-reaccept rule means
+B can be accepted only at tick 5. Both responses return old data 0.
+"""
+
+import agentic_circuit as ac
+
+
+@ac.struct
+class ReadRequest:
+ address: ac.u4
+ data: ac.u16
+ tag: ac.u8
+
+
+@ac.system
+def memory_busy() -> None:
+ sram = ac.memory(ac.u16, entries=16, init=0, latency=3)
+ requests = ac.source(ReadRequest, depth=4, latency=1)
+ responses = sram.request(
+ requests,
+ address=lambda request: request.address,
+ write=lambda request: False,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=1,
+ )
+ ac.sink(responses)
diff --git a/components/agentic-circuit/examples/memory/memory_busy_harness.cpp b/components/agentic-circuit/examples/memory/memory_busy_harness.cpp
new file mode 100644
index 00000000..e8f2b794
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_busy_harness.cpp
@@ -0,0 +1,75 @@
+#include "memory_busy.generated.cpp"
+
+#include
+#include
+#include
+
+namespace {
+
+void step(ac_generated::MemoryBusy &model, std::size_t tick) {
+ const gfsim::Epoch epoch{tick, 0};
+ auto rows = model.dispatch_rows();
+ for (auto &row : rows)
+ row.work(row.object, epoch);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Arbitrate);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Commit);
+}
+
+} // namespace
+
+int main() {
+ ac_generated::MemoryBusy model;
+ const ac_generated::ReadRequest first{3, 0, 1};
+ const ac_generated::ReadRequest second{7, 0, 2};
+
+ std::cout << "epoch req_q received event\n";
+ auto record = [&](std::size_t tick, const char *event) {
+ step(model, tick);
+ std::cout << std::setw(5) << tick << " " << std::setw(5)
+ << model.requests().committedSize() << " " << std::setw(8)
+ << model.sink_0_values().size() << " " << event << "\n";
+ };
+
+ // Epoch 0 publishes the first request into the source Queue.
+ if (!model.requests().proposePush(first))
+ return 1;
+ record(0, "request A queued");
+ if (model.requests().committedSize() != 1)
+ return 2;
+
+ // Offer the second request at a later simulated time. Epoch 1 accepts the
+ // first request and commits the second, leaving exactly one queued request.
+ if (!model.requests().proposePush(second))
+ return 3;
+ record(1, "A accepted; request B queued");
+ if (model.requests().committedSize() != 1)
+ return 4;
+
+ // With instance latency 3, B stays queued throughout epochs 2 and 3. A's
+ // response matures in epoch 4, and the no-same-epoch rule still keeps B.
+ record(2, "B blocked by memory latency");
+ record(3, "B blocked by memory latency");
+ record(4, "A response accepted; busy released");
+ if (model.requests().committedSize() != 1)
+ return 5;
+
+ // B can fire only in the epoch after A releases busy.
+ record(5, "B accepted");
+ if (model.requests().committedSize() != 0)
+ return 6;
+
+ record(6, "B response pending");
+ record(7, "B response pending");
+ record(8, "B response accepted; busy released");
+ record(9, "sink received B");
+ const auto &responses = model.sink_0_values();
+ if (responses.size() != 2 || responses[0].tag != 1 || responses[1].tag != 2 ||
+ responses[0].data != 0 || responses[1].data != 0)
+ return 7;
+
+ std::cout << "latency_blocked=1 accepted_after_release=1 responses="
+ << responses.size() << "\n";
+ return 0;
+}
diff --git a/components/agentic-circuit/examples/memory/memory_simple.py b/components/agentic-circuit/examples/memory/memory_simple.py
new file mode 100644
index 00000000..38fa3cba
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_simple.py
@@ -0,0 +1,43 @@
+"""Shared explicit-memory Queue frontend example for contract epoch 0.3."""
+
+import agentic_circuit as ac
+
+
+@ac.struct
+class MemoryRequest:
+ address: ac.u4
+ data: ac.u16
+ tag: ac.u8
+
+
+@ac.system
+def memory_simple() -> None:
+ # One physical SRAM is owned by the root scope. Both child scopes borrow it.
+ sram = ac.memory(ac.u16, entries=16, init=0, latency=1)
+
+ # Canonical endpoint ordinal 0: fixed-priority writer.
+ with ac.scope("a_writer"):
+ writes = ac.source(MemoryRequest, depth=4, latency=1)
+ write_responses = sram.request(
+ writes,
+ address=lambda request: request.address,
+ write=lambda request: True,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ )
+ ac.sink(write_responses)
+
+ # Canonical endpoint ordinal 1: reader, accepted only when the SRAM is idle
+ # and no writer request is valid.
+ with ac.scope("b_reader"):
+ reads = ac.source(MemoryRequest, depth=4, latency=1)
+ read_responses = sram.request(
+ reads,
+ address=lambda request: request.address,
+ write=lambda request: False,
+ data=lambda request: request.data,
+ result_field="data",
+ depth=2,
+ )
+ ac.sink(read_responses)
diff --git a/components/agentic-circuit/examples/memory/memory_simple_harness.cpp b/components/agentic-circuit/examples/memory/memory_simple_harness.cpp
new file mode 100644
index 00000000..387345b8
--- /dev/null
+++ b/components/agentic-circuit/examples/memory/memory_simple_harness.cpp
@@ -0,0 +1,53 @@
+#include "memory_simple.generated.cpp"
+
+#include
+#include
+#include
+
+int main() {
+ ac_generated::MemorySimple model;
+ const std::array writes{{
+ ac_generated::MemoryRequest{3, 42, 1},
+ ac_generated::MemoryRequest{3, 99, 2},
+ }};
+ const ac_generated::MemoryRequest read{3, 0, 3};
+
+ // Both logical endpoints are valid before the first simulated epoch. Fixed
+ // priority drains both writer requests before accepting the reader request.
+ for (const auto &request : writes)
+ if (!model.writes().proposePush(request))
+ return 1;
+ if (!model.reads().proposePush(read))
+ return 1;
+
+ auto rows = model.dispatch_rows();
+ std::size_t cycles = 0;
+ for (std::size_t tick = 0; tick < 32; ++tick) {
+ const gfsim::Epoch epoch{tick, 0};
+ for (auto &row : rows)
+ row.work(row.object, epoch);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Arbitrate);
+ for (auto &row : rows)
+ row.xfer(row.object, epoch, gfsim::XferPhase::Commit);
+ if (model.sink_0_values().size() == writes.size() &&
+ model.sink_1_values().size() == 1) {
+ cycles = tick + 1;
+ break;
+ }
+ }
+
+ const auto &write_responses = model.sink_0_values();
+ const auto &read_responses = model.sink_1_values();
+ if (write_responses.size() != 2 || write_responses[0].data != 0 ||
+ write_responses[0].tag != 1 || write_responses[1].data != 42 ||
+ write_responses[1].tag != 2 || read_responses.size() != 1 ||
+ read_responses[0].data != 99 || read_responses[0].tag != 3)
+ return 2;
+
+ std::cout << "cycles=" << cycles
+ << " write_old_values=" << write_responses[0].data << ","
+ << write_responses[1].data
+ << " read_after_priority=" << read_responses[0].data << "\n";
+ return 0;
+}
diff --git a/components/agentic-circuit/examples/pipelines/README.md b/components/agentic-circuit/examples/pipelines/README.md
new file mode 100644
index 00000000..1cb3b310
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/README.md
@@ -0,0 +1,110 @@
+# Queue/Var DavinciOO-like model
+
+The [Agentic Circuit Specification Manual](../../docs/spec/agentic-circuit.md)
+defines the authoring, ACIR, runtime, backend, and refinement contracts exercised
+by these examples.
+
+`davincioo_queue_model.py` is the first executable topology generated
+from serial Python. It uses only repository-owned common building blocks:
+`ac.source`, `ac.transform`, `ac.dependency`, `ac.route`, `ac.merge`,
+`ac.observe`, `ac.reorder`, and `ac.sink`, connected by typed `ac.queue` values.
+
+Generate one canonical typed C++ model:
+
+```bash
+PYTHONPATH=src tools/ac-queue-cxxgen.py \
+ examples/pipelines/davincioo_queue_model.py \
+ --system davincioo_queue_model \
+ --acir-output build/davincioo_queue_model.ac.mlir \
+ --plan-output build/davincioo_queue_model.queue-plan.json \
+ --acir-opt build/dev-llvm22/bin/acir-opt \
+ --queue-plan-tool build/dev-llvm22/bin/acir-queue-plan \
+ --queue-cxxgen-tool build/dev-llvm22/bin/acir-queue-cxxgen \
+ -o build/davincioo_queue_model.cpp
+```
+
+The generated class owns every interconnect as a typed `gfsim::SimQueue`.
+Lexical scopes become `gfsim::Module` hierarchy nodes. Engine blocks borrow
+Queue references; they do not allocate or own sibling interconnect.
+
+The example models the reference shape at building-block level:
+
+```text
+trace -> frontend -> dependency window -> 4-way dispatch
+ | scalar
+ | vector
+ | cube
+ | tma
+ merge -> reorder -> retire -> sink
+```
+
+The checked-in
+[`softmax-projection.json`](../../tests/goldens/davincioo/softmax-projection.json) binds
+this generated topology to the provenance-locked 15-record softmax trace. It
+records opcode identities, engine routes, reference execution costs, explicit
+predecessors, fixed boundary-cycle compensation, out-of-order completion order,
+in-order retirement, architectural values, and the 453-cycle oracle.
+
+The generated model uses the official bounded `ac.dependency` window with four
+reserved resource classes, round-robin merge, committed observations, and the
+official `ac.reorder` block. The same serial Python and frozen ACIR now pass all
+of these gates:
+
+- typed gfsim consumes all 15 projected records and finishes in 453 cycles;
+- opcode counts and completion/retirement order match the reference projection;
+- copied-source generation remains byte-identical across unrelated roots;
+- the same frozen ACIR builds with pinned `pycc` as PYC C++ and Verilog;
+- PYC C++ and Verilator produce cycle-identical ready/valid/data observations;
+- gfsim, PYC C++, and Verilog produce the same projected output transactions.
+
+Dependency wait is no longer folded into token latency. `ac.dependency` tracks
+predecessor completion explicitly and counts the reference execution cost. The
+projection applies only a documented 5-cycle ingress and 4-cycle drain
+compensation for the different Queue boundaries. It checks dependency-window
+peak occupancy, per-resource executing peaks, and reorder-window peak occupancy
+through stable generated-model accessors; raw reference rename-table structure
+remains outside the declared observation projection.
+
+## PYC and Verilog slice
+
+`pyc_queue_pipeline.py` exercises the initial scalar hardware lowering. Generate
+frozen ACIR first, then run `acir-queue-pycgen` or the bundled
+`tools/ac-queue-pyc-build.py` command. The bundle command validates the pinned
+toolchain lock, invokes external `pycc` for C++ and Verilog, compiles the C++
+source, runs Verilator lint, and writes a canonical hash manifest.
+
+The pinned toolchain is recorded in `toolchains/pyc.lock.json`. Build that
+exact pyCircuit commit with LLVM 19 before running the PYC gate.
+
+`pyc_struct_pipeline.py` verifies deterministic packed struct layout.
+`pyc_route_merge_pipeline.py` verifies static selector demux and priority merge
+logic, including forward valid and backward ready paths.
+`pyc_select_pipeline.py` verifies runtime selection from a statically shaped
+Queue collection without dynamic Queue pointers.
+`pyc_atomic_pipeline.py` verifies multi-source/multi-sink atomic firing.
+`pyc_firing_pipeline.py` verifies explicit Python `peek`/`pop`/`push` effects
+normalize to the standard atomic transform.
+`gfsim_expect_pipeline.py` verifies a verification-role leaf executes in gfsim
+and is rejected from PYC design hierarchy with testbench-boundary guidance.
+`pyc_fork_pipeline.py` verifies decoupled fanout with per-output delivered state.
+`pyc_conditional_pipeline.py` verifies that a serial runtime `if` becomes an
+official route, two branch transforms, and a mutually exclusive priority merge.
+`pyc_feedback_pipeline.py` verifies a bounded serial `while` as sequential
+feedback data, valid, and iteration state shared by PYC C++ and Verilog.
+`pyc_loop_control_pipeline.py` verifies a leading runtime `break` and tail
+`continue` normalize to explicit bounded feedback conditions.
+`pyc_recursive_pipeline.py` verifies bounded compile-time recursion expands to
+a frozen three-stage Queue chain before ACIR publication.
+`pyc_reorder_pipeline.py` verifies bounded key-ordered retirement with the same
+register-bank and handshake semantics in typed gfsim, PYC C++, and Verilog.
+`pyc_dependency_pipeline.py` verifies predecessor wakeup, execution countdown,
+out-of-order completion, and PYC C++/Verilator cycle equivalence.
+`pyc_barrier_pipeline.py` verifies heterogeneous positional payloads and an
+all-input/all-output atomic synchronization firing shared by typed gfsim, PYC
+C++, and Verilog.
+`pyc_credit_pipeline.py` verifies bounded parallel in-flight slots, independent
+cost countdown, deterministic completion selection, automatic credit return,
+and PYC C++/Verilator cycle equivalence.
+`pyc_memory_pipeline.py` verifies an explicit typed memory instance, old-data
+read-during-write behavior, aligned request/response state, and exactly one
+`pyc.sync_mem` realization per instance in PYC C++ and Verilog.
diff --git a/components/agentic-circuit/examples/pipelines/davincioo_queue_model.py b/components/agentic-circuit/examples/pipelines/davincioo_queue_model.py
new file mode 100644
index 00000000..e3e0d319
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/davincioo_queue_model.py
@@ -0,0 +1,91 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class WorkItem:
+ sequence_id: ac.u8
+ opcode: ac.u8
+ route: ac.u2
+ waits_for: ac.u8
+ cycles: ac.u16
+ value: ac.u64
+
+
+@ac.system
+def davincioo_queue_model() -> None:
+ trace = ac.source(WorkItem, depth=16, latency=1)
+
+ with ac.scope("frontend"):
+ prepared = trace.apply(
+ lambda item: item.with_fields(value=item.value + 1),
+ depth=4,
+ latency=1,
+ )
+
+ with ac.scope("dependency"):
+ scheduled = prepared.depend(
+ key=lambda item: item.sequence_id,
+ waits_for=lambda item: item.waits_for,
+ resource=lambda item: item.route,
+ cost=lambda item: item.cycles,
+ capacity=8,
+ resources=4,
+ no_dependency=255,
+ depth=16,
+ latency=1,
+ )
+ ac.observe(scheduled)
+
+ with ac.scope("dispatch"):
+ scalar, vector, cube, tma = scheduled.route(
+ outputs=4,
+ key=lambda item: item.route,
+ depth=8,
+ latency=1,
+ )
+
+ with ac.scope("scalar_engine"):
+ scalar_done = scalar.apply(
+ lambda item: item.with_fields(value=item.value + 1)
+ )
+ with ac.scope("vector_engine"):
+ vector_done = vector.apply(
+ lambda item: item.with_fields(value=item.value + 2)
+ )
+ ac.observe(vector_done)
+ with ac.scope("cube_engine"):
+ cube_done = cube.apply(
+ lambda item: item.with_fields(value=item.value + 3)
+ )
+ with ac.scope("tma_engine"):
+ tma_done = tma.apply(
+ lambda item: item.with_fields(value=item.value + 4)
+ )
+ ac.observe(tma_done)
+
+ completed = scalar_done.merge(
+ vector_done,
+ cube_done,
+ tma_done,
+ policy="round_robin",
+ depth=8,
+ latency=1,
+ )
+ ac.observe(completed)
+
+ ordered = completed.reorder(
+ key=lambda item: item.sequence_id,
+ capacity=64,
+ start=0,
+ depth=8,
+ latency=1,
+ )
+
+ with ac.scope("retire"):
+ retired = ordered.apply(
+ lambda item: item.with_fields(
+ value=item.value + 100,
+ )
+ )
+
+ ac.sink(retired)
diff --git a/components/agentic-circuit/examples/pipelines/gfsim_expect_pipeline.py b/components/agentic-circuit/examples/pipelines/gfsim_expect_pipeline.py
new file mode 100644
index 00000000..3658a1eb
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/gfsim_expect_pipeline.py
@@ -0,0 +1,17 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class ExpectedToken:
+ value: ac.u16
+
+
+@ac.system
+def gfsim_expect_pipeline() -> None:
+ incoming = ac.source(ExpectedToken, depth=2, latency=1)
+ ac.expect(
+ incoming,
+ predicate=lambda item: item.value > 0,
+ message="value must be positive",
+ )
+ ac.sink(incoming)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_atomic_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_atomic_pipeline.py
new file mode 100644
index 00000000..5cf57d70
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_atomic_pipeline.py
@@ -0,0 +1,12 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_atomic_pipeline() -> None:
+ left = ac.source(int)
+ right = ac.source(int)
+ with ac.atomic():
+ left_next = left.apply(lambda item: item + 1)
+ right_next = right.apply(lambda item: item * 2)
+ ac.sink(left_next)
+ ac.sink(right_next)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_barrier_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_barrier_pipeline.py
new file mode 100644
index 00000000..349aec9b
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_barrier_pipeline.py
@@ -0,0 +1,20 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class LeftToken:
+ value: ac.u16
+
+
+@ac.struct
+class RightToken:
+ value: ac.u32
+
+
+@ac.system
+def pyc_barrier_pipeline() -> None:
+ left = ac.source(LeftToken, depth=2, latency=1)
+ right = ac.source(RightToken, depth=2, latency=1)
+ left_ready, right_ready = left.barrier(right, depth=2, latency=1)
+ ac.sink(left_ready)
+ ac.sink(right_ready)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_broadcast_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_broadcast_pipeline.py
new file mode 100644
index 00000000..ceeb53a7
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_broadcast_pipeline.py
@@ -0,0 +1,10 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_broadcast_pipeline() -> None:
+ input_queue = ac.source(int, depth=2, latency=1)
+ left = input_queue.apply(lambda item: item + 1)
+ right = input_queue.apply(lambda item: item + 2)
+ merged = left.merge(right, policy="priority", depth=2, latency=1)
+ ac.sink(merged)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_conditional_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_conditional_pipeline.py
new file mode 100644
index 00000000..9bd8f77d
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_conditional_pipeline.py
@@ -0,0 +1,21 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class Item:
+ value: ac.u32
+ route: ac.u1
+
+
+@ac.system
+def pyc_conditional_pipeline() -> None:
+ input_queue = ac.source(Item, depth=2, latency=1)
+ if input_queue.route == 0:
+ output_queue = input_queue.apply(
+ lambda item: item.with_fields(value=item.value + 10)
+ )
+ else:
+ output_queue = input_queue.apply(
+ lambda item: item.with_fields(value=item.value + 20)
+ )
+ ac.sink(output_queue)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_credit_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_credit_pipeline.py
new file mode 100644
index 00000000..e4e6639f
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_credit_pipeline.py
@@ -0,0 +1,20 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class CreditToken:
+ sequence: ac.u4
+ cycles: ac.u4
+ value: ac.u16
+
+
+@ac.system
+def pyc_credit_pipeline() -> None:
+ issued = ac.source(CreditToken, depth=4, latency=1)
+ completed = issued.credit(
+ cost=lambda item: item.cycles,
+ credits=2,
+ depth=4,
+ latency=1,
+ )
+ ac.sink(completed)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_dependency_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_dependency_pipeline.py
new file mode 100644
index 00000000..ec410549
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_dependency_pipeline.py
@@ -0,0 +1,27 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class Token:
+ sequence: ac.u4
+ waits_for: ac.u4
+ resource: ac.u1
+ cycles: ac.u4
+ value: ac.u16
+
+
+@ac.system
+def pyc_dependency_pipeline() -> None:
+ issued = ac.source(Token, depth=4, latency=1)
+ completed = issued.depend(
+ key=lambda item: item.sequence,
+ waits_for=lambda item: item.waits_for,
+ resource=lambda item: item.resource,
+ cost=lambda item: item.cycles,
+ capacity=4,
+ resources=2,
+ no_dependency=15,
+ depth=4,
+ latency=1,
+ )
+ ac.sink(completed)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_feedback_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_feedback_pipeline.py
new file mode 100644
index 00000000..5be83465
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_feedback_pipeline.py
@@ -0,0 +1,22 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class Item:
+ value: ac.u32
+ remaining: ac.u4
+
+
+@ac.system
+def pyc_feedback_pipeline() -> None:
+ current = ac.source(Item, depth=2, latency=1)
+ while current.remaining > 0:
+ current = current.apply(
+ lambda item: item.with_fields(
+ value=item.value + 1,
+ remaining=item.remaining - 1,
+ ),
+ depth=1,
+ latency=1,
+ )
+ ac.sink(current)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_firing_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_firing_pipeline.py
new file mode 100644
index 00000000..351b111e
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_firing_pipeline.py
@@ -0,0 +1,19 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class FiringToken:
+ value: ac.u16
+
+
+@ac.system
+def pyc_firing_pipeline() -> None:
+ incoming = ac.source(FiringToken, depth=2, latency=1)
+ outgoing = incoming.firing(
+ lambda queue: queue.push(
+ queue.pop().with_fields(value=queue.peek().value + 1)
+ ),
+ depth=2,
+ latency=1,
+ )
+ ac.sink(outgoing)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_fork_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_fork_pipeline.py
new file mode 100644
index 00000000..3e895c9d
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_fork_pipeline.py
@@ -0,0 +1,9 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_fork_pipeline() -> None:
+ input_queue = ac.source(int)
+ left, right = input_queue.fork(outputs=2, depth=2, latency=1)
+ ac.sink(left)
+ ac.sink(right)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_latency_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_latency_pipeline.py
new file mode 100644
index 00000000..8645eb10
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_latency_pipeline.py
@@ -0,0 +1,12 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_latency_pipeline() -> None:
+ input_queue = ac.source(int, depth=2, latency=1)
+ output_queue = input_queue.apply(
+ lambda item: item + 1,
+ depth=4,
+ latency=3,
+ )
+ ac.sink(output_queue)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_loop_control_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_loop_control_pipeline.py
new file mode 100644
index 00000000..9dc12304
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_loop_control_pipeline.py
@@ -0,0 +1,24 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class LoopToken:
+ remaining: ac.u4
+ stop: bool
+ skip: bool
+
+
+@ac.system
+def pyc_loop_control_pipeline() -> None:
+ current = ac.source(LoopToken, depth=2, latency=1)
+ while current.remaining > 0:
+ if current.stop:
+ break
+ current = current.apply(
+ lambda item: item.with_fields(remaining=item.remaining - 1),
+ depth=1,
+ latency=1,
+ )
+ if current.skip:
+ continue
+ ac.sink(current)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_memory_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_memory_pipeline.py
new file mode 100644
index 00000000..ef66542f
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_memory_pipeline.py
@@ -0,0 +1,24 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class MemoryRequest:
+ address: ac.u4
+ write: ac.u1
+ data: ac.u16
+ tag: ac.u8
+
+
+@ac.system
+def pyc_memory_pipeline() -> None:
+ sram = ac.memory(ac.u16, entries=16, init=0, latency=3)
+ requests = ac.source(MemoryRequest, depth=4, latency=1)
+ responses = sram.request(
+ requests,
+ address=lambda item: item.address,
+ write=lambda item: item.write,
+ data=lambda item: item.data,
+ result_field="data",
+ depth=4,
+ )
+ ac.sink(responses)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_queue_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_queue_pipeline.py
new file mode 100644
index 00000000..14a7b65c
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_queue_pipeline.py
@@ -0,0 +1,12 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_queue_pipeline() -> None:
+ input_queue = ac.source(int, depth=2, latency=1)
+ output_queue = input_queue.apply(
+ lambda item: item + 1,
+ depth=2,
+ latency=1,
+ )
+ ac.sink(output_queue)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_recursive_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_recursive_pipeline.py
new file mode 100644
index 00000000..19c5a853
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_recursive_pipeline.py
@@ -0,0 +1,17 @@
+import agentic_circuit as ac
+
+
+def add_stages(queue, count):
+ if count == 0:
+ return queue
+ return add_stages(
+ queue.apply(lambda item: item + 1, depth=2, latency=1),
+ count - 1,
+ )
+
+
+@ac.system
+def pyc_recursive_pipeline() -> None:
+ incoming = ac.source(int, depth=2, latency=1)
+ outgoing = add_stages(incoming, 3)
+ ac.sink(outgoing)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_reorder_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_reorder_pipeline.py
new file mode 100644
index 00000000..0b076dee
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_reorder_pipeline.py
@@ -0,0 +1,20 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class Token:
+ sequence: ac.u32
+ value: ac.u32
+
+
+@ac.system
+def pyc_reorder_pipeline() -> None:
+ completed = ac.source(Token, depth=8, latency=1)
+ retired = completed.reorder(
+ key=lambda item: item.sequence,
+ capacity=16,
+ start=0,
+ depth=4,
+ latency=1,
+ )
+ ac.sink(retired)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_route_merge_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_route_merge_pipeline.py
new file mode 100644
index 00000000..0ea91aba
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_route_merge_pipeline.py
@@ -0,0 +1,16 @@
+import agentic_circuit as ac
+
+
+@ac.system
+def pyc_route_merge_pipeline() -> None:
+ input_queue = ac.source(int, depth=2, latency=1)
+ left, right = input_queue.route(
+ outputs=2,
+ key=lambda item: item,
+ depth=2,
+ latency=1,
+ )
+ left_done = left.apply(lambda item: item + 10)
+ right_done = right.apply(lambda item: item + 20)
+ merged = left_done.merge(right_done, policy="priority", depth=2, latency=1)
+ ac.sink(merged)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_select_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_select_pipeline.py
new file mode 100644
index 00000000..96b46e36
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_select_pipeline.py
@@ -0,0 +1,19 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class SelectControl:
+ route: ac.u1
+
+
+@ac.system
+def pyc_select_pipeline() -> None:
+ control = ac.source(SelectControl, depth=2, latency=1)
+ lanes = ac.array(2, lambda index: ac.source(int, depth=2, latency=1))
+ selected = lanes.select(
+ control,
+ key=lambda item: item.route,
+ depth=2,
+ latency=1,
+ )
+ ac.sink(selected)
diff --git a/components/agentic-circuit/examples/pipelines/pyc_struct_pipeline.py b/components/agentic-circuit/examples/pipelines/pyc_struct_pipeline.py
new file mode 100644
index 00000000..4f67d750
--- /dev/null
+++ b/components/agentic-circuit/examples/pipelines/pyc_struct_pipeline.py
@@ -0,0 +1,21 @@
+import agentic_circuit as ac
+
+
+@ac.struct
+class Item:
+ value: int
+ remaining: int
+
+
+@ac.system
+def pyc_struct_pipeline() -> None:
+ input_queue = ac.source(Item, depth=2, latency=1)
+ output_queue = input_queue.apply(
+ lambda item: item.with_fields(
+ value=item.value + 1,
+ remaining=item.remaining - 1,
+ ),
+ depth=2,
+ latency=1,
+ )
+ ac.sink(output_queue)
diff --git a/components/agentic-circuit/examples/workspaces/README.md b/components/agentic-circuit/examples/workspaces/README.md
new file mode 100644
index 00000000..39fd8024
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/README.md
@@ -0,0 +1,9 @@
+# Complete workspaces
+
+Each child directory is a self-contained public CLI workspace. A workspace owns
+its component schemas, bindings, canonical input trace, and expected build/run
+artifacts so it can be copied and replayed independently.
+
+The workspace contract intentionally duplicates a small fixture set. Shared
+generated artifacts that are not part of workspace portability belong under
+`tests/goldens` instead.
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/agentic-circuit.toml
new file mode 100644
index 00000000..1afdb03d
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-backpressured-pipeline"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/architecture.py b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/architecture.py
new file mode 100644
index 00000000..3050a386
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("pipeline"):
+ Showcase(scenario=1, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.binding.json
new file mode 100644
index 00000000..27001455
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.binding.json
@@ -0,0 +1,142 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 1
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:bcb524cf922c8470ec7e6210d785c22442de250f1a0ae51b505dde33ef715974",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 1
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 1
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:bcb524cf922c8470ec7e6210d785c22442de250f1a0ae51b505dde33ef715974",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 1
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 1
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-events.jsonl
new file mode 100644
index 00000000..5ac10d08
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-events.jsonl
@@ -0,0 +1,6 @@
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"pending_offers":1,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"stall","name":"backpressure","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"pending_offers":1,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"stall","name":"backpressure","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":5},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-result.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-result.json
new file mode 100644
index 00000000..49404b9f
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"consumed_count":2,"consumed_sum":55,"transfer_count":2}}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-stats.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-stats.json
new file mode 100644
index 00000000..b26c9c0e
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_consumed_count","object_path":"/generated/root-model/runtime","sum":0,"value":2},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_consumed_sum","object_path":"/generated/root-model/runtime","sum":0,"value":55},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_transfer_count","object_path":"/generated/root-model/runtime","sum":0,"value":2},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":6},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/source.davincioo.jsonl b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/source.davincioo.jsonl
new file mode 100644
index 00000000..d060f19a
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/source.davincioo.jsonl
@@ -0,0 +1,2 @@
+{"block_idx":0,"sequence_id":0,"opcode":"TASSIGN","input_tiles":[],"scalar_inputs":[{"dtype":"uint64","value":"0"}],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":1,"opcode":"TLOAD","input_tiles":[{"address":"0xfffd835fd000","shape":[1,1,1,64,256],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
diff --git a/components/agentic-circuit/examples/workspaces/backpressured_pipeline/trace.pto.json b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/backpressured_pipeline/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/agentic-circuit.toml
new file mode 100644
index 00000000..096e1b51
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-multi-time-domain-bridge"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/architecture.py b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/architecture.py
new file mode 100644
index 00000000..efdc8ca9
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("domains"):
+ Showcase(scenario=4, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.binding.json
new file mode 100644
index 00000000..d32e8404
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.binding.json
@@ -0,0 +1,142 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 4
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:9c1b546207ae0685de2ccda7f1e5c89cfff2239fa3dfe022b20734b5d6fd7099",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 4
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 4
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:9c1b546207ae0685de2ccda7f1e5c89cfff2239fa3dfe022b20734b5d6fd7099",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 4
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 4
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-events.jsonl
new file mode 100644
index 00000000..c8de8c0c
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-events.jsonl
@@ -0,0 +1,9 @@
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"pending_offers":1,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"stall","name":"backpressure","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"pending_offers":1,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"stall","name":"backpressure","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":6},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":7},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":0,"pending_offers":1,"showcase_epoch_delta":0,"showcase_epoch_time":8},"cat":"stall","name":"backpressure","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":9},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":10},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-result.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-result.json
new file mode 100644
index 00000000..a85bc3c0
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"bridged_count":3,"bridged_sum":19,"last_transfer_tick":9}}
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-stats.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-stats.json
new file mode 100644
index 00000000..73af9c43
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_bridged_count","object_path":"/generated/root-model/runtime","sum":0,"value":3},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_bridged_sum","object_path":"/generated/root-model/runtime","sum":0,"value":19},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_last_transfer_tick","object_path":"/generated/root-model/runtime","sum":0,"value":9},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":9},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/trace.pto.json b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/multi_time_domain_bridge/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/nested_arrays/agentic-circuit.toml
new file mode 100644
index 00000000..97d6f840
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-nested-arrays"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/architecture.py b/components/agentic-circuit/examples/workspaces/nested_arrays/architecture.py
new file mode 100644
index 00000000..d662b33f
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("lanes"):
+ Showcase(scenario=3, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.binding.json
new file mode 100644
index 00000000..06045036
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.binding.json
@@ -0,0 +1,142 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 3
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:9c2220e4555a613737912eb5d889906b649345e9d8db66075b9814d3809d45e5",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 3
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 3
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:9c2220e4555a613737912eb5d889906b649345e9d8db66075b9814d3809d45e5",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 3
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 3
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-events.jsonl
new file mode 100644
index 00000000..96065a87
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-events.jsonl
@@ -0,0 +1,27 @@
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"occupancy":2,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":0,"occupancy":2,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":0,"occupancy":2,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":9,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":10,"gfsim_object_id":0,"occupancy":1,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":11,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":12,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":13,"gfsim_object_id":0,"occupancy":1,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":14,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":15,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":16,"gfsim_object_id":0,"occupancy":1,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":17,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":18,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":19,"gfsim_object_id":0,"occupancy":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":20,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":21,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":22,"gfsim_object_id":0,"occupancy":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":23,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":24,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":25,"gfsim_object_id":0,"occupancy":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":26,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/expected-result.json b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-result.json
new file mode 100644
index 00000000..2eeb2df9
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"lane_0_sum":3,"lane_1_sum":30,"lane_2_sum":300}}
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/expected-stats.json b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-stats.json
new file mode 100644
index 00000000..37ba82a0
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_lane_0_sum","object_path":"/generated/root-model/runtime","sum":0,"value":3},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_lane_1_sum","object_path":"/generated/root-model/runtime","sum":0,"value":30},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_lane_2_sum","object_path":"/generated/root-model/runtime","sum":0,"value":300},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":27},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/nested_arrays/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/nested_arrays/trace.pto.json b/components/agentic-circuit/examples/workspaces/nested_arrays/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/nested_arrays/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/npu/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/npu/agentic-circuit.toml
new file mode 100644
index 00000000..c04d0085
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-npu"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["traces"]
+default_trace = "traces/pto-trace.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/npu/architecture.py b/components/agentic-circuit/examples/workspaces/npu/architecture.py
new file mode 100644
index 00000000..63fa746b
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/architecture.py
@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ Npu(name="trace_source")
+ with scope("frontend"):
+ NpuNode(name="frontend_decode")
+ NpuNode(name="frontend_dispatch")
+ with scope("backend"):
+ NpuNode(name="backend_dependencies")
+ NpuNode(name="backend_issue_scalar")
+ NpuNode(name="backend_issue_vector")
+ NpuNode(name="backend_issue_cube")
+ NpuNode(name="backend_issue_tma")
+ with scope("execution"):
+ NpuNode(name="execution_scalar_unit_0")
+ NpuNode(name="execution_vector_unit_0")
+ NpuNode(name="execution_vector_unit_1")
+ NpuNode(name="execution_cube_unit_0")
+ NpuNode(name="execution_tma_unit_0")
+ with scope("memory"):
+ NpuNode(name="memory_load_store")
+ NpuNode(name="memory_scratchpad")
+ NpuNode(name="memory_controller")
+ NpuNode(name="completion")
+ NpuNode(name="retirement")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/npu/components/npu.binding.json b/components/agentic-circuit/examples/workspaces/npu/components/npu.binding.json
new file mode 100644
index 00000000..36a445e0
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/components/npu.binding.json
@@ -0,0 +1,196 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Npu_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Npu",
+ "component_schema_fingerprint": "sha256:d4db2ec8813016dce7fc4e03edddbeb45057bbf9d58081c265a27ecc4a7f6968",
+ "construction": {"arguments": [], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_npu_reset",
+ "validate": "gfsim::workspace_npu_validate",
+ "work": "gfsim::workspace_npu_work",
+ "xfer": "gfsim::workspace_npu_xfer"
+ },
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_npu_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:29db918e3fc58e1dcf8bfa1281e6c3f424b0025e78b4e3c28e270126d1db080e",
+ "implementation": "gfsim.NpuTraceSource",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_source",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Npu_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Npu",
+ "component_schema_fingerprint": "sha256:d4db2ec8813016dce7fc4e03edddbeb45057bbf9d58081c265a27ecc4a7f6968",
+ "construction": {"arguments": [], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_npu_reset",
+ "validate": "gfsim::workspace_npu_validate",
+ "work": "gfsim::workspace_npu_work",
+ "xfer": "gfsim::workspace_npu_xfer"
+ },
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_npu_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:29db918e3fc58e1dcf8bfa1281e6c3f424b0025e78b4e3c28e270126d1db080e",
+ "implementation": "gfsim.NpuTraceSource",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_source",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_NpuNode_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.NpuNode",
+ "component_schema_fingerprint": "sha256:3b96b9435f28a5fa08f41dc396618678cede4071171fe56628b11f14071205e3",
+ "construction": {"arguments": [], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_npu_node_reset",
+ "validate": "gfsim::workspace_npu_node_validate",
+ "work": "gfsim::workspace_npu_node_work",
+ "xfer": "gfsim::workspace_npu_node_xfer"
+ },
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuNode",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_npu_node_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:3222d9417a28be5dc2b1b7566f784d780d0bdfeac7a7877beac5cbfa93484d7c",
+ "implementation": "gfsim.NpuNode",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_node",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_NpuNode_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.NpuNode",
+ "component_schema_fingerprint": "sha256:3b96b9435f28a5fa08f41dc396618678cede4071171fe56628b11f14071205e3",
+ "construction": {"arguments": [], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_npu_node_reset",
+ "validate": "gfsim::workspace_npu_node_validate",
+ "work": "gfsim::workspace_npu_node_work",
+ "xfer": "gfsim::workspace_npu_node_xfer"
+ },
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuNode",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_npu_node_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:3222d9417a28be5dc2b1b7566f784d780d0bdfeac7a7877beac5cbfa93484d7c",
+ "implementation": "gfsim.NpuNode",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_node",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Npu_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Npu",
+ "component_schema_fingerprint": "sha256:d4db2ec8813016dce7fc4e03edddbeb45057bbf9d58081c265a27ecc4a7f6968",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_source",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resolution_key": "@Npu",
+ "resources": [],
+ "results": []
+ },
+ {
+ "activation_sources": [],
+ "binding": "workspace_NpuNode_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.NpuNode",
+ "component_schema_fingerprint": "sha256:3b96b9435f28a5fa08f41dc396618678cede4071171fe56628b11f14071205e3",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [],
+ "ports": [],
+ "provider": "workspace_npu_node",
+ "provider_implementation_fingerprint": "sha256:ca6c3fdd699cec3a02697f3714e1b5f70df101b28929cb6ddb118b8fa30c9180",
+ "resolution_key": "@NpuNode",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/npu/components/npu.component.json b/components/agentic-circuit/examples/workspaces/npu/components/npu.component.json
new file mode 100644
index 00000000..e853c0be
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/components/npu.component.json
@@ -0,0 +1,43 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Npu",
+ "family": "source",
+ "provider_namespace": "workspace.npu.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated canonical PTO trace document"],
+ "guarantees": ["deterministic dependency-aware NPU execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "trace exhausted and all instructions retired"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "npu_events", "architectural_retired_instructions", "architectural_digest"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:d4db2ec8813016dce7fc4e03edddbeb45057bbf9d58081c265a27ecc4a7f6968"
+}
diff --git a/components/agentic-circuit/examples/workspaces/npu/components/npu_node.component.json b/components/agentic-circuit/examples/workspaces/npu/components/npu_node.component.json
new file mode 100644
index 00000000..aaa8578a
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/components/npu_node.component.json
@@ -0,0 +1,43 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.NpuNode",
+ "family": "compute",
+ "provider_namespace": "workspace.npu.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/npu.h",
+ "symbol": "gfsim::NpuNode",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": [],
+ "guarantees": ["stable generated hierarchy placement"],
+ "observable_effects": [],
+ "failure_behavior": "none"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "never",
+ "wakeup_contract": [],
+ "quiescence": "always"
+ },
+ "observation": {
+ "probes": [],
+ "counters": [],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3b96b9435f28a5fa08f41dc396618678cede4071171fe56628b11f14071205e3"
+}
diff --git a/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.cpp b/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.cpp
new file mode 100644
index 00000000..247883ae
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.cpp
@@ -0,0 +1,6 @@
+#include "npu_provider.h"
+
+#include "gfsim/components.h"
+
+static_assert(gfsim::Component);
+static_assert(gfsim::Component);
diff --git a/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.h b/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.h
new file mode 100644
index 00000000..989d9162
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/components/npu_provider.h
@@ -0,0 +1,10 @@
+#pragma once
+
+#include "gfsim/npu.h"
+
+namespace workspace::npu::provider {
+
+using NpuProvider = gfsim::NpuTraceSource;
+using NpuNodeProvider = gfsim::NpuNode;
+
+} // namespace workspace::npu::provider
diff --git a/components/agentic-circuit/examples/workspaces/npu/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/npu/expected-events.jsonl
new file mode 100644
index 00000000..911e18d6
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/expected-events.jsonl
@@ -0,0 +1,42 @@
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":0,"stable_object_id":23},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":1,"stable_object_id":20},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"stable_object_id":21},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"producer_sequence_id":0,"tile_identity":"block/0/tile/0x0"},"cat":"dependency","id":5047684461776682,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"producer_sequence_id":1,"tile_identity":"block/0/tile/0x10"},"cat":"dependency","id":7276611561329711,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":3,"stable_object_id":22},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":3,"producer_sequence_id":2,"tile_identity":"block/0/tile/0x20"},"cat":"dependency","id":1432032477267923,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":4,"stable_object_id":21},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":5,"stable_object_id":23},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":9,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":5,"producer_sequence_id":3,"tile_identity":"block/0/tile/0x40"},"cat":"dependency","id":3575161440751033,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":10,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":23},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":11,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":20},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":12,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":21},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":13,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":3,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":14,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":1,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":15,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":2,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":16,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":8,"producer_sequence_id":1},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":17,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":8},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":18,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":9},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":19,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":10,"producer_sequence_id":0},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":20,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":21,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":22,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":23,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"stable_object_id":21},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":24,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"producer_sequence_id":0,"tile_identity":"block/0/tile/0x0"},"bp":"e","cat":"dependency","id":5047684461776682,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":25,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"producer_sequence_id":1,"tile_identity":"block/0/tile/0x10"},"bp":"e","cat":"dependency","id":7276611561329711,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":26,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":12,"unit_index":0},"cat":"instruction","dur":2,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":27,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":14,"producer_sequence_id":2},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":28,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":14},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":29,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":14},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":30,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":15,"stable_object_id":22},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":31,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":15,"producer_sequence_id":2,"tile_identity":"block/0/tile/0x20"},"bp":"e","cat":"dependency","id":1432032477267923,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":32,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":16,"unit_index":0},"cat":"instruction","dur":4,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":33,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":20,"producer_sequence_id":3},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":34,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":35,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":36,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":37,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":21,"stable_object_id":23},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":38,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":21,"producer_sequence_id":3,"tile_identity":"block/0/tile/0x40"},"bp":"e","cat":"dependency","id":3575161440751033,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0}
+{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":39,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":22,"unit_index":0},"cat":"instruction","dur":4,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":40,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":26},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":41,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":26},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/npu/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/npu/expected-hierarchy.json
new file mode 100644
index 00000000..a7375c20
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e5","kind":"call","path":"top.backend_dependencies","schema":"workspace.NpuNode"},{"id":"e8","kind":"call","path":"top.backend_issue_cube","schema":"workspace.NpuNode"},{"id":"e6","kind":"call","path":"top.backend_issue_scalar","schema":"workspace.NpuNode"},{"id":"e9","kind":"call","path":"top.backend_issue_tma","schema":"workspace.NpuNode"},{"id":"e7","kind":"call","path":"top.backend_issue_vector","schema":"workspace.NpuNode"},{"id":"e18","kind":"call","path":"top.completion","schema":"workspace.NpuNode"},{"id":"e13","kind":"call","path":"top.execution_cube_unit_0","schema":"workspace.NpuNode"},{"id":"e10","kind":"call","path":"top.execution_scalar_unit_0","schema":"workspace.NpuNode"},{"id":"e14","kind":"call","path":"top.execution_tma_unit_0","schema":"workspace.NpuNode"},{"id":"e11","kind":"call","path":"top.execution_vector_unit_0","schema":"workspace.NpuNode"},{"id":"e12","kind":"call","path":"top.execution_vector_unit_1","schema":"workspace.NpuNode"},{"id":"e3","kind":"call","path":"top.frontend_decode","schema":"workspace.NpuNode"},{"id":"e4","kind":"call","path":"top.frontend_dispatch","schema":"workspace.NpuNode"},{"id":"e17","kind":"call","path":"top.memory_controller","schema":"workspace.NpuNode"},{"id":"e15","kind":"call","path":"top.memory_load_store","schema":"workspace.NpuNode"},{"id":"e16","kind":"call","path":"top.memory_scratchpad","schema":"workspace.NpuNode"},{"id":"e19","kind":"call","path":"top.retirement","schema":"workspace.NpuNode"},{"id":"e2","kind":"call","path":"top.trace_source","schema":"workspace.Npu"},{"id":"e20","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/npu/expected-perfetto.json b/components/agentic-circuit/examples/workspaces/npu/expected-perfetto.json
new file mode 100644
index 00000000..ffdd01a8
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/expected-perfetto.json
@@ -0,0 +1 @@
+{"traceEvents":[{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":0,"stable_object_id":23},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":1,"stable_object_id":20},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"stable_object_id":21},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"producer_sequence_id":0,"tile_identity":"block/0/tile/0x0"},"cat":"dependency","id":5047684461776682,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":2,"producer_sequence_id":1,"tile_identity":"block/0/tile/0x10"},"cat":"dependency","id":7276611561329711,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0},{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":3,"stable_object_id":22},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":3,"producer_sequence_id":2,"tile_identity":"block/0/tile/0x20"},"cat":"dependency","id":1432032477267923,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":4,"stable_object_id":21},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":5,"stable_object_id":23},"cat":"instruction","name":"dispatch","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":9,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":5,"producer_sequence_id":3,"tile_identity":"block/0/tile/0x40"},"cat":"dependency","id":3575161440751033,"name":"tile","ph":"s","pid":0,"tid":17,"ts":0},{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":10,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":23},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":11,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":20},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":12,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":6,"stable_object_id":21},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":13,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":3,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"engine":"scalar","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":14,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":1,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":15,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":7,"unit_index":0},"cat":"instruction","dur":2,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":16,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":8,"producer_sequence_id":1},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":17,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":8},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":18,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":9},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":19,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":10,"producer_sequence_id":0},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":20,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":21,"gfsim_object_id":17,"gfsim_root_sequence_id":0,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":22,"gfsim_object_id":17,"gfsim_root_sequence_id":1,"npu_epoch_delta":0,"npu_epoch_time":10},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":23,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"stable_object_id":21},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":24,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"producer_sequence_id":0,"tile_identity":"block/0/tile/0x0"},"bp":"e","cat":"dependency","id":5047684461776682,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":25,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":11,"producer_sequence_id":1,"tile_identity":"block/0/tile/0x10"},"bp":"e","cat":"dependency","id":7276611561329711,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0},{"args":{"engine":"vector","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":26,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":12,"unit_index":0},"cat":"instruction","dur":2,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":27,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":14,"producer_sequence_id":2},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":28,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":14},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":29,"gfsim_object_id":17,"gfsim_root_sequence_id":2,"npu_epoch_delta":0,"npu_epoch_time":14},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":30,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":15,"stable_object_id":22},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":31,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":15,"producer_sequence_id":2,"tile_identity":"block/0/tile/0x20"},"bp":"e","cat":"dependency","id":1432032477267923,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0},{"args":{"engine":"cube","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":32,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":16,"unit_index":0},"cat":"instruction","dur":4,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":33,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":20,"producer_sequence_id":3},"cat":"dependency","name":"ready","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":34,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":35,"gfsim_object_id":17,"gfsim_root_sequence_id":3,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":36,"gfsim_object_id":17,"gfsim_root_sequence_id":4,"npu_epoch_delta":0,"npu_epoch_time":20},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":37,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":21,"stable_object_id":23},"cat":"instruction","name":"issue","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":38,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":21,"producer_sequence_id":3,"tile_identity":"block/0/tile/0x40"},"bp":"e","cat":"dependency","id":3575161440751033,"name":"tile","ph":"f","pid":0,"tid":17,"ts":0},{"args":{"engine":"tma","gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":39,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":22,"unit_index":0},"cat":"instruction","dur":4,"name":"execute","ph":"X","pid":0,"tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":40,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":26},"cat":"instruction","name":"complete","ph":"i","pid":0,"s":"t","tid":17,"ts":0},{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":41,"gfsim_object_id":17,"gfsim_root_sequence_id":5,"npu_epoch_delta":0,"npu_epoch_time":26},"cat":"instruction","name":"retire","ph":"i","pid":0,"s":"t","tid":17,"ts":0}]}
diff --git a/components/agentic-circuit/examples/workspaces/npu/expected-result.json b/components/agentic-circuit/examples/workspaces/npu/expected-result.json
new file mode 100644
index 00000000..c7537ff1
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/expected-result.json
@@ -0,0 +1 @@
+{"architectural_values":{"digest":11635184385557860000,"retired_instructions":6},"schema":"workspace-npu-result","simulated_ticks":3,"status":"completed","termination_reason":"trace_drained","trace_position":{"last_committed_sequence_id":5,"next_record_index":6},"version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/npu/expected-stats.json b/components/agentic-circuit/examples/workspaces/npu/expected-stats.json
new file mode 100644
index 00000000..5d98bea8
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_digest","object_path":"/generated/root-model/trace_source","sum":0,"value":11635184385557860000},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_retired_instructions","object_path":"/generated/root-model/trace_source","sum":0,"value":6},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"npu_events","object_path":"/generated/root-model/trace_source","sum":0,"value":42},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/trace_source","sum":0,"value":6}]
diff --git a/components/agentic-circuit/examples/workspaces/npu/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/npu/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/npu/traces/davincioo.jsonl b/components/agentic-circuit/examples/workspaces/npu/traces/davincioo.jsonl
new file mode 100644
index 00000000..187ca141
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/traces/davincioo.jsonl
@@ -0,0 +1,6 @@
+{"block_idx":0,"sequence_id":0,"opcode":"TLOAD","input_tiles":[{"address":"0x100","shape":[2,4],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x0","shape":[2,4],"layout":"ND","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":1,"opcode":"TASSIGN","input_tiles":[],"scalar_inputs":[{"dtype":"uint64","value":"7"}],"output_tiles":[{"address":"0x10","shape":[2,4],"layout":"ND","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":2,"opcode":"TADD","input_tiles":[{"address":"0x0","shape":[2,4],"layout":"ND","dtype":"float32"},{"address":"0x10","shape":[2,4],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x20","shape":[2,4],"layout":"ND","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":3,"opcode":"TMATMUL","input_tiles":[{"address":"0x20","shape":[2,4],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x40","shape":[2,4],"layout":"ND","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":4,"opcode":"TADD","input_tiles":[],"scalar_inputs":[],"output_tiles":[{"address":"0x50","shape":[2,4],"layout":"ND","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":5,"opcode":"TSTORE","input_tiles":[{"address":"0x40","shape":[2,4],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x200","shape":[2,4],"layout":"ND","dtype":"float32"}]}
diff --git a/components/agentic-circuit/examples/workspaces/npu/traces/pto-trace.json b/components/agentic-circuit/examples/workspaces/npu/traces/pto-trace.json
new file mode 100644
index 00000000..40b2c318
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/npu/traces/pto-trace.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:2ca5496aff126de3532252186dda9c25ec0a1a4a7c7b558311d93fe26d42be8e","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":6,"source_program":"examples/workspaces/npu"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0x100","dtype":"float32","layout":"ND","shape":[2,4]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0x100","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x10","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[{"dtype":"uint64","value":"7"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"7"},{"id":"block/0/tile/0x10","kind":"tile"}],"sequence_id":1},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0x0","dtype":"float32","layout":"ND","shape":[2,4]},{"address":"0x10","dtype":"float32","layout":"ND","shape":[2,4]}],"operand_roles":["input_tile","input_tile","output_tile"],"output_tiles":[{"address":"0x20","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TADD","operands":[{"id":"block/0/tile/0x0","kind":"tile"},{"id":"block/0/tile/0x10","kind":"tile"},{"id":"block/0/tile/0x20","kind":"tile"}],"sequence_id":2},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0x20","dtype":"float32","layout":"ND","shape":[2,4]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x40","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TMATMUL","operands":[{"id":"block/0/tile/0x20","kind":"tile"},{"id":"block/0/tile/0x40","kind":"tile"}],"sequence_id":3},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["output_tile"],"output_tiles":[{"address":"0x50","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TADD","operands":[{"id":"block/0/tile/0x50","kind":"tile"}],"sequence_id":4},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0x40","dtype":"float32","layout":"ND","shape":[2,4]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x200","dtype":"float32","layout":"ND","shape":[2,4]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TSTORE","operands":[{"id":"block/0/tile/0x40","kind":"tile"},{"id":"block/0/tile/0x200","kind":"tile"}],"sequence_id":5}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/agentic-circuit.toml
new file mode 100644
index 00000000..1dfd1e74
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-producer-queue-consumer"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/architecture.py b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/architecture.py
new file mode 100644
index 00000000..c11af1fb
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("pipeline"):
+ Showcase(scenario=0, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.binding.json
new file mode 100644
index 00000000..2e33ec75
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.binding.json
@@ -0,0 +1,113 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {"arguments": [0], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:32e7a810b0f32c03a2c2121ec89e038cf6e10282d674553b7ed55d379069acc6",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [{
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 0
+ }],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {"arguments": [0], "kind": "constructor"},
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:32e7a810b0f32c03a2c2121ec89e038cf6e10282d674553b7ed55d379069acc6",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {"kind": "unique", "placement": "member_or_array"},
+ "parameters": [{
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 0
+ }],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [{
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [{"acir_type": "i64", "name": "scenario", "ordinal": 0, "value": 0}],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }]
+}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-events.jsonl
new file mode 100644
index 00000000..d3a68209
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-events.jsonl
@@ -0,0 +1,13 @@
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"occupancy":2,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":0,"occupancy":1,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":0,"occupancy":1,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":9,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":10,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":11,"gfsim_object_id":0,"occupancy":0,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"queue","name":"occupancy","ph":"C","pid":0,"tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":12,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-result.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-result.json
new file mode 100644
index 00000000..3b49a917
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"consumed_count":3,"consumed_sum":16}}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-stats.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-stats.json
new file mode 100644
index 00000000..ebb2ba74
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_consumed_count","object_path":"/generated/root-model/runtime","sum":0,"value":3},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_consumed_sum","object_path":"/generated/root-model/runtime","sum":0,"value":16},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":13},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/source.davincioo.jsonl b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/source.davincioo.jsonl
new file mode 100644
index 00000000..d060f19a
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/source.davincioo.jsonl
@@ -0,0 +1,2 @@
+{"block_idx":0,"sequence_id":0,"opcode":"TASSIGN","input_tiles":[],"scalar_inputs":[{"dtype":"uint64","value":"0"}],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":1,"opcode":"TLOAD","input_tiles":[{"address":"0xfffd835fd000","shape":[1,1,1,64,256],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
diff --git a/components/agentic-circuit/examples/workspaces/producer_queue_consumer/trace.pto.json b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/producer_queue_consumer/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/request_response_memory/agentic-circuit.toml
new file mode 100644
index 00000000..5aad2a56
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-request-response-memory"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/architecture.py b/components/agentic-circuit/examples/workspaces/request_response_memory/architecture.py
new file mode 100644
index 00000000..c6392e93
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("memory_path"):
+ Showcase(scenario=2, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.binding.json
new file mode 100644
index 00000000..98eab3a3
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.binding.json
@@ -0,0 +1,142 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 2
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:04d4bb6c35f30c3202e0d90d520dcd731882ac806e8725490319c8caae770e44",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 2
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 2
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:04d4bb6c35f30c3202e0d90d520dcd731882ac806e8725490319c8caae770e44",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 2
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 2
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-events.jsonl
new file mode 100644
index 00000000..4ce5d5f3
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-events.jsonl
@@ -0,0 +1,10 @@
+{"args":{"correlation_id":10,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"gfsim_root_sequence_id":10,"showcase_epoch_delta":0,"showcase_epoch_time":1},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":10,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"gfsim_root_sequence_id":10,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"transaction","name":"request","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"address":1,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":2},"cat":"memory","name":"write","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":10,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":3,"gfsim_object_id":0,"gfsim_root_sequence_id":10,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":10,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":4,"gfsim_object_id":0,"gfsim_root_sequence_id":10,"showcase_epoch_delta":0,"showcase_epoch_time":4},"cat":"transaction","name":"response","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":11,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":5,"gfsim_object_id":0,"gfsim_root_sequence_id":11,"showcase_epoch_delta":0,"showcase_epoch_time":5},"cat":"transaction","name":"accepted","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":11,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":6,"gfsim_object_id":0,"gfsim_root_sequence_id":11,"showcase_epoch_delta":0,"showcase_epoch_time":6},"cat":"transaction","name":"request","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"address":3,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":7,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":6},"cat":"memory","name":"write","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":11,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":8,"gfsim_object_id":0,"gfsim_root_sequence_id":11,"showcase_epoch_delta":0,"showcase_epoch_time":7},"cat":"transaction","name":"completed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"correlation_id":11,"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":9,"gfsim_object_id":0,"gfsim_root_sequence_id":11,"showcase_epoch_delta":0,"showcase_epoch_time":8},"cat":"transaction","name":"response","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/expected-result.json b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-result.json
new file mode 100644
index 00000000..1d9a5ba5
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"completed_responses":2,"memory_0":0,"memory_1":17,"memory_2":0,"memory_3":29}}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/expected-stats.json b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-stats.json
new file mode 100644
index 00000000..1b6679e3
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_completed_responses","object_path":"/generated/root-model/runtime","sum":0,"value":2},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_memory_0","object_path":"/generated/root-model/runtime","sum":0,"value":0},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_memory_1","object_path":"/generated/root-model/runtime","sum":0,"value":17},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_memory_2","object_path":"/generated/root-model/runtime","sum":0,"value":0},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_memory_3","object_path":"/generated/root-model/runtime","sum":0,"value":29},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":10},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/request_response_memory/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/source.davincioo.jsonl b/components/agentic-circuit/examples/workspaces/request_response_memory/source.davincioo.jsonl
new file mode 100644
index 00000000..d060f19a
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/source.davincioo.jsonl
@@ -0,0 +1,2 @@
+{"block_idx":0,"sequence_id":0,"opcode":"TASSIGN","input_tiles":[],"scalar_inputs":[{"dtype":"uint64","value":"0"}],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
+{"block_idx":0,"sequence_id":1,"opcode":"TLOAD","input_tiles":[{"address":"0xfffd835fd000","shape":[1,1,1,64,256],"layout":"ND","dtype":"float32"}],"scalar_inputs":[],"output_tiles":[{"address":"0x0","shape":[64,256],"layout":"outer=col_major,inner=row_major,fractal_size=512","dtype":"float32"}]}
diff --git a/components/agentic-circuit/examples/workspaces/request_response_memory/trace.pto.json b/components/agentic-circuit/examples/workspaces/request_response_memory/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/request_response_memory/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/agentic-circuit.toml b/components/agentic-circuit/examples/workspaces/suspended_process/agentic-circuit.toml
new file mode 100644
index 00000000..82716d7b
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/agentic-circuit.toml
@@ -0,0 +1,27 @@
+contract_epoch = "0.3"
+
+[project]
+name = "workspace-suspended-process"
+version = "0.1.0"
+architecture = "architecture.py"
+system = "main"
+
+[providers]
+standard_library = ["ac"]
+
+[build]
+profile = "fast"
+compiler = "c++"
+standard_library = "libc++"
+component_roots = ["components"]
+protocol_roots = ["protocols"]
+build_root = "build"
+instrumentation_layers = []
+
+[run]
+trace_roots = ["."]
+default_trace = "trace.pto.json"
+inputs = {}
+
+[diagnostics]
+format = "text"
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/architecture.py b/components/agentic-circuit/examples/workspaces/suspended_process/architecture.py
new file mode 100644
index 00000000..12d17190
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/architecture.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from agentic_circuit import module, process, scope, system
+
+
+@module
+def top() -> None:
+ with scope("controller"):
+ Showcase(scenario=5, name="runtime")
+
+
+@process(kind="workload")
+def workload() -> None:
+ yield_sim()
+
+
+@system(root="top")
+def main() -> None:
+ return
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.binding.json b/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.binding.json
new file mode 100644
index 00000000..0e97ee34
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.binding.json
@@ -0,0 +1,142 @@
+{
+ "candidates": [
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "unknown-unknown",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 5
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:a2791e95a8814f8319e29ce010e24ac1a4e090e560d0721a5cbcada111bf1d95",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 5
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ },
+ {
+ "available": true,
+ "profile": "fast",
+ "target": "native",
+ "record": {
+ "activation_sources": [],
+ "availability": "available",
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "construction": {
+ "arguments": [
+ 5
+ ],
+ "kind": "constructor"
+ },
+ "contract_epoch": "0.3",
+ "cpp": {
+ "concept": "gfsim::Component",
+ "entry_points": {
+ "pure": "",
+ "reset": "gfsim::workspace_reset",
+ "validate": "gfsim::workspace_validate",
+ "work": "gfsim::workspace_work",
+ "xfer": "gfsim::workspace_xfer"
+ },
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "target": "gfsim"
+ },
+ "cpp_type": "workspace_showcase_type",
+ "effect": "stateful",
+ "fingerprint": "sha256:a2791e95a8814f8319e29ce010e24ac1a4e090e560d0721a5cbcada111bf1d95",
+ "implementation": "gfsim.ShowcaseTraceSource",
+ "ownership": {
+ "kind": "unique",
+ "placement": "member_or_array"
+ },
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "cpp_type": "std::uint64_t",
+ "mapping": "constructor_constant",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 5
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resources": [],
+ "results": []
+ }
+ }
+ ],
+ "requests": [
+ {
+ "activation_sources": [],
+ "binding": "workspace_Showcase_binding",
+ "binding_schema": "acsim-binding-0.1",
+ "component_schema": "workspace.Showcase",
+ "component_schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270",
+ "contract_epoch": "0.3",
+ "effect": "stateful",
+ "function_type": "() -> ()",
+ "parameters": [
+ {
+ "acir_type": "i64",
+ "name": "scenario",
+ "ordinal": 0,
+ "value": 5
+ }
+ ],
+ "ports": [],
+ "provider": "workspace",
+ "provider_implementation_fingerprint": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+ "resolution_key": "@Showcase",
+ "resources": [],
+ "results": []
+ }
+ ]
+}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.component.json b/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.component.json
new file mode 100644
index 00000000..e57d3748
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/components/showcase.component.json
@@ -0,0 +1,50 @@
+{
+ "schema_kind": "agentic-circuit-component",
+ "schema_version": "0.1",
+ "contract_epoch": "0.3",
+ "canonical_name": "workspace.Showcase",
+ "family": "source",
+ "provider_namespace": "workspace.provider",
+ "stability": "experimental",
+ "cpp_binding": {
+ "header": "gfsim/showcase.h",
+ "symbol": "gfsim::ShowcaseTraceSource",
+ "language": "c++20",
+ "concept": "gfsim::Component",
+ "toolchain_target": "ac-gfsim-cxx20-v0.1",
+ "functional_policy": "none"
+ },
+ "static_parameters": [{
+ "name": "scenario",
+ "acir_type": "index",
+ "required": true,
+ "default": null,
+ "constraint": "0 <= value < 6",
+ "cpp_mapping": "constructor_constant"
+ }],
+ "bindings": [],
+ "results": [],
+ "resources": [],
+ "address_behavior": null,
+ "protocol_contracts": [],
+ "effect": {
+ "kind": "stateful",
+ "requirements": ["one validated PTO trace document"],
+ "guarantees": ["one deterministic showcase execution"],
+ "observable_effects": ["architectural_values", "runtime_events"],
+ "failure_behavior": "terminate_with_diagnostic"
+ },
+ "activation": {
+ "sources": [],
+ "predicate": "loaded and not committed",
+ "wakeup_contract": [],
+ "quiescence": "showcase committed"
+ },
+ "observation": {
+ "probes": [],
+ "counters": ["trace_records", "showcase_events"],
+ "gauges": [],
+ "histograms": []
+ },
+ "schema_fingerprint": "sha256:3dd113d76227679688dc514e8bbe401a8225925cf592e362891a8857b6f2a270"
+}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/expected-events.jsonl b/components/agentic-circuit/examples/workspaces/suspended_process/expected-events.jsonl
new file mode 100644
index 00000000..4be10f1f
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/expected-events.jsonl
@@ -0,0 +1,3 @@
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":0,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":0},"cat":"process","name":"suspended","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":1,"gfsim_object_id":0,"showcase_epoch_delta":0,"showcase_epoch_time":3},"cat":"process","name":"wake","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
+{"args":{"gfsim_epoch_delta":0,"gfsim_epoch_time":0,"gfsim_local_committed_index":2,"gfsim_object_id":0,"showcase_epoch_delta":1,"showcase_epoch_time":3},"cat":"process","name":"resumed","ph":"i","pid":0,"s":"t","tid":0,"ts":0}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/expected-hierarchy.json b/components/agentic-circuit/examples/workspaces/suspended_process/expected-hierarchy.json
new file mode 100644
index 00000000..f4cf77e2
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/expected-hierarchy.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","kind":"hierarchy","path":null,"records":[{"id":"e1","kind":"module","path":"top","schema":null},{"id":"e2","kind":"call","path":"top.runtime","schema":"workspace.Showcase"},{"id":"e3","kind":"process","path":"top.workload","schema":null}],"schema":"agentic-circuit-inspection","system":"main","version":"0.1"}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/expected-result.json b/components/agentic-circuit/examples/workspaces/suspended_process/expected-result.json
new file mode 100644
index 00000000..6fb56bad
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/expected-result.json
@@ -0,0 +1 @@
+{"schema":"workspace-showcase-result","version":"0.1","status":"completed","termination_reason":"trace_drained","simulated_ticks":3,"trace_position":{"last_committed_sequence_id":1,"next_record_index":2},"architectural_values":{"process_result":42,"resume_count":1,"wake_tick":3}}
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/expected-stats.json b/components/agentic-circuit/examples/workspaces/suspended_process/expected-stats.json
new file mode 100644
index 00000000..64cda148
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/expected-stats.json
@@ -0,0 +1 @@
+[{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_process_result","object_path":"/generated/root-model/runtime","sum":0,"value":42},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_resume_count","object_path":"/generated/root-model/runtime","sum":0,"value":1},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"architectural_wake_tick","object_path":"/generated/root-model/runtime","sum":0,"value":3},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"showcase_events","object_path":"/generated/root-model/runtime","sum":0,"value":3},{"buckets":[],"count":0,"kind":"counter","last_update":{"delta":0,"time":0},"maximum":0,"minimum":0,"name":"trace_records","object_path":"/generated/root-model/runtime","sum":0,"value":2}]
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/protocols/.gitkeep b/components/agentic-circuit/examples/workspaces/suspended_process/protocols/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/protocols/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/components/agentic-circuit/examples/workspaces/suspended_process/trace.pto.json b/components/agentic-circuit/examples/workspaces/suspended_process/trace.pto.json
new file mode 100644
index 00000000..0cc918ce
--- /dev/null
+++ b/components/agentic-circuit/examples/workspaces/suspended_process/trace.pto.json
@@ -0,0 +1 @@
+{"contract_epoch":"0.3","metadata":{"content_hash":"sha256:4ad35c1b1106c2cae0b56e0c7233a019d85e3387653e6e886f3765e0a966f179","data_layout":"davincioo-tile-address-v1","producer":"davincioo@e73633301cabed0d871ea5ff66e76a91df870aeb","pto_identity":"pto-isa@f6d0567c1cae2d6a7b0ebaf7ad0e3b93f8a39da3","record_count":2,"source_program":"examples/beginner_matmul"},"records":[{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[],"operand_roles":["scalar_input","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[{"dtype":"uint64","value":"0"}]}},"dependencies":[],"opcode":"TASSIGN","operands":[{"kind":"immediate","type":"uint64","value":"0"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":0},{"attributes":{"davincioo":{"block_idx":0,"input_tiles":[{"address":"0xfffd835fd000","dtype":"float32","layout":"ND","shape":[1,1,1,64,256]}],"operand_roles":["input_tile","output_tile"],"output_tiles":[{"address":"0x0","dtype":"float32","layout":"outer=col_major,inner=row_major,fractal_size=512","shape":[64,256]}],"scalar_inputs":[]}},"dependencies":[],"opcode":"TLOAD","operands":[{"id":"block/0/tile/0xfffd835fd000","kind":"tile"},{"id":"block/0/tile/0x0","kind":"tile"}],"sequence_id":1}],"schema":"pto-trace","version":"0.1"}
diff --git a/components/agentic-circuit/include/CMakeLists.txt b/components/agentic-circuit/include/CMakeLists.txt
new file mode 100644
index 00000000..4ee86ae6
--- /dev/null
+++ b/components/agentic-circuit/include/CMakeLists.txt
@@ -0,0 +1 @@
+add_subdirectory(acir)
diff --git a/components/agentic-circuit/include/acir/Analysis/ModelAnalysis.h b/components/agentic-circuit/include/acir/Analysis/ModelAnalysis.h
new file mode 100644
index 00000000..dd4fd4a8
--- /dev/null
+++ b/components/agentic-circuit/include/acir/Analysis/ModelAnalysis.h
@@ -0,0 +1,46 @@
+#ifndef ACIR_ANALYSIS_MODELANALYSIS_H
+#define ACIR_ANALYSIS_MODELANALYSIS_H
+
+#include "mlir/IR/BuiltinOps.h"
+#include "mlir/Support/LogicalResult.h"
+
+#include
+namespace acir {
+
+/// Fixed capability limits keep hostile or malformed models diagnosable and
+/// make the whole-model analyses independent of allocator failure behavior.
+inline constexpr uint64_t kMaxModelAnalysisNodes = 1U << 20;
+inline constexpr uint64_t kMaxModelAnalysisEdges = 1U << 22;
+/// The top-level builtin.module has depth 0; each contained operation adds 1.
+inline constexpr uint64_t kMaxModelRegionNesting = 512;
+inline constexpr uint64_t kMaxPureCallFunctions = 1U << 16;
+inline constexpr uint64_t kMaxPureCallEdges = 1U << 18;
+inline constexpr uint64_t kMaxPureCallDepth = 1024;
+
+class ModelAnalysis {
+public:
+ explicit ModelAnalysis(mlir::ModuleOp model) : model(model) {}
+
+ /// Runs the complete IR-stage semantic closure. Existing operation
+ /// verifiers remain authoritative for local contracts; this analysis adds
+ /// deterministic whole-model selection, purity, dependency, and frozen
+ /// integrity checks.
+ mlir::LogicalResult verify();
+
+ /// Verifies module-level require/ensure conditions at topology freeze.
+ mlir::LogicalResult verifyFreezeContracts();
+
+private:
+ mlir::LogicalResult verifyPureProcessCalls();
+ mlir::LogicalResult verifyZeroDelayDependencies();
+ mlir::LogicalResult verifyFrozenIntegrity();
+
+ mlir::ModuleOp model;
+};
+
+mlir::LogicalResult verifyModel(mlir::ModuleOp model);
+bool isTopologyFrozen(mlir::ModuleOp model);
+
+} // namespace acir
+
+#endif // ACIR_ANALYSIS_MODELANALYSIS_H
diff --git a/components/agentic-circuit/include/acir/Analysis/ProcessStatePlan.h b/components/agentic-circuit/include/acir/Analysis/ProcessStatePlan.h
new file mode 100644
index 00000000..abc52b67
--- /dev/null
+++ b/components/agentic-circuit/include/acir/Analysis/ProcessStatePlan.h
@@ -0,0 +1,719 @@
+#ifndef ACIR_ANALYSIS_PROCESSSTATEPLAN_H
+#define ACIR_ANALYSIS_PROCESSSTATEPLAN_H
+
+#include "acir/Dialect/ACIR/ACIROps.h"
+
+#include "mlir/IR/Block.h"
+#include "mlir/IR/BuiltinOps.h"
+#include "mlir/IR/Types.h"
+#include "mlir/IR/Value.h"
+#include "mlir/Support/LogicalResult.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+
+#include
+#include
+#include
+#include
+#include
+#include
+
+namespace acir {
+namespace detail {
+class PlanSetBuilder;
+}
+
+struct ProcessStateLimits {
+ uint64_t maxProcesses = 1U << 20;
+ uint64_t maxProgramCounters = 1U << 20;
+ uint64_t maxLiveSlots = 1U << 20;
+ uint64_t maxWakeRecords = 1U << 20;
+ uint64_t maxCalleeDescriptors = 1U << 20;
+ uint64_t maxPlannedOperations = 1U << 20;
+ uint64_t maxFairnessWork = 1U << 20;
+ uint64_t maxTransitions = 1U << 22;
+ uint64_t maxNestedRegionDepth = 512;
+ uint64_t maxCanonicalReportBytes = 1U << 24;
+};
+
+#define ACIR_DECLARE_PROCESS_ID(Name) \
+ class Name { \
+ public: \
+ uint32_t value() const { return value_; } \
+ auto operator<=>(const Name &) const = default; \
+ \
+ private: \
+ explicit Name(uint32_t value) : value_(value) {} \
+ uint32_t value_; \
+ friend class detail::PlanSetBuilder; \
+ }
+
+ACIR_DECLARE_PROCESS_ID(ProcessCalleeId);
+ACIR_DECLARE_PROCESS_ID(ProcessValueTypeId);
+ACIR_DECLARE_PROCESS_ID(ProcessCaptureId);
+ACIR_DECLARE_PROCESS_ID(ProcessPcId);
+ACIR_DECLARE_PROCESS_ID(ProcessBlockId);
+ACIR_DECLARE_PROCESS_ID(ProcessLiveSlotId);
+ACIR_DECLARE_PROCESS_ID(ProcessWakeId);
+ACIR_DECLARE_PROCESS_ID(ProcessTransitionId);
+#undef ACIR_DECLARE_PROCESS_ID
+
+enum class ProcessWakeKind { Condition, Resource, EventQueue, NextDelta };
+enum class ProcessSubscriptionSourceKind { Capture, Value, Symbol };
+enum class ProcessActionKind {
+ Original,
+ Constant,
+ ForInitialize,
+ ForCondition,
+ ForIncrement,
+ ScalarWrap,
+ ScalarUnwrap
+};
+enum class ProcessEmissionClass {
+ CopyScalar,
+ Inline,
+ Invoke,
+ Wrap,
+ Unwrap,
+ ForwardOnly
+};
+enum class ProcessOccurrenceKind {
+ Original,
+ SyntheticLoop,
+ SyntheticWrapper,
+ SyntheticConstant
+};
+enum class ProcessLoopPhase { Initialize, Condition, Increment };
+enum class ProcessWrapperDirection { Wrap, Unwrap };
+enum class ProcessFrameKind { Entry, ScfIf, ScfFor, ScfWhile };
+enum class ProcessFramePhase {
+ Entry,
+ Then,
+ Else,
+ Merge,
+ Header,
+ Body,
+ Before,
+ After,
+ Exit
+};
+enum class ProcessPlannedValueKind {
+ Original,
+ Capture,
+ LiveSlot,
+ Synthetic,
+ Constant
+};
+enum class ProcessValueCoordinateKind { Result, BlockArgument };
+enum class ProcessControlEdgeKind { Branch, LocalContinue, Suspend, Terminate };
+enum class ProcessTerminateStatus { Success, Failure };
+enum class ProcessEffectKind { Pure, Stateful };
+enum class ProcessValueTypeKind { Value, Packet };
+enum class ProcessHelperRole {
+ RecordCreate,
+ RecordGet,
+ RecordWith,
+ PacketSerialize,
+ PacketDeserialize,
+ TraceDecode,
+ QueueTrySend,
+ QueueTryRecv,
+ EventSchedule,
+ TraceOpen,
+ TraceNext,
+ TraceEof,
+ TracePosition,
+ ContractRequire,
+ ContractEnsure,
+ ContractAssert,
+ Probe,
+ StatAdd,
+ WakeCondition,
+ WakeResource,
+ WakeEventQueue,
+ WakeNextDelta,
+ ScalarWrap,
+ ScalarUnwrap
+};
+enum class ProcessValueTypeMemberKind { Field, Element };
+enum class ProcessStorageSignedness { Signless, Signed, Unsigned };
+
+#define ACIR_PROCESS_PIMPL(Name) \
+ struct Impl; \
+ explicit Name(std::shared_ptr impl) : impl_(std::move(impl)) {} \
+ std::shared_ptr impl_; \
+ friend class detail::PlanSetBuilder
+
+class ProcessCallSitePlan {
+public:
+ mlir::Operation *operation() const;
+ llvm::StringRef operationPath() const;
+ llvm::ArrayRef iterationVector() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessCallSitePlan);
+};
+
+class ProcessOccurrenceId;
+class ProcessOriginalOccurrence {
+public:
+ mlir::Operation *operation() const;
+ llvm::StringRef operationPath() const;
+ llvm::ArrayRef callSites() const;
+ llvm::ArrayRef iterationVector() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessOriginalOccurrence);
+};
+class ProcessSyntheticLoopOccurrence {
+public:
+ const ProcessOccurrenceId &anchor() const;
+ ProcessLoopPhase phase() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessSyntheticLoopOccurrence);
+};
+class ProcessSyntheticWrapperOccurrence {
+public:
+ const ProcessOccurrenceId &anchor() const;
+ ProcessTransitionId transition() const;
+ ProcessLiveSlotId slot() const;
+ ProcessWrapperDirection direction() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessSyntheticWrapperOccurrence);
+};
+class ProcessSyntheticConstantOccurrence {
+public:
+ const ProcessOccurrenceId &anchor() const;
+ uint32_t constant() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessSyntheticConstantOccurrence);
+};
+class ProcessOccurrenceId {
+public:
+ ProcessOccurrenceKind kind() const;
+ const ProcessOriginalOccurrence &original() const;
+ const ProcessSyntheticLoopOccurrence &syntheticLoop() const;
+ const ProcessSyntheticWrapperOccurrence &syntheticWrapper() const;
+ const ProcessSyntheticConstantOccurrence &syntheticConstant() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessOccurrenceId);
+};
+
+class ProcessValueCoordinate {
+public:
+ ProcessValueCoordinateKind kind() const;
+ llvm::StringRef ownerPath() const;
+ uint32_t index() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessValueCoordinate);
+};
+class ProcessOriginalPlannedValue {
+public:
+ mlir::Value value() const;
+ const ProcessOccurrenceId &occurrence() const;
+ const ProcessValueCoordinate &coordinate() const;
+ llvm::StringRef path() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessOriginalPlannedValue);
+};
+class ProcessCapturePlannedValue {
+public:
+ ProcessCaptureId capture() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessCapturePlannedValue);
+};
+class ProcessLiveSlotPlannedValue {
+public:
+ ProcessLiveSlotId slot() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessLiveSlotPlannedValue);
+};
+class ProcessSyntheticPlannedValue {
+public:
+ const ProcessOccurrenceId &occurrence() const;
+ const ProcessValueCoordinate &coordinate() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessSyntheticPlannedValue);
+};
+class ProcessConstantPlannedValue {
+public:
+ llvm::StringRef value() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessConstantPlannedValue);
+};
+class ProcessPlannedValue {
+public:
+ ProcessPlannedValueKind kind() const;
+ mlir::Type type() const;
+ const ProcessOriginalPlannedValue &original() const;
+ const ProcessCapturePlannedValue &capture() const;
+ const ProcessLiveSlotPlannedValue &liveSlot() const;
+ const ProcessSyntheticPlannedValue &synthetic() const;
+ const ProcessConstantPlannedValue &constant() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessPlannedValue);
+};
+
+class ProcessScalarAttribute {
+public:
+ llvm::StringRef name() const;
+ llvm::StringRef value() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessScalarAttribute);
+};
+class ProcessScalarOperationPlan {
+public:
+ llvm::StringRef name() const;
+ llvm::ArrayRef attributes() const;
+ llvm::StringRef properties() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessScalarOperationPlan);
+};
+
+class ProcessCapturePlan {
+public:
+ ProcessCaptureId id() const;
+ llvm::StringRef name() const;
+ mlir::Value operand() const;
+ mlir::Value entryArgument() const;
+ mlir::Type type() const;
+ llvm::StringRef operandPath() const;
+ llvm::StringRef argumentPath() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessCapturePlan);
+};
+class ProcessActionPlan {
+public:
+ uint32_t id() const;
+ ProcessActionKind kind() const;
+ ProcessEmissionClass emission() const;
+ const ProcessOccurrenceId &occurrence() const;
+ mlir::Operation *sourceOperation() const;
+ llvm::ArrayRef iterationVector() const;
+ llvm::ArrayRef operands() const;
+ llvm::ArrayRef results() const;
+ uint32_t cost() const;
+ llvm::ArrayRef resultTypes() const;
+ std::optional callee() const;
+ const ProcessScalarOperationPlan *scalarOp() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessActionPlan);
+};
+class ProcessLiveSlotPlan {
+public:
+ ProcessLiveSlotId id() const;
+ llvm::StringRef name() const;
+ mlir::Type type() const;
+ ProcessValueTypeId storageType() const;
+ llvm::ArrayRef memberValues() const;
+ std::optional wrapCallee() const;
+ std::optional unwrapCallee() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessLiveSlotPlan);
+};
+class ProcessSubscriptionSourcePlan {
+public:
+ ProcessSubscriptionSourceKind kind() const;
+ mlir::Value value() const;
+ mlir::Operation *owner() const;
+ mlir::Operation *declaration() const;
+ std::optional capture() const;
+ llvm::StringRef symbol() const;
+ llvm::StringRef path() const;
+ llvm::StringRef ownerPath() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessSubscriptionSourcePlan);
+};
+class ProcessWakePlan {
+public:
+ ProcessWakeId id() const;
+ ProcessWakeKind kind() const;
+ mlir::Operation *operation() const;
+ mlir::Value triggeringValue() const;
+ mlir::Operation *declaration() const;
+ ProcessCalleeId callee() const;
+ llvm::StringRef typeKey() const;
+ llvm::StringRef operationPath() const;
+ llvm::StringRef target() const;
+ const ProcessOccurrenceId &occurrence() const;
+ llvm::ArrayRef iterationVector() const;
+ llvm::ArrayRef sources() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessWakePlan);
+};
+class ProcessTransitionStorePlan {
+public:
+ ProcessLiveSlotId slot() const;
+ const ProcessPlannedValue &source() const;
+ mlir::Value sourceValue() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessTransitionStorePlan);
+};
+class ProcessTransitionLoadPlan {
+public:
+ ProcessLiveSlotId slot() const;
+ llvm::ArrayRef replacements() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessTransitionLoadPlan);
+};
+class ProcessTransitionPlan {
+public:
+ ProcessTransitionId id() const;
+ ProcessPcId sourcePc() const;
+ ProcessPcId targetPc() const;
+ ProcessWakeId wake() const;
+ llvm::ArrayRef iterationVector() const;
+ llvm::ArrayRef stores() const;
+ llvm::ArrayRef loads() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessTransitionPlan);
+};
+class ProcessForwardingBindingPlan {
+public:
+ const ProcessPlannedValue &from() const;
+ const ProcessPlannedValue &to() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessForwardingBindingPlan);
+};
+class ProcessControlFramePlan {
+public:
+ ProcessFrameKind kind() const;
+ ProcessFramePhase phase() const;
+ mlir::Operation *operation() const;
+ llvm::StringRef operationPath() const;
+ llvm::ArrayRef bindings() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessControlFramePlan);
+};
+class ProcessControlEdgePlan {
+public:
+ ProcessControlEdgeKind kind() const;
+ const ProcessPlannedValue &condition() const;
+ ProcessBlockId trueBlock() const;
+ ProcessBlockId falseBlock() const;
+ llvm::ArrayRef trueBindings() const;
+ llvm::ArrayRef falseBindings() const;
+ ProcessBlockId targetBlock() const;
+ llvm::ArrayRef bindings() const;
+ ProcessTransitionId transition() const;
+ ProcessTerminateStatus status() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessControlEdgePlan);
+};
+class ProcessBlockPlan {
+public:
+ ProcessBlockId id() const;
+ ProcessPcId pc() const;
+ mlir::Region *originRegion() const;
+ mlir::Block *originBlock() const;
+ llvm::StringRef path() const;
+ llvm::ArrayRef frames() const;
+ llvm::ArrayRef loads() const;
+ llvm::ArrayRef actions() const;
+ const ProcessControlEdgePlan &edge() const;
+ uint64_t cost() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessBlockPlan);
+};
+class ProcessPcPlan {
+public:
+ ProcessPcId id() const;
+ llvm::StringRef name() const;
+ llvm::StringRef entryPath() const;
+ llvm::ArrayRef blocks() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessPcPlan);
+};
+class ProcessStatePlan {
+public:
+ llvm::StringRef definitionKey() const;
+ ac::ProcessOp process() const;
+ llvm::ArrayRef captures() const;
+ ProcessPcId entryPc() const;
+ llvm::ArrayRef pcs() const;
+ llvm::ArrayRef blocks() const;
+ llvm::ArrayRef liveSlots() const;
+ llvm::ArrayRef wakes() const;
+ llvm::ArrayRef transitions() const;
+ uint32_t pcBitWidth() const;
+ uint64_t fairnessWork() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessStatePlan);
+};
+
+class ProcessRecordFieldDescriptor {
+public:
+ llvm::StringRef name() const;
+ llvm::StringRef typeKey() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessRecordFieldDescriptor);
+};
+#define ACIR_DECLARE_STRING_PAYLOAD(Name, ...) \
+ class Name { \
+ public: \
+ __VA_ARGS__ private : ACIR_PROCESS_PIMPL(Name); \
+ }
+class ProcessRecordCreatePayload {
+public:
+ llvm::ArrayRef fields() const;
+ llvm::StringRef recordType() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessRecordCreatePayload);
+};
+ACIR_DECLARE_STRING_PAYLOAD(ProcessRecordGetPayload,
+ llvm::StringRef field() const;
+ llvm::StringRef record() const;
+ llvm::StringRef result() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessRecordWithPayload,
+ llvm::StringRef field() const;
+ llvm::StringRef record() const;
+ llvm::StringRef value() const;);
+class ProcessPacketSerializePayload {
+public:
+ uint64_t bytes() const;
+ llvm::StringRef packet() const;
+ llvm::StringRef packetType() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessPacketSerializePayload);
+};
+class ProcessPacketDeserializePayload {
+public:
+ uint64_t bytes() const;
+ llvm::StringRef packet() const;
+ llvm::StringRef packetType() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessPacketDeserializePayload);
+};
+ACIR_DECLARE_STRING_PAYLOAD(ProcessTraceDecodePayload,
+ llvm::StringRef entry() const;
+ llvm::StringRef result() const;
+ llvm::StringRef source() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessQueueTrySendPayload,
+ llvm::StringRef element() const;
+ llvm::StringRef queue() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessQueueTryRecvPayload,
+ llvm::StringRef element() const;
+ llvm::StringRef queue() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessEventSchedulePayload,
+ llvm::StringRef delay() const;
+ llvm::StringRef target() const;
+ llvm::StringRef value() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessTraceOpenPayload,
+ llvm::StringRef source() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessTraceNextPayload,
+ llvm::StringRef entry() const;
+ llvm::StringRef source() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessTraceEofPayload,
+ llvm::StringRef source() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessTracePositionPayload,
+ llvm::StringRef source() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessContractRequirePayload,
+ llvm::StringRef message() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessContractEnsurePayload,
+ llvm::StringRef message() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessContractAssertPayload,
+ llvm::StringRef message() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessProbePayload, llvm::StringRef kind() const;
+ llvm::StringRef result() const;
+ llvm::StringRef target() const;);
+ACIR_DECLARE_STRING_PAYLOAD(ProcessStatAddPayload, llvm::StringRef stat() const;
+ llvm::StringRef valueType() const;);
+#undef ACIR_DECLARE_STRING_PAYLOAD
+#define ACIR_DECLARE_WAKE_PAYLOAD(Name) \
+ class Name { \
+ public: \
+ ProcessWakeKind wakeKind() const; \
+ llvm::StringRef wakeType() const; \
+ \
+ private: \
+ ACIR_PROCESS_PIMPL(Name); \
+ }
+ACIR_DECLARE_WAKE_PAYLOAD(ProcessWakeConditionPayload);
+ACIR_DECLARE_WAKE_PAYLOAD(ProcessWakeResourcePayload);
+ACIR_DECLARE_WAKE_PAYLOAD(ProcessWakeEventQueuePayload);
+ACIR_DECLARE_WAKE_PAYLOAD(ProcessWakeNextDeltaPayload);
+#undef ACIR_DECLARE_WAKE_PAYLOAD
+class ProcessScalarWrapPayload {
+public:
+ ProcessWrapperDirection direction() const;
+ llvm::StringRef scalar() const;
+ llvm::StringRef valueType() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessScalarWrapPayload);
+};
+class ProcessScalarUnwrapPayload {
+public:
+ ProcessWrapperDirection direction() const;
+ llvm::StringRef scalar() const;
+ llvm::StringRef valueType() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessScalarUnwrapPayload);
+};
+
+class ProcessGeneratedCalleePayload {
+public:
+ ProcessHelperRole role() const;
+ const ProcessRecordCreatePayload &recordCreate() const;
+ const ProcessRecordGetPayload &recordGet() const;
+ const ProcessRecordWithPayload &recordWith() const;
+ const ProcessPacketSerializePayload &packetSerialize() const;
+ const ProcessPacketDeserializePayload &packetDeserialize() const;
+ const ProcessTraceDecodePayload &traceDecode() const;
+ const ProcessQueueTrySendPayload &queueTrySend() const;
+ const ProcessQueueTryRecvPayload &queueTryRecv() const;
+ const ProcessEventSchedulePayload &eventSchedule() const;
+ const ProcessTraceOpenPayload &traceOpen() const;
+ const ProcessTraceNextPayload &traceNext() const;
+ const ProcessTraceEofPayload &traceEof() const;
+ const ProcessTracePositionPayload &tracePosition() const;
+ const ProcessContractRequirePayload &contractRequire() const;
+ const ProcessContractEnsurePayload &contractEnsure() const;
+ const ProcessContractAssertPayload &contractAssert() const;
+ const ProcessProbePayload &probe() const;
+ const ProcessStatAddPayload &statAdd() const;
+ const ProcessWakeConditionPayload &wakeCondition() const;
+ const ProcessWakeResourcePayload &wakeResource() const;
+ const ProcessWakeEventQueuePayload &wakeEventQueue() const;
+ const ProcessWakeNextDeltaPayload &wakeNextDelta() const;
+ const ProcessScalarWrapPayload &scalarWrap() const;
+ const ProcessScalarUnwrapPayload &scalarUnwrap() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessGeneratedCalleePayload);
+};
+
+class ProcessValueTypeMemberPlan {
+public:
+ ProcessValueTypeMemberKind kind() const;
+ llvm::StringRef name() const;
+ std::optional index() const;
+ uint64_t offsetBits() const;
+ uint64_t widthBits() const;
+ std::optional signedness() const;
+ llvm::StringRef encoding() const;
+ llvm::StringRef typeKey() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessValueTypeMemberPlan);
+};
+class ProcessStorageValuePayload {
+public:
+ llvm::ArrayRef members() const;
+ uint64_t widthBits() const;
+ llvm::StringRef encoding() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessStorageValuePayload);
+};
+class ProcessStoragePacketPayload {
+public:
+ llvm::ArrayRef members() const;
+ uint64_t widthBits() const;
+ uint64_t bytes() const;
+ llvm::StringRef encoding() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessStoragePacketPayload);
+};
+class ProcessValueTypePayload {
+public:
+ ProcessValueTypeKind kind() const;
+ const ProcessStorageValuePayload &value() const;
+ const ProcessStoragePacketPayload &packet() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessValueTypePayload);
+};
+class ProcessGeneratedCalleePlan {
+public:
+ ProcessCalleeId id() const;
+ llvm::StringRef symbol() const;
+ llvm::StringRef cpp() const;
+ llvm::StringRef kind() const;
+ llvm::StringRef fingerprint() const;
+ ProcessEffectKind effect() const;
+ llvm::ArrayRef inputTypeKeys() const;
+ llvm::ArrayRef resultTypeKeys() const;
+ ProcessHelperRole role() const;
+ const ProcessGeneratedCalleePayload &payload() const;
+ llvm::ArrayRef sourceOperations() const;
+ llvm::ArrayRef declarations() const;
+ llvm::ArrayRef sourcePaths() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessGeneratedCalleePlan);
+};
+class ProcessValueTypePlan {
+public:
+ ProcessValueTypeId id() const;
+ llvm::StringRef symbol() const;
+ llvm::StringRef cpp() const;
+ ProcessValueTypeKind kind() const;
+ llvm::StringRef fingerprint() const;
+ mlir::Type acirType() const;
+ const ProcessValueTypePayload &payload() const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessValueTypePlan);
+};
+class ProcessStatePlanSet {
+public:
+ llvm::ArrayRef processes() const;
+ llvm::ArrayRef callees() const;
+ llvm::ArrayRef valueTypes() const;
+ const ProcessStatePlan *
+ lookupByDefinitionKey(llvm::StringRef definitionKey) const;
+
+private:
+ ACIR_PROCESS_PIMPL(ProcessStatePlanSet);
+};
+
+#undef ACIR_PROCESS_PIMPL
+
+mlir::LogicalResult
+verifyProcessStatePlan(const ProcessStatePlanSet &plans,
+ const ProcessStateLimits &limits = ProcessStateLimits());
+mlir::FailureOr
+planProcessState(mlir::ModuleOp module,
+ const ProcessStateLimits &limits = ProcessStateLimits());
+llvm::Expected serializeProcessStatePlan(
+ const ProcessStatePlanSet &plans,
+ const ProcessStateLimits &limits = ProcessStateLimits());
+
+} // namespace acir
+
+#endif
diff --git a/components/agentic-circuit/include/acir/Bindings/Binding.h b/components/agentic-circuit/include/acir/Bindings/Binding.h
new file mode 100644
index 00000000..a7caeb70
--- /dev/null
+++ b/components/agentic-circuit/include/acir/Bindings/Binding.h
@@ -0,0 +1,184 @@
+#ifndef ACIR_BINDINGS_BINDING_H
+#define ACIR_BINDINGS_BINDING_H
+
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/JSON.h"
+
+#include
+#include
+#include
+#include
+#include
+
+namespace acir::bindings {
+
+inline constexpr llvm::StringLiteral BindingSchema = "acsim-binding-0.1";
+inline constexpr llvm::StringLiteral ContractEpoch = "0.3";
+
+struct JsonParseLimits {
+ size_t maxInputBytes = 1U << 20;
+ size_t maxDepth = 64;
+ size_t maxStructuralWork = 100000;
+ size_t maxStringBytes = 1U << 18;
+ size_t maxTotalStringBytes = 1U << 20;
+ size_t maxArrayElements = 65536;
+ size_t maxObjectMembers = 4096;
+};
+
+/// Parses the accepted RFC 8785/I-JSON subset while retaining lexical checks
+/// that ordinary JSON DOM parsers lose (duplicate keys and negative zero).
+llvm::Expected
+parseIJson(llvm::StringRef input,
+ const JsonParseLimits &limits = JsonParseLimits());
+
+/// Emits RFC 8785 canonical UTF-8 bytes. Object names are ordered by unsigned
+/// UTF-16 code units recursively; arrays retain their input order. Constructed
+/// DOMs are preflighted against the same deterministic resource limits as text.
+llvm::Expected
+canonicalizeJson(const llvm::json::Value &value,
+ const JsonParseLimits &limits = JsonParseLimits());
+llvm::Expected
+canonicalizeJsonText(llvm::StringRef input,
+ const JsonParseLimits &limits = JsonParseLimits());
+
+std::string sha256Fingerprint(llvm::StringRef canonicalBytes);
+
+struct CppEntryPoints {
+ std::string pure;
+ std::string reset;
+ std::string validate;
+ std::string work;
+ std::string xfer;
+
+ bool operator==(const CppEntryPoints &) const = default;
+};
+
+struct CppBinding {
+ std::string conceptName;
+ CppEntryPoints entryPoints;
+ std::string header;
+ std::string symbol;
+ std::string target;
+
+ bool operator==(const CppBinding &) const = default;
+};
+
+struct ConstructionBinding {
+ std::vector arguments;
+ std::string kind;
+
+ bool operator==(const ConstructionBinding &) const = default;
+};
+
+struct OwnershipBinding {
+ std::string kind;
+ std::string placement;
+
+ bool operator==(const OwnershipBinding &) const = default;
+};
+
+struct ParameterBinding {
+ std::string acirType;
+ std::string cppType;
+ std::string mapping;
+ std::string name;
+ int64_t ordinal = 0;
+ llvm::json::Value value = nullptr;
+
+ bool operator==(const ParameterBinding &) const = default;
+};
+
+struct PortBinding {
+ std::string accessor;
+ std::string cardinality;
+ std::string delegation;
+ std::string direction;
+ std::string interface;
+ std::string ownership;
+ std::string payload;
+ std::string protocol;
+ std::string role;
+ std::string timeDomain;
+
+ bool operator==(const PortBinding &) const = default;
+};
+
+struct ResourceBinding {
+ std::string accessor;
+ std::string delegation;
+ std::string mode;
+ std::string ownership;
+ std::string resource;
+ std::string role;
+ std::string timeDomain;
+
+ bool operator==(const ResourceBinding &) const = default;
+};
+
+struct ResultBinding {
+ std::string cppType;
+ std::string name;
+
+ bool operator==(const ResultBinding &) const = default;
+};
+
+struct ActivationSourceBinding {
+ std::string kind;
+ std::string name;
+
+ bool operator==(const ActivationSourceBinding &) const = default;
+};
+
+/// Immutable, typed form of the exact 20-field acsim.binding consumer record.
+class BindingRecord {
+public:
+ BindingRecord(const BindingRecord &) = default;
+ BindingRecord(BindingRecord &&) noexcept = default;
+ BindingRecord &operator=(const BindingRecord &) = default;
+ BindingRecord &operator=(BindingRecord &&) noexcept = default;
+ ~BindingRecord();
+
+ static llvm::Expected
+ parse(const llvm::json::Object &object,
+ const JsonParseLimits &limits = JsonParseLimits());
+
+ llvm::StringRef bindingSchema() const;
+ llvm::StringRef contractEpoch() const;
+ llvm::StringRef binding() const;
+ llvm::StringRef componentSchema() const;
+ llvm::StringRef componentSchemaFingerprint() const;
+ llvm::StringRef availability() const;
+ llvm::StringRef effect() const;
+ llvm::StringRef cppType() const;
+ llvm::StringRef implementation() const;
+ llvm::StringRef provider() const;
+ llvm::StringRef providerImplementationFingerprint() const;
+ llvm::StringRef fingerprint() const;
+ const CppBinding &cpp() const;
+ const ConstructionBinding &construction() const;
+ const OwnershipBinding &ownership() const;
+ llvm::ArrayRef parameters() const;
+ llvm::ArrayRef ports() const;
+ llvm::ArrayRef resources() const;
+ llvm::ArrayRef results() const;
+ llvm::ArrayRef activationSources() const;
+ const llvm::json::Object &json() const;
+
+ llvm::Expected canonicalJson() const;
+ llvm::Expected canonicalJsonForFingerprint() const;
+ llvm::Error validateFingerprint() const;
+
+private:
+ struct Storage;
+ explicit BindingRecord(std::shared_ptr storage);
+ std::shared_ptr storage;
+};
+
+llvm::Expected
+computeBindingRecordFingerprint(const BindingRecord &record);
+
+} // namespace acir::bindings
+
+#endif // ACIR_BINDINGS_BINDING_H
diff --git a/components/agentic-circuit/include/acir/Bindings/Registry.h b/components/agentic-circuit/include/acir/Bindings/Registry.h
new file mode 100644
index 00000000..0c0bcee5
--- /dev/null
+++ b/components/agentic-circuit/include/acir/Bindings/Registry.h
@@ -0,0 +1,179 @@
+#ifndef ACIR_BINDINGS_REGISTRY_H
+#define ACIR_BINDINGS_REGISTRY_H
+
+#include "acir/Bindings/Binding.h"
+
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/raw_ostream.h"
+
+#include
+#include
+#include
+
+namespace acir::bindings {
+
+/// Candidate-only selection metadata is intentionally outside the exact lock
+/// record and is never emitted into acsim.binding.
+class BindingCandidate {
+public:
+ BindingCandidate(const BindingCandidate &) = default;
+ BindingCandidate(BindingCandidate &&) noexcept = default;
+ BindingCandidate &operator=(const BindingCandidate &) = default;
+ BindingCandidate &operator=(BindingCandidate &&) noexcept = default;
+ ~BindingCandidate();
+
+ static llvm::Expected
+ parse(const llvm::json::Object &object,
+ const JsonParseLimits &limits = JsonParseLimits());
+
+ llvm::StringRef profile() const;
+ llvm::StringRef target() const;
+ bool available() const;
+ const BindingRecord &record() const;
+ llvm::Expected deterministicKey() const;
+
+private:
+ struct Storage;
+ explicit BindingCandidate(std::shared_ptr storage);
+ std::shared_ptr storage;
+};
+
+struct ParameterRequirement {
+ std::string acirType;
+ std::string name;
+ int64_t ordinal = 0;
+ llvm::json::Value value = nullptr;
+
+ bool operator==(const ParameterRequirement &) const = default;
+};
+
+struct PortRequirement {
+ std::string cardinality;
+ std::string delegation;
+ std::string direction;
+ std::string interface;
+ std::string ownership;
+ std::string payload;
+ std::string protocol;
+ std::string role;
+ std::string timeDomain;
+
+ bool operator==(const PortRequirement &) const = default;
+};
+
+struct ResourceRequirement {
+ std::string delegation;
+ std::string mode;
+ std::string ownership;
+ std::string resource;
+ std::string role;
+ std::string timeDomain;
+
+ bool operator==(const ResourceRequirement &) const = default;
+};
+
+struct ResultRequirement {
+ std::string acirType;
+ std::string name;
+
+ bool operator==(const ResultRequirement &) const = default;
+};
+
+struct BindingRequest {
+ /// Independent frozen-architecture authority. Candidate-only C++ realization
+ /// fields (accessors, mappings, construction, symbols, and entry points) are
+ /// intentionally absent and must never be synthesized into this request.
+ std::string resolutionKey;
+ std::string functionType;
+ std::string bindingSchema;
+ std::string contractEpoch;
+ std::string binding;
+ std::string componentSchema;
+ std::string componentSchemaFingerprint;
+ std::string effect;
+ std::string provider;
+ std::string providerImplementationFingerprint;
+ std::vector parameters;
+ std::vector ports;
+ std::vector resources;
+ std::vector results;
+ std::vector activationSources;
+};
+
+struct BindingRegistryDocument {
+ /// The two arrays have distinct provenance: candidates cannot author or
+ /// supply defaults for requests.
+ std::vector candidates;
+ std::vector requests;
+};
+
+llvm::Expected
+parseBindingRegistry(llvm::StringRef input,
+ const JsonParseLimits &limits = JsonParseLimits());
+
+class ResolvedBinding {
+public:
+ ResolvedBinding(std::string resolutionKey, BindingCandidate candidate);
+
+ llvm::StringRef resolutionKey() const { return key; }
+ const BindingRecord &record() const { return selected.record(); }
+ const BindingCandidate &candidate() const { return selected; }
+
+private:
+ std::string key;
+ BindingCandidate selected;
+};
+
+class BindingRegistry {
+public:
+ static llvm::Expected
+ create(std::vector candidates);
+
+ llvm::Expected resolve(const BindingRequest &request,
+ llvm::StringRef profile,
+ llvm::StringRef target) const;
+ llvm::ArrayRef candidates() const;
+
+private:
+ explicit BindingRegistry(std::vector candidates);
+ std::vector orderedCandidates;
+};
+
+class BindingResolutionResult {
+public:
+ BindingResolutionResult(std::vector selections,
+ std::string canonicalLock,
+ std::string lockFingerprint);
+
+ llvm::ArrayRef selections() const { return selected; }
+ const ResolvedBinding *
+ selectionForResolutionKey(llvm::StringRef resolutionKey) const;
+ llvm::StringRef canonicalLock() const { return lock; }
+ llvm::StringRef lockFingerprint() const { return fingerprint; }
+
+private:
+ std::vector selected;
+ std::string lock;
+ std::string fingerprint;
+};
+
+llvm::Expected
+resolveBindings(llvm::ArrayRef candidates,
+ llvm::ArrayRef requests,
+ llvm::StringRef profile, llvm::StringRef target);
+
+llvm::Error emitBindingLock(const BindingResolutionResult &result,
+ llvm::raw_ostream &output);
+llvm::Error emitBindingLockAtomically(const BindingResolutionResult &result,
+ llvm::StringRef outputPath);
+llvm::Error
+resolveAndWriteBindingLock(llvm::ArrayRef candidates,
+ llvm::ArrayRef requests,
+ llvm::StringRef profile, llvm::StringRef target,
+ llvm::StringRef outputPath);
+
+} // namespace acir::bindings
+
+#endif // ACIR_BINDINGS_REGISTRY_H
diff --git a/components/agentic-circuit/include/acir/CMakeLists.txt b/components/agentic-circuit/include/acir/CMakeLists.txt
new file mode 100644
index 00000000..557daa84
--- /dev/null
+++ b/components/agentic-circuit/include/acir/CMakeLists.txt
@@ -0,0 +1,2 @@
+add_subdirectory(Dialect)
+add_subdirectory(Transforms)
diff --git a/components/agentic-circuit/include/acir/CodeGen/Build.h b/components/agentic-circuit/include/acir/CodeGen/Build.h
new file mode 100644
index 00000000..0821b2b8
--- /dev/null
+++ b/components/agentic-circuit/include/acir/CodeGen/Build.h
@@ -0,0 +1,131 @@
+#ifndef ACIR_CODEGEN_BUILD_H
+#define ACIR_CODEGEN_BUILD_H
+
+#include "acir/CodeGen/Generator.h"
+
+#include "mlir/IR/BuiltinOps.h"
+#include "llvm/Support/Error.h"
+
+#include
+#include
+
+namespace acir::codegen {
+
+struct ToolchainIdentity {
+ std::string compilerPath;
+ std::string compilerName;
+ std::string compilerBuildId;
+ std::string targetTriple;
+ std::string standardLibrary;
+ std::string abiMode;
+ std::string objectFormat;
+ std::vector contractFlags;
+ Fingerprint fingerprint;
+};
+
+struct PrebuiltProvenance {
+ std::string compilerBuildId;
+ std::string targetTriple;
+ std::string standardLibrary;
+ std::string abiMode;
+ std::string objectFormat;
+ std::string contractEpoch = "0.3";
+ std::vector contractFlags;
+ Fingerprint toolchainFingerprint;
+ Fingerprint sourceFingerprint;
+};
+
+struct PrebuiltInput {
+ std::string path;
+ std::string kind;
+ PrebuiltProvenance provenance;
+ bool sourceAvailable = false;
+};
+
+struct CompileCommand {
+ std::vector arguments;
+ std::string output;
+};
+
+struct LinkInputIdentity {
+ std::string path;
+ Fingerprint fingerprint;
+};
+
+struct FrontendProvenance {
+ // Empty only for the internal canonical-ACSim driver. Frontend-originated
+ // builds populate this record completely and are validated atomically.
+ std::vector sourceFiles;
+ Artifact acpy;
+ std::string acpyBytes;
+ Artifact canonicalAcir;
+ std::string canonicalAcirBytes;
+ std::string pythonVersion;
+ std::vector helperIdentities;
+};
+
+struct CompilePlan {
+ std::string schema = "acsim-compile-plan-0.1";
+ std::vector sourceUnits;
+ std::vector objectOutputs;
+ std::vector includeRoots;
+ std::vector definitions;
+ std::vector compilerFlags;
+ std::vector linkerFlags;
+ std::vector linkInputs;
+ std::vector prebuiltInputs;
+ std::vector compileCommands;
+ CompileCommand linkCommand;
+ std::string executablePath;
+ Fingerprint sourceFingerprint;
+ Fingerprint toolchainFingerprint;
+ Fingerprint fingerprint;
+
+ llvm::Error validate() const;
+ llvm::Expected canonicalJson() const;
+};
+
+struct BuildRequest {
+ Identity project;
+ Identity system;
+ FrontendProvenance frontend;
+ mlir::ModuleOp canonicalACSim;
+ std::string frozenAcirBytes;
+ std::string canonicalACSimBytes;
+ std::string bindingLockBytes;
+ std::string profile;
+ std::vector passPipeline;
+ std::vector instrumentationLayers;
+ std::vector providerInputs;
+ ToolchainIdentity toolchain;
+ std::vector prebuiltInputs;
+ std::vector includeRoots;
+ std::vector definitions;
+ std::vector compilerFlags;
+ std::vector linkerFlags;
+ std::vector linkInputs;
+ std::string outputRoot;
+};
+
+struct BuildResult {
+ std::string buildDirectory;
+ std::string executable;
+ Fingerprint buildFingerprint;
+ bool cacheHit = false;
+};
+
+llvm::Expected
+identifyToolchain(std::string compilerPath, std::string standardLibrary,
+ std::string abiMode, std::string objectFormat,
+ std::vector contractFlags);
+
+llvm::Error preflightBuildRequest(const BuildRequest &request);
+
+llvm::Expected createCompilePlan(const BuildRequest &request,
+ const SourceBundle &bundle);
+
+llvm::Expected buildGeneratedModel(const BuildRequest &request);
+
+} // namespace acir::codegen
+
+#endif // ACIR_CODEGEN_BUILD_H
diff --git a/components/agentic-circuit/include/acir/CodeGen/Emitter.h b/components/agentic-circuit/include/acir/CodeGen/Emitter.h
new file mode 100644
index 00000000..16a9c8d4
--- /dev/null
+++ b/components/agentic-circuit/include/acir/CodeGen/Emitter.h
@@ -0,0 +1,129 @@
+#ifndef ACIR_CODEGEN_EMITTER_H
+#define ACIR_CODEGEN_EMITTER_H
+
+#include "acir/CodeGen/Manifest.h"
+
+#include
+#include
+#include
+#include
+
+namespace acir::codegen {
+
+// ── Structured C++ emitter ────────────────────────────────────────────
+
+/// Deterministic, indentation-aware C++ code emitter.
+/// Produces reproducible output: no timestamps, no pointer values,
+/// no host paths, no non-deterministic ordering.
+class CppEmitter {
+public:
+ explicit CppEmitter(std::ostream &os) : os_(os) {}
+
+ // ── File structure ──────────────────────────────────────────────────
+
+ void emitInclude(const std::string &header, bool system = false);
+ void emitPragmaOnce();
+ void emitNewline();
+ void emitComment(const std::string &text);
+
+ // ── Namespace ───────────────────────────────────────────────────────
+
+ void beginNamespace(const std::string &name);
+ void endNamespace();
+
+ // ── Class ───────────────────────────────────────────────────────────
+
+ void beginClass(const std::string &name, const std::string &base = "",
+ bool isStruct = false, bool isFinal = false);
+ void endClass();
+
+ // ── Access ─────────────────────────────────────────────────────────
+
+ void emitPublic();
+ void emitPrivate();
+ void emitProtected();
+
+ // ── Members ─────────────────────────────────────────────────────────
+
+ void emitMember(const std::string &type, const std::string &name,
+ const std::string &init = "");
+ void emitStaticMember(const std::string &type, const std::string &name,
+ const std::string &init = "");
+
+ // ── Methods ─────────────────────────────────────────────────────────
+
+ void emitConstructor(
+ const std::string &className,
+ const std::vector> ¶ms,
+ const std::vector &initializers,
+ const std::string &body = "");
+ void
+ emitMethod(const std::string &returnType, const std::string &name,
+ const std::vector> ¶ms,
+ bool isConst = false, bool isOverride = false,
+ bool isVirtual = false, bool isStatic = false);
+ void beginMethodBody();
+ void endMethodBody();
+ void emitReturn(const std::string &expr = "");
+ void emitStatement(const std::string &stmt);
+
+ // ── Enums ───────────────────────────────────────────────────────────
+
+ void emitEnum(const std::string &name, const std::vector &values,
+ const std::string &underlyingType = "uint8_t");
+
+ // ── Switch ──────────────────────────────────────────────────────────
+
+ void emitSwitch(const std::string &expr);
+ void emitCase(const std::string &value);
+ void emitDefault();
+ void emitBreak();
+ void endSwitch();
+
+ // ── Template ────────────────────────────────────────────────────────
+
+ void emitTemplate(const std::string ¶ms);
+
+ // ── Raw ─────────────────────────────────────────────────────────────
+
+ void emitRaw(const std::string &code);
+ std::ostream &raw() { return os_; }
+
+ // ── Indentation ─────────────────────────────────────────────────────
+
+ void indent();
+ void dedent();
+ int depth() const { return indent_; }
+
+private:
+ void writeIndent();
+ std::ostream &os_;
+ int indent_ = 0;
+ bool atLineStart_ = true;
+};
+
+// ── Deterministic code generation ─────────────────────────────────────
+
+/// One generated static-dispatch row. Object expressions are C++ lvalues
+/// rooted at the model parameter, for example `model.compute`.
+struct DispatchEntry {
+ uint32_t objectId = 0;
+ std::string objectExpression;
+};
+
+struct ActivationEdge {
+ uint32_t sourceId = 0;
+ uint32_t targetId = 0;
+};
+
+/// Generate the deterministic dense gfsim dispatch-table factory for a model.
+/// Entries may arrive in any order, but their IDs must be exactly [0, N).
+SourceFile
+generateDispatchHeader(const std::string &namespaceName,
+ const std::string &modelType,
+ std::vector entries,
+ std::vector activationEdges = {});
+
+} // namespace acir::codegen
+
+#endif // ACIR_CODEGEN_EMITTER_H
diff --git a/components/agentic-circuit/include/acir/CodeGen/Generator.h b/components/agentic-circuit/include/acir/CodeGen/Generator.h
new file mode 100644
index 00000000..51584857
--- /dev/null
+++ b/components/agentic-circuit/include/acir/CodeGen/Generator.h
@@ -0,0 +1,31 @@
+#ifndef ACIR_CODEGEN_GENERATOR_H
+#define ACIR_CODEGEN_GENERATOR_H
+
+#include "acir/CodeGen/ModelPlan.h"
+
+#include "llvm/Support/Error.h"
+
+#include
+#include
+
+namespace acir::codegen {
+
+struct GeneratedFile {
+ std::string relativePath;
+ std::string content;
+ Fingerprint fingerprint;
+};
+
+struct SourceBundle {
+ Fingerprint sourceFingerprint;
+ Fingerprint buildFingerprint;
+ std::vector files;
+};
+
+llvm::Expected generateModelSources(const ModelPlan &plan);
+llvm::Error validateSourceBundle(const ModelPlan &plan,
+ const SourceBundle &bundle);
+
+} // namespace acir::codegen
+
+#endif // ACIR_CODEGEN_GENERATOR_H
diff --git a/components/agentic-circuit/include/acir/CodeGen/Manifest.h b/components/agentic-circuit/include/acir/CodeGen/Manifest.h
new file mode 100644
index 00000000..c6c47795
--- /dev/null
+++ b/components/agentic-circuit/include/acir/CodeGen/Manifest.h
@@ -0,0 +1,125 @@
+#ifndef ACIR_CODEGEN_MANIFEST_H
+#define ACIR_CODEGEN_MANIFEST_H
+
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/JSON.h"
+
+#include
+#include
+#include