Deploy verification service: scoring + advisory layer

.dockerignore

@@ -0,0 +1,21 @@
+# Keep the build context and the image small.
+#
+# Cloud Build uploads the context before building, and Artifact Registry's free
+# tier is 0.5 GB, so anything shipped here is paid for twice: once in upload
+# time on a Ghanaian connection, once in storage.
+
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# Tests and the attack harness are developer tools. They are run from a
+# checkout against the live database, never from inside the container, and
+# attack_set.py in particular must not be trivially runnable on the server.
+test_*.py
+attack_set.py
+calibrate.py
+
+.env
+.env.*
+*.md

Dockerfile

@@ -0,0 +1,55 @@
+# One container, no vendor lock-in. Runs on Cloud Run, Render, a Hugging Face
+# Space, or a laptop. Nothing in here is specific to a host.
+FROM python:3.11-slim
+
+# OpenCV needs these even in the headless build.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Run as uid 1000 with a writable $HOME. Hugging Face Spaces requires exactly
+# this, and without a writable HOME huggingface_hub cannot write its model
+# cache and the container dies on first request with a permission error that
+# reads like a network failure.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    PYTHONUNBUFFERED=1
+
+WORKDIR $HOME/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user . .
+
+# BAKE THE MODEL INTO THE IMAGE. This is the difference between a live demo and
+# ninety seconds of dead air on stage.
+#
+# Cloud Run scales to zero, so the first request after idle starts a cold
+# container. If the weights are not already present, that request also waits on
+# a ~90 MB download from Hugging Face before it can score anything. Downloading
+# at BUILD time moves that cost to a machine nobody is watching, and cold start
+# becomes container boot plus ONNX session init.
+#
+# It also removes a runtime dependency on huggingface.co being reachable and
+# not rate-limiting, which is not a thing to discover during a pitch.
+#
+# Costs ~90 MB of image size. Artifact Registry's free tier is 0.5 GB, so this
+# may tip storage into a few cents a month. Worth it.
+RUN python -c "from greenproof_ml.embed import _model_path; print('baked:', _model_path())"
+
+EXPOSE 7860
+
+# One worker deliberately: the ONNX session is per-process and ~90 MB of
+# weights, and check-in traffic is a handful of requests per round. Two workers
+# would double memory to serve a queue that is never deep.
+#
+# SHELL FORM, so ${PORT} is expanded at runtime. Every container host injects
+# the port it wants on a different variable-or-default convention, and the
+# exec form ["uvicorn", ...] would pass the literal string "${PORT}" and the
+# container would die on boot with an unreadable error. 7860 is the fallback.
+CMD uvicorn app:app --host 0.0.0.0 --port ${PORT:-7860} --workers 1

README.md

