feat(agentic-circuit): transact slot release in rules

[hmljy2020]

Summary

• allow module/system-owned slots to be explicit rule resources or nested-rule captures
• commit guarded slot release atomically with Queue, Table, and persistent-state effects in QueueGraph/GFSim
• keep standalone release and the provisional PYC/RTL rejection boundary intact
• curate the public state examples and retain decision-specific programs as integration fixtures

pyc6 Decision / Contract Impact

• Decision IDs: 0152, 0236, 0259, 0260, 0262
• Contract areas touched: Agentic Python frontend, ACIR rule/firing legality and lowering, QueueGraph planning/generation, GFSim transaction protocol, public state examples

Issue #138 Acceptance Criteria

Status meanings: ✅ implemented with focused evidence; ⚠️ remaining framework limitation or intentionally deferred evidence; ↗ consumer-owned follow-up outside this repository.

#	Acceptance criterion	Status and evidence
1	A rule reads an explicitly passed or legally captured Slot's valid and value.	✅ test_rule_slot_release_lowers_as_a_guarded_transaction_effect covers both source forms; test_flat_and_nested_slot_rules_generate_and_run_identically compiles and runs both through the native path.
2	A rule declares one unique Slot release effect.	✅ slot.release() lowers to guarded ac.slot.propose_release; frontend and ACIR tests reject duplicate or non-rule owners.
3	Slot release commits atomically with Queue consumption/output and Table/persistent state.	⚠️ test_queue_state_output_and_slot_release_commit_together covers the combined Python → ACIR → QueueGraph → native path, and SlotReleaseCommitsInputTwoOutputsAndTableAsOneTransaction covers one runtime commit group with an input, two outputs, Table write, and Slot release. The specialized optional-multi-output Python rule parser does not yet accept slot.release(), so that authoring combination remains open.
4	Output backpressure preserves the Slot and suppresses every other effect.	✅ SlotReleaseCommitsInputTwoOutputsAndTableAsOneTransaction fills one output and proves the input, both outputs, Table, Slot valid/payload, and reservations remain unchanged; the complete group commits after capacity becomes available.
5	A Slot-only rule runs without an ordinary Queue input and does not spin or fire repeatedly in one tick.	✅ The flat and nested native E2E cases are activated from committed Slot state, produce exactly one value, and remain at one result over additional cycles.
6	Capture is visible on the next tick and release cannot refill in the same tick.	✅ SlotCapturesBackpressuresReleasesAndDoesNotRefill covers next-edge visibility, retained payload, backpressure, and no same-tick refill.
7	Read-only and releasing rules observe the same pre-release committed snapshot.	✅ ReadOnlyAndReleasingSlotTransitionsObserveTheSameCommittedSnapshot and test_read_only_and_releasing_rules_share_the_committed_snapshot assert both observations at runtime, including the generated native path.
8	Duplicate owner, scope, alias, and payload-type errors are stable frontend/ACIR diagnostics.	✅ Focused frontend tests cover duplicate ownership, same-Slot alias, non-Slot binding, and unrelated-scope binding; ACIR lit freezes direct-owner and payload-type diagnostics.
9	Python direct and Frozen ACIR → QueueGraph → native GFSim agree on Slot behavior.	⚠️ Intentionally deferred in this follow-up. Rule programs require native MLIR lowering; the direct Python generator rejects @ac.rule instead of providing a second rule-transaction implementation.
10	Focused tests cover normal consume, backpressure, state conflict, Slot-only activation, same-tick observation, duplicate release, and reset.	✅ Focused frontend, ACIR, GFSim, CodeGen, and native E2E tests now cover each listed behavior. The combined transaction test also checks cancellation state before successful retry.
11	SPE OoO IQ wakeup migrates to Slot and retains its consumer tests.	↗ Consumer-owned follow-up. Decisions 0158 and 0235 require the SuperScalarModel design and compatibility tests to remain in the owning consumer repository against a pinned pyCircuit revision.
12	Completion mailboxes migrate to validation rule + Slot and retain invalid-input, isolation, round-robin, and backpressure tests.	↗ Consumer-owned follow-up under the same Decisions 0158/0235 repository boundary. No SPE OoO implementation or testbench is added to pyCircuit.
13	PYC/RTL explicitly rejects provisional Slot instead of partially lowering it.	✅ PycBackendRejectsProvisionalSlotWithoutLowering freezes the QueueGraph PYC diagnostic (Slot PYC lowering is not implemented); this PR adds no partial Slot lowering.

