installgate 0.1.0__py3-none-any.whl

contracts/README.md

@@ -0,0 +1,11 @@
+# contracts/ — both engineers
+
+`contracts.py` and `contracts.ts` are the shared API shape.
+
+**FROZEN as of gate G1 (2026-10-26).** Field names, types, and enum values in `contracts.py` are final. Kate and Jenny both build against this shape starting now — the API, CLI, terminal output, and UI must all read the same field names, or the same package install will show different results depending on which surface you look at.
+
+Rules from here on:
+
+- No renaming, adding, or removing a field, enum value, or model on a feature branch without saying so in the PR title (e.g. `fix(contracts): ...`).
+- Any such change needs review from **both** engineers before merge — see `.github/CODEOWNERS`.
+- If a field turns out to be wrong, open an issue and discuss before touching the file. Do not silently rename and let the other person find out from a failing build.

contracts/__init__.py

@@ -0,0 +1,31 @@
+"""Frozen data contracts. Changes after gate G1 need both engineers."""
+
+from contracts.contracts import (
+    Ecosystem,
+    Evidence,
+    EvidenceKind,
+    ExplanationSentence,
+    GateVerdict,
+    Outcome,
+    RouteCall,
+    RouterReceipt,
+    SafeRemediation,
+    SandboxResult,
+    TargetRef,
+    Verdict,
+)
+
+__all__ = [
+    "Ecosystem",
+    "Evidence",
+    "EvidenceKind",
+    "ExplanationSentence",
+    "GateVerdict",
+    "Outcome",
+    "RouteCall",
+    "RouterReceipt",
+    "SafeRemediation",
+    "SandboxResult",
+    "TargetRef",
+    "Verdict",
+]

contracts/contracts.py

