Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
Current scaffold policy:
- current CLI package version is `4.0.4`
- minimum supported Rust version is `1.95`, matching the current SolverForge runtime crates
- generated projects currently target `solverforge 0.26.1`; the default web shell additionally targets `solverforge-ui 0.9.1` and `solverforge-maps 2.3.3`; the MCP shell additionally targets `rmcp 3.9.0`
- generated projects currently target `solverforge 0.31.1`; the default web shell additionally targets `solverforge-ui 0.9.1` and `solverforge-maps 2.3.3`; the MCP shell additionally targets `rmcp 3.9.0`
- `solverforge new <name>` is the only public scaffold path and produces a neutral app shell
- `--shell web|api|cli|mcp` is the current public shell selector; `web` is the default, `api` omits frontend assets, `cli` omits Axum/SSE routes and frontend assets, and `mcp` delivers the solver as an MCP server over stdio and stateless Streamable HTTP
- API/CLI/MCP app specs omit `ui_source`, and subsequent CLI mutations must preserve that absence
Expand Down Expand Up @@ -80,7 +80,7 @@ Current end-to-end scenario policy:
- the scalar-only runtime scenario covers full compact telemetry, bounded candidate detail, and qualified trace provenance
- the MCP scenario models a mixed scalar-plus-list problem, generates the sample data, and drives both stdio and stateless Streamable HTTP through the real `rmcp` client: annotated tool surface, task-backed solve to a terminal snapshot with scalar assignment and complete list placement, retained lifecycle via a legacy client, and byte-level stdio stdout purity during a solve, all with parallel evaluation enabled on a pinned Rayon pool

SolverForge `0.26.1` uses list variables as the sequence and route model. The
SolverForge `0.31.1` uses list variables as the sequence and route model. The
generated-app runtime and browser scenarios must continue to start and observe
a real mixed scalar/list solve.

Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Required Rust version: `1.95` or later.

New projects currently target these crate versions:

- `solverforge 0.26.1`
- `solverforge 0.31.1`
- `solverforge-ui 0.9.1` for the default web shell
- `solverforge-maps 2.3.3` for the default web shell
- `rmcp 3.9.0` for the MCP shell
Expand Down Expand Up @@ -199,7 +199,7 @@ Core commands:
- `generate score` and `generate solution --score` accept `HardSoftScore`,
`HardSoftDecimalScore`, `HardMediumSoftScore`, and `SoftScore`.
`BendableScore` is rejected because `#[planning_solution]` requires a
`ParseableScore`, which SolverForge `0.26.1` does not implement for it.
`ParseableScore`, which SolverForge `0.31.1` does not implement for it.
- `solverforge generate scalar-group|conflict-repair` wires opt-in model
resources by exact ID.
- `solverforge destroy fact|entity|variable|constraint|solution|scalar-group|conflict-repair`
Expand Down Expand Up @@ -325,9 +325,12 @@ then from `~/.solverforgerc`. Recognized preferences are intentionally narrow:
Generated web/API apps expose every compact `SolverTelemetry` aggregate,
including applied/not-doable/rejected moves, hard-score direction counts,
construction counters, one record per started phase (`phases`, in execution
order), per-selector and per-move breakdowns, and the bounded applied-move
trace. The six `conflictRepair*` counters are run-level totals; selector
records do not carry them because SolverForge `0.26.1` `SelectorTelemetry`
order), per-selector and per-move breakdowns, the bounded applied-move
trace, and `resolvedPhasePlan`: the policy the solve actually ran (every phase,
the construction chosen for each default stage, the move families and their
limits, acceptor and forager), `null` until the solve ends. The six
`conflictRepair*` counters are run-level totals; selector
records do not carry them because SolverForge `0.31.1` `SelectorTelemetry`
has no such fields. These fields are carried consistently by status,
snapshot, and typed SSE payloads. Constraint analysis reports each
constraint's `name`, `weightMultiplier` (the bound constraint weight, a
Expand Down Expand Up @@ -460,7 +463,7 @@ Current scenario coverage:
byte-level stdio check that the transport channel stays pure JSON-RPC; every
MCP phase runs with parallel evaluation enabled

