Upgrade from miura-nexus 0.65.x to 0.66.x¶

Version 0.66 makes recipe deployment fail early when no admitted case binding is present and removes case-grouping probe methods that never had a production backend implementation. Collection ingest, reads, downloads, and existing properly bound recipes do not require changes.

No collection data migration is required.

Upgrade at a glance¶

Existing usage	Impact	Required action
`deploy_recipe(name, spec, cases=admitted_cases)`	None	None
`deploy_recipe(name, spec)`	Breaking	Pass admitted `cases=`
`create_recipe(name, spec)` for an intentionally unbound definition	None	Keep using `create_recipe`; the definition is not runnable on binding-required platforms
`collection.probe_case_grouping(...)`	Removed	Use plan validation or authoritative admission
`collection.case_grouping.probe(...)`	Removed	Use plan validation or authoritative admission
Collection upload / plan without case grouping	None	None
Case-aware reads and runs with an admitted binding	None	None

Install 0.66.x¶

Install from the same package index you already use:

python -m pip install --upgrade "miura-nexus>=0.66,<0.67"
# Preserve any extras you use, for example:
# python -m pip install --upgrade "miura-nexus[pandas,sigma]>=0.66,<0.67"

Confirm the installed version:

python -c "import importlib.metadata as m; print(m.version('miura-nexus'))"

Supply admitted cases when deploying recipes¶

In 0.65, an unbound call could create or revise a recipe record and then fail later when executed on a binding-required platform:

# 0.65: accepted by the client, but the resulting recipe may not be runnable.
recipe = project.deploy_recipe("vtk-to-xdmf", spec)

In 0.66, deploy_recipe rejects that call locally. Admit case membership and pass the resulting AdmittedCases handle.

For data being ingested now:

upload = collection.upload(
    datasource,
    case_grouping=grouping,
)

recipe = project.deploy_recipe(
    "vtk-to-xdmf",
    spec,
    cases=upload.cases,
)

When you inspect a plan before applying it:

plan = collection.plan(
    datasource,
    case_grouping=grouping,
)

if not plan.is_admissible:
    plan.print_validation_report()
    raise SystemExit("Ingestion plan is not admissible")

upload = plan.apply()
recipe = project.deploy_recipe(
    "vtk-to-xdmf",
    spec,
    cases=upload.cases,  # plan.cases is also the admitted pin
)

For files already in the collection:

cases = collection.case_grouping.admit(
    grouping,
    group_name="data",
)

recipe = project.deploy_recipe(
    "vtk-to-xdmf",
    spec,
    cases=cases,
)

Advanced callers may still pass an admitted CaseGroupingResult or a RecipeSpec that already carries an admitted binding. Bare result IDs, raw CaseGrouping descriptions, and upload or plan objects are not accepted as cases=; use their .cases handle.

Intentionally unbound recipe definitions¶

Use create_recipe(...) only when you deliberately need to store an unbound definition:

draft = project.create_recipe("draft-vtk-to-xdmf", spec)

That record is not runnable on a platform that requires a case-grouping binding. Bind admitted cases through deploy_recipe(..., cases=...) or recipe.update(cases=...) before execution.

Replace removed probe calls¶

The following methods were stubs and always raised NotImplementedError:

collection.probe_case_grouping(grouping)
collection.case_grouping.probe(grouping)

Choose the replacement based on what you need:

For incoming data, pass case_grouping= to collection.plan(...) and inspect plan.validation_gates plus plan.is_admissible.
For existing collection membership, call collection.case_grouping.admit(...). This creates the authoritative, snapshot-bound result that recipes and case-aware reads require.

Admission is not a preview: it returns an immutable admitted pin for the collection snapshot.

Migration checklist¶

Find every deploy_recipe(...) call and ensure it passes admitted cases= or uses a RecipeSpec that already carries an admitted binding.
Replace both removed probe method forms.
Keep create_recipe(...) only where an unbound, non-runnable definition is intentional.
Run one representative recipe through deploy and execute.
Run case-aware reads against the same admitted result.

Verify the upgrade¶

At minimum, verify that:

upload.cases, plan.cases, or collection.case_grouping.admit(...) returns an admitted handle.
deploy_recipe(..., cases=cases) succeeds.
The recipe executes with default inputs="pinned".
Case browsing resolves the same admitted result.

For full release details, see the 0.66.0 changelog.