@@ -1,11 +1,112 @@
----
-title: Greenproof Ml
-emoji: ⚡
-colorFrom: yellow
-colorTo: gray
-sdk: docker
-pinned: false
-short_description: Greenproof
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: GreenProof Verification
+emoji: 🌳
+colorFrom: green
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# GreenProof verification service
+
+Scores a tree check-in and writes back a confidence, a verdict and a per-signal
+breakdown. The only server-side surface in the stack.
+
+## Why this exists
+
+Everything else in GreenProof is Supabase called directly from the browser. This
+service exists for one reason: **a client-computed verification result is
+forgeable.** The anon key ships inside the PWA and must be assumed public, so
+`confidence`, `verdict` and `signals` are not granted to `authenticated` at the
+column level. This process holds the only key that can write them.
+
+`POST /score` takes an id and nothing else. Every input is re-read from the
+database and from storage — a caller can ask for a check-in to be scored, but
+can never influence what the score is.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/health` | liveness, model-loaded, config present |
+| POST | `/score` | score one check-in — `{"checkin_id": "..."}` |
+| POST | `/advise` | species + care advice — **advisory, never a verdict** |
+| POST | `/backfill?limit=50` | score everything still `pending` |
+| GET | `/docs` | interactive OpenAPI |
+
+`/advise` is the only endpoint that is not verification. It writes
+`species_guess` and `advice` and cannot touch `confidence`, `verdict` or
+`signals` — enforced by column grants, and by `pipeline.py` never importing the
+advisor. It is also the only endpoint that **spends money** (~3 cents a call),
+which is why it can be locked behind `ADVISE_TOKEN`.
+
+## How a check-in is judged
+
+**Stage 1 — gates.** Disqualifying on their own, run before any scoring.
+
+| Gate | Catches |
+|---|---|
+| duplicate image (pHash) | resubmitted photo, gallery photo, internet photo |
+| GPS radius | right tree, wrong place |
+| travel speed | one account submitting from two impossible places |
+
+**Stage 2 — scores.** Continuous 0–1 signals, weighted into a confidence.
+
+| Score | Signal |
+|---|---|
+| location | distance from the registered point |
+| liveness | excess-green vegetation fraction |
+| scene match | DINOv2 cosine + ORB/RANSAC inliers vs previous visits |
+| growth | canopy and trunk plausibility, not measurement |
+
+Five of the six fraud types in our attack set are caught in stage 1 by ordinary
+deterministic code. That is the honest reason the system works, and it is why
+overall accuracy is much better than the 54% rank-1 of image matching alone.
+
+## Honest limits
+
+- Image matching is **corroboration, not identity**. Measured on our own 15
+  plants: rank-1 54% against 5% chance, AUC 0.77 — real signal, nowhere near
+  enough to authorise a payout. It is **bimodal**: near-perfect on distinctive
+  trees, near-zero inside a dense same-species stand.
+- Wide-shot matching works partly off the **background**, not the tree.
+- Young bark is smooth; BarkNet's ~94% figures are on **mature** bark.
+- Thresholds and weights in `scoring.py` are **provisional**. They are replaced
+  by weights fitted under leave-one-tree-out cross-validation once real rounds
+  exist. Nothing is tuned on the data used to report performance.
+- A missing signal lowers confidence and routes to a human. It never counts as
+  zero, and it never fails closed on a genuine visit. Designed to degrade.
+
+## Configuration
+
+Space → Settings → Variables and secrets:
+
+| Name | Kind | Value |
+|---|---|---|
+| `SUPABASE_URL` | variable | your project URL |
+| `SUPABASE_SERVICE_KEY` | **secret** | the `service_role` key |
+| `ANTHROPIC_API_KEY` | **secret** | for `/advise` only — omit and advice is simply disabled |
+| `ADVISE_TOKEN` | **secret** | any random string; required in `X-Advise-Token` on `/advise` |
+| `ALLOWED_ORIGINS` | variable | your Vercel URL |
+
+**The service key must never appear in the frontend.** It can write any verdict
+for any tree, and it is the value the whole security model rests on.
+
+**`ANTHROPIC_API_KEY` is billable.** A leak is someone else's spending. Omitting
+it is a supported state, not a failure: `/score` is unaffected and `/advise`
+returns `{"written": false}` — the advisory layer fails soft by design so it can
+never take verification down with it.
+
+**`ADVISE_TOKEN` matters on a public Space.** Without it, anyone who finds this
+URL and a valid check-in id can spend your Anthropic credit three cents at a
+time. `/score` needs no such lock: it costs only our own CPU.
+
+## Local run
+
+```
+cd ml
+pip install -r requirements.txt
+export SUPABASE_URL=... SUPABASE_SERVICE_KEY=...
+uvicorn app:app --reload --port 7860
+```

app.py

@@ -0,0 +1,217 @@
+"""GreenProof verification service.
+
+The ONE new surface in the stack. Everything else is Supabase called directly
+from the browser; this exists because a client-computed verification result is
+forgeable, so scoring has to happen somewhere the user cannot reach.
+
+Runs on Hugging Face Spaces (Docker SDK). Host-agnostic: the same container
+runs on a laptop, Cloud Run, or anywhere else that can run Docker.
+
+    GET  /              service metadata
+    GET  /health        liveness + whether the model is loaded
+    POST /score         score one check-in by id
+    POST /advise        species + care advice for one check-in (advisory only)
+    POST /backfill      score every pending check-in (used after T0)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import threading
+
+from fastapi import FastAPI, Header, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from greenproof_ml import embed as embed_mod
+from greenproof_ml import store
+from greenproof_ml.pipeline import score_checkin
+from greenproof_ml.scoring import MODEL_NAME, MODEL_VERSION
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s"
+)
+log = logging.getLogger("greenproof")
+
+app = FastAPI(title="GreenProof verification service", version=MODEL_VERSION)
+
+# The PWA is served from Vercel, so this is a genuine cross-origin call.
+# Set ALLOWED_ORIGINS to the Vercel URL in the Space's variables; the default
+# is permissive so the pilot is never blocked by a CORS typo at 6am, and the
+# endpoints carry no secrets a caller could extract — the service key stays
+# server-side and every write is derived from stored photos, not from the
+# request body.
+origins = os.environ.get("ALLOWED_ORIGINS", "*").split(",")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[o.strip() for o in origins if o.strip()],
+    allow_methods=["GET", "POST"],
+    allow_headers=["*"],
+)
+
+_model_ready = threading.Event()
+
+
+@app.on_event("startup")
+def _warm() -> None:
+    """Load the model in the background.
+
+    Spaces health-check the container early. Blocking startup on a ~90 MB model
+    download makes the Space look dead and get restarted, which restarts the
+    download — a loop that has eaten whole afternoons.
+    """
+
+    def run() -> None:
+        try:
+            embed_mod.warm()
+            _model_ready.set()
+            log.info("model ready: %s %s", MODEL_NAME, MODEL_VERSION)
+        except Exception:
+            log.exception("model failed to load")
+
+    threading.Thread(target=run, daemon=True).start()
+
+
+class ScoreRequest(BaseModel):
+    checkin_id: str = Field(..., description="checkins.id to score")
+
+
+class ScoreResponse(BaseModel):
+    checkin_id: str
+    confidence: int
+    verdict: str
+    signals: dict
+
+
+@app.get("/")
+def root() -> dict:
+    return {
+        "service": "greenproof-verification",
+        "model": MODEL_NAME,
+        "version": MODEL_VERSION,
+        "docs": "/docs",
+    }
+
+
+@app.get("/health")
+def health() -> dict:
+    return {
+        "ok": True,
+        "model_ready": _model_ready.is_set(),
+        "supabase_configured": bool(
+            os.environ.get("SUPABASE_URL") and os.environ.get("SUPABASE_SERVICE_KEY")
+        ),
+    }
+
+
+@app.post("/score", response_model=ScoreResponse)
+def score(req: ScoreRequest) -> ScoreResponse:
+    """Score one check-in.
+
+    Takes only an id. The request body cannot influence the outcome — every
+    input is re-read from the database and from storage. A caller can ask for a
+    check-in to be scored; it can never say what the score should be.
+    """
+    if not _model_ready.is_set():
+        raise HTTPException(503, "Model still loading, retry shortly")
+    try:
+        result = score_checkin(req.checkin_id)
+    except LookupError as e:
+        raise HTTPException(404, str(e)) from e
+    except Exception as e:  # noqa: BLE001
+        log.exception("scoring failed for %s", req.checkin_id)
+        raise HTTPException(500, f"Scoring failed: {e}") from e
+
+    return ScoreResponse(
+        checkin_id=req.checkin_id,
+        confidence=result.confidence,
+        verdict=result.verdict,
+        signals=result.signals,
+    )
+
+
+# Optional shared secret for /advise. Unset means the endpoint is open.
+#
+# WHY THIS EXISTS, AND WHY ONLY ON THIS ENDPOINT.
+#
+# /score is safe to leave open: it takes an id, re-reads every input from the
+# database, and costs us nothing but a few seconds of our own CPU. /advise is
+# different in one specific way - IT SPENDS MONEY. Each call is about 3 cents of
+# Anthropic usage.
+#
+# On a Cloudflare quick tunnel that barely mattered: the hostname rotated and the
+# service was up for minutes at a time. A permanent public Space URL is a
+# different proposition, and an endpoint that bills the operator per request is
+# worth a lock even when the realistic risk is low.
+#
+# Unset by default so local runs and `uvicorn app:app` need no configuration.
+# Set it in the Space's secrets and in .env, and tools/advise_pilot.py sends it.
+ADVISE_TOKEN = os.environ.get("ADVISE_TOKEN", "").strip()
+
+
+@app.post("/advise")
+def advise(req: ScoreRequest, x_advise_token: str = Header(default="")) -> dict:
+    """Species identification and care advice for one check-in.
+
+    SEPARATE FROM /score ON PURPOSE, and the separation is the design.
+
+    Scoring is fast, local, offline-capable and replayable - it re-runs over the
+    whole pilot dataset whenever a threshold moves, and it must never acquire a
+    dependency on an external API that can be slow, rate-limited or down. This
+    endpoint is none of those things: it makes a paid network call to a model
+    whose error rate we have not measured.
+
+    So they share a service and nothing else. This writes only `species_guess`
+    and `advice`; it cannot move a confidence or a verdict, and a failure here
+    leaves the check-in exactly as scoring left it.
+
+    Note it does NOT require the DINOv2 model to be loaded - the two paths have
+    no components in common, so a cold model should not block advice.
+    """
+    # compare_digest, not ==, so a wrong token cannot be recovered by timing.
+    if ADVISE_TOKEN and not secrets.compare_digest(x_advise_token, ADVISE_TOKEN):
+        raise HTTPException(401, "Missing or invalid X-Advise-Token")
+
+    from greenproof_ml import advisor
+
+    try:
+        result = advisor.advise_checkin(req.checkin_id)
+    except LookupError as e:
+        raise HTTPException(404, str(e)) from e
+    except Exception as e:  # noqa: BLE001
+        log.exception("advice failed for %s", req.checkin_id)
+        raise HTTPException(500, f"Advice failed: {e}") from e
+
+    if result is None:
+        # Not an error. Either the tree shows no decline and the policy skipped
+        # it, or the model declined to answer. Both leave the row untouched.
+        return {"checkin_id": req.checkin_id, "written": False}
+
+    return {"checkin_id": req.checkin_id, "written": True, **result}
+
+
+@app.post("/backfill")
+def backfill(limit: int = 50) -> dict:
+    """Score everything still pending.
+
+    This is what makes T0 safe to run before the service exists: registration
+    only captures and uploads, and the photos sit as `pending` until this is
+    called. Nothing about the pilot depends on the ML service being live on the
+    day.
+    """
+    if not _model_ready.is_set():
+        raise HTTPException(503, "Model still loading, retry shortly")
+
+    rows = store.list_pending(limit)
+    done, failed = [], []
+    for row in rows:
+        try:
+            result = score_checkin(row["id"])
+            done.append({"id": row["id"], "verdict": result.verdict, "confidence": result.confidence})
+        except Exception as e:  # noqa: BLE001
+            log.exception("backfill failed for %s", row["id"])
+            failed.append({"id": row["id"], "error": str(e)})
+
+    return {"scored": len(done), "failed": len(failed), "results": done, "errors": failed}

greenproof_ml/__init__.py

@@ -0,0 +1,3 @@
+"""GreenProof verification signals, scoring and persistence."""
+
+__version__ = "2026.08.1"

greenproof_ml/advisor.py

@@ -0,0 +1,386 @@
+"""Species identification and care advice for the planter.
+
+THE ONE THING TO UNDERSTAND ABOUT THIS FILE
+
+    Nothing here is a verification signal, and nothing here may become one.
+
+The verification engine answers "is this the same tree, alive, in the right
+place, not a duplicate" - and it answers it with detectors whose error rate we
+have measured and published. This file answers a different question that nobody
+has been answering at all: "what is wrong with this tree and what should the
+planter do about it?"
+
+Those two questions deserve different standards of evidence, so they are kept
+apart at every level: a separate module THE SCORING PATH NEVER IMPORTS, a
+separate endpoint, separate database columns, and a separate place in the UI
+that names the model and says the word "advice".
+
+The import direction is the load-bearing part. `pipeline.py` does not know this
+file exists, so there is no code path by which a slow, failed or hallucinated
+advisory call can affect a verdict. Check that property still holds before
+adding any import to this module's callers:
+
+    grep -rn "advisor" ml/greenproof_ml/pipeline.py ml/greenproof_ml/scoring.py
+
+should print nothing, permanently.
+
+WHY AN LLM HERE, WHEN WE REFUSED ONE EVERYWHERE ELSE
+
+The obvious alternative is a leaf-disease classifier trained on PlantVillage.
+We are not doing that, for three reasons and the first is disqualifying:
+
+  1. PlantVillage is single leaves on uniform lab backgrounds. Published
+     cross-domain evaluations collapse from ~99% to roughly 30-50% on real
+     field photographs. We have already made exactly this mistake once and
+     turned it into our best slide: the plant check scored a perfect AUC of
+     1.000 and then flagged five of nine real check-ins as "not a plant",
+     because it had learned photo STYLE, not subject. Shipping a PlantVillage
+     classifier would be repeating a mistake we have documented.
+
+  2. It covers fourteen crops - tomato, potato, corn, grape. None of them are
+     Odum, Wawa, Ofram, Ceiba, or anything else in a Ghanaian planting scheme.
+
+  3. We have no ground truth. No agronomist has labelled our trees. This
+     project's entire claim is that we publish our own measured error rate, and
+     a classifier whose error rate we cannot measure would be the one component
+     contradicting that claim.
+
+An LLM's output is hedged natural language that a person reads and judges, not
+a number that authorises a payment. The bar it has to clear is therefore much
+lower, and it is honest about clearing a lower bar - which is why `limitations`
+below is a required field rather than an optional one.
+
+FAILS SOFT, ALWAYS. No key, no network, a rate limit, a refusal, a malformed
+response: every one of them logs and returns None. The caller writes nothing and
+the check-in is untouched. This service being unreachable already costs us
+nothing (scoring is asynchronous and replayable); the advisory layer inherits
+that property rather than weakening it.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import os
+from typing import Literal
+
+from PIL import Image
+from pydantic import BaseModel, Field
+
+log = logging.getLogger(__name__)
+
+# Opus 5. The images are small and the call is off the critical path, so there
+# is no reason to trade quality away here - this is the output a planter reads
+# and acts on, and bad advice about a real tree is worse than no advice.
+MODEL = "claude-opus-5"
+
+# Generous. The call is fire-and-forget from the caller's perspective and a slow
+# response costs nothing, whereas a truncated one wastes the whole request.
+MAX_TOKENS = 2000
+
+# Images are re-encoded to this before sending. The photos in storage are
+# already 800px/q75 (the client downscales before upload), so this is a ceiling
+# rather than a resize in the normal case, and it bounds the token cost of a
+# photo that arrived by some other route.
+MAX_EDGE_PX = 800
+JPEG_QUALITY = 75
+
+
+class PlantAssessment(BaseModel):
+    """What we ask Claude to return, and what we store.
+
+    Every field is chosen so that a reader can tell how much to trust it.
+    `species_confidence` is SELF-REPORTED and labelled as such in the UI - it is
+    not a measured accuracy and must never be presented as one.
+    """
+
+    species_common: str | None = Field(
+        description="Common name of the species, or null if not identifiable."
+    )
+    species_scientific: str | None = Field(
+        description="Binomial scientific name, or null if not identifiable."
+    )
+    species_confidence: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="Your own confidence in the species identification, 0 to 1.",
+    )
+    health: Literal["healthy", "stressed", "declining", "cannot_tell"] = Field(
+        description="Overall condition of the plant as far as the photos show it."
+    )
+    observations: list[str] = Field(
+        description="What is actually visible in the photographs. Concrete and "
+        "specific: leaf colour, leaf loss, wilting, damage, the state of the "
+        "soil. Do not speculate beyond what the image shows."
+    )
+    actions: list[str] = Field(
+        description="What the planter should do, in plain language, achievable "
+        "by one person with no equipment and no money."
+    )
+    limitations: str = Field(
+        description="What these photographs could NOT tell you, and what would "
+        "need to be checked in person."
+    )
+
+
+# `limitations` being required is the design, not a formality. An assessment
+# that cannot say what it failed to see is indistinguishable from one that saw
+# everything, and a planter cannot calibrate how much to trust it.
+SYSTEM = """You are advising a smallholder tree planter in Ghana who has \
+photographed a young tree (roughly 1-3 years old) they are responsible for \
+keeping alive. They are paid when the tree survives, so your advice has real \
+consequences for them.
+
+You will receive one to three photographs of the same tree from the same visit: \
+a wide shot of the whole tree and its surroundings, a close-up of the trunk, \
+and sometimes a close-up of a leaf.
+
+Your job is to identify the species if you can, describe the tree's condition, \
+and tell the planter what to do about it.
+
+Rules:
+
+- Describe only what is visible. If the photographs do not show something, say \
+so in `limitations` rather than guessing at it.
+- Prefer species common in Ghanaian planting schemes where the image supports \
+it (Odum/Milicia, Wawa/Triplochiton, Ofram/Terminalia, Mahogany/Khaya, \
+Neem/Azadirachta, Ceiba, Mango/Mangifera, Cassia, Acacia, Teak/Tectona), but do \
+not force a match. Return null for species rather than a bad guess, and let \
+`species_confidence` reflect genuine uncertainty.
+- Recommend only actions a person can take with their hands, water, mulch and \
+local materials. No paid inputs, no laboratory tests, no equipment. Watering, \
+mulching, weeding around the base, removing competing growth, staking, \
+protecting from livestock, and clearing termite damage are the realistic \
+interventions.
+- If the tree looks healthy, say so plainly and give one or two things worth \
+keeping up. Do not invent problems.
+- Be brief. Two to four observations, two to four actions. This is read on a \
+phone, outdoors, by someone standing in front of the tree.
+- Never mention verification, scoring, confidence scores or payment. That is a \
+different part of this system and not your concern."""
+
+
+def _client():
+    """Constructed per call, deliberately.
+
+    The API key is read from the environment at call time rather than import
+    time, so the module imports cleanly on a machine that has no key - which is
+    every machine running the scoring path, since scoring must never acquire a
+    dependency on this file.
+    """
+    import anthropic  # imported here so a missing SDK cannot break scoring
+
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        raise RuntimeError(
+            "ANTHROPIC_API_KEY is not set. Note that a Claude Pro subscription "
+            "is NOT API access - the API bills separately at console.anthropic.com."
+        )
+    return anthropic.Anthropic()
+
+
+def _image_block(img: Image.Image, label: str) -> list[dict]:
+    """One photo as a labelled pair of content blocks.
+
+    The text label matters: without it the model cannot tell a trunk close-up
+    from a leaf close-up, and will describe bark as foliage.
+    """
+    im = img.convert("RGB")
+    im.thumbnail((MAX_EDGE_PX, MAX_EDGE_PX))
+
+    buf = io.BytesIO()
+    im.save(buf, format="JPEG", quality=JPEG_QUALITY)
+    data = base64.standard_b64encode(buf.getvalue()).decode("utf-8")
+
+    return [
+        {"type": "text", "text": label},
+        {
+            "type": "image",
+            "source": {"type": "base64", "media_type": "image/jpeg", "data": data},
+        },
+    ]
+
+
+def assess(
+    *,
+    wide: Image.Image | None = None,
+    close: Image.Image | None = None,
+    leaf: Image.Image | None = None,
+    recorded_species: str | None = None,
+) -> PlantAssessment | None:
+    """Identify the species and assess the tree's health. None on any failure.
+
+    EVERY PHOTO THAT EXISTS IS SENT, and none is required. That is what lets
+    this run against the pilot check-ins captured before `leaf_photo` existed,
+    and what lets it improve on its own as leaf photos start arriving - the same
+    property the plant reference set has, where every verified check-in makes
+    the next assessment slightly better.
+
+    `recorded_species` is what the planter typed at registration. It is passed
+    as CONTEXT TO DISAGREE WITH, never as an answer to confirm: the whole value
+    of an independent identification is lost if we tell the model what to say.
+    """
+    blocks: list[dict] = []
+    if wide is not None:
+        blocks += _image_block(wide, "Wide shot: the whole tree and its surroundings.")
+    if close is not None:
+        blocks += _image_block(close, "Close-up of the trunk.")
+    if leaf is not None:
+        blocks += _image_block(leaf, "Close-up of a leaf.")
+
+    if not blocks:
+        log.warning("advisor.assess called with no photographs")
+        return None
+
+    prompt = "Identify this tree and assess its condition."
+    if recorded_species:
+        # Framed to invite contradiction. "The planter recorded X" is a claim to
+        # test; "this is an X" would be an instruction to agree.
+        prompt += (
+            f"\n\nThe planter recorded this tree's species as '{recorded_species}' "
+            "when they registered it. Treat that as an unverified claim, not as "
+            "the answer. If the photographs show something else, say so."
+        )
+    blocks.append({"type": "text", "text": prompt})
+
+    try:
+        response = _client().messages.parse(
+            model=MODEL,
+            max_tokens=MAX_TOKENS,
+            system=SYSTEM,
+            messages=[{"role": "user", "content": blocks}],
+            output_format=PlantAssessment,
+        )
+    except Exception:  # noqa: BLE001 - advisory only, must never break a caller
+        log.exception("advisory assessment failed")
+        return None
+
+    # A refusal is a successful HTTP call with no parsed output. Guard before
+    # reading rather than raising out of a function documented never to raise.
+    parsed = getattr(response, "parsed_output", None)
+    if parsed is None:
+        log.warning(
+            "advisory assessment returned no parsed output (stop_reason=%s)",
+            getattr(response, "stop_reason", None),
+        )
+        return None
+
+    return parsed
+
+
+def split(assessment: PlantAssessment) -> tuple[dict, dict]:
+    """One assessment -> the two columns it is stored in.
+
+    Species and advice are separated in the database because they have different
+    futures: species is a candidate verification signal (a species that changes
+    between visits is evidence of a swapped tree), and advice never will be.
+    Storing them together would make that separation a refactor later.
+    """
+    species = {
+        "common": assessment.species_common,
+        "scientific": assessment.species_scientific,
+        # Named to make its nature unmissable at every layer. This is the
+        # model's opinion of itself, not a measured accuracy, and calling the
+        # field `confidence` next to a column that genuinely IS a measured
+        # confidence would be actively misleading.
+        "self_reported_confidence": assessment.species_confidence,
+        "model": MODEL,
+    }
+    advice = {
+        "health": assessment.health,
+        "observations": assessment.observations,
+        "actions": assessment.actions,
+        "limitations": assessment.limitations,
+        "model": MODEL,
+        "advisory_only": True,
+    }
+    return species, advice
+
+
+# ---------------------------------------------------------------------------
+# When to spend a call
+# ---------------------------------------------------------------------------
+#
+# THE DESIGNED POLICY IS DECLINE-ONLY. The deterministic canopy signal in
+# scoring.score_growth already flags a tree that has lost more than half its
+# canopy since the last visit - that is the dying-tree detector, it costs
+# nothing, and it is measured. Calling an LLM only when that fires is what keeps
+# the per-tree cost defensible at scale:
+#
+#     ~3 cents a call. One million trees checked four times a year is
+#     ~$120k on every visit, ~$6-12k on decline only.
+#
+# WHY IT IS CURRENTLY TRUE FOR EVERY CHECK-IN ANYWAY. The pilot is 6 trees and
+# 9 check-ins, and most of those are first visits - where score_growth returns a
+# neutral 0.5 because there is no previous canopy to compare against. A
+# decline-only trigger would fire zero times on the data we actually have, and
+# an advisory layer with nothing to advise on is not a feature.
+#
+# So this is a policy constant with both branches live, rather than a hardcoded
+# call site. Both statements are true and both are defensible: we assess every
+# visit at pilot scale, and the design for scale is decline-only.
+ADVISE_ON_EVERY_CHECKIN = True
+
+# Below this growth score, the tree is declining enough to be worth advice.
+# Matches the 0.15 that score_growth assigns to >50% canopy loss.
+DECLINE_GROWTH_SCORE = 0.2
+
+
+def should_advise(checkin: dict) -> bool:
+    """Is this check-in worth spending an API call on?"""
+    if ADVISE_ON_EVERY_CHECKIN:
+        return True
+
+    growth = ((checkin.get("signals") or {}).get("scores") or {}).get("growth") or {}
+    score = growth.get("score")
+    # An unscored check-in has no decline evidence either way. Advising on it
+    # would quietly restore "every check-in" through the back door.
+    return score is not None and score <= DECLINE_GROWTH_SCORE
+
+
+def advise_checkin(checkin_id: str) -> dict | None:
+    """Assess one check-in and store the result. None if nothing was written.
+
+    Fetches its own photos from storage, exactly as scoring does, so the request
+    body cannot influence what gets assessed.
+    """
+    from . import store  # local: keeps the module importable without credentials
+
+    row = store.get_checkin(checkin_id)
+    if row is None:
+        raise LookupError(f"No check-in {checkin_id}")
+
+    if not should_advise(row):
+        log.info("skipping advice for %s: no decline detected", checkin_id)
+        return None
+
+    tree = store.get_tree(row["tree_id"])
+
+    def _photo(path: str | None) -> Image.Image | None:
+        """A missing or unreadable photo costs us that photo, never the call."""
+        if not path:
+            return None
+        try:
+            return store.download_image(path)
+        except Exception:  # noqa: BLE001
+            log.warning("could not download %s", path, exc_info=True)
+            return None
+
+    assessment = assess(
+        wide=_photo(row.get("wide_photo")),
+        close=_photo(row.get("close_photo")),
+        leaf=_photo(row.get("leaf_photo")),
+        recorded_species=(tree or {}).get("species"),
+    )
+    if assessment is None:
+        return None
+
+    species, advice = split(assessment)
+    store.write_advice(checkin_id, species, advice)
+    log.info(
+        "advised %s -> %s (species: %s)",
+        checkin_id,
+        assessment.health,
+        assessment.species_common,
+    )
+    return {"species_guess": species, "advice": advice}

greenproof_ml/embed.py

@@ -0,0 +1,99 @@
+"""DINOv2 embeddings via ONNX Runtime.
+
+Preprocessing is deliberately IDENTICAL to spike/measure.py. That file produced
+the numbers we publish — rank-1 54.2%, AUC 0.77 — and if production resized or
+normalised differently, those numbers would no longer describe this system. The
+published figure has to be a measurement of the thing we shipped.
+
+The one intentional difference: the spike cropped a camera-app timestamp
+watermark off the bottom of every frame. App photos have no watermark, so the
+crop is zero here and configurable rather than deleted, so the spike can be
+re-run against production-shaped inputs.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+
+import numpy as np
+from PIL import Image
+
+MODEL_REPO = "onnx-community/dinov2-small"
+
+# DINOv2 uses 14px patches; 224 = 16 x 14.
+IMG_SIZE = 224
+EMBED_DIM = 384
+
+# ImageNet statistics — what DINOv2 was trained with.
+_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+_lock = threading.Lock()
+
+
+def _model_path() -> str:
+    """Download the full-precision ONNX weights, skipping quantised variants.
+
+    Quantised weights would halve memory but shift every cosine similarity
+    slightly, which moves the thresholds we cross-validated. Not worth it at
+    ~90 MB on a 16 GB box.
+    """
+    from huggingface_hub import hf_hub_download, list_repo_files
+
+    onnx = [f for f in list_repo_files(MODEL_REPO) if f.endswith(".onnx")]
+    full = [
+        f
+        for f in onnx
+        if not any(q in f.lower() for q in ("quant", "int8", "uint8", "q4", "fp16", "bnb"))
+    ]
+    return hf_hub_download(MODEL_REPO, sorted(full or onnx, key=len)[0])
+
+
+@functools.lru_cache(maxsize=1)
+def _session():
+    import onnxruntime as ort
+
+    opts = ort.SessionOptions()
+    # Free Spaces gives 2 vCPUs. Letting ORT spawn more threads than that makes
+    # it slower, not faster.
+    opts.intra_op_num_threads = 2
+    opts.inter_op_num_threads = 1
+    return ort.InferenceSession(
+        _model_path(), sess_options=opts, providers=["CPUExecutionProvider"]
+    )
+
+
+def warm() -> None:
+    """Force model download + graph load at startup rather than on first request."""
+    sess = _session()
+    name = sess.get_inputs()[0].name
+    sess.run(None, {name: np.zeros((1, 3, IMG_SIZE, IMG_SIZE), dtype=np.float32)})
+
+
+def preprocess(img: Image.Image, watermark_crop: float = 0.0) -> np.ndarray:
+    img = img.convert("RGB")
+    if watermark_crop:
+        w, h = img.size
+        img = img.crop((0, 0, w, int(h * (1 - watermark_crop))))
+
+    # Resize the WHOLE frame rather than centre-cropping. For the wide shot the
+    # surroundings are a large part of the signal — the spike showed matching
+    # works partly off the background — and a centre crop throws exactly that
+    # away.
+    img = img.resize((IMG_SIZE, IMG_SIZE), Image.BICUBIC)
+    a = np.asarray(img, dtype=np.float32) / 255.0
+    return ((a - _MEAN) / _STD).transpose(2, 0, 1)
+
+
+def embed(img: Image.Image) -> np.ndarray:
+    """L2-normalised 384-d CLS embedding. Dot product of two of these is cosine."""
+    x = preprocess(img)[None, ...]
+    with _lock:  # ORT sessions are not guaranteed thread-safe for concurrent run()
+        out = _session().run(None, {_session().get_inputs()[0].name: x})[0]
+    v = out[0, 0].astype(np.float32)  # CLS token summarises the image
+    return v / (np.linalg.norm(v) + 1e-9)
+
+
+def cosine(a: np.ndarray, b: np.ndarray) -> float:
+    return float(np.dot(a, b))

greenproof_ml/pipeline.py

@@ -0,0 +1,221 @@
+"""Scoring one check-in, end to end.
+
+    fetch row -> download both photos -> gates -> scores -> write back
+
+Idempotent: re-running on the same check-in recomputes from the stored photos
+and overwrites the result. That matters more than it sounds, because it means
+every threshold change can be replayed over the entire pilot dataset without
+going back into the field. The photos are the raw evidence; the verdict is
+derived and disposable.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+
+from . import store
+from .embed import cosine, embed
+from .scoring import (
+    Assessment,
+    assess,
+    PROXIMITY_REVIEW_M,
+    check_plant_plausibility,
+    check_proximity,
+    gate_duplicate,
+    gate_gps,
+    gate_travel,
+    score_growth,
+    score_liveness,
+    score_location,
+    score_scene,
+)
+from .signals import (
+    canopy_fraction,
+    excess_green,
+    haversine_m,
+    liveness_score,
+    orb_inliers,
+    phash,
+    plant_reference,
+    trunk_width_mm,
+)
+
+log = logging.getLogger(__name__)
+
+# Fraction of auto-approved check-ins pulled for human spot-checking.
+# Without this we would have no way to estimate the false-ACCEPT rate, which is
+# the number that actually matters — a wrongly rejected genuine visit is
+# annoying, a wrongly approved fraud is fatal, and nothing else in the system
+# measures the second one.
+AUDIT_RATE = 0.10
+
+
+def score_checkin(checkin_id: str) -> Assessment:
+    row = store.get_checkin(checkin_id)
+    if row is None:
+        raise LookupError(f"No check-in {checkin_id}")
+
+    tree = store.get_tree(row["tree_id"])
+    if tree is None:
+        raise LookupError(f"Check-in {checkin_id} references a missing tree")
+
+    wide = store.download_image(row["wide_photo"])
+    close = store.download_image(row["close_photo"])
+
+    # --- fingerprints ------------------------------------------------------
+    wide_ph = phash(wide)
+    wide_emb = embed(wide)
+    close_emb = embed(close)
+
+    captured_at = store.parse_ts(row["captured_at"])
+    prev_visits = store.previous_checkins(row["tree_id"], row["captured_at"])
+
+    # --- gates -------------------------------------------------------------
+    gates = {}
+
+    gates["duplicate_image"] = gate_duplicate(
+        wide_ph, store.other_phashes(checkin_id)
+    )
+
+    gates["gps_radius"] = gate_gps(
+        tree["lat"],
+        tree["lng"],
+        row["lat"],
+        row["lng"],
+        row.get("gps_accuracy_m"),
+    )
+
+    prev_any = store.previous_by_submitter(
+        row["submitted_by"], row["captured_at"], checkin_id
+    )
+    gates["travel_speed"] = gate_travel(
+        row["lat"],
+        row["lng"],
+        captured_at,
+        (
+            prev_any["id"],
+            prev_any["lat"],
+            prev_any["lng"],
+            store.parse_ts(prev_any["captured_at"]),
+        )
+        if prev_any
+        else None,
+    )
+
+    # --- scores ------------------------------------------------------------
+    scores: dict[str, dict] = {}
+
+    distance = haversine_m(tree["lat"], tree["lng"], row["lat"], row["lng"])
+    scores["location"] = score_location(distance)
+
+    green = excess_green(wide)
+    scores["liveness"] = score_liveness(green, liveness_score(green))
+
+    # Scene match needs something to match AGAINST. On the very first visit
+    # there is nothing, so the signal is absent rather than zero — assess()
+    # renormalises and lowers confidence via the coverage term instead of
+    # treating a registration as suspicious.
+    if prev_visits:
+        best_wide = best_close = None
+        for p in prev_visits:
+            pw = store.parse_embedding(p.get("wide_embedding"))
+            pc = store.parse_embedding(p.get("close_embedding"))
+            if pw is not None:
+                c = cosine(wide_emb, pw)
+                best_wide = c if best_wide is None else max(best_wide, c)
+            if pc is not None:
+                c = cosine(close_emb, pc)
+                best_close = c if best_close is None else max(best_close, c)
+
+        inliers = None
+        try:
+            prev_wide = store.download_image(prev_visits[0]["wide_photo"])
+            inliers = orb_inliers(wide, prev_wide)
+        except Exception:  # noqa: BLE001 - corroboration only, never fatal
+            log.warning("ORB comparison failed for %s", checkin_id, exc_info=True)
+
+        if best_wide is not None or best_close is not None:
+            scores["scene_match"] = score_scene(best_wide, best_close, inliers)
+
+    canopy_now = canopy_fraction(wide)
+    canopy_prev = trunk_prev = None
+    if prev_visits:
+        prev_growth = ((prev_visits[0].get("signals") or {}).get("scores") or {}).get(
+            "growth", {}
+        )
+        canopy_prev = prev_growth.get("canopy_frac")
+        trunk_prev = prev_growth.get("trunk_mm")
+
+    # Millimetres are derived HERE, from the stored photo and the stored taps —
+    # never from anything the client calculated. See signals.trunk_width_mm.
+    measurement = trunk_width_mm(close, row.get("trunk_taps"))
+    trunk_now = measurement.get("trunk_mm") if measurement and measurement.get("available") else None
+
+    scores["growth"] = score_growth(canopy_now, canopy_prev, trunk_now, trunk_prev)
+    if measurement:
+        scores["growth"]["measurement"] = measurement
+
+    # --- review flags ------------------------------------------------------
+    # Not gates: these must not auto-approve, but they are not accusations. See
+    # scoring.check_proximity for why proximity cannot be a gate.
+    review_flags = {}
+
+    # Runs on EVERY visit, not just the first. Registering a chair is the
+    # obvious case, but swapping one in at visit three is the case a
+    # first-visit-only check would wave through.
+    review_flags["plant_plausibility"] = check_plant_plausibility(
+        wide_emb, close_emb, plant_reference()
+    )
+
+    # Only on the tree's FIRST check-in, i.e. its registration. On every later
+    # visit the tree already exists and standing near a neighbour is not news —
+    # re-flagging it every round would bury the reviewer in the same alert.
+    if not prev_visits:
+        review_flags["tree_proximity"] = check_proximity(
+            tree["lat"],
+            tree["lng"],
+            store.trees_near_registered_before(
+                tree["id"],
+                tree["lat"],
+                tree["lng"],
+                tree["created_at"],
+                PROXIMITY_REVIEW_M,
+            ),
+        )
+
+    # --- combine and persist ----------------------------------------------
+    result = assess(gates, scores, review_flags=review_flags)
+
+    # Carry provenance forward. write_result replaces `signals` WHOLESALE, so a
+    # self-test tag written at insert time is destroyed by the very act of
+    # scoring. That is not cosmetic: it made six injected attack rows
+    # indistinguishable from real pilot data, and the only thing that still
+    # identified them was the storage path. Provenance is a fact about where a
+    # row came from, not part of the score, and must survive being scored.
+    provenance = (row.get("signals") or {}).get("self_test")
+    if provenance:
+        result.signals["self_test"] = provenance
+
+    audit = result.verdict == "verified" and random.random() < AUDIT_RATE
+
+    store.write_result(
+        checkin_id,
+        phash=wide_ph,
+        wide_embedding=wide_emb,
+        close_embedding=close_emb,
+        confidence=result.confidence,
+        verdict=result.verdict,
+        signals=result.signals,
+        audit_sample=audit,
+    )
+    store.update_tree_status(row["tree_id"], result.confidence, result.verdict)
+
+    log.info(
+        "scored %s -> %s (%d) gates=%s",
+        checkin_id,
+        result.verdict,
+        result.confidence,
+        {k: v.passed for k, v in gates.items()},
+    )
+    return result

greenproof_ml/plant_reference.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3de6378a6d4c5dc8f1543a0f51e602bb1184ab69b71bc0fd69f742e542c026dc
+size 113792

greenproof_ml/scoring.py

@@ -0,0 +1,528 @@
+"""Combining the detectors into a confidence and a verdict.
+
+TWO-STAGE BY DESIGN.
+
+    Stage 1 — GATES. Disqualifying on their own, regardless of anything else.
+              A duplicate photo is a duplicate photo; no amount of scene
+              similarity should rescue it. Gates run BEFORE scoring so a
+              failure is cheap and unambiguous.
+
+    Stage 2 — SCORES. Continuous 0..1 signals, combined by weights, producing a
+              confidence out of 100.
+
+This ordering is the reason the system's overall accuracy is far better than the
+54% rank-1 of image matching alone: five of the six fraud types in the attack set
+never reach stage 2.
+
+THRESHOLDS AND WEIGHTS BELOW ARE PROVISIONAL. They are informed guesses that let
+the pipeline run end-to-end from day one. They are replaced by weights fitted
+with logistic regression under leave-one-tree-out cross-validation once real
+check-in rounds exist — see calibrate.py. Reporting a number produced by
+hand-tuned weights on the same data would be exactly the mistake CLAUDE.md
+forbids.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .signals import DUPLICATE_MAX_HAMMING, haversine_m, hamming
+
+# --- gate parameters -------------------------------------------------------
+
+# How far from the registered point a check-in may be.
+# Built from the GPS accuracy of BOTH readings plus a slack term, rather than a
+# flat radius: a ±3 m fix and a ±18 m fix genuinely deserve different tolerances,
+# and a flat number would either reject good check-ins under canopy or wave
+# through bad ones in the open.
+GPS_SLACK_M = 15.0
+GPS_MAX_RADIUS_M = 60.0
+
+# Nobody walks a plantation at 120 km/h. Catches one account submitting
+# check-ins from two places faster than a human could travel between them.
+MAX_TRAVEL_KMH = 120.0
+
+# Two TREES registered closer together than this are possibly one tree entered
+# twice — the double-payment case.
+#
+# NOT A GATE, DELIBERATELY. A failed gate means confidence 0 and 'flagged', and
+# trees genuinely do grow 3 m apart: flagging a dense grove as fraud would be
+# both wrong and ruinous to the pilot numbers. Phone GPS at 5-10 m simply cannot
+# tell "one tree measured twice" from "two neighbouring trees", so the honest
+# response is a human look, not an accusation. It routes to REVIEW instead.
+#
+# PROVISIONAL. Calibrate against the pilot's nearest-neighbour distance
+# distribution and set it below the 5th percentile — see tools/proximity_audit.py.
+# Must stay in step with PROXIMITY_WARN_M in app/src/lib/trees.ts, which is the
+# client-side warning for the same condition.
+PROXIMITY_REVIEW_M = 8.0
+
+# Cosine similarity to the nearest known plant, below which a photo does not
+# look like a plant at all.
+#
+# THE FIRST TWO NUMBERS HERE WERE WRONG AND THE STORY IS THE POINT.
+#
+# Held-out spike photos against 300 COCO photographs scored AUC 1.000 with a
+# threshold of 0.519 and an 8.1% false-reject rate. Applied to the 9 REAL pilot
+# check-ins - different plants, different site - that same threshold flagged
+# FIVE OF NINE. The holdout was other angles of the SAME 15 plants at the SAME
+# shoot, so it had been measuring "was this taken at that shoot", not "is this
+# a plant". An AUC of 1.000 is a warning, not a result.
+#
+# Re-measured against genuinely unseen trees:
+#
+#     AUC (real pilot photos vs 300 COCO)      0.966
+#
+#     threshold   check-ins flagged   non-plants accepted
+#       0.250        1/9  (11%)             1.3%
+#       0.300        1/9  (11%)             1.0%     <- chosen
+#       0.350        2/9  (22%)             0.3%
+#       0.519        5/9  (56%)             0.0%
+#
+# 0.30 buys 99% of non-plants for one check-in in nine going to a human. Pushing
+# higher trades real planters' time for a rounding error of extra safety, and a
+# non-plant that slips still faces GPS, duplicate and scene-match.
+#
+# STILL PROVISIONAL: measured on 18 photos from 6 trees at one site. The honest
+# fix is not a better threshold, it is a bigger reference set - every verified
+# check-in is a known-good plant photo, so this improves as the system runs.
+PLANT_SIMILARITY_MIN = 0.30
+
+# --- score shaping ---------------------------------------------------------
+
+LOCATION_FULL_M = 10.0  # at or under this, full marks
+LOCATION_ZERO_M = 60.0  # at or over this, nothing
+
+SCENE_COSINE_FLOOR = 0.35  # below this, no evidence of the same scene
+SCENE_COSINE_CEIL = 0.75  # at or above, as good as same-scene gets
+ORB_INLIER_STRONG = 25  # inliers that would count as strong agreement
+
+# ORB/RANSAC IS MEASURED AND DISABLED. Do not switch this on without re-running
+# the measurement.
+#
+# Tested on the 59 spike photos, 287 pairs (87 same-tree, 200 different-tree):
+#
+#     same tree       63.2% zero inliers, mean 1.7, max 8
+#     different tree  75.0% zero inliers, mean 1.1, max 6
+#
+# The distributions overlap almost entirely. ORB finds no consistent geometry
+# between two genuine photos of the same tree taken minutes apart from slightly
+# different positions — foliage moves, and bark at two scales shares almost no
+# repeatable keypoints. Leaving it in the score would have added up to +0.08 of
+# essentially random confidence, which helps an impostor as readily as a genuine
+# visit.
+#
+# It stays COMPUTED and recorded in `signals` so the decision can be revisited
+# with real data, because the spike had no framing control. The ghost overlay
+# and compass heading exist precisely to reproduce framing, and ORB may become
+# viable once check-in round 1 produces aligned pairs. Re-measure then; turn it
+# on only if the same/different distributions actually separate.
+ORB_CONTRIBUTES_TO_SCORE = False
+
+# --- combination -----------------------------------------------------------
+
+# Deliberately NOT equal. Image matching is the weakest signal we measured
+# (rank-1 54%, AUC 0.77, and bimodal), so it must not dominate. Location and
+# liveness are cheap, deterministic and reliable — they carry more.
+DEFAULT_WEIGHTS: dict[str, float] = {
+    "location": 0.35,
+    "liveness": 0.30,
+    "scene_match": 0.25,
+    "growth": 0.10,
+}
+
+VERIFY_AT = 70
+REVIEW_AT = 45
+
+# ---------------------------------------------------------------------------
+# CRITICAL FLOORS — the fix for a false accept found in testing
+# ---------------------------------------------------------------------------
+#
+# A plain weighted sum lets strong signals COMPENSATE for a failed one. Tested
+# against "a different tree photographed at the correct GPS" — attack #4, the
+# one case that genuinely needs the AI — the result was:
+#
+#     scene_match 0.00, location 1.00, liveness 1.00, growth 1.00
+#     -> 75/100 -> VERIFIED
+#
+# The system auto-approved the exact fraud it exists to catch, because
+# scene_match carries only 0.25 of the weight and the other three were perfect.
+# Compensation is correct for a quality score and wrong for a fraud decision.
+#
+# So a signal that is present and near-zero VETOES auto-approval. It does not
+# flag the visit — it routes it to a human, which is the honest response to
+# "this looks wrong but we are not certain". Confidence is still reported
+# unchanged so the disagreement stays visible in the data.
+#
+# Floors are set BELOW the genuine weak case and ABOVE the fraud case, measured:
+#   dense same-species stand, genuine  -> scene_match ~0.19   (must still pass)
+#   different tree entirely            -> scene_match  0.00   (must be capped)
+CRITICAL_FLOORS: dict[str, float] = {
+    # RAISED FROM 0.20 AFTER MEASUREMENT. A photograph of a brown wooden chair
+    # scored 0.218 and cleared the old floor by 0.018.
+    #
+    # On the 9 real pilot WIDE shots the distribution is bimodal - either 0.000
+    # or >= 0.557, with nothing in between - so 0.35 sits in an empty gap and
+    # rejects no real photo we have, while putting clear daylight above the
+    # chair.
+    #
+    # THIS DOES NOT SOLVE THE CHAIR PROBLEM and must not be described as if it
+    # does. It only catches BROWN fakes. A green wall still scores 1.00, which
+    # is what check_plant_plausibility exists for. Sample is 9 wide shots, so
+    # the "rejects nothing real" claim is thin - revisit with more rounds.
+    "liveness": 0.35,
+    "scene_match": 0.12,
+}
+
+# Auto-approval also requires enough of the signal set to have been available.
+# One signal out of four is not a verification, however good that signal is.
+MIN_COVERAGE_TO_VERIFY = 0.50
+
+MODEL_NAME = "dinov2-small-onnx"
+MODEL_VERSION = "2026.08.1"
+
+
+@dataclass
+class GateResult:
+    passed: bool
+    detail: dict
+
+
+@dataclass
+class Assessment:
+    confidence: int
+    verdict: str
+    signals: dict = field(default_factory=dict)
+
+
+def _ramp(value: float, full: float, zero: float) -> float:
+    """1.0 at `full`, 0.0 at `zero`, linear between. Handles either direction."""
+    if full == zero:
+        return 1.0 if value <= full else 0.0
+    t = (value - zero) / (full - zero)
+    return float(min(1.0, max(0.0, t)))
+
+
+# ---------------------------------------------------------------------------
+# Gates
+# ---------------------------------------------------------------------------
+
+
+def gate_duplicate(this_phash: str, others: list[tuple[str, str]]) -> GateResult:
+    """others: (checkin_id, phash) for every OTHER check-in in the system."""
+    nearest_id, nearest = None, 64
+    for cid, ph in others:
+        if not ph:
+            continue
+        d = hamming(this_phash, ph)
+        if d < nearest:
+            nearest, nearest_id = d, cid
+
+    passed = nearest > DUPLICATE_MAX_HAMMING
+    return GateResult(
+        passed,
+        {
+            "passed": passed,
+            "nearest_phash_distance": nearest,
+            **({"matched_checkin": nearest_id} if not passed and nearest_id else {}),
+        },
+    )
+
+
+def check_plant_plausibility(
+    wide_emb,
+    close_emb,
+    reference,
+) -> GateResult:
+    """Does either photo fail to look like a plant?
+
+    Stops a chair, a wall or a green bedsheet being registered as a tree -
+    which the liveness signal does not, because a green bedsheet is
+    vegetation-coloured and scores a perfect 1.00.
+
+    BOTH photos are checked and the WORSE one decides, so swapping a real
+    tree's wide shot in front of a close-up of something else does not pass.
+
+    Reference vectors are unit-normalised, so a dot product IS the cosine.
+    A missing reference set passes: degrade, don't break.
+    """
+    if reference is None or wide_emb is None or close_emb is None:
+        return GateResult(True, {"passed": True, "available": False})
+
+    sw = float(reference.dot(wide_emb).max())
+    sc = float(reference.dot(close_emb).max())
+    worst = min(sw, sc)
+    passed = worst >= PLANT_SIMILARITY_MIN
+    return GateResult(
+        passed,
+        {
+            "passed": passed,
+            "available": True,
+            "wide_similarity": round(sw, 3),
+            "close_similarity": round(sc, 3),
+            "threshold": PLANT_SIMILARITY_MIN,
+        },
+    )
+
+
+def check_proximity(
+    lat: float,
+    lng: float,
+    earlier: list[tuple[str, float, float]],
+) -> GateResult:
+    """Is there already a tree registered at this spot?
+
+    `earlier` is (tree_id, lat, lng) for trees registered STRICTLY BEFORE this
+    one. The ordering matters: when one trunk becomes two rows, only the second
+    row is the problem. Comparing against all trees would retroactively taint
+    the original — and the original is the one with the honest photo history.
+
+    Returns a GateResult for shape consistency with the real gates, but it is
+    passed to assess() as a REVIEW FLAG, not a gate. `passed=False` here means
+    "a person should look", never "this is fraud".
+    """
+    nearest_id, nearest = None, float("inf")
+    for tid, tlat, tlng in earlier:
+        d = haversine_m(lat, lng, tlat, tlng)
+        if d < nearest:
+            nearest, nearest_id = d, tid
+
+    passed = nearest > PROXIMITY_REVIEW_M
+    detail: dict = {"passed": passed, "radius_m": PROXIMITY_REVIEW_M}
+    if nearest_id is not None:
+        detail["nearest_tree"] = nearest_id
+        detail["nearest_distance_m"] = round(nearest, 1)
+    return GateResult(passed, detail)
+
+
+def gate_gps(
+    tree_lat: float,
+    tree_lng: float,
+    lat: float,
+    lng: float,
+    accuracy_m: float | None,
+    registration_accuracy_m: float | None = None,
+) -> GateResult:
+    dist = haversine_m(tree_lat, tree_lng, lat, lng)
+    allowed = min(
+        GPS_MAX_RADIUS_M,
+        GPS_SLACK_M + (accuracy_m or 0.0) + (registration_accuracy_m or 0.0),
+    )
+    passed = dist <= allowed
+    return GateResult(
+        passed,
+        {"passed": passed, "distance_m": round(dist, 1), "allowed_m": round(allowed, 1)},
+    )
+
+
+def gate_travel(
+    lat: float,
+    lng: float,
+    captured_at: datetime,
+    previous: tuple[str, float, float, datetime] | None,
+) -> GateResult:
+    """previous: the same submitter's most recent check-in elsewhere."""
+    if previous is None:
+        return GateResult(True, {"passed": True})
+
+    pid, plat, plng, pat = previous
+    seconds = abs((captured_at - pat).total_seconds())
+    if seconds < 1:
+        # Two check-ins at the same instant from different places is itself
+        # impossible; treat as a failure rather than dividing by ~zero.
+        metres = haversine_m(plat, plng, lat, lng)
+        passed = metres < 50
+        return GateResult(passed, {"passed": passed, "kmh": None, "from_checkin": pid})
+
+    kmh = (haversine_m(plat, plng, lat, lng) / seconds) * 3.6
+    passed = kmh <= MAX_TRAVEL_KMH
+    return GateResult(
+        passed, {"passed": passed, "kmh": round(kmh, 1), "from_checkin": pid}
+    )
+
+
+# ---------------------------------------------------------------------------
+# Scores
+# ---------------------------------------------------------------------------
+
+
+def score_location(distance_m: float) -> dict:
+    return {
+        "score": _ramp(distance_m, LOCATION_FULL_M, LOCATION_ZERO_M),
+        "distance_m": round(distance_m, 1),
+    }
+
+
+def score_liveness(green_fraction: float, mapped: float) -> dict:
+    return {"score": mapped, "excess_green": round(green_fraction, 4)}
+
+
+def score_scene(
+    cosine_wide: float | None,
+    cosine_close: float | None,
+    inliers: int | None,
+) -> dict:
+    """Corroboration, never identity.
+
+    The wide shot is weighted above the close-up because the spike showed
+    matching works substantially off the surrounding scene, and young bark is
+    smooth and far less distinctive than mature bark — BarkNet's ~94% figures
+    are on MATURE bark and do not transfer to a two-year-old sapling.
+
+    ORB inliers are RECORDED BUT DO NOT AFFECT THE SCORE — see
+    ORB_CONTRIBUTES_TO_SCORE above for the measurement that produced that
+    decision. Reporting a signal we have shown to be non-discriminating would be
+    exactly the unfounded assertion this project exists to avoid.
+    """
+    parts: list[tuple[float, float]] = []
+    if cosine_wide is not None:
+        parts.append((_ramp(-cosine_wide, -SCENE_COSINE_CEIL, -SCENE_COSINE_FLOOR), 0.6))
+    if cosine_close is not None:
+        parts.append((_ramp(-cosine_close, -SCENE_COSINE_CEIL, -SCENE_COSINE_FLOOR), 0.4))
+
+    base = (
+        sum(v * w for v, w in parts) / sum(w for _, w in parts) if parts else 0.0
+    )
+
+    if inliers and ORB_CONTRIBUTES_TO_SCORE:
+        base = min(1.0, base + 0.25 * min(1.0, inliers / ORB_INLIER_STRONG))
+
+    out: dict = {"score": round(base, 4)}
+    if cosine_wide is not None:
+        out["cosine_wide"] = round(cosine_wide, 4)
+    if cosine_close is not None:
+        out["cosine_close"] = round(cosine_close, 4)
+    if inliers is not None:
+        out["orb_inliers"] = int(inliers)
+    return out
+
+
+def score_growth(
+    canopy_now: float | None,
+    canopy_prev: float | None,
+    trunk_mm: float | None = None,
+    trunk_prev_mm: float | None = None,
+) -> dict:
+    """Plausibility, not measurement.
+
+    Trunk diameter barely moves in four weeks on a young tree, so this signal
+    cannot demonstrate growth and we do not claim it does. Its job is catching
+    the IMPOSSIBLE: a trunk that shrank, a seedling that became a mature tree
+    overnight, a canopy that vanished.
+
+    With no prior visit there is nothing to compare, so it returns a neutral 0.5
+    rather than 0 — a first check-in must not be penalised for being first.
+    """
+    out: dict = {}
+    if canopy_now is not None:
+        out["canopy_frac"] = round(canopy_now, 4)
+    if trunk_mm is not None:
+        out["trunk_mm"] = round(trunk_mm, 1)
+
+    if canopy_prev is None and trunk_prev_mm is None:
+        out["score"] = 0.5
+        return out
+
+    score = 1.0
+
+    if canopy_now is not None and canopy_prev is not None:
+        delta = canopy_now - canopy_prev
+        # Losing more than half the canopy in one interval is the dying-tree
+        # signal. Real, and exactly what we want surfaced for review.
+        if canopy_prev > 0.02 and delta / canopy_prev < -0.5:
+            score = min(score, 0.15)
+        # Tripling canopy in days means the framing changed or it is a
+        # different plant.
+        elif canopy_prev > 0.02 and delta / canopy_prev > 2.0:
+            score = min(score, 0.3)
+
+    if trunk_mm is not None and trunk_prev_mm is not None:
+        out["delta_mm"] = round(trunk_mm - trunk_prev_mm, 1)
+        # A trunk cannot shrink. Allow 3mm for measurement error.
+        if trunk_mm < trunk_prev_mm - 3:
+            score = min(score, 0.1)
+        # No young tree gains 30mm of diameter in a check-in interval.
+        elif trunk_mm > trunk_prev_mm + 30:
+            score = min(score, 0.2)
+
+    out["score"] = score
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Combination
+# ---------------------------------------------------------------------------
+
+
+def assess(
+    gates: dict[str, GateResult],
+    scores: dict[str, dict],
+    weights: dict[str, float] | None = None,
+    review_flags: dict[str, GateResult] | None = None,
+) -> Assessment:
+    """`review_flags` are conditions that must not AUTO-APPROVE but are not
+    disqualifying — they demote 'verified' to 'review' and are recorded with a
+    reason. Separate from gates on purpose: a gate says "this is fraud", a review
+    flag says "a person should look at this", and collapsing the two would either
+    accuse honest planters or wave through the thing we wanted a human to see."""
+    w = dict(weights or DEFAULT_WEIGHTS)
+    review_flags = review_flags or {}
+
+    signals: dict = {
+        "gates": {k: v.detail for k, v in gates.items()},
+        "scores": scores,
+        "weights": w,
+        "model": {"name": MODEL_NAME, "version": MODEL_VERSION},
+    }
+    if review_flags:
+        signals["review_flags"] = {k: v.detail for k, v in review_flags.items()}
+
+    failed = [k for k, v in gates.items() if not v.passed]
+    if failed:
+        # Fail closed. A gate failure is not a low score, it is a
+        # disqualification, and reporting a partial confidence next to it would
+        # invite someone to override it.
+        signals["failed_gates"] = failed
+        return Assessment(0, "flagged", signals)
+
+    # Renormalise over the signals we actually have. A missing signal must lower
+    # confidence, never silently count as zero — "designed to degrade, not
+    # break" means an absent compass or a first visit routes to a human rather
+    # than being scored as fraud.
+    present = {k: v for k, v in w.items() if k in scores and "score" in scores[k]}
+    if not present:
+        return Assessment(0, "review", signals)
+
+    total_w = sum(present.values())
+    raw = sum(scores[k]["score"] * wt for k, wt in present.items()) / total_w
+
+    # Coverage penalty: if only half the weight was available, cap confidence
+    # accordingly instead of pretending a partial assessment is a full one.
+    coverage = total_w / sum(w.values())
+    confidence = int(round(100 * raw * (0.6 + 0.4 * coverage)))
+
+    signals["coverage"] = round(coverage, 3)
+
+    if confidence >= VERIFY_AT:
+        verdict = "verified"
+    elif confidence >= REVIEW_AT:
+        verdict = "review"
+    else:
+        verdict = "flagged"
+
+    # --- veto: no compensating away a failed critical signal ---------------
+    vetoes = [
+        name
+        for name, floor in CRITICAL_FLOORS.items()
+        if name in scores and scores[name].get("score", 1.0) < floor
+    ]
+    if coverage < MIN_COVERAGE_TO_VERIFY:
+        vetoes.append("coverage")
+    vetoes.extend(name for name, r in review_flags.items() if not r.passed)
+
+    if vetoes and verdict == "verified":
+        verdict = "review"
+        signals["auto_approval_vetoed_by"] = vetoes
+
+    return Assessment(confidence, verdict, signals)

greenproof_ml/signals.py

@@ -0,0 +1,309 @@
+"""The individual detectors.
+
+Each is deliberately small, pure and independently testable. Five of the six
+fraud types in the attack set are caught here by ordinary deterministic code —
+not by the neural network — and that is the honest reason the system works.
+"""
+
+from __future__ import annotations
+
+import functools
+import math
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+# ---------------------------------------------------------------------------
+# Perceptual hash — the duplicate detector
+# ---------------------------------------------------------------------------
+
+PHASH_SIZE = 32
+PHASH_LOW = 8
+
+
+def phash(img: Image.Image) -> str:
+    """64-bit DCT perceptual hash, as 16 hex characters.
+
+    Catches: resubmitting an identical photo, an old gallery photo of the same
+    tree, and a photo pulled off the internet that someone else also used.
+
+    DCT-based rather than average-hash because it survives the JPEG
+    re-compression the phone applies on resize, while still differing across
+    genuinely different photos. A re-saved copy of the same shot lands within a
+    couple of bits; two real photos of the same tree a week apart are typically
+    20+ bits apart.
+    """
+    a = np.asarray(img.convert("L").resize((PHASH_SIZE, PHASH_SIZE), Image.BICUBIC), dtype=np.float32)
+    d = cv2.dct(a)[:PHASH_LOW, :PHASH_LOW]
+
+    # Exclude the DC term from the median: it carries overall brightness, which
+    # would otherwise drag the threshold around with the weather.
+    flat = d.flatten()[1:]
+    bits = (d.flatten() > np.median(flat)).astype(np.uint8)
+
+    out = 0
+    for bit in bits:
+        out = (out << 1) | int(bit)
+    return f"{out:016x}"
+
+
+def hamming(a: str, b: str) -> int:
+    return bin(int(a, 16) ^ int(b, 16)).count("1")
+
+
+# Below this many differing bits, treat two photos as the same image.
+# Provisional — recalibrate from the T0/round-1 distribution of genuine
+# same-tree pairs, which must sit comfortably ABOVE it.
+DUPLICATE_MAX_HAMMING = 6
+
+
+# ---------------------------------------------------------------------------
+# Liveness — is this a living plant at all?
+# ---------------------------------------------------------------------------
+
+
+def excess_green(img: Image.Image) -> float:
+    """Fraction of the frame that reads as living vegetation.
+
+    ExG = 2G - R - B on channels normalised per-pixel, which is the standard
+    agronomy vegetation index for ordinary RGB cameras. Per-pixel normalisation
+    is what makes it survive Ghanaian midday sun and deep shade in the same
+    frame — an absolute green threshold would not.
+
+    Catches: photographing a dead brown stick, a plank, or the ground.
+    It does NOT prove the plant is the right plant. That is a different signal.
+    """
+    a = np.asarray(img.convert("RGB").resize((256, 256), Image.BILINEAR), dtype=np.float32)
+    total = a.sum(axis=2) + 1e-6
+    r, g, b = a[..., 0] / total, a[..., 1] / total, a[..., 2] / total
+    exg = 2 * g - r - b
+    # 0.05 is the conventional cut for "this pixel is vegetation".
+    return float((exg > 0.05).mean())
+
+
+def liveness_score(frac: float) -> float:
+    """Map green fraction to 0..1.
+
+    A healthy young tree in a wide shot typically fills 0.25-0.6 of the frame
+    with vegetation; below ~0.05 there is essentially nothing living in view.
+    Ramped rather than stepped so a leaf-dropping tree degrades smoothly instead
+    of falling off a cliff — the point is to flag decline, not to fail it.
+    """
+    return float(np.clip((frac - 0.05) / (0.30 - 0.05), 0.0, 1.0))
+
+
+# ---------------------------------------------------------------------------
+# Plant plausibility - "is this even a plant?"
+# ---------------------------------------------------------------------------
+#
+# WHY THIS IS NOT THE LIVENESS SIGNAL. excess_green measures how much of the
+# frame is vegetation-COLOURED. Measured against 250 COCO photographs, a green
+# painted wall and artificial turf both score 1.00, and the median ordinary
+# outdoor photo scores 0.47 because ordinary outdoor photos contain grass. No
+# threshold on green separates a tree from a chair; we tried, and raising the
+# floor rejects real trees faster than it rejects furniture.
+#
+# So this asks a different question of the embedding we already compute: does
+# this photo resemble anything in a reference set of known plants?
+
+_REFERENCE_FILE = Path(__file__).resolve().parent / "plant_reference.npy"
+
+
+@functools.lru_cache(maxsize=1)
+def plant_reference() -> "np.ndarray | None":
+    """Unit-normalised embeddings of known plants, or None if unavailable.
+
+    None is a supported state, not an error: a missing reference file must
+    lower confidence and route to a human, never reject a real planter's tree.
+
+    THE REFERENCE SET IS THE LIMIT OF THIS CHECK. It is 74 photos of 15 plants
+    at one Ghanaian campus in one season, so it recognises "a plant
+    photographed the way our reference photos were". Swapping in PlantNet-300K
+    scored a perfect AUC and then flagged 97% of our own photos, because
+    PlantNet is square cropped specimens and ours are wide shots with sky and
+    buildings in frame - it had learned the photo STYLE, not the subject. The
+    set must therefore grow from our own verified check-ins, which is also why
+    the check gets better the longer the system runs.
+    """
+    try:
+        v = np.load(_REFERENCE_FILE)
+        return v if v.ndim == 2 and v.shape[0] else None
+    except Exception:  # noqa: BLE001 - degrade, don't break
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Scene match — ORB + RANSAC, corroborating the embedding
+# ---------------------------------------------------------------------------
+
+
+def orb_inliers(a: Image.Image, b: Image.Image, max_side: int = 640) -> int:
+    """Count geometrically consistent keypoint matches between two photos.
+
+    Complements the DINOv2 embedding rather than duplicating it. The embedding
+    answers "does this look like the same kind of scene"; ORB+RANSAC answers
+    "are the same physical points present in a consistent geometric arrangement".
+    An attacker can find a visually similar tree far more easily than one that
+    matches point-for-point.
+
+    Returns 0 when there is no consistent geometry at all.
+    """
+
+    def prep(img: Image.Image) -> np.ndarray:
+        g = np.asarray(img.convert("L"))
+        h, w = g.shape
+        s = max_side / max(h, w)
+        if s < 1:
+            g = cv2.resize(g, (int(w * s), int(h * s)), interpolation=cv2.INTER_AREA)
+        return g
+
+    ga, gb = prep(a), prep(b)
+    orb = cv2.ORB_create(nfeatures=1500)
+    ka, da = orb.detectAndCompute(ga, None)
+    kb, db = orb.detectAndCompute(gb, None)
+    if da is None or db is None or len(ka) < 8 or len(kb) < 8:
+        return 0
+
+    matcher = cv2.BFMatcher(cv2.NORM_HAMMING)
+    raw = matcher.knnMatch(da, db, k=2)
+
+    # Lowe's ratio test: keep a match only if it is clearly better than the
+    # runner-up. Foliage produces enormous numbers of near-identical descriptors,
+    # so without this the match list is almost entirely noise.
+    good = [m for m, n in (p for p in raw if len(p) == 2) if m.distance < 0.75 * n.distance]
+    if len(good) < 8:
+        return 0
+
+    src = np.float32([ka[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
+    dst = np.float32([kb[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
+    _, mask = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
+    return 0 if mask is None else int(mask.sum())
+
+
+# ---------------------------------------------------------------------------
+# ArUco — turning a photo into millimetres
+# ---------------------------------------------------------------------------
+
+DEFAULT_MARKER_MM = 80.0
+
+
+def find_aruco(img: Image.Image) -> dict | None:
+    """Locate the reference marker and return millimetres-per-pixel.
+
+    The marker solves two problems at once, which is why it beats holding up a
+    coin or a ruler:
+
+      * SCALE — its real edge length is known, so we get mm per pixel
+      * TILT  — four corners of a known square let us see that the card was
+                photographed at an angle. A plain rectangle cannot give this,
+                and an uncorrected 30 degree tilt is a ~15% error in width.
+
+    `tilt_ratio` near 1.0 means the card was square-on. Far from 1.0 means the
+    measurement should be distrusted rather than silently accepted.
+    """
+    a = np.asarray(img.convert("L"))
+    d = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
+    corners, ids, _ = cv2.aruco.ArucoDetector(d, cv2.aruco.DetectorParameters()).detectMarkers(a)
+    if ids is None or len(corners) == 0:
+        return None
+
+    pts = corners[0].reshape(4, 2)
+    sides = [float(np.linalg.norm(pts[i] - pts[(i + 1) % 4])) for i in range(4)]
+    px = float(np.mean(sides))
+    if px < 10:  # too small in frame to measure anything from
+        return None
+
+    return {
+        "marker_id": int(ids.flatten()[0]),
+        "side_px": px,
+        "mm_per_px": DEFAULT_MARKER_MM / px,
+        "tilt_ratio": float(min(sides) / max(sides)),
+    }
+
+
+def trunk_width_mm(img: Image.Image, taps: dict | None) -> dict | None:
+    """Convert the user's two trunk-edge taps into millimetres.
+
+    THIS IS THE ONLY PLACE MILLIMETRES ARE PRODUCED, and it runs server-side on
+    purpose. The client sends where a finger touched; it never sends a width.
+    Trunk width feeds the "a trunk cannot shrink" plausibility check, so a
+    client-supplied width would let a forged request defeat that check.
+
+    Requires the ArUco marker to be visible in the same frame — without a known
+    reference length a photo has no scale at all, and a thin trunk photographed
+    close up is pixel-for-pixel identical to a thick one photographed far away.
+
+    Returns None when the marker is absent, which is a normal outcome: the visit
+    still counts, the growth signal is simply unavailable and confidence drops
+    via the coverage term rather than the check failing.
+    """
+    if not taps:
+        return None
+
+    marker = find_aruco(img)
+    if marker is None:
+        return {"available": False, "reason": "no marker detected"}
+
+    try:
+        lx, ly = float(taps["left"]["x"]), float(taps["left"]["y"])
+        rx, ry = float(taps["right"]["x"]), float(taps["right"]["y"])
+    except (KeyError, TypeError, ValueError):
+        return {"available": False, "reason": "malformed taps"}
+
+    w, h = img.size
+    # Euclidean, not just horizontal: people rarely tap two points at exactly
+    # the same height, and on a leaning trunk they should not.
+    dx, dy = (rx - lx) * w, (ry - ly) * h
+    px = math.hypot(dx, dy)
+
+    out = {
+        "available": True,
+        "trunk_px": round(px, 1),
+        "mm_per_px": round(marker["mm_per_px"], 5),
+        "marker_id": marker["marker_id"],
+        "tilt_ratio": round(marker["tilt_ratio"], 3),
+        "trunk_mm": round(px * marker["mm_per_px"], 1),
+    }
+
+    # A badly tilted card means the marker's apparent width is foreshortened,
+    # so mm-per-pixel is wrong and so is everything derived from it. Flag rather
+    # than silently returning a confident wrong number.
+    if marker["tilt_ratio"] < 0.80:
+        out["suspect"] = "marker photographed at a steep angle; hold it flat"
+
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Canopy — the signal that actually moves in four weeks
+# ---------------------------------------------------------------------------
+
+
+def canopy_fraction(img: Image.Image) -> float:
+    """Share of the wide shot occupied by vegetation.
+
+    Unlike trunk diameter, this changes measurably in weeks: a stressed tree
+    drops leaves, and July-August is the rainy season so a healthy tree is
+    putting on leaf. This is the dying-tree detector, and it is why the pilot
+    deliberately includes struggling trees.
+
+    Only comparable BETWEEN VISITS when framing is reproduced — which is what
+    the compass heading and the ghost overlay exist to achieve.
+    """
+    return excess_green(img)
+
+
+# ---------------------------------------------------------------------------
+# Travel plausibility
+# ---------------------------------------------------------------------------
+
+
+def haversine_m(lat1: float, lng1: float, lat2: float, lng2: float) -> float:
+    r = 6_371_000.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lng2 - lng1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * r * math.asin(math.sqrt(a))

greenproof_ml/store.py

@@ -0,0 +1,278 @@
+"""All database and storage access, in one place.
+
+Runs with the SERVICE ROLE key, which bypasses RLS and the column grants. That
+is the whole security model in one sentence: the browser physically cannot write
+`confidence`, `verdict` or `signals` because those columns are not granted to
+`authenticated`, and this service is the only thing holding a key that can.
+
+The service key must never reach the frontend. It lives only in the Hugging Face
+Space's secrets.
+"""
+
+from __future__ import annotations
+
+import io
+import math
+import os
+from datetime import datetime, timezone
+
+import numpy as np
+from PIL import Image
+from supabase import Client, create_client
+
+BUCKET = "tree-photos"
+
+
+def _client() -> Client:
+    url = os.environ.get("SUPABASE_URL")
+    key = os.environ.get("SUPABASE_SERVICE_KEY")
+    if not url or not key:
+        raise RuntimeError(
+            "SUPABASE_URL and SUPABASE_SERVICE_KEY must be set. "
+            "On Hugging Face Spaces these go in Settings -> Variables and secrets."
+        )
+    return create_client(url, key)
+
+
+_db: Client | None = None
+
+
+def db() -> Client:
+    global _db
+    if _db is None:
+        _db = _client()
+    return _db
+
+
+def parse_ts(value: str) -> datetime:
+    """Postgres timestamptz -> aware datetime.
+
+    Postgres emits '+00:00' or a 6-digit fractional second; Python's fromisoformat
+    is fussy about 'Z' on older versions. Normalising here stops a timezone bug
+    from silently turning the travel-speed gate into nonsense.
+    """
+    v = value.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(v)
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def vector_literal(v: np.ndarray) -> str:
+    """pgvector wants '[0.1,0.2,...]' as text, not a JSON array."""
+    return "[" + ",".join(f"{x:.6f}" for x in v.tolist()) + "]"
+
+
+# ---------------------------------------------------------------------------
+# Reads
+# ---------------------------------------------------------------------------
+
+
+def get_checkin(checkin_id: str) -> dict | None:
+    r = db().table("checkins").select("*").eq("id", checkin_id).limit(1).execute()
+    return r.data[0] if r.data else None
+
+
+def get_tree(tree_id: str) -> dict | None:
+    r = db().table("trees").select("*").eq("id", tree_id).limit(1).execute()
+    return r.data[0] if r.data else None
+
+
+def list_pending(limit: int = 50) -> list[dict]:
+    r = (
+        db()
+        .table("checkins")
+        .select("id")
+        .eq("verdict", "pending")
+        .order("server_received_at", desc=False)
+        .limit(limit)
+        .execute()
+    )
+    return r.data or []
+
+
+def other_phashes(exclude_checkin_id: str) -> list[tuple[str, str]]:
+    """Every other check-in's pHash, for the duplicate gate.
+
+    Deliberately global, not scoped to this tree: submitting tree 7's photo as
+    tree 12's check-in is one of the attacks, and scoping the search to tree 12
+    would miss it entirely.
+    """
+    r = (
+        db()
+        .table("checkins")
+        .select("id, phash")
+        .not_.is_("phash", "null")
+        .neq("id", exclude_checkin_id)
+        .execute()
+    )
+    return [(row["id"], row["phash"]) for row in (r.data or []) if row.get("phash")]
+
+
+def trees_near_registered_before(
+    tree_id: str,
+    lat: float,
+    lng: float,
+    before_iso: str,
+    radius_m: float,
+) -> list[tuple[str, float, float]]:
+    """Trees within `radius_m` that were registered BEFORE this one.
+
+    Across all owners: one physical tree registered by two different people is
+    the double-payment case, and scoping this to the owner would miss exactly
+    that.
+
+    A bounding box does the elimination in Postgres and the true distance is
+    measured here. PostGIS is available and `trees.location` is indexed, but
+    reaching it needs a SQL function; the box uses the plain lat/lng columns and
+    is correct because the caller re-measures. At pilot scale the difference is
+    unmeasurable — the box is there so this does not become a full table scan
+    when the grove is 40,000 trees rather than 40.
+    """
+    d_lat = radius_m / 111_320.0
+    d_lng = radius_m / max(111_320.0 * math.cos(math.radians(lat)), 1e-6)
+
+    r = (
+        db()
+        .table("trees")
+        .select("id, lat, lng")
+        .gte("lat", lat - d_lat)
+        .lte("lat", lat + d_lat)
+        .gte("lng", lng - d_lng)
+        .lte("lng", lng + d_lng)
+        .lt("created_at", before_iso)
+        .neq("id", tree_id)
+        .execute()
+    )
+    return [(row["id"], row["lat"], row["lng"]) for row in (r.data or [])]
+
+
+def previous_checkins(tree_id: str, before_iso: str) -> list[dict]:
+    """Earlier visits to this tree, newest first, with embeddings."""
+    r = (
+        db()
+        .table("checkins")
+        .select(
+            "id, wide_photo, close_photo, captured_at, wide_embedding, "
+            "close_embedding, signals, verdict"
+        )
+        .eq("tree_id", tree_id)
+        .lt("captured_at", before_iso)
+        .order("captured_at", desc=True)
+        .execute()
+    )
+    return r.data or []
+
+
+def previous_by_submitter(
+    submitter_id: str, before_iso: str, exclude_checkin_id: str
+) -> dict | None:
+    """The submitter's most recent check-in anywhere — for the travel gate."""
+    r = (
+        db()
+        .table("checkins")
+        .select("id, lat, lng, captured_at")
+        .eq("submitted_by", submitter_id)
+        .lt("captured_at", before_iso)
+        .neq("id", exclude_checkin_id)
+        .order("captured_at", desc=True)
+        .limit(1)
+        .execute()
+    )
+    return r.data[0] if r.data else None
+
+
+def download_image(path: str) -> Image.Image:
+    raw = db().storage.from_(BUCKET).download(path)
+    return Image.open(io.BytesIO(raw))
+
+
+def parse_embedding(value) -> np.ndarray | None:
+    """pgvector comes back as either a string literal or a list, depending on
+    the PostgREST version. Handle both rather than discovering it at 2am."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = value.strip().strip("[]")
+        if not value:
+            return None
+        return np.fromstring(value, sep=",", dtype=np.float32)
+    return np.asarray(value, dtype=np.float32)
+
+
+# ---------------------------------------------------------------------------
+# Writes — only this process may perform them
+# ---------------------------------------------------------------------------
+
+
+def write_result(
+    checkin_id: str,
+    *,
+    phash: str,
+    wide_embedding: np.ndarray,
+    close_embedding: np.ndarray,
+    confidence: int,
+    verdict: str,
+    signals: dict,
+    audit_sample: bool = False,
+) -> None:
+    db().table("checkins").update(
+        {
+            "phash": phash,
+            "wide_embedding": vector_literal(wide_embedding),
+            "close_embedding": vector_literal(close_embedding),
+            "confidence": confidence,
+            "verdict": verdict,
+            "signals": signals,
+            "audit_sample": audit_sample,
+        }
+    ).eq("id", checkin_id).execute()
+
+
+def write_advice(checkin_id: str, species_guess: dict, advice: dict) -> None:
+    """Store the advisory assessment.
+
+    Writes ONLY the two advisory columns. It does not touch `confidence`,
+    `verdict` or `signals`, and that separation is the whole point: advice is
+    generated by a component whose error rate we have not measured, so it must
+    not be able to move a number we publish.
+
+    Note this is a separate write from write_result rather than a parameter on
+    it. Scoring is replayable and re-run whenever a threshold changes; advice is
+    a paid external call that should survive a re-score untouched. Folding the
+    two together would either destroy advice on every recalibration or make
+    recalibration cost money.
+    """
+    db().table("checkins").update(
+        {"species_guess": species_guess, "advice": advice}
+    ).eq("id", checkin_id).execute()
+
+
+def list_checkins_without_advice(limit: int = 100) -> list[dict]:
+    """Check-ins that have never been assessed, oldest first."""
+    r = (
+        db()
+        .table("checkins")
+        .select("id")
+        .is_("advice", "null")
+        .order("server_received_at", desc=False)
+        .limit(limit)
+        .execute()
+    )
+    return r.data or []
+
+
+def update_tree_status(tree_id: str, confidence: int, verdict: str) -> None:
+    """Roll the latest verdict up onto the tree.
+
+    'alive' only on a verified check-in. A tree never becomes 'dead'
+    automatically — that is a human decision, because being wrong about it stops
+    someone's payment.
+    """
+    status = {
+        "verified": "alive",
+        "review": "pending",
+        "flagged": "flagged",
+    }.get(verdict, "pending")
+
+    db().table("trees").update(
+        {"status": status, "current_confidence": confidence}
+    ).eq("id", tree_id).execute()

requirements.txt

@@ -0,0 +1,26 @@
+# Pinned loosely — Hugging Face Spaces rebuilds on push and a surprise major
+# version on pitch week is not a risk worth taking for a few KB of convenience.
+
+fastapi>=0.115,<1
+uvicorn[standard]>=0.32,<1
+pydantic>=2.9,<3
+
+# onnxruntime, NOT torch. Torch pulls ~2 GB and would make cold starts on the
+# free Spaces tier unusable. Torch stays a dev-only dependency for the spike.
+onnxruntime>=1.19,<2
+huggingface_hub>=0.26,<1
+
+numpy>=1.26,<3
+pillow>=10.4,<12
+
+# contrib, not plain opencv — cv2.aruco lives in contrib and the ArUco marker is
+# how a photo becomes a measurement in millimetres.
+opencv-contrib-python-headless>=4.10,<5
+
+supabase>=2.9,<3
+httpx>=0.27,<1
+
+# Advisory layer only: species identification and care advice for the planter.
+# NOT on the scoring path - pipeline.py never imports the advisor, so a slow or
+# failed API call cannot affect a verdict.
+anthropic>=0.40