Matter - initial gradio space

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.venv/
+.env
+*.egg-info/
+.DS_Store

PUSH.md

@@ -0,0 +1,79 @@
+# Pushing to `ashu-1069/matter` on Hugging Face Spaces
+
+Space URL: https://huggingface.co/spaces/ashu-1069/matter
+
+## One-time setup
+
+```bash
+cd space
+bash sync.sh                 # pulls matter/ + spec/ + examples/ from upstream
+
+git init
+git remote add origin https://huggingface.co/spaces/ashu-1069/matter
+git fetch origin
+
+# pull the existing Space contents (HF auto-creates a README on Space creation)
+# then overlay our files
+git checkout -b main origin/main 2>/dev/null || git checkout -b main
+
+# auth — pick one:
+#   1) huggingface-cli login            (token with write to ashu-1069)
+#   2) embed token in remote URL:
+#      git remote set-url origin https://ashu-1069:HF_TOKEN@huggingface.co/spaces/ashu-1069/matter
+```
+
+If `git fetch origin` fails with auth errors:
+- Get a write token: https://huggingface.co/settings/tokens (role: `write`)
+- `huggingface-cli login` and paste it
+
+If the Space already has a `README.md` from creation, our `README.md` will overwrite it — that's expected.
+
+## Every push
+
+```bash
+cd space
+bash sync.sh
+git add -A
+git commit -m "matter: <what changed>"
+git push origin main
+```
+
+The Space rebuilds automatically. First build takes ~5 min (torch + transformers).
+Cold-start GPU load adds ~30 s on the first **Live** click after that.
+
+## Space settings to set in the HF UI
+
+- **Hardware**: ZeroGPU (free; spins up an H200 on demand)
+- **Visibility**: Public (for the Impact Challenge submission)
+- **Variables and secrets** (all optional):
+  - `MATTER_MODEL_ID` — override default `google/gemma-4-E2B-it`
+  - `MATTER_LORA_ID` — A/B the E1 QLoRA adapter (off by default; it regressed
+    on real NYC images)
+  - `MATTER_MAX_NEW_TOKENS` — default `512`
+
+## Sanity-check locally before pushing
+
+```bash
+cd space
+bash sync.sh
+uv venv
+uv pip install -r requirements.txt
+uv run python app.py
+# → http://127.0.0.1:7860
+```
+
+Demo mode works without a GPU. Live mode needs a CUDA GPU locally — easier to
+just push and test on the Space.
+
+## Authorization troubleshooting
+
+If `git push` fails with `403 Forbidden`:
+1. Verify you own the Space owner namespace `ashu-1069` (the username with the
+   hyphen — not `ashu1069`).
+2. Token must have **write** scope, not just read.
+3. If using `huggingface-cli login`, run `huggingface-cli whoami` to confirm the
+   token resolves to `ashu-1069`.
+4. As a fallback, embed the token in the remote URL:
+   ```
+   git remote set-url origin https://ashu-1069:hf_xxx@huggingface.co/spaces/ashu-1069/matter
+   ```

app.py

@@ -0,0 +1,300 @@
+"""Matter — Material Intelligence Platform · Gradio Space app.
+
+Two run modes:
+  - Live: upload an image → Gemma 4 → MIE pipeline → Passport
+  - Demo: instant, returns one of the seven canonical example Passports
+
+Live mode loads Gemma 4 E2B lazily on first inference. The demo path never
+touches the model so cold Spaces still serve a fast first impression.
+"""
+
+from __future__ import annotations
+
+import json
+import traceback
+from pathlib import Path
+
+import gradio as gr
+
+from matter.engine import MIE, CaptureInput, MIEError
+from matter.heads import HEADS
+from transformers_runtime import TransformersRuntime
+
+ROOT = Path(__file__).parent
+EXAMPLES_DIR = ROOT / "examples"
+SPEC_EXAMPLES = ROOT / "spec" / "examples"
+
+HEAD_NAMES = list(HEADS.keys())  # domestic, ewaste, ev, medical, cd, textile
+
+SAMPLE_IMAGES: dict[str, str] = {
+    "domestic": "domestic_pet_bottle.jpg",
+    "ewaste":   "ewaste_dead_laptop.jpg",
+    "ev":       "ev_pouch_cell.jpg",
+    "medical":  "medical_glucose_strip.jpg",
+    "cd":       "cd_brick.jpg",
+    "textile":  "textile_cotton_tshirt.jpg",
+}
+
+DEMO_PASSPORTS: dict[str, str] = {
+    "domestic": "passport-01-domestic-pet-bottle.json",
+    "medical":  "passport-03-medical-glucose-strip-guardrail-fires.json",
+    "ev":       "passport-04-ev-18650-cell.json",
+    "ewaste":   "passport-05-ewaste-laptop.json",
+    "cd":       "passport-06-cd-concrete-with-recovery-value.json",
+    "textile":  "passport-07-textile-denim.json",
+}
+
+
+_runtime: TransformersRuntime | None = None
+
+
+def get_engine() -> MIE:
+    global _runtime
+    if _runtime is None:
+        _runtime = TransformersRuntime()
+    return MIE(runtime=_runtime, on_device=True)
+
+
+def render_summary(p: dict) -> str:
+    ident = p.get("identity", {})
+    state = p.get("state", {})
+    nba = p.get("next_best_action", {})
+    routing = p.get("routing", {})
+    prov = p.get("provenance", {})
+    val = (p.get("value") or {}).get("environmental") or {}
+
+    hazards = state.get("hazard_flags") or []
+    do_not = nba.get("do_not") or []
+
+    badge = "🟢 clear"
+    if nba.get("fallback_used"):
+        badge = "🟡 guardrail fired — safe default applied"
+    if any(h in {"biohazard", "sharps_injury_risk", "thermal_runaway_risk"} for h in hazards):
+        badge = "🔴 hazard"
+
+    lines = [
+        f"### {ident.get('class', '?')} · _{ident.get('subclass', '')}_",
+        "",
+        f"**Status** · {badge}",
+        "",
+        "| | |",
+        "|---|---|",
+        f"| **Action** | `{nba.get('primary', '?')}`"
+        + (f" → `{nba.get('secondary')}`" if nba.get("secondary") else "") + " |",
+        f"| **Do not** | "
+        + (", ".join(f"`{x}`" for x in do_not) if do_not else "_none_") + " |",
+        f"| **Confidence** | `{ident.get('confidence', 0):.3f}` "
+        + ("(calibrated)" if prov.get("confidence_calibrated") else "(raw)") + " |",
+        f"| **Hazards** | "
+        + (", ".join(f"`{h}`" for h in hazards) if hazards else "_none_") + " |",
+        f"| **Condition** | `{state.get('condition', '?')}` |",
+        f"| **Jurisdiction** | {routing.get('jurisdiction', '?')} |",
+    ]
+    if val.get("co2e_avoided_kg") is not None:
+        lines.append(f"| **CO₂e avoided** | `{val['co2e_avoided_kg']} kg` |")
+    lines += [
+        f"| **Model** | `{prov.get('model', '?')}` ({prov.get('runtime', '?')}) |",
+        f"| **On-device** | {'✅' if prov.get('on_device') else '—'} |",
+    ]
+    return "\n".join(lines)
+
+
+def render_pipeline(p: dict) -> str:
+    nba = p.get("next_best_action", {})
+    state = p.get("state", {})
+    fallback = nba.get("fallback_used", False)
+    hazards = state.get("hazard_flags") or []
+    return "\n".join([
+        "**MIE pipeline**",
+        "",
+        "| Step | Status |",
+        "|---|---|",
+        "| 01 · Validator | ✅ JSON shape + taxonomy enum |",
+        "| 02 · Calibration | ✅ histogram-calibrated |",
+        "| 03 · Hazard auto-flagger | "
+        + (f"⚠️ flagged: {', '.join(hazards)}" if hazards else "✅ no class-implied hazard") + " |",
+        "| 04 · Guardrail | "
+        + ("⚠️ fired — unsafe action overridden" if fallback else "✅ action passed `do_not` rules") + " |",
+    ])
+
+
+def run_demo(head: str) -> tuple[str, str, str]:
+    fname = DEMO_PASSPORTS.get(head, DEMO_PASSPORTS["domestic"])
+    p = json.loads((SPEC_EXAMPLES / fname).read_text())
+    return render_summary(p), render_pipeline(p), json.dumps(p, indent=2)
+
+
+def run_live(image_path: str | None, head: str, jurisdiction: str) -> tuple[str, str, str]:
+    if image_path is None:
+        return (
+            "⚠️ Upload an image first, or switch to **Demo** mode for the canonical example.",
+            "", "",
+        )
+    try:
+        engine = get_engine()
+        capture = CaptureInput(
+            image_path=Path(image_path),
+            jurisdiction=jurisdiction.strip() or None,
+        )
+        passport = engine.infer(capture, head)
+        p = passport.to_dict()
+        return render_summary(p), render_pipeline(p), json.dumps(p, indent=2)
+    except MIEError as e:
+        return (
+            f"### ❌ MIE pipeline rejected the model output\n\n```\n{e}\n```\n\n"
+            "_The model returned malformed or out-of-taxonomy JSON. Try a clearer image or switch to Demo mode._",
+            "", "",
+        )
+    except Exception as e:
+        return (
+            f"### ❌ Runtime error\n\n```\n{e.__class__.__name__}: {e}\n```\n\n"
+            "_If this is the first call after a cold start, the GPU worker is still loading Gemma 4 (≈30s). Try again in a moment, or use Demo mode._",
+            f"<details><summary>traceback</summary>\n\n```\n{traceback.format_exc()}\n```\n</details>",
+            "",
+        )
+
+
+def dispatch(mode: str, image_path: str | None, head: str, jurisdiction: str):
+    if mode == "Demo (instant)":
+        return run_demo(head)
+    return run_live(image_path, head, jurisdiction)
+
+
+CSS = """
+:root {
+  --bg-0: #04080a;
+  --emerald: #00d97e;
+  --emerald-glow: #00ff8c;
+  --cyan: #00e5ff;
+  --leaf: #7dd3a8;
+  --ink: #e6f3ec;
+  --ink-dim: #8aa39a;
+  --line: rgba(125, 211, 168, 0.12);
+}
+.gradio-container {
+  background: radial-gradient(ellipse 80% 60% at 20% 0%, rgba(0, 217, 126, 0.18), transparent 60%),
+              radial-gradient(ellipse 70% 50% at 85% 20%, rgba(0, 229, 255, 0.10), transparent 60%),
+              linear-gradient(180deg, #04080a 0%, #061410 50%, #04080a 100%) !important;
+  color: var(--ink) !important;
+  font-family: "Inter", ui-sans-serif, system-ui, sans-serif !important;
+}
+#hero { padding: 28px 4px 8px; }
+#hero h1 {
+  font-family: "Fraunces", Georgia, serif;
+  font-weight: 400;
+  font-size: clamp(2rem, 5vw, 3.4rem);
+  letter-spacing: -0.025em;
+  line-height: 1; margin: 0; color: var(--ink);
+}
+#hero h1 em {
+  font-style: italic;
+  background: linear-gradient(135deg, var(--emerald-glow), var(--cyan));
+  -webkit-background-clip: text; background-clip: text;
+  -webkit-text-fill-color: transparent;
+  font-weight: 300;
+}
+#hero p { color: var(--ink-dim); margin-top: 12px; max-width: 680px; }
+#hero .chip {
+  display: inline-flex; gap: 8px; align-items: center;
+  padding: 6px 14px; border-radius: 999px;
+  border: 1px solid rgba(125, 211, 168, 0.28);
+  background: linear-gradient(135deg, rgba(0, 217, 126, 0.08), rgba(0, 229, 255, 0.04));
+  color: var(--leaf); font-size: 0.82rem; font-weight: 500;
+}
+.dot { width: 8px; height: 8px; border-radius: 50%; background: var(--emerald-glow);
+       box-shadow: 0 0 12px var(--emerald-glow); display: inline-block; }
+.gr-button-primary {
+  background: linear-gradient(135deg, var(--emerald), var(--cyan)) !important;
+  color: #04130c !important;
+  border: 0 !important;
+  font-weight: 600 !important;
+}
+.gr-panel, .gr-block, .gr-form {
+  background: rgba(7, 18, 15, 0.6) !important;
+  border-color: var(--line) !important;
+}
+"""
+
+HERO_HTML = """
+<div id="hero">
+  <span class="chip"><span class="dot"></span> Powered by Gemma 4 · On-device · CC0 Passport</span>
+  <h1 style="margin-top:18px;">Material in. <em>Passport out.</em></h1>
+  <p>Point a camera at a thing — bottle, battery, syringe, denim, concrete, e-waste — and Matter
+  returns a calibrated, hazard-aware <strong style="color:var(--ink)">Passport</strong> that routes
+  it to its right next life. One vocabulary, six material heads, four post-model layers, validated.</p>
+</div>
+"""
+
+
+def build_examples() -> list[list]:
+    rows = []
+    for head, fname in SAMPLE_IMAGES.items():
+        p = EXAMPLES_DIR / fname
+        if p.exists():
+            rows.append([str(p), head, HEADS[head].default_jurisdiction])
+    return rows
+
+
+with gr.Blocks(css=CSS, theme=gr.themes.Base(), title="Matter — Material Intelligence") as demo:
+    gr.HTML(HERO_HTML)
+
+    with gr.Row():
+        with gr.Column(scale=5):
+            gr.Markdown("### Capture")
+            image_in = gr.Image(
+                label="Material image",
+                type="filepath",
+                height=320,
+                sources=["upload", "webcam", "clipboard"],
+            )
+            head_in = gr.Dropdown(
+                label="Material head",
+                choices=HEAD_NAMES,
+                value="domestic",
+                info="Which taxonomy and prompt to use.",
+            )
+            juris_in = gr.Textbox(
+                label="Jurisdiction (optional override)",
+                placeholder="leave blank to use the head default",
+                value="",
+            )
+            mode_in = gr.Radio(
+                label="Mode",
+                choices=["Live (Gemma 4)", "Demo (instant)"],
+                value="Demo (instant)",
+                info="Live runs Gemma 4 E2B on ZeroGPU (~8–12s once warm). Demo returns the canonical example passport for this head.",
+            )
+            run_btn = gr.Button("Generate Passport", variant="primary", size="lg")
+
+            ex = build_examples()
+            if ex:
+                gr.Examples(
+                    examples=ex,
+                    inputs=[image_in, head_in, juris_in],
+                    label="Sample materials",
+                    examples_per_page=6,
+                )
+
+        with gr.Column(scale=7):
+            gr.Markdown("### Passport")
+            summary_out = gr.Markdown(value="_Pick a mode and press_ **Generate Passport**.")
+            pipeline_out = gr.Markdown()
+            with gr.Accordion("Passport JSON", open=True):
+                json_out = gr.Code(language="json", label=None, lines=22)
+
+    gr.Markdown(
+        "<div style='color:var(--ink-dim);font-size:0.85rem;margin-top:24px;text-align:center;'>"
+        "Matter · open Material Intelligence platform · "
+        "Built for the <strong>Gemma 4 Impact Challenge</strong>"
+        "</div>"
+    )
+
+    run_btn.click(
+        dispatch,
+        inputs=[mode_in, image_in, head_in, juris_in],
+        outputs=[summary_out, pipeline_out, json_out],
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=8).launch(server_name="0.0.0.0", show_error=True)

matter/__init__.py

@@ -0,0 +1,2 @@
+"""Matter — a Gemma 4-powered Material Intelligence Platform."""
+__version__ = "0.0.1"

matter/calibration.py

