[BUG] Reject schema-invalid manifest identity and policy keys at their parser boundaries

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Manifest and policy parsers now reject wrong-typed native schema values and
+  report unknown policy keys. Migration: quote numeric `apm.yml` versions, use
+  non-empty string identities, and use mappings/lists for policy blocks. (closes #2137) (#2143)
 - Fresh checkouts with declared consumer targets no longer remain
   `apm audit --ci`-red for files those targets cannot restore: `apm install`
   now removes stale `deployed_files` entries outside the legitimate target

docs/src/content/docs/concepts/package-anatomy.md

@@ -29,7 +29,8 @@ name: my-pkg
 version: 1.0.0
 ```
 
-`name` and `version` are the only required fields.
+`name` and `version` are the only required fields. Both must be non-empty
+strings; quote a numeric version so YAML does not parse it as a number.
 `apm install` will validate the manifest, generate `apm.lock.yaml`, and
 deploy `hello` to whatever harnesses you target.
 

docs/src/content/docs/reference/policy-schema.md

@@ -67,7 +67,10 @@ The `<ref>` accepts:
 | `executables`      | object              | see section      | no       | Org ceiling for executable-primitive trust (hooks, bin, self-defined MCP, canvas). See [executables](#executables). |
 | `bin_deploy`       | object              | see section      | no       | DEPRECATED alias folded into `executables.deny` (bin-scoped). See [bin_deploy](#bin_deploy). |
 
-Unknown top-level keys produce a warning, never an error -- so newer policy files load on older clients.
+Unknown top-level keys produce a warning, never an error -- so newer policy
+files load on older clients. `apm policy status --json` returns these in the
+`warnings` array. Known fields with the wrong native YAML type are rejected
+instead of being silently replaced by defaults.
 
 ## Enforcement modes
 

packages/apm-guide/.apm/skills/apm-usage/governance.md

@@ -22,6 +22,10 @@ environment-only so redirecting binary downloads remains invocation-scoped.
 
 ## Policy schema overview
 
+Unknown top-level keys are reported as warnings. Known fields with the wrong
+native YAML type are rejected; for example, `cache` must be a mapping and
+`dependencies.allow` must be a list.
+
 ```yaml
 name: "Contoso Engineering Policy"
 version: "1.0.0"

packages/apm-guide/.apm/skills/apm-usage/package-authoring.md

@@ -31,6 +31,8 @@ backfills one from the other:
   is no apm.yml-side equivalent.
 - `name`, `version`, `license`, `dependencies`, `scripts` live
   exclusively in `apm.yml`.
+- `name` and `version` must be non-empty strings. Quote numeric versions so
+  YAML does not parse them as numbers.
 
 Populate both descriptions when you ship a HYBRID package. `apm pack`
 warns when `apm.yml.description` is missing so listings do not

src/apm_cli/commands/deps/_utils.py

@@ -5,6 +5,7 @@
 
 from ...constants import APM_DIR, APM_YML_FILENAME, SKILL_MD_FILENAME
 from ...models.apm_package import APMPackage
+from ...utils.yaml_io import load_yaml
 
 
 def _scan_installed_packages(apm_modules_dir: Path) -> list:
@@ -154,6 +155,35 @@ def _get_detailed_context_counts(package_path: Path) -> dict[str, int]:
     return counts
 
 
+def _tolerant_identity(package_path: Path, apm_yml_path: Path) -> dict[str, str] | None:
+    """Best-effort name/version read for the tolerant ``deps`` display paths.
+
+    ``APMPackage.from_apm_yml`` is the strict identity authority: it rejects
+    empty/non-string ``name`` and ``version`` so ``audit`` and ``policy``
+    surfaces fail schema-invalid manifests. The ``deps list`` / ``deps info``
+    display commands are a different surface -- they must stay tolerant so a
+    manifest that merely omits or empties ``version`` still renders as
+    ``@unknown`` rather than an alarming ``@error`` that masks the package.
+
+    Returns a ``{"name", "version"}`` dict on a best-effort read, or ``None``
+    only when the apm.yml cannot be parsed at all (genuinely malformed YAML),
+    which the callers surface as ``error``.
+    """
+    try:
+        data = load_yaml(apm_yml_path)
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    raw_name = data.get("name")
+    name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else package_path.name
+    raw_version = data.get("version")
+    version = (
+        raw_version.strip() if isinstance(raw_version, str) and raw_version.strip() else "unknown"
+    )
+    return {"name": name, "version": version}
+
+
 def _get_package_display_info(package_path: Path) -> dict[str, str]:
     """Get package display information."""
     try:
@@ -173,10 +203,17 @@ def _get_package_display_info(package_path: Path) -> dict[str, str]:
                 "version": "unknown",
             }
     except Exception:
+        identity = _tolerant_identity(package_path, package_path / APM_YML_FILENAME)
+        if identity is None:
+            return {
+                "display_name": f"{package_path.name}@error",
+                "name": package_path.name,
+                "version": "error",
+            }
         return {
-            "display_name": f"{package_path.name}@error",
-            "name": package_path.name,
-            "version": "error",
+            "display_name": f"{identity['name']}@{identity['version']}",
+            "name": identity["name"],
+            "version": identity["version"],
         }
 
 
@@ -228,6 +265,22 @@ def _get_detailed_package_info(package_path: Path) -> dict[str, Any]:
                 "hooks": primitives.get("hooks", 0),
             }
     except Exception as e:
+        identity = _tolerant_identity(package_path, package_path / APM_YML_FILENAME)
+        if identity is not None:
+            # Tolerant display: a readable manifest with incomplete identity
+            # (e.g. empty/missing version) renders gracefully -- symmetric with
+            # `deps list` -- instead of masking the package behind an error.
+            return {
+                "name": identity["name"],
+                "version": identity["version"],
+                "description": "apm.yml identity incomplete",
+                "author": "Unknown",
+                "source": "local",
+                "install_path": str(package_path.resolve()),
+                "context_files": _get_detailed_context_counts(package_path),
+                "workflows": 0,
+                "hooks": 0,
+            }
         return {
             "name": package_path.name,
             "version": "error",

src/apm_cli/commands/policy.py

@@ -199,6 +199,7 @@ def _build_report(
         "cached": bool(result.cached),
         "fetch_error": result.fetch_error,
         "error": result.error,
+        "warnings": result.warnings,
         "extends_chain": chain,
         "rule_counts": counts,
         "rule_summary": _summarize_rules(counts),
@@ -228,6 +229,10 @@ def _render_table(report: dict[str, Any]) -> None:
             "Effective rules",
             "; ".join(report["rule_summary"]) if report["rule_summary"] else "none",
         ),
+        (
+            "Warnings",
+            "; ".join(report["warnings"]) if report["warnings"] else "none",
+        ),
     ]
 
     console = _get_console()

src/apm_cli/models/apm_package.py

@@ -388,6 +388,10 @@ def from_apm_yml(
             raise ValueError("Missing required field 'name' in apm.yml")
         if "version" not in data:
             raise ValueError("Missing required field 'version' in apm.yml")
+        if not isinstance(data["name"], str) or not data["name"].strip():
+            raise ValueError("Invalid apm.yml identity: 'name' must be a non-empty string")
+        if not isinstance(data["version"], str) or not data["version"].strip():
+            raise ValueError("Invalid apm.yml identity: 'version' must be a non-empty string")
 
         # Top-level ``registries:`` block per design §3.1.
         registries, default_registry = _parse_registries_block(data, apm_yml_path)