SolverForge `0.26.1` supports mixed scalar/list construction, canonical mixed
SolverForge `0.31.1` supports mixed scalar/list construction, canonical mixed
local-search defaults, and list-based sequence modeling. The CLI suite proves
the mixed path in both runtime and browser pipelines; the scalar-only scenario keeps the deeper
pause/resume, analysis, reconnect, and qualified-trace checks.
Expand Down
66 changes: 51 additions & 15 deletions UPSTREAM_FEATURE_AUDIT.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# SolverForge Upstream Feature Audit

Audit date: 2026-11-11
Audit date: 2026-11-17

This audit compares the current `solverforge-cli` scaffold surface against the
live SolverForge upstream checkout at `/srv/lab/dev/solverforge/solverforge`
and the crates.io release state. Generated projects now target the published
SolverForge `0.26.1` release. Registry-only generated-app validation is the
SolverForge `0.31.1` release. Registry-only generated-app validation is the
release gate; `SF_USE_LOCAL_PATCHES=1` remains reserved for explicit future
prerelease checks against sibling checkouts.

Expand All @@ -15,13 +15,13 @@ without turning the neutral scaffold into a domain-specific demo.

## Source Evidence

- Published gate: `cargo info solverforge@0.26.1` resolves the published crate
on 2026-11-10, with Rust `1.95` and the `serde`, `console`, and
- Published gate: `cargo info solverforge@0.31.1` resolves the published crate
on 2026-11-17, with Rust `1.95` and the `serde`, `console`, and
`verbose-logging` features; `verbose-logging` is
`[console, solverforge-console/verbose-logging]`, so the web, API, and CLI
shells keep all three and the MCP shell enables only `serde`.
- Upstream local checkout: the workspace and inter-crate dependency baseline is
`0.26.1`, with `v0.26.1` (`f3b41788`) at the checked-out release commit. The `0.19.0`
`0.31.1`, with `v0.31.1` (`ff945a3b`) at the checked-out release commit. The `0.19.0`
release made list variables the sole sequence and route model; the published
`0.19.1` through `0.19.7` patch line carries the subsequent solver fixes.
- Upstream `0.19.7..0.22.0` release surface: `0.19.8` through `0.19.14` are
Expand Down Expand Up @@ -201,6 +201,38 @@ without turning the neutral scaffold into a domain-specific demo.
permutation. No public API or configuration change; generated apps pick it
up through the version pin, and their late-acceptance searches accept the
worsening moves the algorithm is meant to accept.
- Upstream `0.26.1..0.27.0` release surface: the CVRP crate reads leg
distances through a pluggable `RouteMetric` (breaking for `ProblemData` and
`VrpSolution`), Clarke-Wright savings are bounded to nearest neighbours, and
Clarke-Wright owner admission and the scalar swap cursor open faster.
Generated apps use neither the CVRP crate nor its types, so the scaffold
needs no template change.
- Upstream `0.27.0..0.28.0` release surface: constraint analysis describes
matched entities by type name and `Debug` text without copying them, grouped
and complemented constraints report their matches, and final telemetry
carries `resolved_phase_plan`, the policy the solve actually ran. Generated
apps never construct `EntityRef`; the status, snapshot, SSE and telemetry
payloads project `resolvedPhasePlan`, `null` until the solve ends.
- Upstream `0.28.0..0.29.0` release surface: constraint matches report each
entity's planning id. Generated analysis reports per-constraint totals and
needs no template change.
- Upstream `0.29.0..0.30.0` release surface: cascading list shadows propagate
across list owners, `ComplementedConstraintStream` gains a filter type
parameter, and uni grouped complements apply the stream filter. Generated
code names none of these types.
- Upstream `0.30.0..0.30.1` release surface: a cascading list arrival is
retracted before its structure shadows change. No public API change.
- Upstream `0.30.1..0.31.0` release surface: list element groups move,
construct, ruin and recreate as units (`element_group_fn`, the
`list_group_change_move_selector` and `list_group_swap_move_selector`, and
`max_member_distance`/`max_group_owners` on ruin and construction), and
joint groups of cascading elements compute together (`cascading_peers`).
Opt-in model surfaces; the neutral scaffold declares none of them.
- Upstream `0.31.0..0.31.1` release surface: scoring rescores only the
list-shadow rows a cascading move changes, and grouped ruins recreate in one
pass with shared trial prefixes, through a new defaulted
`PlanningSolution::list_structure_unchanged` hook the macros generate. No
configuration change; generated apps pick it up through the version pin.
- Upstream `0.24.0..0.25.0` release surface (source-carrying, breaking):
configuration semantics made literal and validated, partitioned search run by
the framework, the `auto` parallel-evaluation policy, and construction and
Expand Down Expand Up @@ -234,13 +266,13 @@ without turning the neutral scaffold into a domain-specific demo.
`scalar_groups`, `ScalarGroup::assignment`, grouped scalar construction with
`group_name`, `construction_obligation = "assign_when_candidate_exists"`, and
`grouped_scalar_move_selector`.
- CLI coverage today: the scaffold targets `solverforge 0.26.1`, exposes the
- CLI coverage today: the scaffold targets `solverforge 0.31.1`, exposes the
`web`, `api`, `cli`, and `mcp` shells, and includes the retained
`SolverManager` lifecycle, typed SSE, snapshots, analysis,
pause/resume/cancel/delete, generated `solverforge.app.toml`, scalar/list
variable generation, complete executable scalar/list metadata projection,
countable scalar ranges, full compact telemetry (including per-phase records
and speculative counts), bounded candidate-detail retrieval, qualified trace
countable scalar ranges, full compact telemetry (including per-phase records,
speculative counts and the resolved phase plan), bounded candidate-detail retrieval, qualified trace
jobs, validated opt-in parallel evaluation, and a neutral `solver.toml` that
defers to the runtime default pipeline.
- Neutral solve gate: the neutral runtime pipeline solves the untouched
Expand Down Expand Up @@ -358,7 +390,7 @@ without turning the neutral scaffold into a domain-specific demo.