@@ -0,0 +1,152 @@
+"""Post-hoc confidence calibration for the Material Intelligence Engine.
+
+Gemma 4 E4B is badly over-confident at zero-shot (A1: every prediction at 0.95 or 0.98
+regardless of correctness — ECE ~0.16 on 43 samples). This module fits a small, honest
+calibration function on a held-out set and applies it at Passport construction time.
+
+See DECISIONS.md D015 for the rationale and the `confidence_calibrated` flag in the
+Matter Passport schema.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+from sklearn.isotonic import IsotonicRegression
+from sklearn.linear_model import LogisticRegression
+
+Method = Literal["platt", "isotonic", "histogram"]
+
+
+@dataclass
+class Calibration:
+    method: Method
+    n_fit: int
+    ece_before: float
+    ece_after: float
+    params: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "method": self.method,
+            "n_fit": self.n_fit,
+            "ece_before": self.ece_before,
+            "ece_after": self.ece_after,
+            "params": self.params,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Calibration":
+        return cls(**d)
+
+
+def ece(confidences: np.ndarray, correctness: np.ndarray, n_bins: int = 10) -> float:
+    """Expected Calibration Error with equal-width bins."""
+    confidences = np.asarray(confidences, dtype=float)
+    correctness = np.asarray(correctness, dtype=float)
+    bins = np.linspace(0.0, 1.0, n_bins + 1)
+    err = 0.0
+    n = len(confidences)
+    for i in range(n_bins):
+        lo, hi = bins[i], bins[i + 1]
+        mask = (confidences >= lo) & (confidences < hi if i < n_bins - 1 else confidences <= hi)
+        k = int(mask.sum())
+        if k == 0:
+            continue
+        err += (k / n) * abs(confidences[mask].mean() - correctness[mask].mean())
+    return float(err)
+
+
+def fit_platt(confidences: np.ndarray, correctness: np.ndarray) -> Calibration:
+    """Logistic regression: P(correct | conf) = sigmoid(a*conf + b). 2 params."""
+    X = np.asarray(confidences, dtype=float).reshape(-1, 1)
+    y = np.asarray(correctness, dtype=int)
+    clf = LogisticRegression(C=1e6).fit(X, y)
+    calibrated = clf.predict_proba(X)[:, 1]
+    return Calibration(
+        method="platt",
+        n_fit=len(y),
+        ece_before=ece(confidences, correctness),
+        ece_after=ece(calibrated, correctness),
+        params={"a": float(clf.coef_[0, 0]), "b": float(clf.intercept_[0])},
+    )
+
+
+def fit_isotonic(confidences: np.ndarray, correctness: np.ndarray) -> Calibration:
+    """Non-parametric monotonic mapping; stores the knots."""
+    X = np.asarray(confidences, dtype=float)
+    y = np.asarray(correctness, dtype=int)
+    iso = IsotonicRegression(out_of_bounds="clip").fit(X, y)
+    calibrated = iso.predict(X)
+    return Calibration(
+        method="isotonic",
+        n_fit=len(y),
+        ece_before=ece(confidences, correctness),
+        ece_after=ece(calibrated, correctness),
+        params={
+            "x": iso.X_thresholds_.tolist(),
+            "y": iso.y_thresholds_.tolist(),
+        },
+    )
+
+
+def fit_histogram(confidences: np.ndarray, correctness: np.ndarray, n_bins: int = 10) -> Calibration:
+    """Per-bin empirical accuracy as the calibrated score."""
+    X = np.asarray(confidences, dtype=float)
+    y = np.asarray(correctness, dtype=int)
+    bins = np.linspace(0.0, 1.0, n_bins + 1)
+    bin_acc: dict[int, float] = {}
+    for i in range(n_bins):
+        lo, hi = bins[i], bins[i + 1]
+        mask = (X >= lo) & (X < hi if i < n_bins - 1 else X <= hi)
+        if int(mask.sum()) > 0:
+            bin_acc[i] = float(y[mask].mean())
+
+    def _apply(c: np.ndarray) -> np.ndarray:
+        idx = np.clip(np.digitize(c, bins) - 1, 0, n_bins - 1)
+        return np.array([bin_acc.get(int(i), float(c[j])) for j, i in enumerate(idx)])
+
+    calibrated = _apply(X)
+    return Calibration(
+        method="histogram",
+        n_fit=len(y),
+        ece_before=ece(confidences, correctness),
+        ece_after=ece(calibrated, correctness),
+        params={"bins": bins.tolist(), "bin_accuracy": bin_acc},
+    )
+
+
+def apply(cal: Calibration, confidences: np.ndarray | list[float]) -> np.ndarray:
+    """Apply a fitted calibration to new confidences."""
+    c = np.asarray(confidences, dtype=float)
+    if cal.method == "platt":
+        a = cal.params["a"]
+        b = cal.params["b"]
+        return 1.0 / (1.0 + np.exp(-(a * c + b)))
+    if cal.method == "isotonic":
+        xs = np.array(cal.params["x"])
+        ys = np.array(cal.params["y"])
+        return np.interp(c, xs, ys)
+    if cal.method == "histogram":
+        bins = np.array(cal.params["bins"])
+        bin_acc = cal.params["bin_accuracy"]
+        n_bins = len(bins) - 1
+        idx = np.clip(np.digitize(c, bins) - 1, 0, n_bins - 1)
+        return np.array([bin_acc.get(int(i), float(c[j])) for j, i in enumerate(idx)])
+    raise ValueError(f"unknown method: {cal.method}")
+
+
+def save(cal: Calibration, path: Path) -> None:
+    path.write_text(json.dumps(cal.to_dict(), indent=2))
+
+
+def load(path: Path) -> Calibration:
+    cal = Calibration.from_dict(json.loads(path.read_text()))
+    # Normalize histogram bin_accuracy keys to int — JSON serialization stringifies them.
+    if cal.method == "histogram" and isinstance(cal.params.get("bin_accuracy"), dict):
+        cal.params["bin_accuracy"] = {int(k): v for k, v in cal.params["bin_accuracy"].items()}
+    return cal

matter/engine.py

@@ -0,0 +1,206 @@
+"""Material Intelligence Engine (MIE) — wired four-layer pipeline.
+
+Composes the platform primitives the project shipped piecemeal:
+
+  1. JSON + enum validator               (D012)
+  2. Confidence calibration              (D015 — calibration_v1.json)
+  3. Class-implied hazard auto-flagger   (D019 — hazard_flags_v1.json)
+  4. do_not guardrail                    (D018 — safety_rules_v1.json)
+  -> validated Passport (Pydantic)
+
+Runtime is injected via the `Runtime` protocol — the engine doesn't know whether
+it's calling Ollama, llama.cpp, Cactus, or a fake. That keeps the engine itself
+unit-testable without a model.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from matter import calibration as cal
+from matter.guardrail import apply_guardrail, load_rules as load_safety_rules
+from matter.hazard_flagger import apply_hazard_flagger, load_hazard_rules
+from matter.heads import HEADS, build_prompt
+from matter.passport import (
+    Capture,
+    Identity,
+    NextBestAction,
+    Passport,
+    Provenance,
+    Routing,
+    State,
+    make_passport_id,
+    now_utc,
+)
+
+
+_SPEC_DIR = Path(__file__).resolve().parent.parent / "spec"
+_CALIB_PATH = _SPEC_DIR / "calibration_v1.json"
+_SAFETY_PATH = _SPEC_DIR / "safety_rules_v1.json"
+_HAZARD_PATH = _SPEC_DIR / "hazard_flags_v1.json"
+_JSON_RE = re.compile(r"\{.*\}", re.DOTALL)
+
+
+@dataclass
+class CaptureInput:
+    """Caller-facing capture struct. Resolved into a Passport `capture` block."""
+
+    image_path: Path | None = None
+    image_bytes: bytes | None = None
+    text: str | None = None
+    jurisdiction: str | None = None
+    geohash_coarse: str | None = None
+
+
+@runtime_checkable
+class Runtime(Protocol):
+    """Anything that turns (prompt, image_path) -> raw model output text."""
+
+    name: str
+    model_id: str
+
+    def infer(self, prompt: str, image: Path | None) -> str: ...
+
+
+class MIEError(Exception):
+    pass
+
+
+def _content_hash(c: CaptureInput) -> tuple[str, str]:
+    """Return (modality, content_hash). Modality inferred from inputs."""
+    if c.image_path is not None:
+        b = Path(c.image_path).read_bytes()
+        return "image", "sha256:" + hashlib.sha256(b).hexdigest()
+    if c.image_bytes is not None:
+        return "image", "sha256:" + hashlib.sha256(c.image_bytes).hexdigest()
+    if c.text is not None:
+        return "text", "sha256:" + hashlib.sha256(c.text.encode()).hexdigest()
+    raise MIEError("CaptureInput needs one of image_path / image_bytes / text")
+
+
+def _parse_json_block(text: str) -> dict:
+    m = _JSON_RE.search(text)
+    if m is None:
+        raise MIEError(f"no JSON object in model output: {text[:200]!r}")
+    try:
+        return json.loads(m.group(0))
+    except json.JSONDecodeError as e:
+        raise MIEError(f"invalid JSON in model output: {e} | {text[:200]!r}") from e
+
+
+def _validate_enum(parsed: dict, head_name: str) -> None:
+    """D012 — enum-membership check beyond JSON-shape validity."""
+    head = HEADS[head_name]
+    cls = (parsed.get("identity") or {}).get("class")
+    if cls not in head.identity_classes:
+        raise MIEError(f"identity.class {cls!r} not in {head_name} taxonomy")
+    nba = (parsed.get("next_best_action") or {}).get("primary")
+    if nba not in head.nba_classes:
+        raise MIEError(f"next_best_action.primary {nba!r} not in {head_name} NBA taxonomy")
+
+
+def _calibrate(c: float, table: cal.Calibration) -> float:
+    return float(cal.apply(table, [c])[0])
+
+
+class MIE:
+    """Compose the four primitives + the runtime into one entry point."""
+
+    def __init__(
+        self,
+        runtime: Runtime,
+        on_device: bool = False,
+        calibration_path: Path = _CALIB_PATH,
+        safety_path: Path = _SAFETY_PATH,
+        hazard_path: Path = _HAZARD_PATH,
+    ):
+        self.runtime = runtime
+        self.on_device = on_device
+        self.calib = cal.load(calibration_path)
+        self.safety_rules = load_safety_rules(safety_path)
+        self.hazard_rules = load_hazard_rules(hazard_path)
+        self._calibration_ref = f"{self.calib.method}@" + hashlib.sha256(
+            calibration_path.read_bytes()
+        ).hexdigest()[:16]
+
+    def infer(self, capture: CaptureInput, head_name: str) -> Passport:
+        if head_name not in HEADS:
+            raise MIEError(f"unknown head: {head_name}. Heads: {list(HEADS)}")
+        head = HEADS[head_name]
+        jurisdiction = capture.jurisdiction or head.default_jurisdiction
+        prompt = build_prompt(head_name, jurisdiction)
+
+        # 1. Runtime call
+        raw = self.runtime.infer(prompt, capture.image_path)
+
+        # 2. Layer A — JSON parse + enum validation (D012)
+        parsed = _parse_json_block(raw)
+        _validate_enum(parsed, head_name)
+        ident = parsed["identity"]
+        st = parsed.get("state", {})
+        nba = parsed["next_best_action"]
+
+        # 3. Layer B — calibration on per-block confidences (D015)
+        ident_conf_calibrated = _calibrate(float(ident.get("confidence", 0.0)), self.calib)
+        state_conf_calibrated = _calibrate(float(st.get("confidence", 0.0)), self.calib)
+        nba_conf_calibrated = _calibrate(float(nba.get("confidence", 0.0)), self.calib)
+
+        # 4. Construct draft passport (dict — guardrail + flagger mutate dicts)
+        modality, content_hash = _content_hash(capture)
+        ts = now_utc()
+        passport_id = make_passport_id(content_hash, ident["class"], ts)
+        draft: dict = {
+            "schema": "matter-passport/v0.1",
+            "passport_id": passport_id,
+            "prev": None,
+            "timestamp": ts,
+            "capture": {
+                "modality": modality,
+                "content_hash": content_hash,
+                **({"geohash_coarse": capture.geohash_coarse} if capture.geohash_coarse else {}),
+            },
+            "identity": {
+                "class": ident["class"],
+                "subclass": ident.get("subclass"),
+                "taxonomy": head.taxonomy_uri,
+                "confidence": ident_conf_calibrated,
+            },
+            "state": {
+                "condition": st.get("condition", "unknown"),
+                "hazard_flags": list(st.get("hazard_flags") or []),
+                "confidence": state_conf_calibrated,
+            },
+            "next_best_action": {
+                "primary": nba["primary"],
+                "secondary": nba.get("secondary"),
+                "do_not": list(nba.get("do_not") or []),
+                "confidence": nba_conf_calibrated,
+                "fallback_used": False,
+            },
+            "routing": {"jurisdiction": jurisdiction, "regulation_refs": []},
+            "provenance": {
+                "model": self.runtime.model_id,
+                "runtime": self.runtime.name,
+                "on_device": self.on_device,
+                "confidence_calibrated": True,
+                "calibration_ref": self._calibration_ref,
+            },
+        }
+
+        # 5. Layer C — class-implied hazard auto-flagger (D019)
+        apply_hazard_flagger(draft, self.hazard_rules)
+
+        # 6. Layer D — do_not guardrail (D018)
+        apply_guardrail(draft, self.safety_rules)
+
+        # 7. Final Pydantic validation against the v0.1 schema
+        return Passport.model_validate(draft)
+
+
+__all__ = ["MIE", "MIEError", "Runtime", "CaptureInput", "Capture", "Identity",
+           "State", "NextBestAction", "Provenance", "Routing", "Passport"]

matter/guardrail.py

@@ -0,0 +1,70 @@
+"""MIE rule-based do_not guardrail (D018).
+
+Enforces per-identity-class safety constraints on a Passport's `next_best_action`
+before the MIE returns. If the model's proposed primary action is in the item's
+`do_not` set, the guardrail overrides it with the safe default and sets
+`next_best_action.fallback_used = true` on the Passport.
+
+This is a platform primitive — it runs regardless of which model produced the draft.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Rule:
+    do_not: frozenset[str]
+    safe_default: str
+    severity: str  # "critical" | "high" | "environmental" | "economic" | "informational"
+
+
+@dataclass
+class GuardrailResult:
+    passport: dict
+    fallback_used: bool
+    triggered_rule: Rule | None
+    original_primary: str | None
+
+
+def load_rules(path: str | Path) -> dict[str, Rule]:
+    """Load do_not rules. JSON files retain `reason` and other documentation
+    fields the Python type doesn't carry — they're for downstream consumers."""
+    data = json.loads(Path(path).read_text())
+    raw = data.get("rules", data)
+    return {
+        key: Rule(
+            do_not=frozenset(v.get("do_not", [])),
+            safe_default=v["safe_default"],
+            severity=v.get("severity", "informational"),
+        )
+        for key, v in raw.items()
+    }
+
+
+def apply_guardrail(passport: dict, rules: dict[str, Rule]) -> GuardrailResult:
+    """Validate and potentially override next_best_action.primary. Mutates passport."""
+    identity_cls = (passport.get("identity") or {}).get("class")
+    nba = passport.setdefault("next_best_action", {})
+    primary = nba.get("primary")
+
+    rule = rules.get(identity_cls) if identity_cls else None
+    if rule is None or primary is None or primary not in rule.do_not:
+        nba.setdefault("fallback_used", False)
+        return GuardrailResult(passport, False, rule, None)
+
+    # Guardrail fires: override primary, append to do_not list, flag fallback.
+    nba["primary"] = rule.safe_default
+    nba["fallback_used"] = True
+    existing_do_not = nba.setdefault("do_not", [])
+    if primary not in existing_do_not:
+        existing_do_not.append(primary)
+    return GuardrailResult(passport, True, rule, primary)
+
+
+def critical_violation(result: GuardrailResult) -> bool:
+    """Convenience: did the guardrail catch a critical-severity rule violation?"""
+    return result.fallback_used and result.triggered_rule is not None and result.triggered_rule.severity == "critical"

matter/hazard_flagger.py

@@ -0,0 +1,51 @@
+"""Class-implied hazard auto-flagger (D019).
+
+A1/A6 showed that Gemma 4's self-reported hazard_flags miss real biohazards
+(37.5% sensitivity on the medical eval). This module guarantees that canonical
+hazards implied by the identity class are present in the Passport, regardless
+of whether the model produced them.
+
+Runs BEFORE the do_not guardrail in the MIE pipeline.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class HazardRule:
+    required: tuple[str, ...]
+
+
+def load_hazard_rules(path: str | Path) -> dict[str, HazardRule]:
+    """Load class → required-hazards rules. JSON retains `context_dependent`
+    and other documentation the Python type doesn't carry."""
+    data = json.loads(Path(path).read_text())
+    raw = data.get("rules", data)
+    return {cls: HazardRule(required=tuple(v.get("required", []))) for cls, v in raw.items()}
+
+
+def apply_hazard_flagger(passport: dict, rules: dict[str, HazardRule]) -> tuple[dict, list[str]]:
+    """Ensure canonical hazards for the identity class are in passport.state.hazard_flags.
+
+    Returns (mutated_passport, added_flags).
+    """
+    identity_cls = (passport.get("identity") or {}).get("class")
+    state = passport.setdefault("state", {})
+    existing = list(state.get("hazard_flags") or [])
+    # Drop sentinels like "none" if present.
+    existing = [f for f in existing if f and f != "none"]
+
+    rule = rules.get(identity_cls) if identity_cls else None
+    added: list[str] = []
+    if rule is not None:
+        for flag in rule.required:
+            if flag not in existing:
+                existing.append(flag)
+                added.append(flag)
+
+    state["hazard_flags"] = existing
+    return passport, added

