Add fixed-topology portal-layer refinement

[AnasSarkiz]

Summary

• Add explicit physical portal-group identities, compact group/layer lookup tables, and portal-assignment locks.
• Add a deterministic fixed-topology dynamic-programming refinement pass that changes only portal layers while preserving each route's ordered region sequence.
• Validate candidate moves transactionally against exact touched-region caches; reject port conflicts, locked assignments, cost/intersection regressions, and candidates without strictly lower predicted via demand and entry/exit layer changes.
• Run refinement as the third section-pipeline stage and expose before/after demand, acceptance, timing, and separate rejection-reason diagnostics.

Safety properties

• No route forking, topology changes, region-sequence changes, rerouting, A* reordering, or final-cleanup workaround.
• Deterministic queueing and tie-breaking.
• No-op refinements retain the original assignment order.

Current validation

• bun test tests/solver/fixed-topology-portal-layer-refinement.test.ts: 2 passed, 0 failed, 21 expectations
• bun run typecheck
• git diff --check

Integration

The companion tscircuit-autorouter draft PR pins this exact commit (9cc3a682a8abf8ca6fd20144140716273f2f11ae).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiny-hypergraph	Ready	Preview	Aug 6, 2026 12:01am

[tscircuitbot]

Benchmark This PR

Run benchmarks by commenting on this PR:

/benchmark [benchmark.sh args...]
/benchmark --dataset <hg07|srj18> --limit <n> --solver <core|poly> --families <default|default+deep|all> --concurrency <n|auto>

Everything after /benchmark is forwarded directly to ./benchmark.sh.
The result comment shows the matching dataset from the latest stored main-branch benchmark artifact beside the PR run; main is not rerun for each PR benchmark request.

Examples:

• /benchmark -> hg07, all samples, core solver
• /benchmark --dataset srj18 --limit 20 -> first 20 srj18 samples
• /benchmark --dataset srj18 --concurrency auto -> srj18 samples with runner CPU-count concurrency
• /benchmark --sample sample002 -> one hg07 sample
• /benchmark --limit 20 --solver poly -> first 20 hg07 samples with the poly solver
• /benchmark --limit 40 --families default+deep -> first 40 hg07 samples with deeper candidate families

Any PR whose title contains [BENCHMARK TEST] will automatically run the benchmark workflow on PR updates.

[AnasSarkiz]

/benchmark --dataset srj18

[tscircuitbot]

Tiny Hypergraph Benchmark Results

Run	Dataset	Solver	Families	Success	P50	P95
Main	srj18	core	default	31.3%	1.927s	7.419s
PR	srj18	core	default	31.3%	2.007s	8.277s

Main Branch Details

Metric	Value
Dataset	srj18
Solver	core
Families	default
Samples	16
Success rate	31.3%
Improved rate	60.0%
Zero final max region cost rate	0.0%
Avg baseline max region cost	0.565
Avg final max region cost	0.499
Avg max region delta	0.066
Avg candidate count	5.200
Avg duration	2.332s
P50 duration	1.927s
P95 duration	7.419s

Sample	Status	Baseline	Final	Delta	Attempts	Duration	Error
sample001	success	0.670	0.579	0.090	4	2.086s
sample002	success	0.391	0.358	0.033	6	1.461s
sample003	success	0.429	0.429	0.000	5	0.783s
sample004	failed	n/a	n/a	n/a	0	0.026s	Error: Static reachability precheck failed: 2 route(s) have no legal path under the current reservation and start-reg...
sample005	success	0.423	0.423	0.000	7	1.021s
sample006	failed	n/a	n/a	n/a	0	0.252s	Error: Static reachability precheck failed: 9 route(s) have no legal path under the current reservation and start-reg...
sample007	failed	n/a	n/a	n/a	0	7.419s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample008	failed	n/a	n/a	n/a	0	1.927s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample009	failed	n/a	n/a	n/a	0	0.308s	Error: Static reachability precheck failed: 2 route(s) have no legal path under the current reservation and start-reg...
sample010	failed	n/a	n/a	n/a	0	3.173s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample011	failed	n/a	n/a	n/a	0	4.025s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample012	failed	n/a	n/a	n/a	0	6.152s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample013	failed	n/a	n/a	n/a	0	0.314s	Error: Static reachability precheck failed: 11 route(s) have no legal path under the current reservation and start-re...
sample014	failed	n/a	n/a	n/a	0	2.588s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample015	failed	n/a	n/a	n/a	0	3.517s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample016	success	0.912	0.707	0.205	4	2.258s

PR Details

Metric	Value
Dataset	srj18
Solver	core
Families	default
Samples	16
Success rate	31.3%
Improved rate	60.0%
Zero final max region cost rate	0.0%
Avg baseline max region cost	0.565
Avg final max region cost	0.499
Avg max region delta	0.066
Avg candidate count	5.200
Avg duration	2.589s
P50 duration	2.007s
P95 duration	8.277s

Sample	Status	Baseline	Final	Delta	Attempts	Duration	Error
sample001	success	0.670	0.579	0.090	4	2.651s
sample002	success	0.391	0.358	0.033	6	1.666s
sample003	success	0.429	0.429	0.000	5	1.059s
sample004	failed	n/a	n/a	n/a	0	0.036s	Error: Static reachability precheck failed: 2 route(s) have no legal path under the current reservation and start-reg...
sample005	success	0.423	0.423	0.000	7	1.420s
sample006	failed	n/a	n/a	n/a	0	0.310s	Error: Static reachability precheck failed: 9 route(s) have no legal path under the current reservation and start-reg...
sample007	failed	n/a	n/a	n/a	0	8.277s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample008	failed	n/a	n/a	n/a	0	2.007s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample009	failed	n/a	n/a	n/a	0	0.334s	Error: Static reachability precheck failed: 2 route(s) have no legal path under the current reservation and start-reg...
sample010	failed	n/a	n/a	n/a	0	3.503s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample011	failed	n/a	n/a	n/a	0	4.403s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample012	failed	n/a	n/a	n/a	0	6.437s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample013	failed	n/a	n/a	n/a	0	0.311s	Error: Static reachability precheck failed: 11 route(s) have no legal path under the current reservation and start-re...
sample014	failed	n/a	n/a	n/a	0	2.779s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample015	failed	n/a	n/a	n/a	0	3.932s	Error: TinyHyperGraphSectionPipelineSolver ran out of iterations
sample016	success	0.912	0.707	0.205	4	2.298s

Workflow: View run
Artifact: https://github.com/tscircuit/tiny-hypergraph/actions/runs/30997278674