## Recommended Follow-Up Implementation Slice

The current starter-safe 0.26.1 surface is implemented, apart from the
The current starter-safe 0.31.1 surface is implemented, apart from the
unknown-key `solver.toml` validation gap recorded in the matrix. The next high-value slice
is domain-specific documentation and executable examples, not more neutral
scaffold defaults.
Expand All @@ -375,17 +407,21 @@ scaffold defaults.

## Implementation Status

- Release state: `solverforge 0.26.1` is published on crates.io and matches
- Release state: `solverforge 0.31.1` is published on crates.io and matches
the live upstream release checkout and this generated target. The
`0.19.8..0.26.1` line is source-carrying (grouped-scalar search/perf work,
`0.19.8..0.31.1` line is source-carrying (grouped-scalar search/perf work,
the `0.20.3` search-order hooks, the `0.21.0` scoring `group_by` joins, the
`0.21.2` selector-subgraph edge rebase fix, the `0.21.3` precedence route
delta fix, the `0.22.0` grouped-stream accumulator-kernel rework, the
`0.23.0` parallel local-search evaluation, the `0.24.0` constraint weights
and API cleanup, the `0.25.0` configuration audit, framework partitioned
search and `auto` evaluation policy, the `0.25.1` bounded nearby list
candidate buffer, the `0.26.0` compact generic type names, and the `0.26.1`
late-acceptance history fix), and the published crate, the `v0.26.1` tag,
candidate buffer, the `0.26.0` compact generic type names, the `0.26.1`
late-acceptance history fix, the `0.27.0` route metric, the `0.28.0` resolved
phase plan and match descriptions, the `0.29.0` planning ids in matches, the
`0.30.0` cross-owner cascading shadows, the `0.31.0` list element groups and
joint cascading groups, and the `0.31.1` list-shadow row rescoring), and the
published crate, the `v0.31.1` tag,
and this
generated target are the same code. Registry-only validation is therefore authoritative.
`SF_USE_LOCAL_PATCHES=1` is only for an explicit future coordinated prerelease
Expand Down Expand Up @@ -486,7 +522,7 @@ scaffold defaults.
help says: unary is `for_each` + `filter` + `penalize` for both hardness
levels, reward is `for_each` + `filter` + `reward`, and pair filters out
unassigned entities before a `joiner::equal` self-join (each unordered pair
once; `0.26.1` has no `for_each_unique_pair`) and selects conflicts with a
once; `0.31.1` has no `for_each_unique_pair`) and selects conflicts with a
filter.
- Changed: the neutral `solver.toml` declares no `[[phases]]` and defers to the
runtime's model-aware default pipeline; its explicit phases remain as a
Expand Down Expand Up @@ -516,7 +552,7 @@ Any implementation from this audit should pass:
- focused parser/generator/app-spec tests for the new metadata;
- scaffold contract tests proving fresh generated projects include only the
opt-in scalar-group surface requested by the user;
- generated app `cargo check` against the published `0.26.1` registry target;
- generated app `cargo check` against the published `0.31.1` registry target;
- runtime pipeline coverage only if the new command claims actual solving
behavior;
- `SF_USE_LOCAL_PATCHES=1` only for an explicit future sibling-checkout
Expand Down
12 changes: 7 additions & 5 deletions WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Required Rust version: `1.95` or later.