matter/heads.py

@@ -0,0 +1,114 @@
+"""Head registry: identity taxonomy + NBA taxonomy + prompt template per domain.
+
+Extracted from the A1, A2, and A6 notebooks so the MIE engine has a single source
+of truth for prompts and allowed-class enums. Each head bundles the same shape:
+
+  - identity_classes: allowed `identity.class` values
+  - nba_classes: allowed `next_best_action.primary` values
+  - taxonomy_uri: URI used in `identity.taxonomy`
+  - jurisdiction: default jurisdiction for prompts (overridable per call)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Head:
+    name: str
+    identity_classes: tuple[str, ...]
+    nba_classes: tuple[str, ...]
+    taxonomy_uri: str
+    default_jurisdiction: str
+
+
+HEADS: dict[str, Head] = {
+    "domestic": Head(
+        name="domestic",
+        identity_classes=("plastic_bottle", "multilayer_plastic", "carton", "metal_can",
+                          "organic", "glass", "paper", "other"),
+        nba_classes=("blue_bin_recycle", "compost_bin", "special_collection", "general_waste"),
+        taxonomy_uri="https://matter.spec/taxonomy/domestic/v0.1",
+        default_jurisdiction="NYC (DSNY + NY EPR)",
+    ),
+    "ewaste": Head(
+        name="ewaste",
+        identity_classes=("laptop", "smartphone", "cable", "power_adapter", "audio",
+                          "battery", "pcb", "lighting", "other"),
+        nba_classes=("retailer_takeback", "ewaste_collection_event", "battery_drop_off",
+                     "general_waste"),
+        taxonomy_uri="https://matter.spec/taxonomy/ewaste/v0.1",
+        default_jurisdiction="NYC (DSNY + NY EPR)",
+    ),
+    "ev": Head(
+        name="ev",
+        identity_classes=("lithium_ion_cell", "lead_acid_battery", "battery_pack",
+                          "connector", "pcb", "other"),
+        nba_classes=("second_life_stationary_storage", "certified_ev_recycler",
+                     "battery_drop_off", "general_waste"),
+        taxonomy_uri="https://matter.spec/taxonomy/ev/v0.1",
+        default_jurisdiction="NYC (DSNY + NY EPR)",
+    ),
+    "medical": Head(
+        name="medical",
+        identity_classes=("blister_pack", "sharps", "medicine_bottle", "diagnostic",
+                          "wound_care", "packaging", "device", "other"),
+        nba_classes=("pharmacy_takeback", "biomedical_waste_collector",
+                     "general_waste", "recycle_paper"),
+        taxonomy_uri="https://matter.spec/taxonomy/medical/v0.1",
+        default_jurisdiction="NYC (CPCB + NY DOH biomedical waste rules)",
+    ),
+    "cd": Head(
+        name="cd",
+        identity_classes=("concrete", "brick", "gypsum", "steel", "plastic", "ceramic",
+                          "insulation", "other"),
+        nba_classes=("aggregate_recycler", "metal_recycler", "gypsum_recycler",
+                     "specialty_recycler", "landfill"),
+        taxonomy_uri="https://matter.spec/taxonomy/cd/v0.1",
+        default_jurisdiction="NYC (Local Law 97 + DEP construction debris rules)",
+    ),
+    "textile": Head(
+        name="textile",
+        identity_classes=("cotton_garment", "denim", "blended_garment", "synthetic_garment",
+                          "wool_garment", "leather", "mixed_fabric_scrap", "other"),
+        nba_classes=("resale_reuse", "fiber_recycler", "downcycle_rags",
+                     "leather_reclaim", "landfill"),
+        taxonomy_uri="https://matter.spec/taxonomy/textile/v0.1",
+        default_jurisdiction="NYC (NY EPR Packaging + Higg MSI alignment)",
+    ),
+}
+
+
+PROMPT_TEMPLATE = """You are a Material Intelligence model identifying a single object in an image and recommending its disposal action.
+
+Domain: {domain}
+Jurisdiction: {jurisdiction}
+Allowed identity classes: {identity_classes}
+Allowed next_best_action values: {nba_classes}
+
+CONFIDENCE RUBRIC — use these anchors strictly:
+- 0.95-1.00  unambiguous; multiple distinctive features match exactly one class
+- 0.80-0.94  likely correct; one or two details could plausibly fit another class
+- 0.60-0.79  best guess; visual evidence is weak or partially occluded
+- 0.40-0.59  coin-flip between two classes; pick the more likely one
+- below 0.40 uncertain; prefer 'other' and say so in the reason
+
+SAFETY: For sharps, contaminated diagnostics, batteries, or pharmaceuticals, route to the safest action. The Matter rule layer will override unsafe choices but you should not propose them.
+
+Respond ONLY with valid JSON in this exact shape:
+{{"identity": {{"class": "<one of the identity classes>", "subclass": "<short>", "confidence": <0-1>, "reason": "<one sentence>"}},
+ "state": {{"condition": "<good|degraded|contaminated|unknown>", "hazard_flags": ["<flags or []>"], "confidence": <0-1>}},
+ "next_best_action": {{"primary": "<one of the NBA values>", "secondary": "<NBA or null>", "do_not": ["<NBA values>"], "confidence": <0-1>, "reason": "<one sentence>"}}
+}}
+"""
+
+
+def build_prompt(head_name: str, jurisdiction: str | None = None) -> str:
+    head = HEADS[head_name]
+    return PROMPT_TEMPLATE.format(
+        domain=head.name,
+        jurisdiction=jurisdiction or head.default_jurisdiction,
+        identity_classes=", ".join(head.identity_classes),
+        nba_classes=", ".join(head.nba_classes),
+    )

matter/impact.py

@@ -0,0 +1,82 @@
+"""Carbon footprint enrichment — fills Passport.value.environmental.co2e_avoided_kg
+from the CC0 factors table at spec/co2e_factors_v1.json.
+
+This is an OPTIONAL fifth layer that runs after the safety pipeline. Scope is
+strictly carbon footprint; water / land-use / biodiversity are out of scope.
+
+Per-kg factors with class-typical unit weights are looked up by (head, identity_class,
+next_best_action). If the caller supplies a measured weight, that is used; otherwise
+the typical_unit_weight_kg from the table is used as the best-available estimate.
+
+Footprint sign convention (matches spec/co2e_factors_v1.json):
+  positive value = kg CO2e *avoided* by routing to this action vs. landfill BAU
+  negative value = the action *adds* to the carbon footprint relative to BAU
+                   (e.g. autoclave incineration of sharps — a safety-driven cost)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from matter.passport import Environmental, Passport, Value
+
+
+@dataclass(frozen=True)
+class Co2eEntry:
+    co2e_avoided_kg_per_kg: float
+    typical_unit_weight_kg: float
+    source: str
+
+
+def load_factors(path: str | Path) -> dict[tuple[str, str, str], Co2eEntry]:
+    """Load the CO2e factor table.
+
+    Returns a flat lookup keyed by (head, identity_class, next_best_action).
+    """
+    raw = json.loads(Path(path).read_text())
+    table: dict[tuple[str, str, str], Co2eEntry] = {}
+    for head, classes in raw["factors"].items():
+        for cls, actions in classes.items():
+            for action, entry in actions.items():
+                table[(head, cls, action)] = Co2eEntry(
+                    co2e_avoided_kg_per_kg=float(entry["co2e_avoided_kg_per_kg"]),
+                    typical_unit_weight_kg=float(entry["typical_unit_weight_kg"]),
+                    source=entry["source"],
+                )
+    return table
+
+
+def estimate_footprint(
+    passport: Passport,
+    head_name: str,
+    factors: dict[tuple[str, str, str], Co2eEntry],
+    measured_weight_kg: float | None = None,
+) -> Passport:
+    """Fill `passport.value.environmental` based on identity.class + NBA + (head).
+
+    If a factor is missing for the (head, class, action) tuple, the function leaves
+    the value block unchanged. Returns the (possibly mutated) Passport.
+    """
+    cls = passport.identity.class_
+    action = passport.next_best_action.primary
+    key = (head_name, cls, action)
+    entry = factors.get(key)
+    if entry is None:
+        return passport
+
+    weight_kg = measured_weight_kg if measured_weight_kg is not None else entry.typical_unit_weight_kg
+    co2e_kg = entry.co2e_avoided_kg_per_kg * weight_kg
+    basis = (
+        f"co2e_factors_v1[{head_name}/{cls}/{action}] "
+        f"({entry.co2e_avoided_kg_per_kg:+.2f} kg CO2e/kg × {weight_kg:.3f} kg)"
+        + (" [measured weight]" if measured_weight_kg is not None else " [typical unit weight]")
+    )
+
+    env = Environmental(co2e_avoided_kg=round(co2e_kg, 4), basis=basis)
+    if passport.value is None:
+        passport.value = Value(environmental=env)
+    else:
+        passport.value.environmental = env
+    return passport

matter/passport.py

@@ -0,0 +1,150 @@
+"""Pydantic models for the Matter Passport v0.1.
+
+Mirrors `spec/matter-passport-v0.1.schema.json`. Every field that the JSON Schema
+declares is represented here with Python types + Pydantic validation.
+
+Used by:
+- the MIE engine to construct + validate Passports end-to-end
+- the CLI to emit valid Passport JSON
+- integration tests to assert pipeline correctness
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+SCHEMA_VERSION = "matter-passport/v0.1"
+PASSPORT_ID_RE = re.compile(r"^mp_sha256:[0-9a-f]{6,64}$")
+
+Modality = Literal["image", "video", "text", "audio", "multimodal"]
+Runtime = Literal["unsloth", "cactus", "litert", "llama.cpp", "mlx", "ollama", "other"]
+
+
+def make_passport_id(content_hash: str, identity_class: str, ts: str) -> str:
+    """Derive a content-addressed passport_id."""
+    h = hashlib.sha256(f"{content_hash}|{identity_class}|{ts}".encode()).hexdigest()[:32]
+    return f"mp_sha256:{h}"
+
+
+def now_utc() -> str:
+    return datetime.now(tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+class Capture(BaseModel):
+    modality: Modality
+    content_hash: str
+    geohash_coarse: str | None = Field(default=None, max_length=5)
+
+
+class Identity(BaseModel):
+    class_: str = Field(alias="class")
+    subclass: str | None = None
+    taxonomy: str
+    gs1_alias: str | None = None
+    confidence: float = Field(ge=0.0, le=1.0)
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class State(BaseModel):
+    condition: str
+    estimated_soh: float | None = Field(default=None, ge=0.0, le=1.0)
+    contamination: str | None = None
+    hazard_flags: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class Economic(BaseModel):
+    amount: float
+    currency: str
+    basis: str
+
+
+class Environmental(BaseModel):
+    co2e_avoided_kg: float
+    basis: str
+
+
+class Value(BaseModel):
+    economic: Economic | None = None
+    environmental: Environmental | None = None
+
+
+class NextBestAction(BaseModel):
+    primary: str
+    secondary: str | None = None
+    do_not: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+    fallback_used: bool = False
+
+
+class Routing(BaseModel):
+    jurisdiction: str | None = None
+    regulation_refs: list[str] = Field(default_factory=list)
+    function_call: str | None = None
+
+
+class Provenance(BaseModel):
+    model: str
+    runtime: Runtime
+    on_device: bool
+    lora: str | None = None
+    confidence_calibrated: bool = False
+    calibration_ref: str | None = None
+
+
+class Signature(BaseModel):
+    type: str
+    created: str
+    verificationMethod: str
+    proofPurpose: str | None = None
+    proofValue: str
+
+
+class Passport(BaseModel):
+    """Matter Passport v0.1 — typed, validated representation of one inference."""
+
+    schema_: Literal["matter-passport/v0.1"] = Field(default=SCHEMA_VERSION, alias="schema")
+    context: str | list[str] | None = Field(default=None, alias="@context")
+    passport_id: str
+    prev: str | None = None
+    timestamp: str
+    capture: Capture
+    identity: Identity
+    state: State
+    value: Value | None = None
+    next_best_action: NextBestAction
+    routing: Routing | None = None
+    provenance: Provenance
+    signature: Signature | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    @field_validator("passport_id")
+    @classmethod
+    def _check_id(cls, v: str) -> str:
+        if not PASSPORT_ID_RE.match(v):
+            raise ValueError(f"passport_id must match {PASSPORT_ID_RE.pattern}: got {v!r}")
+        return v
+
+    def to_json(self, **kwargs) -> str:
+        """Emit canonical JSON with the field aliases (`schema`, `@context`, `class`)."""
+        return self.model_dump_json(by_alias=True, exclude_none=True, **kwargs)
+
+    def to_dict(self) -> dict:
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+    @classmethod
+    def from_json(cls, raw: str | dict | Path) -> "Passport":
+        if isinstance(raw, Path):
+            raw = raw.read_text()
+        if isinstance(raw, str):
+            raw = json.loads(raw)
+        return cls.model_validate(raw)

matter/runtimes/__init__.py

@@ -0,0 +1,18 @@
+"""Runtime adapters that implement the `matter.engine.Runtime` protocol.
+
+Each adapter is responsible for: (a) accepting a prompt + optional image,
+(b) calling its underlying inference backend, (c) returning the raw model
+output text. The MIE engine handles parsing, calibration, hazard flagging,
+and guardrail enforcement on top.
+
+Available adapters:
+- OllamaRuntime: HTTP client for a local Ollama daemon (Mac, Linux, Pi)
+
+Planned (Stage 1):
+- HFInferenceRuntime: Hugging Face Inference Endpoints (cloud demo)
+- CactusRuntime: Native Android via the Cactus SDK
+"""
+
+from matter.runtimes.ollama import OllamaRuntime
+
+__all__ = ["OllamaRuntime"]

matter/runtimes/ollama.py

@@ -0,0 +1,121 @@
+"""Ollama runtime adapter — `Runtime` protocol over a local Ollama HTTP daemon.
+
+Works with text-only and multimodal Gemma 4 variants. Multimodal calls send the
+image as base64-encoded bytes in the `images` array per Ollama's /api/generate
+contract.
+
+Tested against:
+- Mac M3 Pro / Ollama 0.20.x with `gemma4:e2b` (text — A5 Tier 1 measured 2.3s p50)
+- Multimodal models via the same registry path
+
+If Ollama isn't running, calls raise httpx.ConnectError; the engine surfaces it.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Literal
+
+import httpx
+
+
+DEFAULT_HOST = "http://localhost:11434"
+DEFAULT_NUM_PREDICT = 512
+DEFAULT_TIMEOUT_S = 300.0
+
+
+class OllamaRuntime:
+    """Implements the engine `Runtime` protocol via Ollama's REST API."""
+
+    name: Literal["ollama"] = "ollama"
+
+    def __init__(
+        self,
+        model: str = "gemma4:e2b",
+        host: str = DEFAULT_HOST,
+        num_predict: int = DEFAULT_NUM_PREDICT,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        client: httpx.Client | None = None,
+    ):
+        self.model_id = model
+        self.host = host.rstrip("/")
+        self.num_predict = num_predict
+        self.timeout = timeout
+        self._client = client or httpx.Client(timeout=timeout)
+        self._owns_client = client is None
+
+    def __enter__(self) -> "OllamaRuntime":
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    # --- Health ---
+
+    def is_alive(self) -> bool:
+        try:
+            r = self._client.get(f"{self.host}/api/tags", timeout=2.0)
+            return r.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def model_available(self) -> bool:
+        """True iff `model_id` is in the local Ollama tag list."""
+        try:
+            r = self._client.get(f"{self.host}/api/tags", timeout=5.0)
+            r.raise_for_status()
+        except httpx.HTTPError:
+            return False
+        names = {m.get("name", "") for m in r.json().get("models", [])}
+        return self.model_id in names
+
+    # --- Inference ---
+
+    def infer(self, prompt: str, image: Path | None) -> str:
+        # Use /api/chat — applies the model's chat template (e.g. Gemma 4's
+        # <start_of_turn>...<end_of_turn> markers). /api/generate feeds the
+        # prompt raw and instruct-tuned models produce special-token garbage.
+        message: dict = {"role": "user", "content": prompt}
+        if image is not None:
+            message["images"] = [_b64(Path(image))]
+        body = {
+            "model": self.model_id,
+            "messages": [message],
+            "stream": False,
+            "options": {"temperature": 0, "num_predict": self.num_predict},
+        }
+        r = self._client.post(f"{self.host}/api/chat", json=body)
+        r.raise_for_status()
+        payload = r.json()
+        text = (payload.get("message") or {}).get("content", "")
+        if not text:
+            done_reason = payload.get("done_reason", "unknown")
+            eval_count = payload.get("eval_count", 0)
+            prompt_eval = payload.get("prompt_eval_count", 0)
+            hint = ""
+            if done_reason == "length" and eval_count == 0:
+                hint = (
+                    " — context likely full from prompt+image before generation could start. "
+                    "Try a multimodal model (e.g. gemma4:e4b on a GPU host), increase num_predict, "
+                    "or run text-only via --no-image."
+                )
+            elif done_reason == "length":
+                hint = (
+                    f" — model generated {eval_count} tokens but produced no decoded text. "
+                    "Likely a chat-template / special-token issue. Try a different model or check "
+                    "Ollama version compatibility."
+                )
+            raise RuntimeError(
+                f"Ollama returned empty response (done_reason={done_reason!r}, "
+                f"eval_count={eval_count}, prompt_eval_count={prompt_eval}).{hint}"
+            )
+        return text
+
+
+def _b64(path: Path) -> str:
+    return base64.b64encode(path.read_bytes()).decode("ascii")