@@ -0,0 +1,260 @@
+"""InstallGate data contracts (Pydantic v2).
+
+FROZEN as of gate G1 (2026-10-26). Field names, types, and enum values below
+are final. Renaming, adding, or removing any of them requires both engineers
+on the PR (see contracts/README.md and AGENTS.md section 9) — the API, CLI,
+and UI all read these field names and must stay in sync.
+
+Design rules enforced in code, not in prose:
+  * Evidence is frozen and content-hashed (immutable once emitted).
+  * final_verdict == max(policy_verdict, llm_verdict) on the ALLOW<REVIEW<BLOCK lattice.
+  * The LLM may only raise ALLOW -> REVIEW. BLOCK requires hard, deterministic evidence.
+  * Every explanation sentence must cite at least one existing Evidence id.
+  * VERIFIED_SUBSTITUTE is an *outcome*, never a loosened verdict: the original target stays BLOCK/REVIEW.
+  * A substitute must come from a closed candidate set and be pinned (version + sha256).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+EV_ID = r"^EV-[0-9]{1,4}$"
+SHA256 = r"^[0-9a-f]{64}$"
+
+
+class Ecosystem(str, Enum):
+    PYPI = "pypi"
+    NPM = "npm"
+    HUGGINGFACE = "huggingface"
+    DOCKER = "docker"
+
+
+class Verdict(str, Enum):
+    ALLOW = "ALLOW"
+    REVIEW = "REVIEW"
+    BLOCK = "BLOCK"
+
+    @property
+    def rank(self) -> int:
+        return {"ALLOW": 0, "REVIEW": 1, "BLOCK": 2}[self.value]
+
+
+class Outcome(str, Enum):
+    ALLOW = "ALLOW"
+    REVIEW = "REVIEW"
+    BLOCK = "BLOCK"
+    VERIFIED_SUBSTITUTE = "VERIFIED_SUBSTITUTE"  # original stays blocked; a pinned alternative passed Stage 4
+
+
+class Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class TargetRef(Frozen):
+    ecosystem: Ecosystem
+    name: str = Field(min_length=1, max_length=214, pattern=r"^[A-Za-z0-9@/_.\-:]+$")  # validated BEFORE any network call
+    version: Optional[str] = Field(default=None, max_length=64)
+    artifact_sha256: Optional[str] = Field(default=None, pattern=SHA256)
+    revision: Optional[str] = Field(default=None, pattern=r"^[0-9a-f]{40}$")  # git commit; for Hugging Face, pinned = revision is set
+
+
+CHECK_UNAVAILABLE_REASONS = frozenset({
+    "no_floor_for_branch", "floating_tag", "digest_only", "image_not_in_table", "typosquat_unsupported_ecosystem",
+})
+
+
+class EvidenceKind(str, Enum):
+    NOT_FOUND = "not_found"
+    NEW_PROJECT = "new_project"          # first upload is recent
+    NEW_RELEASE = "new_release"          # latest version is recent (soft by itself)
+    MAINTAINER_CHANGE = "maintainer_change"
+    OSV_MALICIOUS = "osv_malicious"      # MAL-* record
+    TYPOSQUAT = "typosquat"
+    TYPOSQUAT_NEW_PROJECT = "typosquat_new_project"  # derived: typosquat + first upload < 7 days (rule P4, hard)
+    HF_PICKLE = "hf_pickle"
+    HF_SAFETENSORS_SIBLING = "hf_safetensors_sibling"
+    RUNTIME_BELOW_FLOOR = "runtime_below_floor"
+    WEB_REPORT = "web_report"            # Tavily; untrusted, soft only
+    RECHECK_PASSED = "recheck_passed"
+    SANDBOX_IMPORT = "sandbox_import"
+    CHECK_UNAVAILABLE = "check_unavailable"  # a check could not run; observed["reason"] says why; never hard
+
+
+class Evidence(Frozen):
+    id: str = Field(pattern=EV_ID)
+    kind: EvidenceKind
+    source: Literal["pypi", "npm", "osv", "huggingface", "docker_registry", "policy_yaml", "tavily", "sandbox"]
+    trust: Literal["deterministic", "retrieved_untrusted"]
+    severity: Literal["info", "soft", "hard"]
+    target: TargetRef
+    observed: dict[str, Any] = Field(default_factory=dict)
+    source_url: Optional[str] = Field(default=None, max_length=2048)
+    fetched_at: datetime
+    content_hash: str = Field(pattern=SHA256)
+
+    @staticmethod
+    def compute_hash(kind: str, target: TargetRef, observed: dict[str, Any], source_url: Optional[str]) -> str:
+        t = target.model_dump(mode="json")
+        if t.get("revision") is None:
+            t.pop("revision", None)  # keeps hashes of evidence made before the revision field unchanged
+        blob = json.dumps(
+            {"k": kind, "t": t, "o": observed, "u": source_url},
+            sort_keys=True, separators=(",", ":"), default=str,
+        )
+        return hashlib.sha256(blob.encode()).hexdigest()
+
+    @model_validator(mode="after")
+    def _invariants(self) -> "Evidence":
+        if self.trust == "retrieved_untrusted" and self.severity == "hard":
+            raise ValueError("untrusted (web) evidence can never be 'hard'")
+        if self.kind == EvidenceKind.CHECK_UNAVAILABLE and self.severity == "hard":
+            raise ValueError("check_unavailable can never be 'hard'")
+        if self.kind == EvidenceKind.CHECK_UNAVAILABLE and self.observed.get("reason") not in CHECK_UNAVAILABLE_REASONS:
+            raise ValueError(f"check_unavailable needs observed['reason'] in {sorted(CHECK_UNAVAILABLE_REASONS)}")
+        if self.content_hash != self.compute_hash(self.kind.value, self.target, self.observed, self.source_url):
+            raise ValueError("content_hash mismatch: evidence was mutated")
+        return self
+
+
+class ExplanationSentence(Frozen):
+    text: str = Field(min_length=1, max_length=400)
+    evidence_ids: list[str] = Field(min_length=1)
+
+
+# ---------- Router ----------
+class ModelTier(str, Enum):
+    NANO = "nano"
+    SUPER = "super"
+    ULTRA = "ultra"
+
+
+class RouteCall(Frozen):
+    stage: Literal["extract", "explain", "rank_substitute", "escalate"]
+    tier: ModelTier
+    model_id: str                      # resolved from GET /v1/models at startup, never hard-coded
+    prompt_tokens: int = Field(ge=0)
+    completion_tokens: int = Field(ge=0)
+    cost_usd: float = Field(ge=0)
+    latency_ms: int = Field(ge=0)
+    escalation_reason: Optional[str] = None
+    schema_valid: bool = True          # structured output parsed on first try?
+    retries: int = Field(default=0, ge=0)
+
+
+class RouterReceipt(Frozen):
+    calls: list[RouteCall]
+    total_cost_usd: float = Field(ge=0)
+    counterfactual_all_ultra_usd: float = Field(ge=0)
+    savings_pct: float
+    price_table_version: str           # e.g. "2026-10-25 token-factory-catalog"
+    tavily_calls: int = Field(default=0, ge=0)
+    deterministic_only_ms: int = Field(ge=0)   # Stage 1 latency, shown to prove the LLM is not on the hot path
+
+
+# ---------- Remediation ----------
+class SandboxResult(Frozen):
+    provider: Literal["nebius_token_factory_sandboxes"]
+    sandbox_id: str
+    image_digest: str
+    prepare_phase_network: Literal["registry_only", "on"]
+    verify_phase_network: Literal["off"]               # verification MUST run offline
+    egress_denial_confirmed: bool
+    exit_code: int
+    import_ok: bool
+    probe_symbols_ok: list[str] = Field(default_factory=list)   # AST-validated import/hasattr probes only
+    duration_ms: int = Field(ge=0)
+
+
+class SafeRemediation(Frozen):
+    status: Literal["VERIFIED_SUBSTITUTE", "NO_SAFE_SUBSTITUTE", "VERIFICATION_UNAVAILABLE", "VERIFICATION_FAILED"]
+    original: TargetRef
+    candidate: Optional[TargetRef] = None
+    candidate_source: Optional[Literal["alias_map", "top_n_neighbor", "hf_sibling", "docker_patched_floor"]] = None
+    candidate_set_ids: list[str] = Field(default_factory=list)    # closed set the LLM ranked over, by id
+    selected_by: Optional[Literal["rule", "llm_rank"]] = None
+    verification_level: Optional[Literal["sandbox_import", "static_registry"]] = None
+    recheck_evidence_ids: list[str] = Field(default_factory=list)
+    approved_requirement: Optional[str] = None                     # e.g. "requests-oauthlib==2.0.0 --hash=sha256:..."
+    sandbox: Optional[SandboxResult] = None
+    equivalence_note: str = "import-compatible only; behavioural equivalence is not guaranteed"
+
+    @model_validator(mode="after")
+    def _verified_requires_proof(self) -> "SafeRemediation":
+        if self.status == "VERIFIED_SUBSTITUTE":
+            c = self.candidate
+            if c is None or not c.version or not c.artifact_sha256:
+                raise ValueError("verified substitute must be pinned (version + sha256)")
+            if self.candidate_source is None or not self.candidate_set_ids:
+                raise ValueError("substitute must come from a closed candidate set")
+            if not self.recheck_evidence_ids:
+                raise ValueError("Stage 1 must be re-run on the substitute")
+            if self.verification_level == "sandbox_import":
+                s = self.sandbox
+                if s is None or not (s.import_ok and s.egress_denial_confirmed and s.exit_code == 0):
+                    raise ValueError("sandbox verification incomplete")
+            elif self.verification_level != "static_registry":
+                raise ValueError("verification_level required")
+        return self
+
+
+# ---------- Verdict ----------
+class GateVerdict(Frozen):
+    request_id: str
+    target: TargetRef
+    policy_version: str
+    policy_verdict: Verdict
+    llm_verdict: Optional[Verdict] = None
+    final_verdict: Verdict
+    outcome: Outcome
+    risk_score: float = Field(ge=0, le=1)
+    failed_closed: bool = False
+    evidence: list[Evidence]
+    explanation: list[ExplanationSentence] = Field(default_factory=list)
+    dropped_sentences: int = Field(default=0, ge=0)
+    next_action: Literal["proceed", "use_substitute", "ask_human", "abort"]
+    remediation: Optional[SafeRemediation] = None
+    receipt: Optional[RouterReceipt] = None
+
+    @model_validator(mode="after")
+    def _invariants(self) -> "GateVerdict":
+        ids = {e.id for e in self.evidence}
+        if len(ids) != len(self.evidence):
+            raise ValueError("duplicate evidence ids")
+        for s in self.explanation:
+            if not set(s.evidence_ids) <= ids:
+                raise ValueError("explanation cites unknown evidence id")
+        # lattice: LLM can only tighten
+        llm = self.llm_verdict or Verdict.ALLOW
+        expected = self.policy_verdict if self.policy_verdict.rank >= llm.rank else llm
+        if self.final_verdict != expected:
+            raise ValueError("final_verdict must equal max(policy, llm)")
+        # LLM may raise ALLOW->REVIEW only; BLOCK needs hard deterministic evidence
+        if self.final_verdict == Verdict.BLOCK and self.policy_verdict != Verdict.BLOCK:
+            raise ValueError("BLOCK must come from deterministic policy, not the LLM")
+        if self.policy_verdict == Verdict.BLOCK and not any(
+            e.severity == "hard" and e.trust == "deterministic" for e in self.evidence
+        ):
+            raise ValueError("policy BLOCK requires hard deterministic evidence")
+        if self.failed_closed and self.final_verdict == Verdict.ALLOW:
+            raise ValueError("fail-closed can never yield ALLOW")
+        # outcome consistency
+        if self.outcome == Outcome.VERIFIED_SUBSTITUTE:
+            if self.final_verdict == Verdict.ALLOW:
+                raise ValueError("nothing to substitute for an ALLOW")
+            if not self.remediation or self.remediation.status != "VERIFIED_SUBSTITUTE":
+                raise ValueError("VERIFIED_SUBSTITUTE outcome requires verified remediation")
+            if self.next_action != "use_substitute":
+                raise ValueError("next_action must be use_substitute")
+        elif self.outcome.value != self.final_verdict.value:
+            raise ValueError("outcome must mirror final_verdict unless VERIFIED_SUBSTITUTE")
+        pinned = bool(self.target.version and self.target.artifact_sha256) or (
+            self.target.ecosystem == Ecosystem.HUGGINGFACE and self.target.revision is not None
+        )
+        if self.final_verdict == Verdict.ALLOW and self.outcome == Outcome.ALLOW and not pinned:
+            raise ValueError("ALLOW must be pinned (version + sha256, or a Hugging Face revision) to be meaningful (TOCTOU)")
+        return self

contracts/contracts.ts

@@ -0,0 +1,151 @@
+// InstallGate data contracts (TypeScript, zod v3/v4). Mirror of contracts.py.
+// Generate once from the Python models (pydantic -> JSON Schema -> json-schema-to-zod) in CI so the two cannot drift.
+import { z } from "zod";
+
+export const Ecosystem = z.enum(["pypi", "npm", "huggingface", "docker"]);
+export const Verdict = z.enum(["ALLOW", "REVIEW", "BLOCK"]);
+export const Outcome = z.enum(["ALLOW", "REVIEW", "BLOCK", "VERIFIED_SUBSTITUTE"]);
+export type Verdict = z.infer<typeof Verdict>;
+
+const rank: Record<Verdict, number> = { ALLOW: 0, REVIEW: 1, BLOCK: 2 };
+export const maxVerdict = (a: Verdict, b: Verdict): Verdict => (rank[a] >= rank[b] ? a : b);
+
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+const evId = z.string().regex(/^EV-[0-9]{1,4}$/);
+
+export const TargetRef = z.object({
+  ecosystem: Ecosystem,
+  name: z.string().min(1).max(214).regex(/^[A-Za-z0-9@/_.\-:]+$/),
+  version: z.string().max(64).optional(),
+  artifact_sha256: sha256.optional(),
+  revision: z.string().regex(/^[0-9a-f]{40}$/).optional(),
+}).strict();
+
+export const EvidenceKind = z.enum([
+  "not_found", "new_project", "new_release", "maintainer_change", "osv_malicious",
+  "typosquat", "typosquat_new_project", "hf_pickle", "hf_safetensors_sibling", "runtime_below_floor",
+  "web_report", "recheck_passed", "sandbox_import", "check_unavailable",
+]);
+
+export const CHECK_UNAVAILABLE_REASONS = [
+  "no_floor_for_branch", "floating_tag", "digest_only", "image_not_in_table", "typosquat_unsupported_ecosystem",
+] as const;
+
+export const Evidence = z.object({
+  id: evId,
+  kind: EvidenceKind,
+  source: z.enum(["pypi", "npm", "osv", "huggingface", "docker_registry", "policy_yaml", "tavily", "sandbox"]),
+  trust: z.enum(["deterministic", "retrieved_untrusted"]),
+  severity: z.enum(["info", "soft", "hard"]),
+  target: TargetRef,
+  observed: z.record(z.string(), z.unknown()),
+  source_url: z.string().max(2048).optional(),
+  fetched_at: z.string().datetime(),
+  content_hash: sha256,
+}).strict().refine(e => !(e.trust === "retrieved_untrusted" && e.severity === "hard"),
+  { message: "untrusted (web) evidence can never be 'hard'" })
+  .refine(e => !(e.kind === "check_unavailable" && e.severity === "hard"),
+    { message: "check_unavailable can never be 'hard'" })
+  .refine(e => e.kind !== "check_unavailable" ||
+    (CHECK_UNAVAILABLE_REASONS as readonly unknown[]).includes(e.observed["reason"]),
+    { message: "check_unavailable needs observed['reason'] from CHECK_UNAVAILABLE_REASONS" });
+
+export const ExplanationSentence = z.object({
+  text: z.string().min(1).max(400),
+  evidence_ids: z.array(evId).min(1),
+}).strict();
+
+export const ModelTier = z.enum(["nano", "super", "ultra"]);
+
+export const RouteCall = z.object({
+  stage: z.enum(["extract", "explain", "rank_substitute", "escalate"]),
+  tier: ModelTier,
+  model_id: z.string(),
+  prompt_tokens: z.number().int().nonnegative(),
+  completion_tokens: z.number().int().nonnegative(),
+  cost_usd: z.number().nonnegative(),
+  latency_ms: z.number().int().nonnegative(),
+  escalation_reason: z.string().optional(),
+  schema_valid: z.boolean().default(true),
+  retries: z.number().int().nonnegative().default(0),
+}).strict();
+
+export const RouterReceipt = z.object({
+  calls: z.array(RouteCall),
+  total_cost_usd: z.number().nonnegative(),
+  counterfactual_all_ultra_usd: z.number().nonnegative(),
+  savings_pct: z.number(),
+  price_table_version: z.string(),
+  tavily_calls: z.number().int().nonnegative().default(0),
+  deterministic_only_ms: z.number().int().nonnegative(),
+}).strict();
+
+export const SandboxResult = z.object({
+  provider: z.literal("nebius_token_factory_sandboxes"),
+  sandbox_id: z.string(),
+  image_digest: z.string(),
+  prepare_phase_network: z.enum(["registry_only", "on"]),
+  verify_phase_network: z.literal("off"),
+  egress_denial_confirmed: z.boolean(),
+  exit_code: z.number().int(),
+  import_ok: z.boolean(),
+  probe_symbols_ok: z.array(z.string()).default([]),
+  duration_ms: z.number().int().nonnegative(),
+}).strict();
+
+export const SafeRemediation = z.object({
+  status: z.enum(["VERIFIED_SUBSTITUTE", "NO_SAFE_SUBSTITUTE", "VERIFICATION_UNAVAILABLE", "VERIFICATION_FAILED"]),
+  original: TargetRef,
+  candidate: TargetRef.optional(),
+  candidate_source: z.enum(["alias_map", "top_n_neighbor", "hf_sibling", "docker_patched_floor"]).optional(),
+  candidate_set_ids: z.array(z.string()).default([]),
+  selected_by: z.enum(["rule", "llm_rank"]).optional(),
+  verification_level: z.enum(["sandbox_import", "static_registry"]).optional(),
+  recheck_evidence_ids: z.array(evId).default([]),
+  approved_requirement: z.string().optional(),
+  sandbox: SandboxResult.optional(),
+  equivalence_note: z.string().default("import-compatible only; behavioural equivalence is not guaranteed"),
+}).strict().refine(r => r.status !== "VERIFIED_SUBSTITUTE" || (
+  !!r.candidate?.version && !!r.candidate?.artifact_sha256 &&
+  !!r.candidate_source && r.candidate_set_ids.length > 0 && r.recheck_evidence_ids.length > 0
+), { message: "verified substitute must be pinned, from a closed set, and re-checked" });
+
+export const GateVerdict = z.object({
+  request_id: z.string(),
+  target: TargetRef,
+  policy_version: z.string(),
+  policy_verdict: Verdict,
+  llm_verdict: Verdict.optional(),
+  final_verdict: Verdict,
+  outcome: Outcome,
+  risk_score: z.number().min(0).max(1),
+  failed_closed: z.boolean().default(false),
+  evidence: z.array(Evidence),
+  explanation: z.array(ExplanationSentence).default([]),
+  dropped_sentences: z.number().int().nonnegative().default(0),
+  next_action: z.enum(["proceed", "use_substitute", "ask_human", "abort"]),
+  remediation: SafeRemediation.optional(),
+  receipt: RouterReceipt.optional(),
+}).strict().superRefine((v, ctx) => {
+  const bad = (message: string) => ctx.addIssue({ code: "custom", message });
+  const ids = new Set(v.evidence.map(e => e.id));
+  if (ids.size !== v.evidence.length) bad("duplicate evidence ids");
+  if (v.explanation.some(s => s.evidence_ids.some(i => !ids.has(i)))) bad("explanation cites unknown evidence id");
+  if (v.final_verdict !== maxVerdict(v.policy_verdict, v.llm_verdict ?? "ALLOW")) bad("final_verdict must equal max(policy, llm)");
+  if (v.final_verdict === "BLOCK" && v.policy_verdict !== "BLOCK") bad("BLOCK must come from deterministic policy");
+  if (v.policy_verdict === "BLOCK" && !v.evidence.some(e => e.severity === "hard" && e.trust === "deterministic")) bad("policy BLOCK requires hard deterministic evidence");
+  if (v.failed_closed && v.final_verdict === "ALLOW") bad("fail-closed can never yield ALLOW");
+  if (v.outcome === "VERIFIED_SUBSTITUTE") {
+    if (v.final_verdict === "ALLOW") bad("nothing to substitute for an ALLOW");
+    if (v.remediation?.status !== "VERIFIED_SUBSTITUTE") bad("VERIFIED_SUBSTITUTE outcome requires verified remediation");
+    if (v.next_action !== "use_substitute") bad("next_action must be use_substitute");
+  } else if (v.outcome !== v.final_verdict) bad("outcome must mirror final_verdict");
+  const pinned = !!(v.target.version && v.target.artifact_sha256) ||
+    (v.target.ecosystem === "huggingface" && v.target.revision !== undefined);
+  if (v.outcome === "ALLOW" && !pinned) bad("ALLOW must be pinned (version + sha256, or a Hugging Face revision) (TOCTOU)");
+});
+
+export type GateVerdict = z.infer<typeof GateVerdict>;
+export type Evidence = z.infer<typeof Evidence>;
+export type SafeRemediation = z.infer<typeof SafeRemediation>;
+export type RouterReceipt = z.infer<typeof RouterReceipt>;

engine/README.md

@@ -0,0 +1,36 @@
+# engine/ — Kate
+
+Stage 1. Deterministic. Zero model calls. Metadata only — do not install or import the package.
+
+| File | Build this |
+| --- | --- |
+| `parsers.py` | Parse pip / npm / HF repo id / Dockerfile FROM |
+| `clients/pypi.py` | GET pypi.org JSON |
+| `clients/npm.py` | GET registry.npmjs.org |
+| `clients/osv.py` | POST api.osv.dev (MAL- records) |
+| `clients/huggingface.py` | GET huggingface.co model file list |
+| `checks.py` | exists, age, maintainers, osv_mal, typosquat, hf_format, runtime_floor |
+| `evidence.py` | Hashed Evidence with ids `EV-1`, `EV-2`, … |
+| `policy.yaml` + `policy.py` | Rules P1–P10. Strictest match wins |
+| `runtime_floors.yaml` | Patched version floors (e.g. php) |
+| `cache.py` | SQLite with TTL |
+| `data/` | Dated top-5k names for typosquat |
+
+## P10: a check that could not run
+
+A check that cannot run does not stay silent. It emits a soft `check_unavailable`
+evidence record with the cause in `observed["reason"]`, and rule **P10** turns any
+such record into REVIEW. P9 (ALLOW) needs zero evidence, so a gap can never read as
+a clean result, and being soft it can never produce a BLOCK (FR-09).
+
+| `observed["reason"]` | When |
+| --- | --- |
+| `no_floor_for_branch` | The tag is on a release branch with no recorded floor |
+| `floating_tag` | `latest`, `bookworm`, or `8.3` / `8.3-apache` with no patch release |
+| `digest_only` | A Dockerfile reference with no tag |
+| `image_not_in_table` | No floors recorded for this image |
+| `typosquat_unsupported_ecosystem` | A registry listed for typosquat has no snapshot. npm is not listed; exists/pin still ALLOW. |
+
+Tasks: T03, T04, T05, T06, T22. Tests first. Mock HTTP with respx. No live network in unit tests.
+
+Timeouts and host allowlists on every client. Fail closed to REVIEW on errors.

engine/__init__.py

@@ -0,0 +1 @@
+# Kate. See README.md.

engine/cache.py

@@ -0,0 +1,64 @@
+"""SQLite cache with a per-source TTL. Stores raw registry JSON, never secrets."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PATH = Path(os.environ.get("CACHE_PATH", "./.cache/installgate.sqlite"))
+
+TTL_SECONDS: dict[str, int] = {
+    "pypi": 3600,
+    "npm": 3600,
+    "osv": 900,
+    "huggingface": 3600,
+    "docker_registry": 3600,
+}
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS entries (
+    source TEXT NOT NULL,
+    key    TEXT NOT NULL,
+    body   TEXT NOT NULL,
+    stored_at REAL NOT NULL,
+    PRIMARY KEY (source, key)
+)
+"""
+
+
+class Cache:
+    def __init__(self, path: Path | str = DEFAULT_PATH) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.path, check_same_thread=False)
+        self._conn.execute(_SCHEMA)
+        self._conn.commit()
+
+    def get(self, source: str, key: str) -> Any | None:
+        ttl = TTL_SECONDS.get(source, 900)
+        row = self._conn.execute(
+            "SELECT body, stored_at FROM entries WHERE source = ? AND key = ?",
+            (source, key),
+        ).fetchone()
+        if row is None:
+            return None
+        body, stored_at = row
+        if time.time() - stored_at > ttl:
+            self._conn.execute("DELETE FROM entries WHERE source = ? AND key = ?", (source, key))
+            self._conn.commit()
+            return None
+        return json.loads(body)
+
+    def set(self, source: str, key: str, value: Any) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO entries (source, key, body, stored_at) VALUES (?, ?, ?, ?)",
+            (source, key, json.dumps(value), time.time()),
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()