Because criterion 9 is intentionally deferred, criteria 11 and 12 are consumer-owned follow-ups, and the optional-multi-output authoring combination in criterion 3 remains open, this PR relates to #138 but does not auto-close it.

Validation

• Focused and complete relevant lanes:
  • GfsimTests: 254/254 passed
  • CodeGenTests: 171/171 passed
  • ACIROpsTests: 1/1 passed
  • focused Slot/field-write ACIR lit: 5/5 passed
  • focused Slot/combined-effect frontend tests: 8/8 passed
  • complete queue frontend file: 214/214 passed
  • native Slot transaction E2E: 4/4 passed
  • diagnostic catalog and ACIR inventory/coverage checks passed
  • strict MkDocs, changed-file pre-commit, API hygiene, and whitespace checks passed
• Evidence paths:
  • docs/gates/logs/20260915-ac-slot-rule-transactions/summary.md
  • docs/gates/logs/20260915-state-example-curation/summary.md
• Existing checkout-wide failures remain documented in the evidence: one typed-state JIT schema error, nine unrelated Agentic lit failures, workspace-local designs/davincioo policy failures, and two missing historical Decision evidence references.

Documentation

• Updated the English and Chinese Agentic Circuit specifications, frontend/language guidance, Decision 0262, decision status, state example catalog, and gate evidence.

Risk / Compatibility

• User-visible impact: rules can read a Slot and conditionally release it as part of one atomic firing; nested syntax is optional because explicit leading Slot parameters are also supported.
• Compatibility boundaries: Slots remain topology declarations, each Slot has one release owner, release does not permit same-tick refill, and PYC/RTL continues to reject provisional Slots explicitly.
• The added frontend fix preserves the Slot-valid predicate across ordinary Queue consumption, persistent-state proposal, output presence, and Slot release; the complete queue frontend test file remains green.

Related Issues

• Relates to 让 ac.slot 参与 @ac.rule 的原子事务 #138

[hmljy2020]

Dependency note: #144 is the issue #136 follow-up stacked directly on this PR's head commit 84146e9b.

Please merge #142 before #144. The temporary upstream feat/ac-slot-rule-transactions base ref should remain until #144 is rebased onto the post-#142 main; #144 will then be retargeted to main and the temporary base ref can be removed.

[zhoubot]

Merge blocker: rule-owned Slot release sets SlotState::pendingRelease and QueueSlot::doXfer applies it, but QueueSlot::hasPendingCommit() reports only fired_ (simulator/gfsim/include/gfsim/queue_blocks.h:3373-3378,3439-3451). SimSystem wakes activation dependents only from objects reported committed (simulator/gfsim/system.cpp:898-949,973-981), so a rule release can change Slot state without scheduling Slot-dependent rules. Existing generated tests manually execute every dispatch row and miss this scheduler boundary. Please make the Slot the committed activation source for rule-owned release and add a SimSystem scheduler regression. Also move the root-symbol lookup repair currently in #144 into this PR or otherwise ensure #142 does not land with the unresolved persistent-struct regression reported by its own evidence.

[zhoubot]

Re-reviewed at 893bd9c. The Slot commit-source regression, root symbol lookup regressions, scheduler coverage, enum/struct MLIR coverage, and IR ledger are repaired. Focused native/MLIR validation and both required G0 checks pass.