requirements.txt

@@ -0,0 +1,11 @@
+gradio==4.44.1
+spaces>=0.30.0
+torch==2.4.0
+transformers>=4.46.0
+accelerate>=0.34.0
+pillow>=10.3
+pydantic>=2.7
+jsonschema>=4.22
+numpy>=1.26
+scikit-learn>=1.5
+httpx>=0.27

spec/calibration_v1.json

@@ -0,0 +1,115 @@
+{
+  "method": "histogram",
+  "n_fit": 43,
+  "ece_before": 0.16046511627906979,
+  "ece_after": 0.0,
+  "params": {
+    "bins": [
+      0.0,
+      0.01,
+      0.02,
+      0.03,
+      0.04,
+      0.05,
+      0.06,
+      0.07,
+      0.08,
+      0.09,
+      0.1,
+      0.11,
+      0.12,
+      0.13,
+      0.14,
+      0.15,
+      0.16,
+      0.17,
+      0.18,
+      0.19,
+      0.2,
+      0.21,
+      0.22,
+      0.23,
+      0.24,
+      0.25,
+      0.26,
+      0.27,
+      0.28,
+      0.29,
+      0.3,
+      0.31,
+      0.32,
+      0.33,
+      0.34,
+      0.35000000000000003,
+      0.36,
+      0.37,
+      0.38,
+      0.39,
+      0.4,
+      0.41000000000000003,
+      0.42,
+      0.43,
+      0.44,
+      0.45,
+      0.46,
+      0.47000000000000003,
+      0.48,
+      0.49,
+      0.5,
+      0.51,
+      0.52,
+      0.53,
+      0.54,
+      0.55,
+      0.56,
+      0.5700000000000001,
+      0.58,
+      0.59,
+      0.6,
+      0.61,
+      0.62,
+      0.63,
+      0.64,
+      0.65,
+      0.66,
+      0.67,
+      0.68,
+      0.6900000000000001,
+      0.7000000000000001,
+      0.71,
+      0.72,
+      0.73,
+      0.74,
+      0.75,
+      0.76,
+      0.77,
+      0.78,
+      0.79,
+      0.8,
+      0.81,
+      0.8200000000000001,
+      0.8300000000000001,
+      0.84,
+      0.85,
+      0.86,
+      0.87,
+      0.88,
+      0.89,
+      0.9,
+      0.91,
+      0.92,
+      0.93,
+      0.9400000000000001,
+      0.9500000000000001,
+      0.96,
+      0.97,
+      0.98,
+      0.99,
+      1.0
+    ],
+    "bin_accuracy": {
+      "94": 0.375,
+      "98": 0.9142857142857143
+    }
+  }
+}

spec/co2e_factors_v1.json

@@ -0,0 +1,171 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "license": "CC0-1.0",
+    "scope": "carbon footprint only — kg CO2-equivalent avoided per kg of material when routed to the listed action vs. business-as-usual landfill",
+    "description": "Per-(identity_class, action) CO2e factors used by matter.impact to fill Passport.value.environmental.co2e_avoided_kg. Values are central estimates from peer-reviewed lifecycle assessments and government inventories. Out of scope: water footprint, land-use change, biodiversity. Stage 1 may add jurisdiction-conditional factors.",
+    "primary_sources": [
+      "ICE — Inventory of Carbon and Energy v3.0 (Hammond & Jones, University of Bath; updated 2019)",
+      "EPA WARM v15 — US EPA Waste Reduction Model (2020)",
+      "IPCC AR6 — Working Group III, Chapter 11: Industry (2022)",
+      "Geyer, R., Jambeck, J. R., & Law, K. L. (2017). Production, use, and fate of all plastics ever made. Science Advances 3:e1700782",
+      "Hischier, R. et al. (2020). Lifecycle assessment of plastic recycling. International Journal of LCA",
+      "Ellingsen, L. A.-W. et al. (2017). The size and range effect: lifecycle GHG of EV batteries. ERL 12"
+    ],
+    "limitations_disclosed": [
+      "Factors are point estimates; real LCA distributions are wide. Stage 1 will add ±sigma bands.",
+      "Baseline (counterfactual) is jurisdiction-specific landfill mix; ICE/EPA values assume OECD-typical landfill.",
+      "EV/battery factors carry the highest uncertainty (5-50x range across studies).",
+      "Pharmaceutical takeback factor is dominated by avoided water contamination, not direct CO2; included for completeness but reported low and noted."
+    ]
+  },
+  "factors": {
+    "domestic": {
+      "plastic_bottle": {
+        "blue_bin_recycle":   {"co2e_avoided_kg_per_kg": 1.5, "typical_unit_weight_kg": 0.030, "source": "Geyer 2017; ICE v3.0 (PET, recycled vs. virgin)"},
+        "general_waste":      {"co2e_avoided_kg_per_kg": 0.0, "typical_unit_weight_kg": 0.030, "source": "baseline (BAU)"}
+      },
+      "multilayer_plastic": {
+        "special_collection": {"co2e_avoided_kg_per_kg": 0.4, "typical_unit_weight_kg": 0.005, "source": "Hischier 2020 (multilayer recovery efficiency low)"},
+        "general_waste":      {"co2e_avoided_kg_per_kg": 0.0, "typical_unit_weight_kg": 0.005, "source": "baseline"}
+      },
+      "carton": {
+        "blue_bin_recycle":   {"co2e_avoided_kg_per_kg": 0.9, "typical_unit_weight_kg": 0.030, "source": "EPA WARM v15 (mixed paper/aseptic)"}
+      },
+      "metal_can": {
+        "blue_bin_recycle":   {"co2e_avoided_kg_per_kg": 9.0, "typical_unit_weight_kg": 0.015, "source": "ICE v3.0 (aluminum, recycled vs. primary)"}
+      },
+      "organic": {
+        "compost_bin":        {"co2e_avoided_kg_per_kg": 0.5, "typical_unit_weight_kg": 0.150, "source": "EPA WARM v15 (food scraps composted vs. landfilled, includes avoided methane)"},
+        "general_waste":      {"co2e_avoided_kg_per_kg": -0.7, "typical_unit_weight_kg": 0.150, "source": "EPA WARM (organics in landfill emit methane — *positive* footprint)"}
+      },
+      "glass": {
+        "blue_bin_recycle":   {"co2e_avoided_kg_per_kg": 0.3, "typical_unit_weight_kg": 0.250, "source": "ICE v3.0 (glass cullet vs. virgin)"}
+      },
+      "paper": {
+        "blue_bin_recycle":   {"co2e_avoided_kg_per_kg": 0.7, "typical_unit_weight_kg": 0.010, "source": "EPA WARM v15 (mixed paper recycled)"},
+        "compost_bin":        {"co2e_avoided_kg_per_kg": 0.4, "typical_unit_weight_kg": 0.010, "source": "EPA WARM v15"}
+      }
+    },
+    "ewaste": {
+      "laptop": {
+        "ewaste_collection_event": {"co2e_avoided_kg_per_kg": 35.0, "typical_unit_weight_kg": 2.0, "source": "Andrae & Edler 2015 (laptop recovery, rare earths + precious metals)"}
+      },
+      "smartphone": {
+        "retailer_takeback":       {"co2e_avoided_kg_per_kg": 50.0, "typical_unit_weight_kg": 0.180, "source": "Apple Environmental Reports + Andrae 2015"}
+      },
+      "cable": {
+        "retailer_takeback":       {"co2e_avoided_kg_per_kg": 5.0,  "typical_unit_weight_kg": 0.080, "source": "ICE (copper, recycled vs. mined)"}
+      },
+      "power_adapter": {
+        "ewaste_collection_event": {"co2e_avoided_kg_per_kg": 8.0,  "typical_unit_weight_kg": 0.150, "source": "ICE (mixed metals + PCB)"}
+      },
+      "audio": {
+        "retailer_takeback":       {"co2e_avoided_kg_per_kg": 6.0,  "typical_unit_weight_kg": 0.050, "source": "Andrae 2015 (consumer electronics)"}
+      },
+      "battery": {
+        "battery_drop_off":        {"co2e_avoided_kg_per_kg": 1.5,  "typical_unit_weight_kg": 0.024, "source": "EPA WARM (alkaline batteries)"}
+      },
+      "pcb": {
+        "ewaste_collection_event": {"co2e_avoided_kg_per_kg": 12.0, "typical_unit_weight_kg": 0.200, "source": "Cucchiella 2015 (PCB recycling, copper + gold + silver recovery)"}
+      },
+      "lighting": {
+        "retailer_takeback":       {"co2e_avoided_kg_per_kg": 2.0,  "typical_unit_weight_kg": 0.025, "source": "EPA WARM (mercury-containing lamps, LED average)"}
+      }
+    },
+    "ev": {
+      "lithium_ion_cell": {
+        "second_life_stationary_storage": {"co2e_avoided_kg_per_kg": 8.0, "typical_unit_weight_kg": 0.050, "source": "Ellingsen 2017 + Bobba 2018 (extended-life ratio applied to manufacturing-phase emissions)"},
+        "battery_drop_off":               {"co2e_avoided_kg_per_kg": 4.0, "typical_unit_weight_kg": 0.050, "source": "Dunn 2015 (Li-ion hydrometallurgical recovery)"},
+        "certified_ev_recycler":          {"co2e_avoided_kg_per_kg": 4.0, "typical_unit_weight_kg": 0.050, "source": "Dunn 2015"}
+      },
+      "lead_acid_battery": {
+        "certified_ev_recycler":          {"co2e_avoided_kg_per_kg": 0.5, "typical_unit_weight_kg": 15.0, "source": "ILA 2019 (lead recycling, 99% recovery rate baseline)"}
+      },
+      "battery_pack": {
+        "certified_ev_recycler":          {"co2e_avoided_kg_per_kg": 5.0, "typical_unit_weight_kg": 25.0, "source": "Ellingsen 2017 (full pack disassembly + recovery)"},
+        "second_life_stationary_storage": {"co2e_avoided_kg_per_kg": 10.0, "typical_unit_weight_kg": 25.0, "source": "Bobba 2018"}
+      },
+      "connector": {
+        "retailer_takeback":              {"co2e_avoided_kg_per_kg": 4.0, "typical_unit_weight_kg": 0.500, "source": "ICE (mixed-metal recovery)"}
+      },
+      "pcb": {
+        "ewaste_collection_event":        {"co2e_avoided_kg_per_kg": 12.0, "typical_unit_weight_kg": 0.200, "source": "Cucchiella 2015 (BMS PCB)"}
+      }
+    },
+    "medical": {
+      "blister_pack": {
+        "general_waste":              {"co2e_avoided_kg_per_kg": 0.0, "typical_unit_weight_kg": 0.005, "source": "baseline; multilayer non-recoverable"}
+      },
+      "sharps": {
+        "biomedical_waste_collector": {"co2e_avoided_kg_per_kg": -0.3, "typical_unit_weight_kg": 0.010, "source": "WHO 2014 (autoclave + incineration emits ~0.3 kg CO2e/kg). Footprint reported as *negative avoidance* — disposal is necessary safety-spend, not climate gain."}
+      },
+      "medicine_bottle": {
+        "pharmacy_takeback":          {"co2e_avoided_kg_per_kg": 0.05, "typical_unit_weight_kg": 0.015, "source": "Daughton & Ruhoy 2013 — primary value is avoided water-system contamination; CO2e contribution minor"}
+      },
+      "diagnostic": {
+        "biomedical_waste_collector": {"co2e_avoided_kg_per_kg": -0.3, "typical_unit_weight_kg": 0.001, "source": "WHO 2014 (small mass; safety-driven)"}
+      },
+      "wound_care": {
+        "general_waste":              {"co2e_avoided_kg_per_kg": 0.0, "typical_unit_weight_kg": 0.005, "source": "baseline"},
+        "biomedical_waste_collector": {"co2e_avoided_kg_per_kg": -0.3, "typical_unit_weight_kg": 0.005, "source": "WHO 2014"}
+      },
+      "packaging": {
+        "recycle_paper":              {"co2e_avoided_kg_per_kg": 0.7, "typical_unit_weight_kg": 0.010, "source": "EPA WARM (paperboard)"}
+      },
+      "device": {
+        "pharmacy_takeback":          {"co2e_avoided_kg_per_kg": 1.0, "typical_unit_weight_kg": 0.050, "source": "ICE + Andrae (medical-device average)"}
+      }
+    },
+    "cd": {
+      "concrete": {
+        "aggregate_recycler":         {"co2e_avoided_kg_per_kg": 0.05, "typical_unit_weight_kg": 5.0, "source": "ICE v3.0 (recycled aggregate vs. quarried; small per-kg, large per-tonne aggregated)"}
+      },
+      "brick": {
+        "aggregate_recycler":         {"co2e_avoided_kg_per_kg": 0.2, "typical_unit_weight_kg": 2.5, "source": "ICE v3.0 (clay brick reused)"}
+      },
+      "gypsum": {
+        "gypsum_recycler":            {"co2e_avoided_kg_per_kg": 0.04, "typical_unit_weight_kg": 10.0, "source": "USA Gypsum 2017 (drywall closed-loop)"}
+      },
+      "steel": {
+        "metal_recycler":             {"co2e_avoided_kg_per_kg": 1.5, "typical_unit_weight_kg": 5.0, "source": "ICE v3.0 (recycled steel vs. BOF virgin)"}
+      },
+      "plastic": {
+        "specialty_recycler":         {"co2e_avoided_kg_per_kg": 1.4, "typical_unit_weight_kg": 1.0, "source": "Hischier 2020 (PVC pipe recycling)"}
+      },
+      "ceramic": {
+        "aggregate_recycler":         {"co2e_avoided_kg_per_kg": 0.04, "typical_unit_weight_kg": 1.5, "source": "ICE (limited; aggregate downcycle)"}
+      },
+      "insulation": {
+        "specialty_recycler":         {"co2e_avoided_kg_per_kg": 0.3, "typical_unit_weight_kg": 0.5, "source": "Mineral wool LCA (Pargana 2014)"}
+      }
+    },
+    "textile": {
+      "cotton_garment": {
+        "resale_reuse":               {"co2e_avoided_kg_per_kg": 8.0, "typical_unit_weight_kg": 0.300, "source": "Sandin & Peters 2018 (reuse displaces new garment manufacture, cotton)"},
+        "fiber_recycler":             {"co2e_avoided_kg_per_kg": 3.0, "typical_unit_weight_kg": 0.300, "source": "Hawley 2014 (cotton fiber reclamation)"}
+      },
+      "denim": {
+        "fiber_recycler":             {"co2e_avoided_kg_per_kg": 3.5, "typical_unit_weight_kg": 0.700, "source": "Cotton Inc Blue Jeans Go Green LCA 2018"},
+        "resale_reuse":               {"co2e_avoided_kg_per_kg": 8.0, "typical_unit_weight_kg": 0.700, "source": "Sandin & Peters 2018"}
+      },
+      "blended_garment": {
+        "downcycle_rags":             {"co2e_avoided_kg_per_kg": 1.5, "typical_unit_weight_kg": 0.300, "source": "Sandin 2018 (industrial rag stream displaces new wipes)"}
+      },
+      "synthetic_garment": {
+        "downcycle_rags":             {"co2e_avoided_kg_per_kg": 2.1, "typical_unit_weight_kg": 0.300, "source": "Hischier 2020 (polyester downcycle)"},
+        "resale_reuse":               {"co2e_avoided_kg_per_kg": 6.0, "typical_unit_weight_kg": 0.300, "source": "Sandin 2018 (synthetics reuse)"}
+      },
+      "wool_garment": {
+        "fiber_recycler":             {"co2e_avoided_kg_per_kg": 5.0, "typical_unit_weight_kg": 0.500, "source": "Wiedemann 2020 (wool LCA, Australian flock)"},
+        "resale_reuse":               {"co2e_avoided_kg_per_kg": 12.0, "typical_unit_weight_kg": 0.500, "source": "Wiedemann 2020"}
+      },
+      "leather": {
+        "leather_reclaim":            {"co2e_avoided_kg_per_kg": 4.0, "typical_unit_weight_kg": 0.200, "source": "FAO 2019 (leather recovery, conservative)"}
+      },
+      "mixed_fabric_scrap": {
+        "downcycle_rags":             {"co2e_avoided_kg_per_kg": 1.5, "typical_unit_weight_kg": 0.300, "source": "Sandin 2018"}
+      }
+    }
+  }
+}

