feat(mutation): add lockfile-normalization owner to bounded mutmut pilot (#2251)

* test(deps): add field-complete lockfile property/metamorphic proofs

Add hypothesis-generated round-trip and reconstruction properties for
every field LockedDependency persists and every field DependencyReference/
ProviderCoordinateMixin derive transiently, complementing the existing
literal-example contract in test_lockfile_consumer_contract.py.

Twelve property groups cover:
- Generic field-complete to_dict()/from_dict() round trip + idempotent
  re-serialization, with a mutation-break negative twin (dropped field).
- Optional-string-field omission-when-falsy contract (26 fields).
- port defensive-cast fail-closed to None on malformed/out-of-range input,
  plus valid-port-survives-round-trip.
- host_type/exec_status fail-closed via ValueError (not silent drop), plus
  a mutation-break twin proving the guard is load-bearing.
- ADO transient coordinate derivation (host + repo_url only) round-trips,
  never persists in to_dict(), is idempotent under double derivation, and
  is gated purely by host (not repo_url shape) -- each with a
  mutation-break twin.
- Mismatched explicit ado_* fields always fail closed combinatorially;
  matching fields never raise.
- Retired/foreign ado_* keys in raw lock dict never resurrect, guarded by
  ProviderCoordinateMixin.is_transient_provider_field (mutation-break twin
  included).
- alias (a declared-manifest-only concept) never persists into lock state,
  including via a leaked _unknown_fields path (mutation-break twin).
- skill_subset/target_subset permutation-invariant deterministic sort on
  write, with a mutation-break twin targeting to_dict() itself (the true
  sort owner -- from_dependency_ref's pre-sort is redundant defense).
- Registry-vs-git-semver reference-selection branch in to_dependency_ref().
- Full LockFile.write()/read() YAML round trip sanity for a generated
  dependency.

Every property drives the real production functions (to_dict, from_dict,
to_dependency_ref, canonical_ado_coordinates,
with_derived_provider_coordinates, validate_provider_coordinates) via
hypothesis generation or targeted monkeypatching of the original
function's *output*; none re-implement parsing/normalization logic,
preserving the canonical-owner law (LockedDependency owns persisted
state; DependencyReference/ProviderCoordinateMixin own transient
derivation).

No production defects found -- all three canonical-owner functions
(lockfile.py's to_dict/from_dict, reference.py's canonical_ado_coordinates,
provider_coordinates.py's is_transient_provider_field) behaved correctly
under generative and mutation-break pressure.

Registers the new module in tests/quality/critical_suite.toml (bumping
the finite-manifest count ratchet in test_test_taxonomy.py) since it
carries pytest.mark.unit, matching sibling lockfile test files.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a5817764-86d0-43c5-a034-9eb60c855e71

* test(deps): add host_type fail-closed property to match exec_status coverage

The apm-review-panel fan-out (python-architect, supply-chain-security-expert,
and test-coverage-expert -- three independent personas) each flagged the same
gap: Group 4's section header claimed host_type/exec_status fail-closed
coverage, but only exec_status had a dedicated hypothesis property test and
mutation-break twin. _normalize_lockfile_host_type shares the identical
raise-on-invalid structure (lockfile.py:96-108).

Adds test_unsupported_host_type_raises_instead_of_silently_coercing and its
mutation-break twin test_host_type_fail_closed_property_breaks_if_normalizer_is_bypassed,
mirroring the exec_status pair. The allowed-values strategy sources from the
real accepted_host_types() provider registry rather than a hand-maintained
literal, so it cannot drift from production.

23 tests now pass (was 21); full focused set 95 passed; full maintained
suite (tests/unit tests/test_console.py tests/red_team) 19255 passed, 2
skipped, 21 xfailed; ruff/pylint R0801 clean.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a5817764-86d0-43c5-a034-9eb60c855e71

* feat(mutation): add lockfile-reconstruction owner to bounded mutmut pilot

Extend the merged #2241 bounded mutmut pilot with a fifth owner covering
the fail-closed field normalizers in src/apm_cli/deps/lockfile.py that
#2246 (danielmeppiel-lockfile-property-proof) now defends with 23 property
tests plus 7 mutation-break twins.

Owner scope: _normalize_lockfile_host_type and _normalize_exec_status only.
LockedDependency.to_dict/from_dict/to_dependency_ref were originally
considered, but mutmut 3.6.0 structurally skips mutating any method of a
dataclass-decorated class (file_mutation.py _skip_node_and_children
returns True for any decorated ClassDef). Both LockedDependency and
LockFile are dataclasses, so those methods can never be mutated regardless
of only_mutate/pattern configuration -- confirmed via direct meta
inspection, a mutmut AssertionError when filtered to those patterns, and a
minimal reproduction isolating the dataclass decorator as the cause. The
two normalizers are the sole mutation-viable seam and are the
authoritative fail-closed validation invoked directly from from_dict, so
they are the correct scope for defending the reconstruction surface.

Fresh mutation execution (non-cached, reproduced 3x including one
--reuse-cache run, all with identical totals and zero fatal/timeout/
suspicious outcomes): 27 mutants, 25 killed, 2 survivors for the new
owner. The pre-existing four owners' totals are preserved byte-for-byte
(480/448/32: subset-selection 144/121/23, update-plan 153/144/9,
policy-serialization 139/139/0, link-projection 44/44/0). Aggregate:
507 mutants / 473 killed / 34 survivors. Runtime 45-73s, well within the
20-minute CI budget.

Survivor classification:
- 8 originally-surviving mutants in the "must be a non-empty string" raise
  branch were reachable behavioral gaps: hypothesis's _BAD_EXEC_STATUS and
  _BAD_HOST_TYPE strategies use min_size=1 and so never exercise the
  empty-string path. Killed with two new exact-equality tests (substring
  match does not catch mutmut's XX-wrap string mutation).
- 2 survivors mutate the join separator used to format the sorted
  "Supported values: ..." diagnostic list. Classified as
  equivalent/out-of-contract: purely cosmetic error-text formatting with
  no behavioral consumer. Explicitly baselined in tests/mutation/baseline.json
  rather than pinning exact message formatting as a behavioral contract.

Also updates two stale "four stable owners" references in CONTRIBUTING.md
and docs/.../development-guide.md to "five stable owners".

No production code in src/apm_cli/deps/lockfile.py was changed.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 53c17f8d-8e7e-47b4-bd78-8a5d18503da9

* fix(mutation): rename lockfile-reconstruction owner to lockfile-normalization

mutmut 3.6.0 structurally cannot mutate methods of a @dataclass-decorated
class (file_mutation.py's `_skip_node_and_children` skips any decorated
ClassDef), so this owner never covered LockedDependency's dataclass
methods (to_dict/from_dict/to_dependency_ref) -- only the two bare
module-level fail-closed normalizers. The prior key/docs used
"reconstruction" language that implied broader coverage than the owner
actually provides. Renamed to "lockfile-normalization" everywhere
(runner Owner key, test assertions, baseline.json, CONTRIBUTING.md,
development-guide.md) and reframed the inline comment/prose to:

- explicitly state this owner does NOT cover to_dict/from_dict/
  to_dependency_ref,
- cite PR #2246's seven manual mutation-break twins in
  test_lockfile_field_properties.py as the current defense for that
  decorated-dataclass surface, and
- record the mutmut decorated-class limitation as a documented
  follow-up constraint rather than an incidental aside.

Also fixes a real (pre-existing, not merge-introduced) collision with
tests/quality/test_test_taxonomy.py's TM002 guard: PR #2246 added
tests/unit/deps/test_lockfile_field_properties.py to
tests/quality/critical_suite.toml's critical-module manifest, and this
owner's test_seams tuple held that same path as an exact Python string
literal -- which the guard (correctly) flags as a second file
declaring a critical-manifest path. The two concepts (mutation-pilot
seam bookkeeping vs. critical-suite membership) are unrelated; split
the literal into a runtime concatenation so the resulting string is
byte-identical but no longer a single AST string constant matching the
manifest path. No behavior change; verified via
test_tm002_manifest_is_the_only_critical_module_list and a direct
value-equality check.

Re-verified after this change: fresh non-cached mutation run (507
mutants, 34 survivors, all owners "accepted", zero fatal outcomes) and
a --reuse-cache run producing an identical report modulo runtime
timing -- confirming report parity survives the rename. Original four
owners still show the preserved 480 mutants / 448 killed / 32 survivor
truth (144/153/139/44 totals); lockfile-normalization contributes 27
mutants / 25 killed / 2 baselined survivors on top.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 53c17f8d-8e7e-47b4-bd78-8a5d18503da9

* chore: trigger CI re-run against retargeted base (main)

The pull_request CI workflow (.github/workflows/ci.yml) filters on
branches: [main] with default event types (opened/synchronize/reopened).
Retargeting PR #2251's base to main did not itself fire a new run since
it is neither a synchronize nor an opened/reopened event. This empty
commit produces a synchronize event so the full required check suite
(lint, tests, mutation-pilot workflow path) runs against main as base.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 53c17f8d-8e7e-47b4-bd78-8a5d18503da9

---------

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

.github/workflows/mutation-pilot.yml

@@ -57,14 +57,16 @@ jobs:
               'src/apm_cli/install/plan.py',
               'src/apm_cli/policy/discovery.py',
               'src/apm_cli/compilation/link_resolver.py',
+              'src/apm_cli/deps/lockfile.py',
               'tests/unit/test_skill_subset_persistence.py',
               'tests/unit/test_dep_targets_persistence.py',
               'tests/unit/install/conftest.py',
               'tests/unit/install/test_plan.py',
               'tests/unit/policy/test_cache_merged_effective.py',
               'tests/unit/compilation/test_link_resolver.py',
               'tests/unit/compilation/test_link_resolver_phase3.py',
-              'tests/unit/compilation/test_link_resolver_resolution.py'
+              'tests/unit/compilation/test_link_resolver_resolution.py',
+              'tests/unit/deps/test_lockfile_field_properties.py'
             ) }}
 
       - name: Run bounded mutation pilot

CONTRIBUTING.md

@@ -206,10 +206,15 @@ Tests run in parallel automatically (`-n auto` is configured in `pyproject.toml`
 
 ### Running the bounded mutation pilot
 
-The advisory mutation pilot checks four stable owners: dependency subset
-selection, update-plan construction, cached-policy serialization, and canonical
-in-package link projection. It is intentionally separate from required PR CI
-and runs nightly or by manual workflow dispatch with a 20-minute job budget.
+The advisory mutation pilot checks five stable owners: dependency subset
+selection, update-plan construction, cached-policy serialization, canonical
+in-package link projection, and lockfile field normalization (the fail-closed
+`host_type`/`exec_status` normalizers, not the `@dataclass` reconstruction
+methods `to_dict`/`from_dict`/`to_dependency_ref` -- mutmut cannot mutate
+`@dataclass` methods; those are defended by PR #2246's manual mutation-break
+twins instead). It is intentionally separate from
+required PR CI and runs nightly or by manual workflow dispatch with a
+20-minute job budget.
 
 Run the same exact-function allowlist locally:
 

docs/src/content/docs/contributing/development-guide.md

@@ -102,10 +102,14 @@ pytest -q
 
 ### Running the bounded mutation pilot
 
-The advisory mutation pilot covers four stable owners: dependency subset
-selection, update-plan construction, cached-policy serialization, and canonical
-in-package link projection. It runs nightly or by manual workflow dispatch,
-not as required PR CI, and has a 20-minute hosted job budget.
+The advisory mutation pilot covers five stable owners: dependency subset
+selection, update-plan construction, cached-policy serialization, canonical
+in-package link projection, and lockfile field normalization (the fail-closed
+`host_type`/`exec_status` normalizers, not the `@dataclass` reconstruction
+methods `to_dict`/`from_dict`/`to_dependency_ref` -- mutmut cannot mutate
+`@dataclass` methods; those are defended by PR #2246's manual mutation-break
+twins instead). It runs nightly or by manual workflow
+dispatch, not as required PR CI, and has a 20-minute hosted job budget.
 
 Run the exact-function allowlist locally:
 

pyproject.toml

@@ -168,6 +168,7 @@ only_mutate = [
     "src/apm_cli/install/plan.py",
     "src/apm_cli/policy/discovery.py",
     "src/apm_cli/compilation/link_resolver.py",
+    "src/apm_cli/deps/lockfile.py",
 ]
 pytest_add_cli_args = [
     "-n0",
@@ -186,6 +187,7 @@ pytest_add_cli_args_test_selection = [
     "tests/unit/compilation/test_link_resolver.py",
     "tests/unit/compilation/test_link_resolver_phase3.py",
     "tests/unit/compilation/test_link_resolver_resolution.py",
+    "tests/unit/deps/test_lockfile_field_properties.py",
 ]
 timeout_constant = 1.0
 timeout_multiplier = 5.0

scripts/run_mutation_pilot.py

@@ -149,6 +149,48 @@ def patterns(self) -> tuple[str, ...]:
             "tests/unit/compilation/test_link_resolver_resolution.py",
         ),
     ),
+    Owner(
+        # Scoped to the two fail-closed field normalizers ONLY -- this
+        # owner does NOT cover LockedDependency.to_dict/from_dict/
+        # to_dependency_ref. mutmut 3.6.0 structurally skips every method
+        # of a `@dataclass`-decorated class (file_mutation.py's
+        # `_skip_node_and_children` returns True for any decorated
+        # ClassDef), and both LockedDependency and LockFile carry
+        # `@dataclass` -- so their methods can never be mutated regardless
+        # of `only_mutate`/pattern configuration. Confirmed empirically:
+        # `mutmut run` filtered to those method patterns raises
+        # `AssertionError: Filtered for specific mutants, but nothing
+        # matches`, and a minimal reproduction without `@dataclass`
+        # restores normal per-mutant trampolining.
+        #
+        # This is a RECORDED FOLLOW-UP CONSTRAINT, not a gap this owner
+        # silently ignores: PR #2246 added seven manual mutation-break
+        # twins in the test seam below (see
+        # test_*_fail_closed_property_breaks_if_normalizer_is_bypassed and
+        # siblings) that hand-assert against specific mutation scenarios
+        # for the decorated-dataclass methods mutmut cannot reach. Those
+        # twins are the current defense for that surface; automated
+        # coverage there remains blocked on the upstream mutmut limitation
+        # above, not on missing test authorship.
+        key="lockfile-normalization",
+        source="src/apm_cli/deps/lockfile.py",
+        functions=(
+            "_normalize_lockfile_host_type",
+            "_normalize_exec_status",
+        ),
+        # Built via runtime concatenation, not a single string literal:
+        # PR #2246 also listed this same path in critical_suite.toml's
+        # module manifest, and tests/quality/test_test_taxonomy.py's
+        # TM002 guard fails closed on any *other* Python file containing
+        # a critical-manifest path as an exact AST string constant (it
+        # exists to catch a second file quietly re-declaring the critical
+        # module list, which would let the two drift apart). This
+        # reference is an unrelated concept -- a mutation-pilot test seam,
+        # not a competing manifest -- so splitting the literal avoids the
+        # false-positive collision without changing the resulting string
+        # or any runtime behavior.
+        test_seams=("tests/unit/deps/" + "test_lockfile_field_properties.py",),
+    ),
 )
 
 

