Skip to content

refactor(R1): retire eleven roots and bind Apps inspection #459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dong1017 wants to merge 2 commits into
base: main
Choose a base branch
from
+2,106 −868
Open

refactor(R1): retire eleven roots and bind Apps inspection #459

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e406ba6
refactor: retire eleven root entries and bind Apps inspection
Dong1017 Nov 15, 2026
225d578
fix(R1): align seam guard and regenerate skill coverage
Dong1017 Nov 15, 2026
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
3 changes: 0 additions & 3 deletions .github/knowledge-model-policy.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,6 @@
"docs/knowledge-base.md",
"docs/knowledge-operations.md",
"docs/knowledge-store.md",
"src/inferrsi/catalog.py",
"src/inferrsi/skill_catalog.py",
"src/inferrsi/knowledge_operations.py",
"src/inferrsi/knowledge/catalog.py",
"src/inferrsi/knowledge/skill_catalog.py",
"src/inferrsi/knowledge/knowledge_operations.py"
Expand Down
98 changes: 98 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,100 @@

### Changed

- Eleven legacy root modules are removed (Refs #412, R1). Their implementations
already lived in `inferrsi.knowledge` and `inferrsi.apps`. The root files are
deleted in the change that moves their last consumers, with no forwarding
shells, `sys.modules` aliases or import fallbacks:
- `inferrsi._skill_selection` → `inferrsi.knowledge._skill_selection`
- `inferrsi._source_snapshot` → `inferrsi.knowledge._source_snapshot`
- `inferrsi.catalog` → `inferrsi.knowledge.catalog`, and
`inferrsi.resources.repository_packs` for `REPO_TYPES` and `repository_pack`
- `inferrsi.knowledge_operations` → `inferrsi.knowledge.knowledge_operations`
- `inferrsi.knowledge_store` → `inferrsi.knowledge.knowledge_store`
- `inferrsi.research` → `inferrsi.knowledge.research`
- `inferrsi.skill_catalog` → `inferrsi.knowledge.skill_catalog`
- `inferrsi.evaluation` → `inferrsi.apps.legacy.evaluation`
- `inferrsi.execution` → `inferrsi.apps.legacy.run` for `run_experiment` and
for `execute_trial`, the former `_execute`; `inferrsi.infra.targets` for
`repository_identity`; `inferrsi.harness.local_process` for `_WindowsJob`
and `_stop_tree`
- `inferrsi.reporting` → `inferrsi.apps.legacy.reporting`
- `inferrsi.inspection` → `inferrsi.apps.inspection`
- Importing any of the eleven old module paths now raises
`ModuleNotFoundError`, in external Python code as well as in this
repository. A pickle that names a class or function by one of those paths
no longer loads. Objects defined in the canonical modules have named them
in new pickles since they moved there. `inferrsi.execution.run_experiment`
and `inferrsi.inspection.inspect_environment` were defined in the root
files themselves, so every existing pickle of either function reference is
affected. Such pickles need explicit migration or the prior release. `src/`
has no pickle usage, and frozen evidence is not rewritten: a historical
campaign replays with its original source-pinned bundle or wheel.
- No CLI command, flag, output or exit code changes. Root `cli.py` and
`arguments.py` stay in place until A1 (#408); this change edits only their
imports. `arguments.REPO_TYPES` is still the one
`inferrsi.resources.repository_packs.REPO_TYPES` tuple object, now imported
from that module directly instead of through root `catalog`.
- Root `inspection.py` was not an alias: it bound the Infra facts API to the
host. `inferrsi.apps.inspection.inspect_environment` keeps its signature and
result and holds that binding. `_command` is `infra.commands.probe_command`
and `repository_identity` is `infra.targets.repository_identity`, both read
from the module on each call. Test injection points move with it, from
`inferrsi.inspection._command` and `inferrsi.execution.repository_identity`
to those two names on `inferrsi.apps.inspection`. `infra/inspection.py` is
unchanged and imports no Apps module, and an inspection no longer loads the
old-run composition or Benchmark to obtain the snapshot.
- `inferrsi.apps.legacy.run.run_experiment(spec, environment)` is the
two-argument entry that root `execution.run_experiment` was. Its `execute`
and `snapshot` keyword defaults are now `None` and resolve to the module's
`execute_trial` and `repository_identity` when the run starts. A test that
replaced `inferrsi.execution._execute` now replaces
`inferrsi.apps.legacy.run.execute_trial`. An explicitly passed port still
wins.
- `docs/legacy-knowledge-manifest.json` ends at zero `compatibility_pairs`,
from nine. Eight were edges of the seven deleted Knowledge shells; root
`catalog` had two. The nine records and root `catalog`'s two routes are
kept, unchanged, under the manifest's last `revision_history` entry. The
ninth pair, `infra.inspection` → `inferrsi.resources.repository_packs`, is a
live import that no deletion removes. It is now a permanent exact rule
outside the allowlist: `technical_leaf.permanent_importers` in the manifest
and `LEAF_IMPORTERS` in `tests/_gate_policy_support.py`. That one module
binds only `repository_pack`, with one plain module-level `from` import.
Any other importer, name, alias, import of the leaf as a module object,
nested import, `sys.modules` use or dynamic import fails, and an
`inferrsi.resources.` prefix allows nothing. The leaf's bytes, locked
SHA-256, allowed imports, two symbols, top-level shape and import-free
parent initializer are unchanged.
- One temporary entry is declared beside that rule and is not part of it.
Root `arguments.py` reads `REPO_TYPES` from the leaf
(`technical_leaf.temporary_importers`, `TEMPORARY_LEAF_IMPORTERS`), and it
joins `cli.py` in the gate's exact `APPLICATION_ENTRIES` because it now
names `inferrsi.knowledge` itself. Both end in A1 (#408), which removes root
`arguments.py`. Until then the report carries a
`temporary leaf importers: 1` blocker.
- The gate no longer registers `LEGACY_RUN_FORWARDERS`. The eleven names are
`RETIRED_ROOT_MODULES`: a file that returns under one is a violation, and
no Knowledge, Harness, Benchmark or Apps closure may reach one.
- `first_wave_report()` on this tree has no violation, and the `allowlist`
and `legacy run forwarders` blockers are gone. `isolation_complete` and
`new_core_closure_isolated` are still false. Three blockers remain: the
temporary entry above, twelve `harness` → `inferrsi.infra` hits in six
Harness modules (R2), and five declared runtime resource loaders (R3).
- The permanent importer rule, the temporary entry and this manifest revision
require formal architecture review. Passing tests do not supply it, and the
implementer does not self-approve them.
- `.github/knowledge-model-policy.json` drops the three deleted shell paths
(`src/inferrsi/catalog.py`, `src/inferrsi/skill_catalog.py` and
`src/inferrsi/knowledge_operations.py`) from `protected_paths`. The three
`src/inferrsi/knowledge/` implementations stay protected, and no other
policy field changes.
- The exact root inventory in `tests/test_package_root_inventory.py` shrinks
from 21 to 10 tracked files: `__init__.py`, `__main__.py`,
`_mindie_read_worker.py`, `arguments.py`, `benchmark_operations.py`,
`cli.py`, `mindie_context.py`, `mindie_mcp.py`, `mindie_project.py` and
`summary_chart.py`. The final two-file root waits for the A1/A2 (#408) and
M1 (#452) moves. The build-generated `_version.py` stays wheel metadata, not
a tracked root file.
- Repository-pack access and the evidence path rules leave the package root
(Refs #451). Root `_repo_pack_data.py` and `evidence_paths.py` are removed in the
same change, with no forwarding shells or `sys.modules` aliases:
Expand Down Expand Up @@ -42,6 +136,9 @@
`summary_chart.py`. It is an exact set that each later removal shrinks, not
the final two-file root. The build-generated `_version.py` is wheel metadata,
not a tracked root file.
- The #412 entry above supersedes three statements in this entry: root
`catalog` is no longer a `REPO_TYPES` consumer, the nine compatibility pairs
are retired, and the root inventory is 10 files.
- Shared technical contracts now live in `inferrsi.contracts` (Refs #451). The four
root files `_json_v1.py`, `runspec.py`, `claim.py`, and `contracts.py` are removed
in the same change. Canonical implementations are `contracts/json_v1.py`,
Expand Down Expand Up @@ -73,6 +170,7 @@
- The old `run` chain is split by owner. The CLI, its exit codes 0/1/2 and the
`evaluation.json` bytes are unchanged. Root `inferrsi.evaluation`,
`inferrsi.execution` and `inferrsi.reporting` keep working as forwarders.
That held until the #412 entry above removed all three.
- Moved import paths, with no forwarder left under `inferrsi.harness`:
- `inferrsi.harness.evaluation` → `inferrsi.apps.legacy.evaluation` (`evaluate` with a
`RunSpec`) and `inferrsi.benchmark.legacy_run_v0` (the gates).
Expand Down
59 changes: 43 additions & 16 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,21 @@ Dependencies flow from entrypoints to Harness, from scenarios to Model/Infra,
and from Model to Infra utilities. Infra does not import Model or Harness. None
of these shared packages imports a campaign from `examples/`.

Environment inspection follows that direction. `infra/inspection.py` is the
facts API: it takes the command probe and the repository snapshot as ports.
`apps/inspection.py` binds those ports to this host with
`infra.commands.probe_command` and `infra.targets.repository_identity`, and the
CLI calls that composition. Infra reaches no Apps, Knowledge, Harness or
Benchmark module and is not a fourth core. `infra/inspection.py` reads a
repository-pack description through the neutral `resources.repository_packs`
leaf, under the one permanent importer rule in
[module-layout.md](module-layout.md#permanent-neutral-leaf-importer-rule-proposed).

The implemented table above is not the target four-module layout. The
suggested rule, including what the import gate does not prove, is
[module-layout.md](module-layout.md). That page does not move code. It also
lists the Proposed first-wave compatibility exceptions recorded in
records the first-wave compatibility pairs that #412 R1 retired and the
permanent neutral-leaf importer rule, both held in
[legacy-knowledge-manifest.json](legacy-knowledge-manifest.json).

The caller still prepares the benchmark runtime and baseline/candidate source
Expand Down Expand Up @@ -165,6 +176,7 @@ src/inferrsi/
skill_evaluation.py Composed bundle export, trial run and summary
skill_eval_engineering.py Composed artifact check: task rules around sandbox replay
improvement.py Composed assessment, selection, rerun and holdout acceptance
inspection.py Environment inspection bound to the host probe and Git identity
legacy/
run.py Old run composed from Harness, Benchmark and the report
evaluation.py Old evaluate entry: RunSpec to the Benchmark gates
Expand All @@ -177,12 +189,6 @@ src/inferrsi/
resources/
__init__.py Import-free initializer
repository_packs.py Neutral REPO_TYPES and pack.json reader; imports no inferrsi module
catalog.py Knowledge search and cited context
skill_catalog.py Packaged/default or custom skill metadata/body/resource resolution
knowledge_operations.py Normalized reads and bounded Collect (KnowledgeReader)
knowledge_store.py Authorized local store Create/Update (KnowledgeStore)
research.py Read-only model-aware discovery joined over catalog queries
_skill_selection.py Deterministic lexical skill ranking and context view
summary_chart.py Stdlib SVG gain chart (chain/branch) and report figure spec
apps/
evidence_layout.py Create the plan/results/patch/validator evidence directories
Expand All @@ -205,6 +211,13 @@ src/inferrsi/
codex_search.py Bounded attributable file-search evidence from Codex rollouts
codex_tool_returns.py Correlate Codex tool-return windows
knowledge/
catalog.py Knowledge search and cited context
skill_catalog.py Packaged/default or custom skill metadata/body/resource resolution
knowledge_operations.py Normalized reads and bounded Collect (KnowledgeReader)
knowledge_store.py Authorized local store Create/Update (KnowledgeStore)
research.py Read-only model-aware discovery joined over catalog queries
_skill_selection.py Deterministic lexical skill ranking and context view
_source_snapshot.py Shared source snapshot for stored records: manifest, compact, resolve
context_projection.py Collected context text and item projection
harness/
api.py H public allocate/execute/read over one RunStore and CPU target
Expand Down Expand Up @@ -244,7 +257,7 @@ src/inferrsi/
processes.py Supervised Linux serving workers and their group cleanup
targets/git.py Repository identity and source snapshots
platforms/ Backend discovery registry; CUDA qualification
inspection.py Environment inspection coordinator
inspection.py Environment inspection facts API; command and snapshot ports
commands.py Bounded read-only probes
environment.py Dependency versions and storage checks
http.py HTTP POST/download timing
Expand All @@ -254,14 +267,22 @@ src/inferrsi/
repo_packs/ Contribution descriptors and versioned tuning knowledge
knowledge_packs/ Dependency and peer knowledge, preserving existing tiers
skill_library/ Complete categorized English skills and resources
execution.py Compatibility entrypoint -> apps.legacy.run
evaluation.py Compatibility exports -> apps.legacy.evaluation
inspection.py Compatibility entrypoint -> infra.inspection
reporting.py Compatibility export -> apps.legacy.reporting
examples/ Current Qwen runner, image validator and v4 adapter
tests/fixtures/legacy/ Frozen historical validation dependencies for regressions
```

The package root holds exactly ten tracked files at this stage: `__init__.py`,
`__main__.py`, `cli.py`, `arguments.py`, `benchmark_operations.py`,
`summary_chart.py`, `mindie_context.py`, `mindie_mcp.py`, `mindie_project.py`
and `_mindie_read_worker.py`. #412 R1 deleted eleven root modules with no
forwarding shell or alias: the seven Knowledge shells, whose code is in
`knowledge/`; the three old-run forwarders `evaluation.py`, `execution.py` and
`reporting.py`, whose code is in `apps/legacy/`; and `inspection.py`, whose
host binding is `apps/inspection.py`. The final two-file root (`__init__.py`
and `__main__.py`) waits for the A1/A2 (#408) and M1 (#452) moves.
[module-layout.md](module-layout.md#retired-root-modules) maps each retired
path to its replacement and lists what still keeps the isolation gate false.

## Where to extend

| Add | Main extension locations | Required qualification |
Expand All @@ -281,7 +302,10 @@ synthetic contract fixtures, not accelerator measurements.
`apps.legacy.run.run_experiment(spec, environment, *, execute, snapshot)` composes
the old run and accepts small callable adapters. It passes them, the Benchmark v0
gates and the report to `harness.runner.run_experiment`, whose four ports
(`execute`, `snapshot`, `assess`, `report`) have no defaults. For a new external
(`execute`, `snapshot`, `assess`, `report`) have no defaults. An omitted
`execute` or `snapshot` is read from `apps.legacy.run` when the run starts
(`execute_trial` and `repository_identity`), which is the two-argument call
that the retired root `execution.run_experiment` provided. For a new external
benchmark format, reuse the standard executor and only replace metric interpretation:

```python
Expand Down Expand Up @@ -344,7 +368,7 @@ the default control package continues to require only the standard library.

Register a device probe in `infra.platforms.PLATFORM_PROBES`; supply the selected
IDs, device model and bounded command runner. A new backend name additionally
needs an entry in `catalog.BACKENDS`, which supplies the CLI `--backend` choices
needs an entry in `knowledge.catalog.BACKENDS`, which supplies the CLI `--backend` choices
and the accepted knowledge and skill backends; no package-data descriptor is
required. Adding a device SKU within a backend is a parameter/configuration
change. CUDA qualification takes an explicit device count and model; it contains
Expand All @@ -367,8 +391,11 @@ group. Windows Job Object support in the general command executor
(`harness.local_process`) does not extend to these server helpers. These constraints do not restrict read-only knowledge
operations or the control CLI to Linux.

- Existing CLI flags, root import paths, external JSON metrics, run artifacts,
cancellation handling and report generation are retained.
- Existing CLI flags, external JSON metrics, run artifacts, cancellation
handling and report generation are retained. Root Python import paths are
not all retained: #451 and #412 R1 retired the root modules listed in
[CHANGELOG.md](../CHANGELOG.md) with no forwarding shell or alias. That file
maps each old path to its replacement and states the pickle impact.
- `examples/qwen21_turbo_b300.py` retains its command interface and campaign
settings while delegating lifecycle, requests and sampling to shared modules.
- The LTX helper and quality script, plus the pre-cleanup Qwen quality script,
Expand Down
Loading
Loading