qcoder 0.4.0a1__tar.gz → 0.4.0a2__tar.gz

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on common practice for pre-1.0 semantic versioning: **`MAJOR.MINOR.PATCH`** with **`aN`** for alpha prereleases.
 
+## 0.4.0a2 (alpha)
+
+### Added
+
+- **Local Guidance Pack shadow metadata** — optional **`guidance_metadata`** records the bundled local resource-guidance candidate pack, including pack identity, version/hash metadata, caveats, and **`shadow_guidance`** with **`applied: false`**; deterministic guidance remains authoritative.
+
+### Improved
+
+- **Free Single-Run Intelligence** and **BYO LLM** artifact examples clarify that shadow guidance is metadata only.
+- **Release notes** — this alpha has no hosted qCoder compute, no telemetry upload, no qCoder-hosted LLM, no runtime ML dependency, and no optimality, fidelity, runtime, hardware, backend-ranking, or causal-savings claims.
+
 ## 0.4.0a1 (alpha)
 
 qCoder **0.4.0a1** adds opt-in derived **feature profiles**, mixed-width **review** checks, and a **5‑minute preflight→review** path.

{qcoder-0.4.0a1/src/qcoder.egg-info → qcoder-0.4.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.4.0a1
+Version: 0.4.0a2
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -48,7 +48,7 @@ Stable structural **feature vectors** (`schema_version`, `feature_names`, `featu
 pip install qcoder
 ```
 
-Pre-release lines on PyPI may look like **`0.4.0a1`**.
+Pre-release lines on PyPI may look like **`0.4.0a2`**.
 
 **2. Create a small Bell circuit** as `bell.qasm` (OpenQASM 2), or use the copy in **[`examples/circuits/bell.qasm`](examples/circuits/bell.qasm)** from a clone:
 
@@ -108,6 +108,9 @@ In real use, **`counts.json`** comes from **your** simulator or hardware pipelin
 
 **Examples:** **[`examples/README.md`](examples/README.md)** (Bell QASM + illustrative counts for clones).
 
+- **Free single-run intelligence** and **BYO LLM artifact workflow:** [`examples/06_single_run_intelligence.md`](examples/06_single_run_intelligence.md), [`examples/07_byo_llm_artifact_pack.md`](examples/07_byo_llm_artifact_pack.md), copy-paste prompt [`examples/prompts/single_run_artifact_to_action.md`](examples/prompts/single_run_artifact_to_action.md).
+- Full walkthrough on the site: [Single-run intelligence with qCoder](https://qcoder.ai/manual/workflows/single-run-intelligence/).
+
 ---
 
 ## What qCoder analyzes
@@ -116,7 +119,7 @@ qCoder summarizes **circuit structure** from OpenQASM (and optional framework ex
 
 ## Package layout (supported public surface)
 
-For **this release**, treat the **supported surface** as:
+**Current supported public surface:**
 
 - **`qcoder analyze`** — single-circuit extraction (human or `--json`).
 - **`qcoder batch`** — directory batch to **JSONL**.
@@ -130,7 +133,7 @@ For **this release**, treat the **supported surface** as:
 - **`qcoder[pennylane]`** — optional PennyLane circuit intake into the **same extractor** as OpenQASM.
 - **Documented feature output** — see [qcoder.ai — Feature reference](https://qcoder.ai/manual/feature-reference/) and `engines/feature_extraction/features/schema_v0.py`; JSON carries a **`schema_version`** alongside named fields.
 
-Other modules under **`src/qcoder`** may exist for prototyping (extra tooling or engines outside the commands above). Unless documented here, **`docs/`**, or **qcoder.ai**, they do **not** share the same stability expectations as the commands and artifact formats listed above.
+The public package contains the documented deterministic free-product surface above.
 
 Brief notes live in **`docs/architecture.md`**.
 
@@ -144,7 +147,7 @@ pip install "qcoder[pennylane]"
 
 Machine-readable JSON from **`qcoder analyze --json`** includes a derived **`feature_map`** object (`name → value`) for easier reading. The canonical circuit feature bundle remains the nested **`features`** object (`schema_version`, **`feature_names`**, **`features`**).
 
-Optional **`--guidance`** adds heuristic shot-count and simulator/MPS starting-point suggestions derived from structural features. These suggestions are transparent, non-guaranteed starting points only; qCoder performs no backend execution and includes no telemetry/upload in this flow.
+Optional **`--guidance`** adds heuristic shot-count and simulator/MPS starting-point suggestions derived from structural features. These suggestions are transparent, non-guaranteed starting points only; qCoder performs no backend execution and includes no telemetry/upload in this flow. When a bundled local guidance pack is present, the guidance JSON may also include **`guidance_metadata`** (pack id/version/hash, shadow suggestions, explicit `fallback_used`) for BYO-LLM workflows; **deterministic** `pressure` / `starting_points` remain the user-visible values until a future release explicitly applies pack output.
 
 Optional **`--profiles`** adds deterministic **`feature_profiles`** derived from `feature_map` for compact structural taxonomy. This is an additive interpretation layer with its own schema version and does not modify canonical `features` (`schema_version`, `feature_names`, `features`).
 

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/README.md

@@ -18,7 +18,7 @@ Stable structural **feature vectors** (`schema_version`, `feature_names`, `featu
 pip install qcoder
 ```
 
-Pre-release lines on PyPI may look like **`0.4.0a1`**.
+Pre-release lines on PyPI may look like **`0.4.0a2`**.
 
 **2. Create a small Bell circuit** as `bell.qasm` (OpenQASM 2), or use the copy in **[`examples/circuits/bell.qasm`](examples/circuits/bell.qasm)** from a clone:
 
@@ -78,6 +78,9 @@ In real use, **`counts.json`** comes from **your** simulator or hardware pipelin
 
 **Examples:** **[`examples/README.md`](examples/README.md)** (Bell QASM + illustrative counts for clones).
 
+- **Free single-run intelligence** and **BYO LLM artifact workflow:** [`examples/06_single_run_intelligence.md`](examples/06_single_run_intelligence.md), [`examples/07_byo_llm_artifact_pack.md`](examples/07_byo_llm_artifact_pack.md), copy-paste prompt [`examples/prompts/single_run_artifact_to_action.md`](examples/prompts/single_run_artifact_to_action.md).
+- Full walkthrough on the site: [Single-run intelligence with qCoder](https://qcoder.ai/manual/workflows/single-run-intelligence/).
+
 ---
 
 ## What qCoder analyzes
@@ -86,7 +89,7 @@ qCoder summarizes **circuit structure** from OpenQASM (and optional framework ex
 
 ## Package layout (supported public surface)
 
-For **this release**, treat the **supported surface** as:
+**Current supported public surface:**
 
 - **`qcoder analyze`** — single-circuit extraction (human or `--json`).
 - **`qcoder batch`** — directory batch to **JSONL**.
@@ -100,7 +103,7 @@ For **this release**, treat the **supported surface** as:
 - **`qcoder[pennylane]`** — optional PennyLane circuit intake into the **same extractor** as OpenQASM.
 - **Documented feature output** — see [qcoder.ai — Feature reference](https://qcoder.ai/manual/feature-reference/) and `engines/feature_extraction/features/schema_v0.py`; JSON carries a **`schema_version`** alongside named fields.
 
-Other modules under **`src/qcoder`** may exist for prototyping (extra tooling or engines outside the commands above). Unless documented here, **`docs/`**, or **qcoder.ai**, they do **not** share the same stability expectations as the commands and artifact formats listed above.
+The public package contains the documented deterministic free-product surface above.
 
 Brief notes live in **`docs/architecture.md`**.
 
@@ -114,7 +117,7 @@ pip install "qcoder[pennylane]"
 
 Machine-readable JSON from **`qcoder analyze --json`** includes a derived **`feature_map`** object (`name → value`) for easier reading. The canonical circuit feature bundle remains the nested **`features`** object (`schema_version`, **`feature_names`**, **`features`**).
 
-Optional **`--guidance`** adds heuristic shot-count and simulator/MPS starting-point suggestions derived from structural features. These suggestions are transparent, non-guaranteed starting points only; qCoder performs no backend execution and includes no telemetry/upload in this flow.
+Optional **`--guidance`** adds heuristic shot-count and simulator/MPS starting-point suggestions derived from structural features. These suggestions are transparent, non-guaranteed starting points only; qCoder performs no backend execution and includes no telemetry/upload in this flow. When a bundled local guidance pack is present, the guidance JSON may also include **`guidance_metadata`** (pack id/version/hash, shadow suggestions, explicit `fallback_used`) for BYO-LLM workflows; **deterministic** `pressure` / `starting_points` remain the user-visible values until a future release explicitly applies pack output.
 
 Optional **`--profiles`** adds deterministic **`feature_profiles`** derived from `feature_map` for compact structural taxonomy. This is an additive interpretation layer with its own schema version and does not modify canonical `features` (`schema_version`, `feature_names`, `features`).
 

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/docs/architecture.md

@@ -21,10 +21,12 @@ The supported product surface described in **`README.md`** (**Package layout**)
 
 The canonical circuit feature schema remains the existing `features` payload (`schema_version`, `feature_names`, `features`) produced by extraction. Guidance/context/review outputs are additive artifact layers and do not change canonical feature schema/version/order.
 
-When requested via CLI flags, qCoder may emit an additional top-level `guidance` block built deterministically from `feature_map`. This guidance is outside the canonical feature schema (`features`) and is intended as transparent heuristic starting points rather than execution-validated recommendations.
+When requested via CLI flags, qCoder may emit an additional top-level `guidance` block built deterministically from `feature_map`. This guidance is outside the canonical feature schema (`features`) and is intended as transparent heuristic starting points rather than execution-validated recommendations. The same block may include **`guidance_metadata`** describing a packaged **shadow-mode** local guidance JSON candidate (read from disk via `importlib.resources`; no network): pack id/version/content hash, optional shadow suggestions, and explicit fallback flags. **Deterministic** MPS `pressure` and `starting_points` stay authoritative in this slice; the pack does not override them yet.
 
 qCoder may also emit an optional top-level `feature_profiles` block derived deterministically from `feature_map`. `feature_profiles` is additive, separately versioned (`feature_profiles_schema_version`), and does not alter canonical `features` schema/version/order.
 
 The `context` and `review` commands generate deterministic local artifacts (Markdown/JSON) for user-controlled planning and post-run analysis workflows. "LLM-ready/RAG-ready" in this context means users can attach/paste artifacts manually; qCoder itself makes no LLM calls and performs no retrieval, embeddings, network calls, telemetry upload, or database writes. qCoder also does not execute simulators or hardware backends in these flows.
 
 Optional framework adapters perform conversion/intake only; they do not execute circuits, simulators, or hardware.
+
+The public package contains the documented deterministic free-product surface. Backend-specific runners, learned-prediction experiments, and private analysis prototypes are not part of the public package.

qcoder-0.4.0a2/docs/model-cards/resource-guidance-local-v0.md

@@ -0,0 +1,33 @@
+# Model card — `resource_guidance_local_v0` (shadow / metadata only)
+
+**Status:** Packaged as **candidate** JSON (`0.1.0-candidate`) in the public `qcoder` wheel under `qcoder.model_packs`. **Shadow mode only:** qCoder **does not** apply pack suggestions to `simulation_guidance.mps_bond_dimension.pressure` or `starting_points` in this release slice. Deterministic structural heuristics remain the user-visible source of truth.
+
+## Data scope
+
+- **Synthetic / public / qCoder-owned generated variants** only (as declared in the pack `training_data` block).
+- **No** real user telemetry, **no** Pro/private workflow exports, **no** unaudited archive dumps.
+
+## Runtime posture
+
+- **Local** package data only (`importlib.resources`); **no** network calls, **no** hosted inference, **no** telemetry upload from this path.
+- **No** runtime ML dependency (plain JSON; stdlib load and validate).
+
+## Non-claims (machine-readable keys also appear in the pack JSON)
+
+This pack and any shadow suggestions are **not**:
+
+- an optimality proof (`not_optimality_proof`);
+- a fidelity proof (`not_fidelity_proof`);
+- hardware correctness proof (`not_hardware_correctness_proof`);
+- a runtime guarantee (`not_runtime_guarantee`);
+- backend ranking or universal QPU quality scoring (`not_backend_ranking`);
+- causal savings or cost optimality (`not_causal_savings`).
+
+## Behavior in qCoder today
+
+- **Deterministic fallback preserved:** `build_resource_guidance` continues to set `pressure` and `starting_points` from structural scores only.
+- **`guidance_metadata`:** additive block on the guidance dict documenting pack id/version/hash, `fallback_used`, and `shadow_guidance` with `applied: false` until a future evaluated release explicitly enables application.
+
+## Promotion (future)
+
+Public promotion requires evaluation gates, reproducible labels, and explicit product/API review before any **non-shadow** application of pack outputs.

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.4.0a1"
+version = "0.4.0a2"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -46,6 +46,9 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+qcoder = ["model_packs/*.json"]
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.4.0a1"
+__version__ = "0.4.0a2"
 file = __file__

{qcoder-0.4.0a1 → qcoder-0.4.0a2}/src/qcoder/core/run_config.py

@@ -30,7 +30,7 @@ def normalize_precision(x: str | None) -> str:
 @dataclass(frozen=True)
 class RunConfig:
     """
-    Conditioning variables for runtime/fidelity predictors.
+    User-supplied run context for analyze reports.
 
     These are NOT circuit-derived features.
     """
@@ -38,10 +38,6 @@ class RunConfig:
     backend: str                    # normalized: "CPU" | "GPU"
     precision: str                  # normalized: "single" | "double"
     threshold: float | None = None  # e.g. bond-dimension/threshold conditioning
-    prediction_artifact_path: str | None = None
-    prediction_allow_schema_mismatch: bool = False
-    prediction_fidelity_target: float | None = None
-    prediction_fidelity_metric: str | None = None
 
     @staticmethod
     def from_raw(
@@ -50,10 +46,6 @@ class RunConfig:
         backend: str | None = None,
         precision: str | None = None,
         threshold: float | None = None,
-        prediction_artifact_path: str | None = None,
-        prediction_allow_schema_mismatch: bool | None = None,
-        prediction_fidelity_target: float | None = None,
-        prediction_fidelity_metric: str | None = None,
     ) -> "RunConfig":
         # accept processor OR backend as the same input channel
         raw = processor if processor is not None else backend
@@ -65,10 +57,6 @@ class RunConfig:
             backend=normalize_backend(raw or backend),
             precision=normalize_precision(precision),
             threshold=float(threshold) if threshold is not None else None,
-            prediction_artifact_path=prediction_artifact_path,
-            prediction_allow_schema_mismatch=prediction_allow_schema_mismatch or False,
-            prediction_fidelity_target=prediction_fidelity_target,
-            prediction_fidelity_metric=prediction_fidelity_metric,
         )
 
     def to_dict(self) -> dict:
@@ -77,8 +65,4 @@ class RunConfig:
             "backend": self.backend,
             "precision": self.precision,
             "threshold": self.threshold,
-            "prediction_artifact_path": self.prediction_artifact_path,
-            "prediction_allow_schema_mismatch": self.prediction_allow_schema_mismatch,
-            "prediction_fidelity_target": self.prediction_fidelity_target,
-            "prediction_fidelity_metric": self.prediction_fidelity_metric,
         }

qcoder-0.4.0a2/src/qcoder/engines/guidance/model_pack.py

@@ -0,0 +1,353 @@
+"""Local resource guidance JSON pack: load, validate, and shadow evaluation (stdlib only, no network)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any, Mapping
+
+PACK_RESOURCE = "resource_guidance_local_v0.json"
+PACK_PACKAGE = "qcoder.model_packs"
+
+ALLOWED_OPS = frozenset({"<", "<=", "==", ">=", ">"})
+REQUIRED_NON_CLAIMS = frozenset(
+    {
+        "not_optimality_proof",
+        "not_fidelity_proof",
+        "not_hardware_correctness_proof",
+        "not_runtime_guarantee",
+        "not_backend_ranking",
+        "not_causal_savings",
+    }
+)
+EXPECTED_OUTPUT_MAPPING = {
+    "mps_pressure": "simulation_guidance.mps_bond_dimension.pressure",
+    "mps_ladder": "simulation_guidance.mps_bond_dimension.starting_points",
+}
+REQUIRED_TOP_LEVEL = (
+    "model_pack_schema_version",
+    "model_pack_id",
+    "model_pack_version",
+    "target_feature_schema_versions",
+    "targets",
+    "rule_evaluation",
+    "condition_logic",
+    "no_match_behavior",
+    "training_data",
+    "features",
+    "support_bounds",
+    "outputs",
+    "output_mapping",
+    "rules",
+    "fallback",
+    "non_claims",
+)
+EXPECTED_FEATURES = frozenset(
+    {
+        "n_qubits",
+        "n_cbits",
+        "n_measure_ops",
+        "n_2q_gate_ops",
+        "n_param_ops",
+        "real_depth",
+        "entangling_depth",
+        "n_entangling_layers",
+        "cut_max",
+        "cut_mean",
+        "cut_entropy",
+        "n_active_cuts",
+        "span_avg",
+        "span_max",
+        "span_long_range_ratio",
+        "ig_edge_density",
+        "ig_avg_degree",
+        "ig_is_connected",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ResourceGuidancePack:
+    """Validated resource guidance pack (shadow / metadata only in v0)."""
+
+    model_pack_id: str
+    model_pack_version: str
+    model_pack_schema_version: str
+    sha256_hex: str
+    data: dict[str, Any]
+
+
+def compute_pack_sha256(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _feat(feature_map: Mapping[str, Any], key: str) -> float:
+    value = feature_map.get(key, 0.0)
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _float(x: Any) -> float | None:
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return None
+
+
+def _condition_matches(feature_map: Mapping[str, Any], cond: Mapping[str, Any]) -> bool:
+    feat = cond.get("feature")
+    op = cond.get("op")
+    val = cond.get("value")
+    if feat not in EXPECTED_FEATURES or op not in ALLOWED_OPS:
+        return False
+    lhs = _feat(feature_map, str(feat))
+    rhs = _float(val)
+    if rhs is None:
+        return False
+    if op == "<":
+        return lhs < rhs
+    if op == "<=":
+        return lhs <= rhs
+    if op == "==":
+        return lhs == rhs
+    if op == ">=":
+        return lhs >= rhs
+    if op == ">":
+        return lhs > rhs
+    return False
+
+
+def _trivial_catchall(cond: Mapping[str, Any], *, n_qubits_min: float) -> bool:
+    feat = cond.get("feature")
+    op = cond.get("op")
+    rhs = _float(cond.get("value"))
+    if rhs is None or feat not in EXPECTED_FEATURES or op not in ALLOWED_OPS:
+        return False
+    if feat == "n_qubits" and op == ">=":
+        if rhs <= 0:
+            return True
+        if rhs <= n_qubits_min:
+            return True
+    if op == ">=" and rhs <= 0:
+        return True
+    return False
+
+
+def validate_resource_guidance_pack(data: Mapping[str, Any]) -> list[str]:
+    """Return a list of validation errors; empty means the pack is acceptable."""
+    errors: list[str] = []
+
+    if not isinstance(data, dict):
+        return ["root must be a JSON object"]
+
+    for key in REQUIRED_TOP_LEVEL:
+        if key not in data:
+            errors.append(f"missing top-level key: {key}")
+
+    if data.get("model_pack_schema_version") != "resource_guidance_pack.v0":
+        errors.append("model_pack_schema_version must be resource_guidance_pack.v0")
+
+    targets = data.get("targets")
+    if targets != ["mps_pressure", "mps_bond_ladder"]:
+        errors.append("targets must be exactly ['mps_pressure', 'mps_bond_ladder']")
+
+    if data.get("rule_evaluation") != "first_match":
+        errors.append("rule_evaluation must be 'first_match'")
+
+    if data.get("condition_logic") != "all":
+        errors.append("condition_logic must be 'all'")
+
+    if data.get("no_match_behavior") != "fallback_deterministic":
+        errors.append("no_match_behavior must be 'fallback_deterministic'")
+
+    om = data.get("output_mapping")
+    if om != EXPECTED_OUTPUT_MAPPING:
+        errors.append("output_mapping must match expected public guidance paths")
+
+    nc = data.get("non_claims", [])
+    if not isinstance(nc, list) or frozenset(nc) != REQUIRED_NON_CLAIMS or len(nc) != len(REQUIRED_NON_CLAIMS):
+        errors.append("non_claims must contain exactly the required non-claim keys")
+
+    feats = data.get("features", [])
+    if not isinstance(feats, list) or frozenset(feats) != EXPECTED_FEATURES or len(feats) != len(EXPECTED_FEATURES):
+        errors.append("features must be the expected unique structural set (18 names)")
+
+    sb = data.get("support_bounds", {})
+    nqb = sb.get("n_qubits", {}) if isinstance(sb, dict) else {}
+    n_min = _float(nqb.get("min")) if isinstance(nqb, dict) else None
+    n_max = _float(nqb.get("max")) if isinstance(nqb, dict) else None
+    if n_min is None or n_max is None:
+        errors.append("support_bounds.n_qubits must include numeric min and max")
+        n_qubits_min = 1.0
+    else:
+        n_qubits_min = float(n_min)
+
+    ladders = data.get("outputs", {}).get("mps_ladders", {}) if isinstance(data.get("outputs"), dict) else {}
+    if not isinstance(ladders, dict):
+        errors.append("outputs.mps_ladders must be an object")
+    else:
+        for label in ("low", "medium", "high"):
+            if label not in ladders or not isinstance(ladders[label], list):
+                errors.append(f"outputs.mps_ladders.{label} must be a non-empty array")
+
+    ladder_keys = frozenset(ladders.keys()) if isinstance(ladders, dict) else frozenset()
+
+    rules = data.get("rules", [])
+    if not isinstance(rules, list) or len(rules) < 1:
+        errors.append("rules must be a non-empty array")
+        return errors
+
+    for i, rule in enumerate(rules):
+        if not isinstance(rule, dict):
+            errors.append(f"rules[{i}] must be an object")
+            continue
+        for rk in ("rule_id", "conditions", "output"):
+            if rk not in rule:
+                errors.append(f"rules[{i}] missing {rk}")
+        conds = rule.get("conditions", [])
+        if isinstance(conds, list) and len(conds) == 1 and isinstance(conds[0], dict):
+            if _trivial_catchall(conds[0], n_qubits_min=n_qubits_min):
+                errors.append(
+                    f"rules[{i}] is a trivial catch-all (forbidden for public guidance packs); "
+                    "use no_match_behavior fallback instead"
+                )
+        out = rule.get("output", {})
+        if isinstance(out, dict):
+            if out.get("mps_pressure") not in ladder_keys:
+                errors.append(f"rules[{i}].output.mps_pressure must be a ladder label")
+            if out.get("mps_ladder") not in ladder_keys:
+                errors.append(f"rules[{i}].output.mps_ladder must be a ladder label")
+        if not isinstance(conds, list) or not conds:
+            errors.append(f"rules[{i}].conditions must be a non-empty array")
+            continue
+        for j, c in enumerate(conds):
+            if not isinstance(c, dict):
+                errors.append(f"rules[{i}].conditions[{j}] must be an object")
+                continue
+            if c.get("op") not in ALLOWED_OPS:
+                errors.append(f"rules[{i}].conditions[{j}].op is not an allowed op")
+            if c.get("feature") not in EXPECTED_FEATURES:
+                errors.append(f"rules[{i}].conditions[{j}].feature is not a known feature")
+
+    return errors
+
+
+def load_resource_guidance_pack() -> ResourceGuidancePack | None:
+    """Load the bundled resource guidance pack from package data, or None if missing/invalid."""
+    try:
+        root = resources.files(PACK_PACKAGE)
+        path = root.joinpath(PACK_RESOURCE)
+        raw = path.read_bytes()
+    except (OSError, FileNotFoundError, TypeError, ValueError):
+        return None
+
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+
+    if validate_resource_guidance_pack(data):
+        return None
+
+    if not isinstance(data, dict):
+        return None
+
+    digest = compute_pack_sha256(raw)
+    return ResourceGuidancePack(
+        model_pack_id=str(data.get("model_pack_id", "")),
+        model_pack_version=str(data.get("model_pack_version", "")),
+        model_pack_schema_version=str(data.get("model_pack_schema_version", "")),
+        sha256_hex=digest,
+        data=dict(data),
+    )
+
+
+def evaluate_resource_guidance_pack_shadow(
+    features: Mapping[str, Any],
+    pack: ResourceGuidancePack,
+    *,
+    feature_schema_version: str,
+) -> dict[str, Any]:
+    """
+    First-match shadow evaluation: suggest pack ladder/pressure without applying to public guidance.
+
+    Out-of-support ``n_qubits`` or unsupported feature schema version yields no match
+    (caller should keep deterministic guidance).
+    """
+    tvers = pack.data.get("target_feature_schema_versions", [])
+    if not isinstance(tvers, list) or feature_schema_version not in tvers:
+        return {
+            "matched_rule_id": None,
+            "suggested_mps_pressure": None,
+            "suggested_mps_ladder": None,
+            "suggested_starting_points": None,
+            "no_match_reason": "unsupported_feature_schema",
+        }
+
+    sb = pack.data.get("support_bounds", {})
+    nqb = sb.get("n_qubits", {}) if isinstance(sb, dict) else {}
+    n_min = _float(nqb.get("min")) if isinstance(nqb, dict) else None
+    n_max = _float(nqb.get("max")) if isinstance(nqb, dict) else None
+    nq = _feat(features, "n_qubits")
+    if n_min is not None and nq < n_min:
+        return {
+            "matched_rule_id": None,
+            "suggested_mps_pressure": None,
+            "suggested_mps_ladder": None,
+            "suggested_starting_points": None,
+            "no_match_reason": "out_of_support_bounds",
+        }
+    if n_max is not None and nq > n_max:
+        return {
+            "matched_rule_id": None,
+            "suggested_mps_pressure": None,
+            "suggested_mps_ladder": None,
+            "suggested_starting_points": None,
+            "no_match_reason": "out_of_support_bounds",
+        }
+
+    rules = pack.data.get("rules", [])
+    ladders = pack.data.get("outputs", {}).get("mps_ladders", {})
+    if not isinstance(rules, list) or not isinstance(ladders, dict):
+        return {
+            "matched_rule_id": None,
+            "suggested_mps_pressure": None,
+            "suggested_mps_ladder": None,
+            "suggested_starting_points": None,
+            "no_match_reason": "invalid_pack_shape",
+        }
+
+    for rule in rules:
+        if not isinstance(rule, dict):
+            continue
+        conds = rule.get("conditions", [])
+        if not isinstance(conds, list) or not conds:
+            continue
+        if not all(isinstance(c, dict) and _condition_matches(features, c) for c in conds):
+            continue
+        out = rule.get("output", {})
+        if not isinstance(out, dict):
+            continue
+        ladder_key = out.get("mps_ladder")
+        sp = ladders.get(ladder_key) if isinstance(ladder_key, str) else None
+        if not isinstance(sp, list):
+            sp = None
+        return {
+            "matched_rule_id": rule.get("rule_id"),
+            "suggested_mps_pressure": out.get("mps_pressure"),
+            "suggested_mps_ladder": ladder_key,
+            "suggested_starting_points": list(sp) if sp is not None else None,
+            "no_match_reason": None,
+        }
+
+    return {
+        "matched_rule_id": None,
+        "suggested_mps_pressure": None,
+        "suggested_mps_ladder": None,
+        "suggested_starting_points": None,
+        "no_match_reason": "no_matching_rule",
+    }