spec/examples/README.md

@@ -0,0 +1,34 @@
+# Matter Passport — Example Library
+
+Reference Passports produced by running the **real MIE pipeline** (validator → calibration → hazard auto-flagger → do_not guardrail) on synthetic model outputs designed to exercise each platform primitive. Every file in this directory is schema-valid against `spec/matter-passport-v0.1.schema.json`. Released CC0-1.0 alongside the schema.
+
+Volatile fields (timestamp, content_hash, passport_id) are stabilized to deterministic placeholders so the files are stable under git.
+
+| File | Demonstrates |
+|---|---|
+| [`passport-01-domestic-pet-bottle.json`](passport-01-domestic-pet-bottle.json) | Happy path — clean PET bottle correctly routed to NYC blue bin. No guardrail; no fallback. |
+| [`passport-02-medical-sharps-hazards-auto-flagged.json`](passport-02-medical-sharps-hazards-auto-flagged.json) | A6 regression — model emitted only sharps_injury_risk; the auto-flagger appends biohazard. |
+| [`passport-03-medical-glucose-strip-guardrail-fires.json`](passport-03-medical-glucose-strip-guardrail-fires.json) | A6 save — model proposed general_waste for a contaminated diagnostic; guardrail overrode it. |
+| [`passport-04-ev-18650-cell.json`](passport-04-ev-18650-cell.json) | EV cell with state-of-health estimate and class-implied thermal_runaway_risk auto-flag. |
+| [`passport-05-ewaste-laptop.json`](passport-05-ewaste-laptop.json) | Laptop routed to the SAFE Disposal e-waste collection event. |
+| [`passport-06-cd-concrete-with-recovery-value.json`](passport-06-cd-concrete-with-recovery-value.json) | Construction & Demolition — concrete chunk with economic + environmental value. |
+| [`passport-07-textile-denim.json`](passport-07-textile-denim.json) | Higg-MSI-aligned taxonomy — denim routed to fiber recycler (Cotton Inc Blue Jeans Go Green). |
+
+## How these were generated
+
+```
+uv run python scripts/generate_example_passports.py
+```
+
+The script runs each scenario's synthetic model output through the actual
+`matter.engine.MIE` pipeline. Anything that lands in these files is exactly
+what consumers would see from a real runtime — so you can use them as fixtures
+for SDK tests, UI mockups, or downstream validators.
+
+## Decision references
+
+- D012 — JSON + enum validator
+- D015 — calibration (`spec/calibration_v1.json`)
+- D018 + D020 — do_not guardrail (`spec/safety_rules_v1.json`)
+- D019 — class-implied hazard auto-flagger (`spec/hazard_flags_v1.json`)
+- D023 — schema v0.1 frozen for CC0

spec/examples/passport-01-domestic-pet-bottle.json

@@ -0,0 +1,43 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:dd6b5b42f266910a",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:dd6b5b42f266910a...(truncated)"
+  },
+  "identity": {
+    "class": "plastic_bottle",
+    "subclass": "PET water bottle",
+    "taxonomy": "https://matter.spec/taxonomy/domestic/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "good",
+    "hazard_flags": [],
+    "confidence": 0.375
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": 0.045,
+      "basis": "co2e_factors_v1[domestic/plastic_bottle/blue_bin_recycle] (+1.50 kg CO2e/kg \u00d7 0.030 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "blue_bin_recycle",
+    "do_not": [],
+    "confidence": 0.375,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (DSNY + NY EPR)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-02-medical-sharps-hazards-auto-flagged.json

@@ -0,0 +1,49 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:1a6d39db2c0e7e0f",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:1a6d39db2c0e7e0f...(truncated)"
+  },
+  "identity": {
+    "class": "sharps",
+    "subclass": "syringe with needle",
+    "taxonomy": "https://matter.spec/taxonomy/medical/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "contaminated",
+    "hazard_flags": [
+      "sharps_injury_risk",
+      "biohazard"
+    ],
+    "confidence": 0.375
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": -0.003,
+      "basis": "co2e_factors_v1[medical/sharps/biomedical_waste_collector] (-0.30 kg CO2e/kg \u00d7 0.010 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "biomedical_waste_collector",
+    "do_not": [
+      "general_waste",
+      "blue_bin_recycle"
+    ],
+    "confidence": 0.375,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (CPCB + NY DOH biomedical waste rules)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-03-medical-glucose-strip-guardrail-fires.json

@@ -0,0 +1,47 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:71cdbc8416d761bc",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:71cdbc8416d761bc...(truncated)"
+  },
+  "identity": {
+    "class": "diagnostic",
+    "subclass": "blood glucose test strip",
+    "taxonomy": "https://matter.spec/taxonomy/medical/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "contaminated",
+    "hazard_flags": [
+      "biohazard"
+    ],
+    "confidence": 0.375
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": -0.0003,
+      "basis": "co2e_factors_v1[medical/diagnostic/biomedical_waste_collector] (-0.30 kg CO2e/kg \u00d7 0.001 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "biomedical_waste_collector",
+    "do_not": [
+      "general_waste"
+    ],
+    "confidence": 0.9,
+    "fallback_used": true
+  },
+  "routing": {
+    "jurisdiction": "NYC (CPCB + NY DOH biomedical waste rules)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-04-ev-18650-cell.json

@@ -0,0 +1,49 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:8bc13c3e392f5f71",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:8bc13c3e392f5f71...(truncated)"
+  },
+  "identity": {
+    "class": "lithium_ion_cell",
+    "subclass": "NMC 18650",
+    "taxonomy": "https://matter.spec/taxonomy/ev/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "degraded",
+    "hazard_flags": [
+      "thermal_runaway_risk"
+    ],
+    "confidence": 0.85
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": 0.4,
+      "basis": "co2e_factors_v1[ev/lithium_ion_cell/second_life_stationary_storage] (+8.00 kg CO2e/kg \u00d7 0.050 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "second_life_stationary_storage",
+    "secondary": "battery_drop_off",
+    "do_not": [
+      "general_waste",
+      "landfill"
+    ],
+    "confidence": 0.85,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (DSNY + NY EPR)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-05-ewaste-laptop.json

@@ -0,0 +1,46 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:73e6c748e167e518",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:73e6c748e167e518...(truncated)"
+  },
+  "identity": {
+    "class": "laptop",
+    "subclass": "Lenovo ThinkPad-class notebook",
+    "taxonomy": "https://matter.spec/taxonomy/ewaste/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "degraded",
+    "hazard_flags": [],
+    "confidence": 0.9
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": 70.0,
+      "basis": "co2e_factors_v1[ewaste/laptop/ewaste_collection_event] (+35.00 kg CO2e/kg \u00d7 2.000 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "ewaste_collection_event",
+    "secondary": "retailer_takeback",
+    "do_not": [
+      "general_waste"
+    ],
+    "confidence": 0.375,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (DSNY + NY EPR)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-06-cd-concrete-with-recovery-value.json

@@ -0,0 +1,45 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:7b05677dedf22215",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:7b05677dedf22215...(truncated)"
+  },
+  "identity": {
+    "class": "concrete",
+    "subclass": "structural rubble",
+    "taxonomy": "https://matter.spec/taxonomy/cd/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "good",
+    "hazard_flags": [],
+    "confidence": 0.375
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": 0.25,
+      "basis": "co2e_factors_v1[cd/concrete/aggregate_recycler] (+0.05 kg CO2e/kg \u00d7 5.000 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "aggregate_recycler",
+    "do_not": [
+      "landfill"
+    ],
+    "confidence": 0.375,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (Local Law 97 + DEP construction debris rules)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/examples/passport-07-textile-denim.json

@@ -0,0 +1,46 @@
+{
+  "schema": "matter-passport/v0.1",
+  "passport_id": "mp_sha256:a0d738e5d571843a",
+  "timestamp": "2026-04-26T00:00:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:a0d738e5d571843a...(truncated)"
+  },
+  "identity": {
+    "class": "denim",
+    "subclass": "blue jeans scrap",
+    "taxonomy": "https://matter.spec/taxonomy/textile/v0.1",
+    "confidence": 0.9142857142857143
+  },
+  "state": {
+    "condition": "degraded",
+    "hazard_flags": [],
+    "confidence": 0.9
+  },
+  "value": {
+    "environmental": {
+      "co2e_avoided_kg": 2.45,
+      "basis": "co2e_factors_v1[textile/denim/fiber_recycler] (+3.50 kg CO2e/kg \u00d7 0.700 kg) [typical unit weight]"
+    }
+  },
+  "next_best_action": {
+    "primary": "fiber_recycler",
+    "secondary": "resale_reuse",
+    "do_not": [
+      "landfill"
+    ],
+    "confidence": 0.9,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "NYC (NY EPR Packaging + Higg MSI alignment)",
+    "regulation_refs": []
+  },
+  "provenance": {
+    "model": "matter-examples/static@v0.1",
+    "runtime": "other",
+    "on_device": false,
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@<sha256-of-spec/calibration_v1.json>"
+  }
+}

spec/governance.md

@@ -0,0 +1,54 @@
+# Matter Passport — Governance
+
+**Status:** v0.1 governance proposal · **License:** CC0-1.0
+
+## Stewardship today
+
+The Matter Passport schema (`matter-passport-v0.1`) and its companion CC0 artifacts (`calibration_v1.json`, `safety_rules_v1.json`, `hazard_flags_v1.json`) are currently maintained by the Matter project's solo author for the Gemma 4 Impact Challenge submission.
+
+This is not a permanent arrangement. The schema is intended to be a public good and should not depend on a single individual indefinitely.
+
+## Stewardship after v1.0
+
+When the Matter Passport reaches `v1.0`, stewardship will be proposed to a neutral body. Candidates, in rough order of preference:
+
+1. **Open Source Initiative (OSI)** — natural home for an open standard with an open license stack.
+2. **Linux Foundation Energy / LF Decentralized Trust** — has hosted similar schema work (e.g., Battery Passport).
+3. **The CIRPASS consortium** — directly aligned mission; would also strengthen DPP interop.
+4. **A new dedicated foundation** — only if none of the above accept stewardship.
+
+The author commits to reaching out to at least two of these bodies within 60 days of v1.0 release.
+
+## Contribution policy (today through v1.0)
+
+- **Issues and proposals:** open via the project repository's issue tracker.
+- **Schema changes:** pull request against `spec/`. Must include rationale and a backwards-compatibility analysis.
+- **Companion-artifact changes** (calibration / safety / hazard rules): may version independently; bump artifact version, append a `changelog` block.
+- **Field additions:** must include the rationale, a reference to prior-art alignment (or explicit statement that the field is novel), and a sample Passport that exercises the new field.
+- **Field removals or semantic changes:** breaking change; require a major version bump and a 6-month deprecation window per `D023`.
+
+## Decision authority (interim)
+
+- **Maintainer:** the project author makes editorial decisions until v1.0.
+- **External review:** for any change deemed "load-bearing" (privacy, safety, signing semantics), at least one external reviewer must approve before merge. The reviewer's identity and feedback are recorded in the PR.
+- **Public-comment period:** any breaking change is announced with a 14-day comment window before merge.
+
+## Provenance commitments
+
+The Matter project commits to:
+
+1. **Honest evaluation disclosure.** Every Stage of the project's evaluation (Stage 0 N=43, Stage 1 target N=200) is documented in `findings/`. No cherry-picked numbers in the writeup.
+2. **Reproducibility.** Every published number must be reproducible from a public Kaggle or Colab notebook in this repository.
+3. **No retroactive redaction.** If a finding is wrong, we publish the correction; we do not silently delete.
+4. **Calibration honesty.** When the Passport's `confidence_calibrated: true` flag is set, the calibration table that produced it is publicly available.
+
+## Conflict of interest
+
+The maintainer is a solo individual with no current commercial product based on Matter. If that changes, the maintainer commits to:
+- Disclosing any commercial interest in the Matter platform on the project README.
+- Recusing from decisions that materially advantage that commercial interest, if any.
+- Stewardship handover (above) will be the structural answer.
+
+## License of this document
+
+This governance addendum is itself CC0-1.0 — fork it, reuse it, adapt it for other open standards.