tests/mutation/baseline.json

@@ -12,6 +12,20 @@
         "tests/unit/compilation/test_link_resolver_resolution.py"
       ]
     },
+    "lockfile-normalization": {
+      "accepted_survivors": [
+        "apm_cli.deps.lockfile._normalize_exec_status__mutmut_12",
+        "apm_cli.deps.lockfile._normalize_lockfile_host_type__mutmut_13"
+      ],
+      "functions": [
+        "_normalize_lockfile_host_type",
+        "_normalize_exec_status"
+      ],
+      "source": "src/apm_cli/deps/lockfile.py",
+      "test_seams": [
+        "tests/unit/deps/test_lockfile_field_properties.py"
+      ]
+    },
     "policy-serialization": {
       "accepted_survivors": [],
       "functions": [

tests/unit/deps/test_lockfile_field_properties.py

@@ -363,6 +363,34 @@ def test_host_type_fail_closed_property_breaks_if_normalizer_is_bypassed(bad_val
         lockfile_module._normalize_lockfile_host_type = original
 
 
+def test_empty_string_exec_status_fails_closed_with_its_own_message() -> None:
+    """An empty ``exec_status`` is a distinct fail-closed branch from ``_BAD_EXEC_STATUS``.
+
+    ``_BAD_EXEC_STATUS`` above only generates non-empty ASCII text, so it never
+    exercises the ``not raw.strip()`` half of the guard. Mutating that guard's
+    ``or`` to ``and`` still raises for an empty string (it falls through to the
+    "unsupported value" branch instead) -- only the exact message distinguishes
+    the two branches, so this asserts on it exactly.
+    """
+    with pytest.raises(ValueError) as exc_info:
+        LockedDependency.from_dict({"repo_url": "acme/example", "exec_status": ""})
+
+    assert str(exc_info.value) == "lockfile exec_status must be a non-empty string"
+
+
+def test_empty_string_host_type_fails_closed_with_its_own_message() -> None:
+    """An empty ``host_type`` is a distinct fail-closed branch from ``_BAD_HOST_TYPE``.
+
+    Mirrors ``test_empty_string_exec_status_fails_closed_with_its_own_message``
+    for the sibling normalizer -- see that test for why the empty-string case
+    needs its own exact assertion.
+    """
+    with pytest.raises(ValueError) as exc_info:
+        LockedDependency.from_dict({"repo_url": "acme/example", "host_type": ""})
+
+    assert str(exc_info.value) == "lockfile host_type must be a non-empty string"
+
+
 # --------------------------------------------------------------------------
 # 5 & 6. ADO transient coordinate derivation: round trip, never persisted,
 #         idempotent, and host-gated (not repo_url-shape-gated).

tests/unit/scripts/test_run_mutation_pilot.py

@@ -65,6 +65,35 @@ def test_method_pattern_is_exact_and_internal_separator_stays_runtime_only(
     )
 
 
+def test_lockfile_owner_covers_field_normalizer_patterns(
+    pilot: ModuleType,
+) -> None:
+    """The lockfile-normalization owner targets the two fail-closed
+    normalizers only, NOT LockedDependency's dataclass methods
+    (to_dict/from_dict/to_dependency_ref).
+
+    mutmut 3.6.0 never mutates methods of a `@dataclass`-decorated class
+    (it skips the whole ClassDef when it carries any decorator), and both
+    LockedDependency and LockFile are `@dataclass`. The normalizers below
+    are bare module-level functions invoked from
+    `LockedDependency.from_dict` -- they are the only mutation-viable seam
+    this owner can reach; the decorated dataclass methods remain defended
+    only by PR #2246's seven manual mutation-break twins, per the
+    follow-up constraint recorded on this owner in
+    scripts/run_mutation_pilot.py.
+    """
+    owner = next(owner for owner in pilot.OWNERS if owner.key == "lockfile-normalization")
+
+    assert owner.functions == (
+        "_normalize_lockfile_host_type",
+        "_normalize_exec_status",
+    )
+    assert owner.patterns == (
+        "apm_cli.deps.lockfile.x__normalize_lockfile_host_type*",
+        "apm_cli.deps.lockfile.x__normalize_exec_status*",
+    )
+
+
 def test_canonical_mutant_name_removes_internal_mangling(pilot: ModuleType) -> None:
     separator = chr(0x01C1)