better throughput scheduling with steady state cost model, now limited to spatial

docs/compiler/scheduling-implementation.md

@@ -72,6 +72,59 @@ byte-sized elements. Blueprint assembly charges per fragment. A full fragment
 receive directly into assembly storage omits duplicate endpoint-memory edge
 cost; later copy elimination can leave this estimate conservative.
 
+`CopyAccessPlan` shares ordered contiguous-run geometry between projection
+costing and PIM copy normalization. Its inputs are a logical copy shape and
+proven source and destination strides, in elements. The immutable result keeps
+outer dimensions, run count, run length, and relative offsets compact. Building
+the plan takes linear time and space in rank, independent of loop trip counts.
+It creates no IR and does not prove aliasing, storage ownership, or copy legality.
+PIM bufferization still owns those decisions and the mapping to byte accesses.
+The plan alone does not describe a complete scheduled memory-request stream.
+Construction rejects an unrepresentable maximum relative element offset,
+including the last element of each run. Callers still check byte scaling and
+base-address addition.
+Projection costing uses checked row-major strides. Unsupported flattened
+offsets or strides produce at most one warning per graph cost query. The query
+uses one separately rounded request per element as a conservative service bound.
+It does not reject otherwise valid Spatial IR. Target lowering retains its own
+address and layout legality checks. Unsupported estimates and malformed IR are
+different conditions.
+
+The PIM adapter's `planComputeInputMaterialization` reads scheduled Spatial
+regions without changing them. It returns `Unused`, `ForwardConstant`,
+`ForwardFunctionInput`, or `CopyAtEntry`. Function-input normalization forwards
+host inputs into compute bodies before entry-copy materialization.
+Single-core lowering forwards used arithmetic constants. Batch lowering copies
+remaining inputs at body entry, including constants. Lowering and costing
+consume the same decisions. The query has constant time and space per
+input and does not expand lanes or loops. Abstract target work extraction uses
+the same query. Subsequent canonicalization can remove uses.
+`getReusableOutputTensor` shares read-only destination selection with vector
+lowering. It identifies a tensor operand or requires fresh storage. It does not
+prove a physical alias, assign an address, or replace one-shot bufferization.
+The result is valid only for the current SSA graph. Changes to uses, operation
+order, loop yields, or operands require recomputation. Lowering consumes this
+decision immediately; it does not cache values across rewrites. Current PIM
+bufferization consumes the explicit destination ties introduced by target
+lowering. Output-copy forwarding also consumes the resulting allocation,
+subview, copy, and dominance facts. An early destination choice alone cannot
+describe those physical aliases or the final storage lifetimes.
+Logical storage identity and physical address equality are different facts.
+Local-memory planning can assign the same address to distinct allocations whose
+lifetimes do not overlap. Scalar register setup therefore needs placement and
+instruction-order information in addition to logical alias relationships.
+Abstract cost estimates need not reconstruct these addresses.
+
+This input plan does not count physical constant loads. A forwarded host
+constant can need a new local buffer at each use. Bufferization, host folding,
+alias analysis, and memory normalization determine the resulting requests.
+`isZeroBitPatternSplat` shares constant-content classification between graph
+accounting and code generation. PIM replaces eligible positive-zero and integer-zero
+loads with local fills. Negative floating zero retains its distinct bit pattern.
+Constant content is candidate-independent; input placement and buffer reuse
+depend on the realized candidate. Production uses these shared decisions when
+extracting Spatial execution events for the queue estimate.
+
 Execution transpose costs share `getTransposeRun` with lowering: round memory
 reads/writes per run and add vector execution when source stride is not one.
 The [Pimsim vector unit](../../backend-simulators/pim/pimsim-nn/src/core/component/VectorUnit.cpp)
@@ -118,3 +171,89 @@ scheduling overview. Cached PEFT center distances avoid a topology scan per task
 projection and priority analyses share/cache work rather than revisiting every
 template body per chunk. Ready-transfer signature searches remain another
 potential compile-time hotspot.