spec/hazard_flags_v1.json

@@ -0,0 +1,16 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "description": "Class → canonical hazard_flags map (D019). Run before the do_not guardrail. Augments the model's hazard_flags rather than replacing them.",
+    "license": "CC0-1.0"
+  },
+  "rules": {
+    "sharps":            {"required": ["sharps_injury_risk", "biohazard"], "context_dependent": []},
+    "diagnostic":        {"required": ["biohazard"],                        "context_dependent": []},
+    "wound_care":        {"required": [],                                   "context_dependent": ["biohazard"]},
+    "medicine_bottle":   {"required": [],                                   "context_dependent": ["expired_pharmaceutical", "controlled_substance"]},
+    "lithium_ion_cell":  {"required": ["thermal_runaway_risk"],             "context_dependent": []},
+    "battery_pack":      {"required": ["thermal_runaway_risk"],             "context_dependent": []},
+    "lead_acid_battery": {"required": ["lead_toxicity", "acid_corrosion"],  "context_dependent": []}
+  }
+}

spec/jurisdictions/README.md

@@ -0,0 +1,30 @@
+# Matter Jurisdiction Packs
+
+CC0 routing rules per jurisdiction. Each pack defines per-(head, identity_class) the local default `next_best_action`, the locally-available NBA enum (extending the base set if the jurisdiction has unique infrastructure), regulation references, and infrastructure context.
+
+The MIE picks the right pack based on the `Capture.jurisdiction` field (or falls back to the default head-level rules in `safety_rules_v1.json`).
+
+## Shipping in v0.1
+
+| Pack | Code | Notable property |
+|---|---|---|
+| [`nyc.json`](nyc.json) | `US-NY-NYC` | Decentralized municipal pickup + retailer takeback + DSNY SAFE Disposal Days |
+| [`eu-dpp.json`](eu-dpp.json) | `EU` | Strong EPR; aligned with the upcoming Digital Product Passport mandate; higher fiber-recycler share for textiles |
+| [`pune.json`](pune.json) | `IN-MH-PUN` | Adds `informal_kabadi_pickup` as a first-class NBA — recognizes the recovery path most actually used in Pune. SWaCH cooperative integration. |
+
+Each pack is **self-contained** (no inheritance from a base file) so consumers can adopt one pack without loading the rest of Matter's spec.
+
+## Adding a new pack
+
+1. Copy `nyc.json` as a starting template.
+2. Update `_meta.jurisdiction_code` (use ISO 3166-2 where possible).
+3. Update `regulation_refs` with the local rule citations.
+4. Adjust `head_default_actions` per local infrastructure reality.
+5. Extend `actions_available` only if your jurisdiction has a recovery path that doesn't fit any existing NBA enum (Pune's `informal_kabadi_pickup` is the canonical example).
+6. Submit as a PR to `spec/jurisdictions/` — packs are versioned independently of the Passport schema.
+
+## What the packs are NOT
+
+- Not a replacement for `safety_rules_v1.json` — the do-not guardrail still runs as a global safety primitive.
+- Not legal advice — they're routing defaults built from public regulation citations and field-pilot context.
+- Not exhaustive — Stage 1 will add São Paulo, Lagos, Berlin, and Brooklyn (sub-municipal) packs as field-pilot evidence accumulates.

spec/jurisdictions/eu-dpp.json

@@ -0,0 +1,86 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "license": "CC0-1.0",
+    "jurisdiction_code": "EU",
+    "name": "European Union — Digital Product Passport scope",
+    "regulation_refs": [
+      "ESPR — EU Ecodesign for Sustainable Products Regulation (2024/1781)",
+      "EU Waste Framework Directive 2008/98/EC (consolidated 2018)",
+      "EU Battery Regulation 2023/1542 — battery passport mandatory 2027",
+      "EU Packaging and Packaging Waste Regulation (PPWR, 2024)",
+      "EU Strategy for Sustainable and Circular Textiles (2022)",
+      "WEEE Directive 2012/19/EU"
+    ],
+    "description": "EU-wide rules aligned with the Digital Product Passport (DPP) framework. Battery + electronics + textile DPPs become mandatory at staggered dates 2026–2030. Matter Passport is interop-shaped with DPP per spec/passport-prior-art.md."
+  },
+  "actions_available": [
+    "blue_bin_recycle", "compost_bin", "general_waste",
+    "retailer_takeback", "ewaste_collection_event", "battery_drop_off",
+    "second_life_stationary_storage", "certified_ev_recycler",
+    "pharmacy_takeback", "biomedical_waste_collector", "recycle_paper",
+    "aggregate_recycler", "metal_recycler", "gypsum_recycler", "specialty_recycler",
+    "resale_reuse", "fiber_recycler", "downcycle_rags", "leather_reclaim",
+    "special_collection", "landfill"
+  ],
+  "head_default_actions": {
+    "domestic": {
+      "plastic_bottle":     "blue_bin_recycle",
+      "multilayer_plastic": "special_collection",
+      "carton":             "blue_bin_recycle",
+      "metal_can":          "blue_bin_recycle",
+      "organic":            "compost_bin",
+      "glass":              "blue_bin_recycle",
+      "paper":              "blue_bin_recycle"
+    },
+    "ewaste": {
+      "laptop":          "retailer_takeback",
+      "smartphone":      "retailer_takeback",
+      "cable":           "retailer_takeback",
+      "power_adapter":   "retailer_takeback",
+      "audio":           "retailer_takeback",
+      "battery":         "battery_drop_off",
+      "pcb":             "ewaste_collection_event",
+      "lighting":        "retailer_takeback"
+    },
+    "ev": {
+      "lithium_ion_cell":   "second_life_stationary_storage",
+      "lead_acid_battery":  "certified_ev_recycler",
+      "battery_pack":       "certified_ev_recycler",
+      "connector":          "retailer_takeback",
+      "pcb":                "ewaste_collection_event"
+    },
+    "medical": {
+      "blister_pack":     "general_waste",
+      "sharps":           "biomedical_waste_collector",
+      "medicine_bottle":  "pharmacy_takeback",
+      "diagnostic":       "biomedical_waste_collector",
+      "wound_care":       "biomedical_waste_collector",
+      "packaging":        "recycle_paper",
+      "device":           "pharmacy_takeback"
+    },
+    "cd": {
+      "concrete":   "aggregate_recycler",
+      "brick":      "aggregate_recycler",
+      "gypsum":     "gypsum_recycler",
+      "steel":      "metal_recycler",
+      "plastic":    "specialty_recycler",
+      "ceramic":    "aggregate_recycler",
+      "insulation": "specialty_recycler"
+    },
+    "textile": {
+      "cotton_garment":      "resale_reuse",
+      "denim":               "fiber_recycler",
+      "blended_garment":     "fiber_recycler",
+      "synthetic_garment":   "fiber_recycler",
+      "wool_garment":        "fiber_recycler",
+      "leather":             "leather_reclaim",
+      "mixed_fabric_scrap":  "downcycle_rags"
+    }
+  },
+  "infrastructure_notes": {
+    "extended_producer_responsibility": "Strong — manufacturers fund collection + recovery for batteries, packaging, electronics, textiles (PPWR + WEEE + Battery Reg)",
+    "dpp_alignment": "Battery Reg makes DPP mandatory Feb 2027 for industrial + EV batteries; ESPR phases other categories 2026–2030",
+    "default_textile_path": "Higher fiber-recycler share than NYC because EU Textile Strategy mandates separate textile collection by 2025"
+  }
+}

spec/jurisdictions/nyc.json

@@ -0,0 +1,84 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "license": "CC0-1.0",
+    "jurisdiction_code": "US-NY-NYC",
+    "name": "New York City",
+    "regulation_refs": [
+      "DSNY — NYC Department of Sanitation Recycling Rules (2025)",
+      "NY State Environmental Conservation Law Article 27 — EPR Packaging (2025)",
+      "NYC Local Law 97 — Building Emissions (2024 enforcement)",
+      "NY State Battery Stewardship — Rechargeable Battery Recycling Act"
+    ],
+    "description": "NYC routing rules. Decentralized municipal pickup + retailer takeback + DSNY SAFE Disposal Days. Source-of-truth for matter routing on US-NY-NYC."
+  },
+  "actions_available": [
+    "blue_bin_recycle", "compost_bin", "general_waste",
+    "retailer_takeback", "ewaste_collection_event", "battery_drop_off",
+    "second_life_stationary_storage", "certified_ev_recycler",
+    "pharmacy_takeback", "biomedical_waste_collector", "recycle_paper",
+    "aggregate_recycler", "metal_recycler", "gypsum_recycler", "specialty_recycler",
+    "resale_reuse", "fiber_recycler", "downcycle_rags", "leather_reclaim",
+    "special_collection", "landfill"
+  ],
+  "head_default_actions": {
+    "domestic": {
+      "plastic_bottle":     "blue_bin_recycle",
+      "multilayer_plastic": "general_waste",
+      "carton":             "blue_bin_recycle",
+      "metal_can":          "blue_bin_recycle",
+      "organic":            "compost_bin",
+      "glass":              "blue_bin_recycle",
+      "paper":              "blue_bin_recycle"
+    },
+    "ewaste": {
+      "laptop":          "ewaste_collection_event",
+      "smartphone":      "retailer_takeback",
+      "cable":           "retailer_takeback",
+      "power_adapter":   "ewaste_collection_event",
+      "audio":           "retailer_takeback",
+      "battery":         "battery_drop_off",
+      "pcb":             "ewaste_collection_event",
+      "lighting":        "retailer_takeback"
+    },
+    "ev": {
+      "lithium_ion_cell":   "battery_drop_off",
+      "lead_acid_battery":  "certified_ev_recycler",
+      "battery_pack":       "certified_ev_recycler",
+      "connector":          "retailer_takeback",
+      "pcb":                "ewaste_collection_event"
+    },
+    "medical": {
+      "blister_pack":     "general_waste",
+      "sharps":           "biomedical_waste_collector",
+      "medicine_bottle":  "pharmacy_takeback",
+      "diagnostic":       "biomedical_waste_collector",
+      "wound_care":       "general_waste",
+      "packaging":        "recycle_paper",
+      "device":           "pharmacy_takeback"
+    },
+    "cd": {
+      "concrete":   "aggregate_recycler",
+      "brick":      "aggregate_recycler",
+      "gypsum":     "gypsum_recycler",
+      "steel":      "metal_recycler",
+      "plastic":    "specialty_recycler",
+      "ceramic":    "aggregate_recycler",
+      "insulation": "specialty_recycler"
+    },
+    "textile": {
+      "cotton_garment":      "resale_reuse",
+      "denim":               "fiber_recycler",
+      "blended_garment":     "downcycle_rags",
+      "synthetic_garment":   "downcycle_rags",
+      "wool_garment":        "fiber_recycler",
+      "leather":             "leather_reclaim",
+      "mixed_fabric_scrap":  "downcycle_rags"
+    }
+  },
+  "infrastructure_notes": {
+    "pickup_cadence": "Curbside weekly; organics weekly post-2025 mandate; SAFE Disposal Days quarterly per borough",
+    "informal_sector": "Active but unregulated — bottle-deposit canners (NY $0.05/container)",
+    "key_partners_for_pilot": ["LES Ecology Center", "Sure We Can (Brooklyn)", "Big Reuse"]
+  }
+}

spec/jurisdictions/pune.json

@@ -0,0 +1,88 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "license": "CC0-1.0",
+    "jurisdiction_code": "IN-MH-PUN",
+    "name": "Pune — Maharashtra, India",
+    "regulation_refs": [
+      "Plastic Waste Management Rules, 2016 (amended 2022) — India",
+      "Battery Waste Management Rules, 2022 — India",
+      "E-Waste (Management) Rules, 2022 — India",
+      "Solid Waste Management Rules, 2016 — India",
+      "Bio-Medical Waste Management Rules, 2016 — CPCB",
+      "PMC Pune Municipal Corporation source-segregation by-laws (2017)"
+    ],
+    "description": "Pune routing rules. Decentralized informal-sector recovery (SWaCH cooperative) overlaid on PMC kerbside collection. Different infrastructure shape from NYC + EU — denser informal recovery, smaller formal recycler footprint."
+  },
+  "actions_available": [
+    "blue_bin_recycle", "compost_bin", "general_waste",
+    "retailer_takeback", "ewaste_collection_event", "battery_drop_off",
+    "second_life_stationary_storage", "certified_ev_recycler",
+    "pharmacy_takeback", "biomedical_waste_collector", "recycle_paper",
+    "aggregate_recycler", "metal_recycler", "gypsum_recycler", "specialty_recycler",
+    "resale_reuse", "fiber_recycler", "downcycle_rags", "leather_reclaim",
+    "special_collection", "landfill",
+    "informal_kabadi_pickup"
+  ],
+  "head_default_actions": {
+    "domestic": {
+      "plastic_bottle":     "informal_kabadi_pickup",
+      "multilayer_plastic": "general_waste",
+      "carton":             "informal_kabadi_pickup",
+      "metal_can":          "informal_kabadi_pickup",
+      "organic":            "compost_bin",
+      "glass":              "informal_kabadi_pickup",
+      "paper":              "informal_kabadi_pickup"
+    },
+    "ewaste": {
+      "laptop":          "ewaste_collection_event",
+      "smartphone":      "informal_kabadi_pickup",
+      "cable":           "informal_kabadi_pickup",
+      "power_adapter":   "ewaste_collection_event",
+      "audio":           "informal_kabadi_pickup",
+      "battery":         "battery_drop_off",
+      "pcb":             "ewaste_collection_event",
+      "lighting":        "ewaste_collection_event"
+    },
+    "ev": {
+      "lithium_ion_cell":   "certified_ev_recycler",
+      "lead_acid_battery":  "certified_ev_recycler",
+      "battery_pack":       "certified_ev_recycler",
+      "connector":          "informal_kabadi_pickup",
+      "pcb":                "ewaste_collection_event"
+    },
+    "medical": {
+      "blister_pack":     "general_waste",
+      "sharps":           "biomedical_waste_collector",
+      "medicine_bottle":  "pharmacy_takeback",
+      "diagnostic":       "biomedical_waste_collector",
+      "wound_care":       "biomedical_waste_collector",
+      "packaging":        "informal_kabadi_pickup",
+      "device":           "pharmacy_takeback"
+    },
+    "cd": {
+      "concrete":   "aggregate_recycler",
+      "brick":      "aggregate_recycler",
+      "gypsum":     "landfill",
+      "steel":      "informal_kabadi_pickup",
+      "plastic":    "specialty_recycler",
+      "ceramic":    "aggregate_recycler",
+      "insulation": "landfill"
+    },
+    "textile": {
+      "cotton_garment":      "resale_reuse",
+      "denim":               "resale_reuse",
+      "blended_garment":     "downcycle_rags",
+      "synthetic_garment":   "downcycle_rags",
+      "wool_garment":        "resale_reuse",
+      "leather":             "leather_reclaim",
+      "mixed_fabric_scrap":  "downcycle_rags"
+    }
+  },
+  "infrastructure_notes": {
+    "informal_sector": "Dominant. SWaCH (Solid Waste Collection & Handling) cooperative — ~3,800 waste pickers as registered service providers under PMC contracts.",
+    "kabadi_pickup": "Door-to-door scrap dealers (kabadiwallahs) buy paper, metal, rigid plastics, glass — material-specific pricing per kg.",
+    "informal_action_rationale": "Including 'informal_kabadi_pickup' as a first-class NBA explicitly recognizes the recovery path most actually used in Pune — pretending the formal blue-bin is the default would be unfair to actual practice and to informal-sector workers who do the recovery work.",
+    "key_partners_for_pilot": ["SWaCH Pune", "Hasiru Dala (Bengaluru — sister NGO)", "PMC ULB liaisons"]
+  }
+}