Current generated projects target:

- `solverforge 0.26.1`
- `solverforge 0.31.1`
- `solverforge-ui 0.9.1` for the web shell
- `solverforge-maps 2.3.3` for the web shell
- `rmcp 3.9.0` for the MCP shell
Expand Down Expand Up @@ -279,8 +279,10 @@ Generated apps should behave like production references:
snapshot revision
- status, snapshot, and SSE payloads expose every compact SolverForge telemetry
aggregate and phase/selector/move/applied-move breakdown; the six
`conflictRepair*` counters are run-level only, because SolverForge `0.26.1`
`conflictRepair*` counters are run-level only, because SolverForge `0.31.1`
`SelectorTelemetry` does not carry them
- telemetry carries `resolvedPhasePlan`, the phase plan the solve resolved and
ran, once the solve ends (`null` before that)
- constraint analysis carries `name`, `weightMultiplier` (the bound constraint
weight), `score`, and `matchCount` per constraint
- `GET /jobs/{id}/telemetry` exposes the atomically paired retained status and
Expand Down Expand Up @@ -333,7 +335,7 @@ warning, not an error, so the user can define it afterward.
`generate score` and `generate solution --score` accept `HardSoftScore`,
`HardSoftDecimalScore`, `HardMediumSoftScore`, and `SoftScore`.
`BendableScore` is rejected: `#[planning_solution]` requires a
`ParseableScore`, and SolverForge `0.26.1` does not implement it for
`ParseableScore`, and SolverForge `0.31.1` does not implement it for
`BendableScore`. Score rewrites change only the bare type name inside `use`
items.

Expand All @@ -348,7 +350,7 @@ functions that panic with the function name and the
- `--reward`: `for_each` + `filter(reward_condition)` + `reward`
- `--pair`: `for_each` + `filter` (variable assigned) + `join(joiner::equal(key))`
self-join, which yields each unordered pair once, + `filter(pair_condition)`
+ `penalize`; SolverForge `0.26.1` has no `for_each_unique_pair`
+ `penalize`; SolverForge `0.31.1` has no `for_each_unique_pair`

Weight helpers return the unit penalty or reward. A solve that reaches a
placeholder fails: the job ends `FAILED` and the panic names the file and
Expand Down Expand Up @@ -446,7 +448,7 @@ Current scenario policy:
legacy client, and byte-level stdio stdout purity during a solve, all with
parallel evaluation enabled

SolverForge `0.26.1` uses list variables for ordered sequences and routes. Both
SolverForge `0.31.1` uses list variables for ordered sequences and routes. Both
generated-app end-to-end suites start and observe the real mixed scalar/list
path.

Expand Down
48 changes: 15 additions & 33 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"install:e2e": "playwright install chromium"
},
"devDependencies": {
"@playwright/test": "^1.59.1"
"@playwright/test": "^1.65.1"
},
"version": "4.0.4"
}
Loading
Loading