+
+### Spatial execution costs
+
+`SchedulingTarget::estimateRealizedScheduleCost` is a read-only query on realized Spatial IR.
+The PIM adapter extracts compact ordered execution events without constructing PIM operations.
+It uses physical core assignments, communication, input-materialization decisions, and shared copy geometry.
+No physical buffer addresses are required.
+The shared engine models controller arbitration, source FIFOs, synchronization, and repeated generations.
+Both arbitration policies are sensitivity checks, not guaranteed bounds.
+The engine returns typed intervals and recurrence evidence before diagnostic serialization.
+The target adapter adds static lowering support. Spatial owns the selection policy margin.
+JSON fields are report output and do not control availability or eligibility.
+Typed evaluation completes before reporting. Serialization never runs queue analysis.
+Only optional diagnostics construct fingerprints, traces, and per-core resource reports.
+
+Normal compilation extracts costs for multiple candidates and lowers only the selected schedule.
+A single candidate bypasses the cost query entirely.
+Candidate summaries distinguish available timing, static lowering support, and proved modeled recurrence.
+Unknown support remains explicit. All candidates must satisfy these checks before comparison.
+`Unsupported` identifies a known static violation, including invalid or repeated physical-core assignments.
+`Unknown` identifies missing evidence or an unmodeled form, rather than a proven backend rejection.
+`Supported` covers checked static forms and does not prove final allocation success.
+A finite interval alone does not establish eligibility.
+
+Preflight does not repeat bufferization or allocation.
+The backend owns final legality and signed 32-bit local-memory address validation.
+Resource failures marked by that owner permit an explicit retry from the original checkpoint.
+Unclassified failures stop compilation. Every attempted schedule and cause appears in the selection report.
+
+### Complete-state recurrence
+
+Queue analysis checks translated states at one fixed core's body entry.
+Snapshots contain completion counts relative to core entry, ready-input counts, and busy state for every event.
+Run-length encoding keeps these records compact.
+Snapshots also contain pending events in arbitration order, remaining FIFO tokens, controller availability, and the tie policy.
+One pending firing per event makes node IDs sufficient to resolve simultaneous-event ties.
+The graph and target parameters remain fixed within each query.
+Time offsets use checked unsigned differences.
+Equal states require equal positive generation progress on every core.
+This proves recurrence for the deterministic abstract model, not physical execution-time accuracy.
+Reporting counters and analysis budgets are not hardware state.
+
+Token initialization distances and graph edges remain immutable within a query.
+Consumption clears a drained queue and resets its head immediately.
+Drained and never-populated queues therefore have the same readiness state.
+Consumed prefixes, capacities, and compaction indices cannot affect future timing or FIFO contents.
+An idle controller's past completion cannot delay future arrivals.
+These normalizations require causal, monotonic transitions, which the proof checks.
+
+Proof construction uses at most 256 generations and 16 MiB of snapshot storage.
+Each checkpoint scans events, dependencies, and remaining tokens, then orders a copy of the pending frontier.
+Exact comparisons use bounded history; hashes only filter comparisons.
+Unproved recurrence remains explicit and cannot guide multi-candidate selection.
+When recurrence is proved, its interval is authoritative for that arbitration policy and its report.
+Proof-mode reports retain interval-window results under `legacy_interval_window`.
+Normal costing stops once recurrence is proved. Detailed diagnostics can continue to collect interval-window evidence.
+A legacy event or generation limit cannot override a later complete-state proof.
+Budget limits, lack of ready events, and unproved recurrence remain separate evidence.
+Internal diagnostic queries can cap interval-window work without reducing the recurrence proof budget.
+The standalone instruction diagnostic keeps its interval-window behavior when recurrence is not requested.
+
+### Approximation and diagnostics
+
+Scalar setup, copy forwarding, local reuse, and host-slice folding can change request readiness.
+These effects remain prediction limitations. Physical address reuse itself adds no execution work.
+Direct returns use the same return-operand test as lowering and preserve output multiplicity.
+Captured weights used by vector operations require host loads.
+Publication-only slices of compact results use `CopyAccessPlan` runs without an intermediate copy.
+Matrix writeback requires complete aligned array groups.
+Partial output groups, encoded layouts, unavailable geometry, and indirect output collection produce unavailable costs.
+
+`--pim-periodic-diagnostics` adds resource summaries and ordered-request fingerprints.
+Normal compilation creates no fingerprints, detailed traces, or sensitivity runs.
+Optional local-copy sensitivity removes modeled copy work without changing generated code.
+It does not describe a legal transformed program or an interval bound.
+The standalone instruction diagnostic remains available for offline timing validation.
+
+Checked arithmetic rejects unrepresentable sizes, loop bounds, repeated work, and service durations.
+Work-only repeats remain compact. Immutable summaries are cached within a query.
+Ordered memory and communication occurrences expand within the event budget.
+For `P` compact records, `R` expanded events, and `D` dependencies, construction costs `O(P+R+D)` time.
+With `B` processed events and `T` token propagations, queue evaluation costs `O(B log R+T)` time.
+Storage costs `O(P+R+G D)` for bounded generation count `G`, plus bounded recurrence history.
+Reports separate extraction, expansion, and queue-analysis times.
+Fingerprints compare memory and blocking-operation order, without addresses or work between requests.
+Equal fingerprints therefore do not prove equal request readiness or timing.