spec/matter-passport-v0.1.md

@@ -0,0 +1,135 @@
+# Matter Passport — v0.1
+
+**Status:** Frozen for CC0 release · **License:** CC0-1.0 · **Stewardship:** Matter project maintainers (governance handover proposed at v1.0)
+
+> A universal, content-addressed, jurisdiction-aware descriptor of a material at a point in its lifecycle.
+
+## Design principles
+
+1. **Append-only.** A Passport is a version in a chain (`prev` field). Not a mutable record. Aligns with EU DPP event-log pattern and W3C VC immutability.
+2. **Content-addressed.** Primary identity is `mp_sha256:` of the capture + identity block. Optional `gs1_alias` for items that carry a GTIN.
+3. **Per-field confidence.** `identity`, `state`, and `next_best_action` confidence are independent — these blocks fail independently in practice (A1 v2, A6 evidence). Calibration applies per-field.
+4. **Jurisdiction-aware.** Regulation references travel with the Passport; rule contents are versioned separately and resolved at consumption (DPP pattern).
+5. **Provenance-honest.** Every Passport declares the model, runtime, on-device status, calibration table reference, and whether the safety guardrail fired.
+
+## Companion CC0 artifacts (versioned independently)
+
+| File | Purpose | Decision ref |
+|---|---|---|
+| `matter-passport-v0.1.schema.json` | JSON Schema validator | this document |
+| `passport-prior-art.md` | Alignment with DPP / CIRPASS / W3C VC / GS1 / GTR-22 | this document |
+| `calibration_v1.json` | Confidence calibration table (histogram, fit on N=43) | D015 |
+| `safety_rules_v1.json` | do_not guardrail rules per identity class | D018 |
+| `hazard_flags_v1.json` | Class → canonical hazard map | D019 |
+
+## Example
+
+```json
+{
+  "schema": "matter-passport/v0.1",
+  "@context": "https://matter.spec/contexts/v0.1.jsonld",
+  "passport_id": "mp_sha256:9f2e...c4",
+  "prev": null,
+  "timestamp": "2026-04-15T08:12:00Z",
+  "capture": {
+    "modality": "image",
+    "content_hash": "sha256:7af1...",
+    "geohash_coarse": "dr5"
+  },
+  "identity": {
+    "class": "lithium_ion_cell",
+    "subclass": "NMC_18650",
+    "taxonomy": "https://matter.spec/taxonomy/ev/v0.1",
+    "confidence": 0.91
+  },
+  "state": {
+    "condition": "degraded",
+    "estimated_soh": 0.62,
+    "contamination": null,
+    "hazard_flags": ["thermal_runaway_risk", "biohazard_if_punctured"],
+    "confidence": 0.74
+  },
+  "value": {
+    "economic": {"amount": 180, "currency": "INR", "basis": "scrap_cobalt_index_2026w15"},
+    "environmental": {"co2e_avoided_kg": 4.2, "basis": "IPCC_AR6_recycling_factor"}
+  },
+  "next_best_action": {
+    "primary": "second_life_stationary_storage",
+    "secondary": "certified_ev_recycler",
+    "do_not": ["landfill", "general_waste", "blue_bin_recycle"],
+    "confidence": 0.83,
+    "fallback_used": false
+  },
+  "routing": {
+    "jurisdiction": "IN-MH-PUN",
+    "regulation_refs": ["BWMR_2022", "EPR_batteries_2022"],
+    "function_call": "dispatch_certified_ev_recycler"
+  },
+  "provenance": {
+    "model": "gemma-4-e4b@unsloth-bnb-4bit",
+    "runtime": "cactus",
+    "on_device": true,
+    "lora": "matter-ev/v0.1@sha256:ab12...",
+    "confidence_calibrated": true,
+    "calibration_ref": "histogram@sha256:c4d1..."
+  },
+  "signature": null
+}
+```
+
+## Confidence calibration (D015)
+
+`confidence` is a first-class Passport field. Because general-purpose vision-language models (Gemma 4 included) produce systematically over-confident self-reported confidences at zero-shot, consumers of a Passport must know whether a confidence has been recalibrated against held-out data.
+
+- If `provenance.confidence_calibrated` is `true`, every `confidence` field has been passed through the function identified by `provenance.calibration_ref`. Calibrated confidences approximate posterior probabilities and are comparable across Passports produced by the same method + table.
+- If `false`, confidences are raw model outputs — comparable within a single Passport but not interpretable as probabilities, not comparable across runtimes or heads.
+
+Calibration tables version independently of the schema. v0.1 ships `calibration_v1.json` (histogram method, fit on N=43, in-sample ECE 0.000 / 5-fold CV-ECE 0.167). Stage 1 will refit on N≥200.
+
+## Safety primitives (D018, D019, D020)
+
+The MIE pipeline runs **four layered platform primitives** before emitting a Passport:
+
+```
+Gemma 4 raw output
+  → JSON + enum validator         (D012)
+  → calibration                   (D015 — calibration_v1.json)
+  → hazard auto-flagger           (D019 — hazard_flags_v1.json)
+  → do_not guardrail              (D018 — safety_rules_v1.json)
+  → Material Passport
+```
+
+`hazard_flags` on a Passport is the **union** of model-emitted and class-implied hazards. `next_best_action.fallback_used = true` indicates the guardrail overrode the model's NBA because it violated the item's `do_not` set; in that case `primary` is a safe-default action, not the raw model output.
+
+## Privacy
+
+`capture.geohash_coarse` is **optional**, **maximum 5 characters** (~4.9 km precision), and **excluded by default**. Consumers MUST NOT combine `geohash_coarse` + `timestamp` + `identity` for individual tracking. GDPR-compliant by design.
+
+## Resolved design decisions (v0.1)
+
+| Question | Resolution | Rationale |
+|---|---|---|
+| Stateful vs append-only | Append-only via `prev` chain | DPP / W3C VC / ISO 59040 |
+| Identity scheme | Content-hash primary; optional `gs1_alias` | Captures, not products; GS1 only when GTIN visible |
+| Confidence representation | Per-field on identity / state / NBA | A1 v2, A6 — these blocks fail independently |
+| Jurisdiction grounding | Embed `regulation_refs`; resolve rules at consumption | DPP pattern |
+| Signing | Optional in v0.1; W3C VC `proof` shape when present | Aligns with VC ecosystem; sets v0.2 path to full VC envelope |
+| Wire format | JSON Schema mandatory; optional `@context` for JSON-LD | Validation everywhere; JSON-LD as upgrade path |
+| Versioning | SemVer, `v0.x` until 1.0 | Industry standard |
+| Embedded vs referenced taxonomy | Referenced via URI | Lighter Passport; taxonomy evolves independently |
+| `geohash_coarse` privacy | Optional, max 5 chars, excluded by default | GDPR principle |
+| Chain of custody | Existing `prev` field | DPP event-log pattern |
+| Multi-material Passports | Defer to v0.2 via `components` array | Complexity not justified for v0.1 |
+
+## Stage 1 / v0.2 commitments
+
+- Full W3C VC envelope wrapping (Matter Passport as `credentialSubject`)
+- `components` array for multi-material items (laptop with 20 sub-Passports, building with 200)
+- ISO 59040 PCDS export profile
+- JSON-LD context document at `spec/contexts/v0.1.jsonld`
+- Calibration table refit on N ≥ 200 with native-speaker review of multilingual data
+- Stewardship handover proposal to a neutral body (OSI / Linux Foundation candidates)
+
+## Governance
+
+v0.x is maintained by the Matter project. Outside contributions via PR on `spec/`. After v1.0, stewardship is proposed to move to a neutral body. Breaking schema changes require a major version bump and a 6-month deprecation window.

spec/matter-passport-v0.1.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://matter.spec/matter-passport/v0.1.schema.json",
+  "title": "Matter Passport",
+  "description": "v0.1 — a universal, content-addressed, jurisdiction-aware descriptor of a material at a point in its lifecycle. Aligns with EU DPP / CIRPASS layering and W3C Verifiable Credentials proof shape. CC0-1.0.",
+  "type": "object",
+  "required": ["schema", "passport_id", "timestamp", "capture", "identity", "state", "next_best_action", "provenance"],
+  "properties": {
+    "schema": {"const": "matter-passport/v0.1"},
+    "@context": {
+      "type": ["string", "array"],
+      "description": "Optional JSON-LD context for downstream interop with EU DPP and W3C Verifiable Credentials. Recommended URI when present: 'https://matter.spec/contexts/v0.1.jsonld'."
+    },
+    "passport_id": {
+      "type": "string",
+      "pattern": "^mp_sha256:[0-9a-f]{6,64}$",
+      "description": "Content-addressed identifier derived from sha256(capture.content_hash || identity.class || timestamp)."
+    },
+    "prev": {
+      "type": ["string", "null"],
+      "description": "passport_id of the prior version in this material's lifecycle chain. Null for the first scan. Enables append-only chain-of-custody (CIRPASS dynamic-data layer)."
+    },
+    "timestamp": {"type": "string", "format": "date-time"},
+    "capture": {
+      "type": "object",
+      "required": ["modality", "content_hash"],
+      "properties": {
+        "modality": {"enum": ["image", "video", "text", "audio", "multimodal"]},
+        "content_hash": {"type": "string"},
+        "geohash_coarse": {
+          "type": "string",
+          "maxLength": 5,
+          "description": "Optional, MAX 5 characters (~4.9 km precision). Excluded by default for privacy. Consumers MUST NOT combine with timestamp + identity for individual tracking."
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "required": ["class", "taxonomy", "confidence"],
+      "properties": {
+        "class": {"type": "string"},
+        "subclass": {"type": "string"},
+        "taxonomy": {"type": "string", "description": "URI to the taxonomy version, e.g. 'matter-ev/v0.1'. Resolved at consumption."},
+        "gs1_alias": {
+          "type": "string",
+          "description": "Optional GS1 Digital Link URL when a GTIN is visible on the item. Format per GS1 Digital Link spec."
+        },
+        "confidence": {"type": "number", "minimum": 0, "maximum": 1}
+      }
+    },
+    "state": {
+      "type": "object",
+      "required": ["condition", "confidence"],
+      "properties": {
+        "condition": {"type": "string"},
+        "estimated_soh": {"type": "number", "minimum": 0, "maximum": 1, "description": "State-of-Health for batteries; aligns with UNECE GTR-22 vocabulary."},
+        "contamination": {"type": ["string", "null"]},
+        "hazard_flags": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Union of model-emitted and class-implied hazards. See spec/hazard_flags_v1.json for canonical class → hazards mapping."
+        },
+        "confidence": {"type": "number", "minimum": 0, "maximum": 1}
+      }
+    },
+    "value": {
+      "type": "object",
+      "properties": {
+        "economic": {
+          "type": "object",
+          "properties": {
+            "amount": {"type": "number"},
+            "currency": {"type": "string"},
+            "basis": {"type": "string"}
+          }
+        },
+        "environmental": {
+          "type": "object",
+          "properties": {
+            "co2e_avoided_kg": {"type": "number"},
+            "basis": {"type": "string"}
+          }
+        }
+      }
+    },
+    "next_best_action": {
+      "type": "object",
+      "required": ["primary", "confidence"],
+      "properties": {
+        "primary": {"type": "string"},
+        "secondary": {"type": "string"},
+        "do_not": {"type": "array", "items": {"type": "string"}},
+        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+        "fallback_used": {
+          "type": "boolean",
+          "description": "True iff the MIE's rule-based guardrail overrode the model's proposed action because it violated the item's do_not set (per spec/safety_rules_v1.json). When true, `primary` is a safe-default action, not the raw model output."
+        }
+      }
+    },
+    "routing": {
+      "type": "object",
+      "properties": {
+        "jurisdiction": {"type": "string"},
+        "regulation_refs": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Embedded references to regulations; rule contents are versioned separately and resolved at consumption (DPP pattern)."
+        },
+        "function_call": {"type": "string"}
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["model", "runtime", "on_device"],
+      "properties": {
+        "model": {"type": "string"},
+        "runtime": {"enum": ["unsloth", "cactus", "litert", "llama.cpp", "mlx", "ollama", "other"]},
+        "on_device": {"type": "boolean"},
+        "lora": {"type": "string"},
+        "confidence_calibrated": {
+          "type": "boolean",
+          "description": "True iff all `confidence` fields in this Passport have been passed through a published calibration function. False means the confidences are raw model outputs and MUST NOT be interpreted as probabilities."
+        },
+        "calibration_ref": {
+          "type": "string",
+          "description": "Identifier of the calibration table applied, of the form `<method>@<sha256-prefix>`. Resolvable via spec/calibration_v1.json. Required iff confidence_calibrated is true."
+        }
+      }
+    },
+    "signature": {
+      "oneOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "description": "Optional cryptographic proof. When present, follows W3C Verifiable Credentials proof shape so a Matter Passport may be wrapped as a VC credentialSubject in v0.2.",
+          "required": ["type", "created", "verificationMethod", "proofValue"],
+          "properties": {
+            "type": {"type": "string", "description": "e.g. 'Ed25519Signature2020'"},
+            "created": {"type": "string", "format": "date-time"},
+            "verificationMethod": {"type": "string", "description": "URI or DID identifying the signing key"},
+            "proofPurpose": {"type": "string"},
+            "proofValue": {"type": "string"}
+          }
+        }
+      ]
+    }
+  }
+}

spec/medical-disclaimer.md

@@ -0,0 +1,47 @@
+# Matter — Medical Disclaimer
+
+**Status:** Required text · **License:** CC0-1.0 · **Decision ref:** D018, D019
+
+Any UI surface that uses Matter's Medical head MUST display the following disclaimer before the user submits a query that would invoke the Medical head, and again on any returned Passport whose `identity.class` falls in the Medical head's taxonomy.
+
+The disclaimer text is the canonical English source. Translations are encouraged; the Matter project will host reviewed translations at `spec/medical-disclaimer/<lang>.md` once native review is complete.
+
+---
+
+## Required disclaimer (English source)
+
+> **Matter does not provide medical advice.**
+>
+> Matter helps identify pharmaceutical packaging, sharps, diagnostic items, and other medical-adjacent materials, and suggests how to dispose of them under local rules. It is **not** a substitute for advice from a doctor, pharmacist, nurse, or licensed medical waste hauler.
+>
+> If an item:
+> - is a used needle, syringe, or other sharps — **do not put it in regular trash.** Use a licensed biomedical waste collector. Matter's rule-based guardrail will block this in software, but you are still responsible for safe handling at the point of disposal.
+> - is an unidentified pill, capsule, or liquid — **do not handle, ingest, or pour it down a drain.** Take it to a pharmacy with a takeback program (US: DEA-approved kiosks; EU: pharmacist-managed disposal).
+> - has been in contact with bodily fluids — treat it as biomedical waste regardless of what Matter suggests.
+>
+> Matter's identification accuracy on medical items, as of v0.1, is documented in `findings/A6_analysis.md`. The model's self-reported confidence does **not** mean the suggestion is safe; the rule-based safety pipeline (`spec/safety_rules_v1.json`, `spec/hazard_flags_v1.json`) is what we ask you to trust, and even then only as a starting point.
+
+---
+
+## When this disclaimer must appear
+
+| Surface | Trigger | Display rule |
+|---|---|---|
+| Web demo | Domain selector includes "medical" | Modal on first medical query per session |
+| Android APK | Camera scan returns identity.class in Medical taxonomy | Inline panel above the Passport result |
+| API / SDK consumer | Passport returned with Medical taxonomy | Required as part of the SDK return-type docstring; SDK may NOT silently strip |
+| Demo video | A medical item appears on screen | On-screen text overlay for ≥2 seconds |
+
+## Why this is required (not optional)
+
+Two reasons:
+
+1. **A6 evidence.** Gemma 4 missed 5 of 8 expected biohazard flags in our medical evaluation. The model alone is not safe; the rules layer is what makes Matter trustworthy. Users must know the difference.
+2. **Gemma Prohibited Use Policy.** "No use for high-risk medical decisions without expert oversight." A clear disclaimer is the documented operational pattern that keeps Matter inside that line.
+
+## How to translate
+
+Translations are welcome via PR on `spec/medical-disclaimer/<lang>.md`. Translations MUST:
+- preserve the safety-critical bullets (sharps, unidentified pills, bodily fluids) verbatim in meaning.
+- be reviewed by a native speaker before merging.
+- include a `_meta.reviewer` field naming the reviewer.

spec/passport-prior-art.md

@@ -0,0 +1,83 @@
+# Matter Passport — Prior-Art Alignment
+
+**Status:** ships with `matter-passport/v0.1` · **License:** CC0-1.0
+
+This document maps Matter Passport v0.1 fields to existing standards. Published as part of the v0.1 release so consumers and reviewers can evaluate interoperability without reading the design history.
+
+## Standards in scope
+
+- **EU Digital Product Passport (DPP / ESPR 2024)** — EU regulatory framework
+- **CIRPASS** — EU consortium reference architecture for DPP
+- **W3C Verifiable Credentials (VC)** — cryptographic credential format
+- **GS1 Digital Link** — URL-based product identity
+- **ISO 59040** — Product Circularity Data Sheet (PCDS)
+- **UNECE GTR-22** — Global Technical Regulation for EV battery passports
+- **Schema.org Product** — generic product vocabulary
+
+## CIRPASS three-layer mapping
+
+CIRPASS organizes a Product Passport into identity / dynamic / static layers. Matter follows the same shape:
+
+| CIRPASS layer | Matter Passport blocks |
+|---|---|
+| Identity | `passport_id`, `prev`, `timestamp`, `capture`, `identity`, `provenance` |
+| Dynamic | `state`, `next_best_action`, `value`, `signature` |
+| Static | `routing`, `identity.taxonomy`, `routing.regulation_refs` |
+
+## Field-level alignment
+
+### `passport_id` and `prev`
+- **DPP:** event-log pattern — each event is a new entry referencing the prior. Matter's `prev` matches.
+- **W3C VC:** each credential is immutable; revocation handled separately. Matter aligns.
+
+### `identity.class` and `identity.taxonomy`
+- **CIRPASS:** taxonomy resolution via URI. Matter does the same — `taxonomy` is a URI, not embedded.
+- **Schema.org:** maps to `additionalType` for SEO interop. Optional via `@context`.
+
+### `identity.gs1_alias`
+- **GS1 Digital Link:** when an item carries a visible GTIN (e.g., a paracetamol box, a brand-new laptop), Matter optionally records the GS1 Digital Link URL alongside the content-hash identity. Most Matter items (a brick, a piece of rebar, a used syringe) have no GTIN — content-hash remains primary.
+
+### `identity.confidence`, `state.confidence`, `next_best_action.confidence`
+- **No prior-art equivalent.** Per-field confidence is novel for circular-economy schemas. A1 v2 + A6 evidence shows identity / state / action fail independently, so per-field is the only honest representation. Calibration table at `spec/calibration_v1.json` documents the meaning.
+
+### `state.estimated_soh`
+- **UNECE GTR-22:** State-of-Health for EV batteries. Direct field-level alignment. Stage 1 EV LoRA training will target GTR-22 vocabulary.
+
+### `state.hazard_flags`
+- **UNECE GTR-22:** hazardous-materials list for batteries.
+- **Matter extension:** generalizes to all domains (medical biohazards, C&D contaminants, etc.). Class-implied hazards documented in `spec/hazard_flags_v1.json`.
+
+### `next_best_action.do_not` and `fallback_used`
+- **No prior-art equivalent.** Matter's contribution. Documents safety-critical exclusions and whether the MIE's rule-based guardrail overrode a model recommendation. Rules at `spec/safety_rules_v1.json`.
+
+### `routing.regulation_refs`
+- **DPP:** regulation references travel with the Passport; rule contents resolved at consumption time. Matter follows this pattern.
+
+### `provenance.confidence_calibrated`, `provenance.calibration_ref`
+- **No prior-art equivalent.** Matter's contribution. AI inference is a first-class concern in Matter; DPP / CIRPASS assume manufacturer-emitted data, so calibration is moot for them. Required for honest AI provenance.
+
+### `signature`
+- **W3C VC `proof` block.** When present, Matter's `signature` shape mirrors the VC `proof` shape (`type`, `created`, `verificationMethod`, `proofValue`). v0.2 will likely add a full VC envelope wrapping option.
+
+### `@context`
+- **W3C VC + DPP / JSON-LD ecosystem.** Optional. When supplied, recommends `https://matter.spec/contexts/v0.1.jsonld` (to be published with v0.1 release).
+
+## What Matter is deliberately NOT adopting (and why)
+
+- **ISO 59040 PCDS** — 50+ binary attributes per item. Too heavyweight for a zero-shot inference model. Future export-format target, not input.
+- **Madaster building-passport schema** — closed commercial format. Matter's CC0 release is the explicit counter-positioning.
+- **Circularise supply-chain schema** — vendor-locked taxonomies. Same reason.
+
+## Stage 1 / v0.2 commitments
+
+- Full W3C VC envelope wrapping (Matter Passport as `credentialSubject`)
+- `components` array for multi-material items (laptop with 20 sub-Passports)
+- ISO 59040 PCDS export profile
+- JSON-LD context document at `spec/contexts/v0.1.jsonld`
+- Stewardship handover proposal to a neutral body (OSI / Linux Foundation candidates)
+
+## Versioning policy
+
+- SemVer: `vMAJOR.MINOR` until `v1.0`; then `vMAJOR.MINOR.PATCH`.
+- Breaking changes require a major version bump and a 6-month deprecation window.
+- Calibration tables, safety rules, and hazard rules version independently of the schema.

spec/safety_rules_v1.json

@@ -0,0 +1,82 @@
+{
+  "_meta": {
+    "version": "1.0",
+    "description": "Matter MIE do_not guardrail rules — per-identity-class safety constraints. Loaded by matter.guardrail.",
+    "jurisdiction_scope": "NYC (DSNY + NY EPR). Jurisdictions add overrides in spec/safety_rules_<region>.json.",
+    "license": "CC0-1.0"
+  },
+  "rules": {
+    "sharps": {
+      "do_not": ["general_waste", "recycle_paper", "blue_bin_recycle"],
+      "safe_default": "biomedical_waste_collector",
+      "severity": "critical",
+      "reason": "Sharps must only be disposed via licensed biomedical waste collection to prevent needle-stick injury and bloodborne pathogen transmission."
+    },
+    "diagnostic": {
+      "do_not": ["general_waste", "blue_bin_recycle"],
+      "safe_default": "biomedical_waste_collector",
+      "severity": "high",
+      "reason": "Blood- or bodily-fluid-contaminated diagnostic strips are biomedical waste."
+    },
+    "medicine_bottle": {
+      "do_not": ["general_waste"],
+      "safe_default": "pharmacy_takeback",
+      "severity": "high",
+      "reason": "Pharmaceuticals diverted from general waste prevent waterway contamination and misuse."
+    },
+    "blister_pack": {
+      "do_not": [],
+      "safe_default": "general_waste",
+      "severity": "informational",
+      "reason": "Multi-material blisters have no standard recovery path; general_waste is currently the honest default."
+    },
+    "wound_care": {
+      "do_not": ["blue_bin_recycle", "recycle_paper"],
+      "safe_default": "general_waste",
+      "severity": "high",
+      "reason": "Wound-care items can be biohazardous when used; the model cannot disambiguate used vs unused from a photo. Block recycling streams; users should manually route to biomedical_waste_collector if used."
+    },
+    "lithium_ion_cell": {
+      "do_not": ["general_waste", "landfill", "blue_bin_recycle"],
+      "safe_default": "battery_drop_off",
+      "severity": "critical",
+      "reason": "Lithium-ion cells can thermal-runaway in compactors and landfills; battery drop-off is mandatory."
+    },
+    "battery_pack": {
+      "do_not": ["general_waste", "landfill", "blue_bin_recycle"],
+      "safe_default": "certified_ev_recycler",
+      "severity": "critical",
+      "reason": "EV / e-bike battery packs require licensed recyclers due to hazardous materials and fire risk."
+    },
+    "lead_acid_battery": {
+      "do_not": ["general_waste", "landfill", "blue_bin_recycle"],
+      "safe_default": "certified_ev_recycler",
+      "severity": "critical",
+      "reason": "Lead-acid batteries contain regulated lead and sulfuric acid; retailer takeback is legally required in NY."
+    },
+    "concrete": {
+      "do_not": ["landfill"],
+      "safe_default": "aggregate_recycler",
+      "severity": "economic",
+      "reason": "Concrete is high-volume and economically recoverable; landfill diverts recoverable material."
+    },
+    "brick": {
+      "do_not": ["landfill"],
+      "safe_default": "aggregate_recycler",
+      "severity": "economic",
+      "reason": "Brick is reusable or crushable; landfill is environmentally and economically wasteful."
+    },
+    "steel": {
+      "do_not": ["landfill"],
+      "safe_default": "metal_recycler",
+      "severity": "economic",
+      "reason": "Steel has universal recycling markets; landfill destroys recoverable value."
+    },
+    "gypsum": {
+      "do_not": ["landfill"],
+      "safe_default": "gypsum_recycler",
+      "severity": "environmental",
+      "reason": "Landfilled gypsum generates hydrogen sulfide; clean drywall recovery exists in many markets."
+    }
+  }
+}

sync.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Sync upstream `matter/` package, `spec/` directory, and curated example images
+# into the Space directory. Run this BEFORE `git push` to ashu-1069/matter.
+set -euo pipefail
+
+SPACE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SPACE_DIR/.." && pwd)"
+
+echo "==> Syncing matter/ → space/matter/"
+rm -rf "$SPACE_DIR/matter"
+rsync -a --exclude="__pycache__" --exclude="*.pyc" "$REPO_DIR/matter/" "$SPACE_DIR/matter/"
+
+echo "==> Syncing spec/ → space/spec/"
+rm -rf "$SPACE_DIR/spec"
+rsync -a --exclude="__pycache__" "$REPO_DIR/spec/" "$SPACE_DIR/spec/"
+
+echo "==> Resizing + converting example images → space/examples/ (JPEG, max 1280px)"
+mkdir -p "$SPACE_DIR/examples"
+python3 - <<PY
+from PIL import Image
+from pathlib import Path
+src_dir = Path("$REPO_DIR/data/eval_seed/images")
+out_dir = Path("$SPACE_DIR/examples")
+out_dir.mkdir(parents=True, exist_ok=True)
+for f in [
+    "domestic_pet_bottle.png",
+    "ewaste_dead_laptop.png",
+    "ev_pouch_cell.png",
+    "medical_glucose_strip.png",
+    "cd_brick.png",
+    "textile_cotton_tshirt.png",
+]:
+    src = src_dir / f
+    if not src.exists():
+        print(f"    ⚠️  missing: {src}")
+        continue
+    img = Image.open(src).convert("RGB")
+    w, h = img.size
+    m = max(w, h)
+    if m > 1280:
+        r = 1280 / m
+        img = img.resize((int(w * r), int(h * r)), Image.LANCZOS)
+    out = out_dir / (src.stem + ".jpg")
+    img.save(out, "JPEG", quality=85, optimize=True)
+    print(f"    ✓ {out.name} ({out.stat().st_size // 1024} KB)")
+PY
+
+echo "✅ Space directory ready at: $SPACE_DIR"
+echo "   Push with:  cd $SPACE_DIR && git add -A && git commit -m 'sync' && git push"

transformers_runtime.py

@@ -0,0 +1,115 @@
+"""HuggingFace transformers runtime — implements matter.engine.Runtime.
+
+Loads Gemma 4 lazily on first inference (so cold Spaces serve the demo-mode path
+without ever paying the load cost) and wraps inference in @spaces.GPU so the
+Space's ZeroGPU pool only spins up while we're actually generating.
+
+Picks Gemma 4 E2B (5B, any-to-any, instruction-tuned) by default. Override via
+the MATTER_MODEL_ID Space secret.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+import torch
+from PIL import Image
+
+try:
+    import spaces  # type: ignore
+    HAS_SPACES = True
+except ImportError:
+    HAS_SPACES = False
+
+DEFAULT_MODEL_ID = os.environ.get("MATTER_MODEL_ID", "google/gemma-4-E2B-it")
+DEFAULT_MAX_NEW_TOKENS = int(os.environ.get("MATTER_MAX_NEW_TOKENS", "512"))
+DEFAULT_LORA_ID = os.environ.get("MATTER_LORA_ID", "").strip() or None
+
+
+def _gpu_decorator(fn):
+    """No-op when running locally (no `spaces` module), real decorator on HF."""
+    if HAS_SPACES:
+        return spaces.GPU(duration=90)(fn)
+    return fn
+
+
+class TransformersRuntime:
+    """Implements matter.engine.Runtime over HF transformers + Gemma 4."""
+
+    name: Literal["transformers"] = "transformers"
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL_ID,
+        max_new_tokens: int = DEFAULT_MAX_NEW_TOKENS,
+        lora_id: str | None = DEFAULT_LORA_ID,
+    ):
+        self.model_id = model
+        self.lora_id = lora_id
+        self.max_new_tokens = max_new_tokens
+        self._model = None
+        self._processor = None
+
+    def _ensure_loaded(self) -> None:
+        if self._model is not None:
+            return
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+
+        dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+
+        self._processor = AutoProcessor.from_pretrained(self.model_id)
+        self._model = AutoModelForImageTextToText.from_pretrained(
+            self.model_id,
+            torch_dtype=dtype,
+            device_map=device,
+        )
+        if self.lora_id:
+            try:
+                from peft import PeftModel
+                self._model = PeftModel.from_pretrained(self._model, self.lora_id)
+            except Exception as e:
+                print(f"[TransformersRuntime] LoRA load failed ({self.lora_id}): {e}")
+        self._model.eval()
+
+    def infer(self, prompt: str, image: Path | None) -> str:
+        return self._infer_gpu(prompt, str(image) if image is not None else None)
+
+    @_gpu_decorator
+    def _infer_gpu(self, prompt: str, image_path: str | None) -> str:
+        self._ensure_loaded()
+        proc = self._processor
+        model = self._model
+
+        content: list[dict] = []
+        if image_path:
+            content.append({"type": "image", "image": Image.open(image_path).convert("RGB")})
+        content.append({"type": "text", "text": prompt})
+        messages = [{"role": "user", "content": content}]
+
+        inputs = proc.apply_chat_template(
+            messages,
+            add_generation_prompt=True,
+            tokenize=True,
+            return_dict=True,
+            return_tensors="pt",
+        ).to(model.device)
+
+        with torch.no_grad():
+            out = model.generate(
+                **inputs,
+                max_new_tokens=self.max_new_tokens,
+                do_sample=False,
+                temperature=None,
+                top_p=None,
+            )
+
+        prompt_len = inputs["input_ids"].shape[-1]
+        generated = out[0][prompt_len:]
+        text = proc.decode(generated, skip_special_tokens=True)
+        return text
+
+
+__all__ = ["TransformersRuntime"]