[NOTICKET] feat(knowledge): seam version gate (N6b) + ingest auth posture (N11)

N6b - SEAM VERSION GATE. `parsed_doc_from_artifact` read the artifact envelope
and ignored `schema_version` entirely, so a shape this build cannot read would
be parsed anyway on a best-effort basis. That is the one failure worth being
loud about: a shape we do not understand is not a smaller version of the right
input, it is a different input, and reading it produces entries that look fine
and are wrong.

Rules: major mismatch rejects; a NEWER minor rejects (structure this code has
never seen); an older minor or any patch is accepted, because minor bumps have
been additive by convention (0.3.0 -> 0.3.3 added source_title,
normaliser_version, page_no) and the committed eval fixture is deliberately an
older minor than the current parser - rejecting it would break the baseline
measurement for no safety gain. An absent version warns and proceeds, so
pre-envelope fixtures and bare chunk lists stay loadable.

SUPPORTED_SCHEMA is a literal, not an import from knowledge_parsing:
extraction must not depend on the parsing package at runtime - that
independence is the seam's whole point. Drift is caught instead by a local
seam test that imports knowledge_parsing.contracts directly and asserts the
two agree, so a bump on either side fails in tests rather than at read time.
Verified all three committed fixtures still load (0.3.0 and 0.3.3).

N11 - INGEST AUTH POSTURE, decided rather than inherited. The service-secret
gate cannot be armed here for the same reason it was unwired in #37: the browser
SPA is the sole caller, we do not own that repo, and a secret shipped to a
browser is not a secret - arming it would 401 the feature. But this is a WRITE
that spends LLM budget, a different risk class from the read surface, so the
posture is bounded by four controls rather than inherited silently:

1. rate limit, 5/minute - shipped here, verified firing (5x202 then 2x429).
Deliberately far below chat's 30/minute: a legitimate caller clicks this a
few times a year, not a few times a minute.
2. single-flight per scope - already shipped.
3. pre-flight spend ceiling ) both land with the pipeline (N10c)
4. content-hash idempotency )

What they do NOT do is identify the caller: user_id is still whatever the
request says, so one user can spend budget under another's id. That closes
only with a forwarded identity (#43). Stated in the router docstring so the
next reader knows it is an accepted posture, not an oversight.

Verification: ruff clean on touched paths; `import main` OK; suite 570 passed /
7 skipped (555 + 15 new local seam-gate tests; tests/ stays gitignored).

N7b (torch CPU pin) is NOT in this commit - it is blocked, see the report.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/api/v1/knowledge.py

@@ -18,13 +18,27 @@ difference is real: charts is called unconditionally on every turn where absence
 is normal, whereas a polled `job_id` was handed to the caller, so its absence is
 genuinely exceptional.
 
-⚠️ **No auth.** `user_id` is caller-supplied, exactly like every other live
-endpoint (DEV_PLAN §0.7 #37 — the browser SPA is the sole caller and cannot send
-a service secret). This route is a *write* that spends LLM budget, which is a
-different risk class from the read surface, and the posture is an open decision
-(KNOWLEDGE_SURFACE_PLAN.md §6). The bounded controls — single-flight, the
-pre-flight spend ceiling and content-addressed idempotency — limit the damage
-but do not identify the caller.
+⚠️ **No caller authentication — decided 2026-09-07, not inherited.** `user_id` is
+caller-supplied, exactly like every other live endpoint. The service-secret gate
+(DEV_PLAN §0.7 #37) cannot be armed here for the same reason it was unwired
+there: the browser SPA is the sole caller, we do not own that repo, and a secret
+shipped to a browser is not a secret. Arming it would 401 the feature.
+
+But this is a **write that spends LLM budget**, which is a different risk class
+from the read surface, so the posture is not inherited silently — it is bounded
+by four controls, and the gap they leave is stated rather than papered over:
+
+  1. **Rate limit** (below) — caps calls per client per window.
+  2. **Single-flight per scope** — a second click returns the running job.
+  3. **Pre-flight spend ceiling** — the free stages produce an exact estimate and
+     the job stops rather than spending past it (N10c, lands with the pipeline).
+  4. **Content-addressed idempotency** — re-ingesting an unchanged document
+     re-spends nothing (N10c).
+
+**What they do not do is identify the caller.** `user_id` is still whatever the
+request says, so one user can spend budget under another's id. That closes only
+with a real forwarded identity (DEV_PLAN #43). Recorded here so the next reader
+knows this is a bounded, accepted posture and not an oversight.
 
 `scope_id` is deliberately NOT accepted from the caller: it is derived
 server-side from `users.company`. Accepting a tenant key on an unauthenticated
@@ -33,12 +47,13 @@ route is a cross-tenant write with extra steps.
 
 import uuid
 
-from fastapi import APIRouter, HTTPException, Query, status
+from fastapi import APIRouter, HTTPException, Query, Request, status
 from pydantic import BaseModel, Field, field_validator
 
 from src.knowledge_ingest.models import IngestJob
 from src.knowledge_ingest.service import IngestService
 from src.middlewares.logging import get_logger, log_execution
+from src.middlewares.rate_limit import limiter
 
 # NOTE: this module must NOT use `from __future__ import annotations`.
 # With it, FastAPI cannot resolve a Pydantic body model's annotation through
@@ -111,8 +126,15 @@ class IngestAccepted(BaseModel):
     status_code=status.HTTP_202_ACCEPTED,
     summary="Extract knowledge from a user's documents (async batch)",
 )
+# N11, control 1 of 4. Deliberately far below the chat route's 30/minute: this
+# starts GPU-less but LLM-spending batch work, and a legitimate caller clicks it
+# a few times a year, not a few times a minute. `slowapi` needs a Starlette
+# `Request` param named `request`, which is why the body is `payload`.
+# NOTE: `get_remote_address` buckets by client IP — if calls ever arrive through
+# a proxy, every caller shares one bucket. Revisit when identity is forwarded.
+@limiter.limit("5/minute")
 @log_execution(logger)
-async def ingest(payload: IngestRequest) -> IngestAccepted:
+async def ingest(request: Request, payload: IngestRequest) -> IngestAccepted:
     """Admit a batch and return immediately. Poll `GET /jobs/{job_id}`."""
     job, reused = await _service.start(
         user_id=payload.user_id, document_ids=payload.document_ids

src/knowledge_extraction/adapter.py

@@ -24,8 +24,12 @@ import hashlib
 import json
 from typing import Any
 
+from src.middlewares.logging import get_logger
+
 from .models import Chunk, ParsedDoc
 
+logger = get_logger("knowledge_adapter")
+
 # Field names accepted for the same concept. `page_idx`/`page_idxs` are the
 # parsing half's contract; the rest are earlier drafts and the prototype's shape,
 # kept so old fixtures still load.
@@ -39,6 +43,84 @@ _PAGES_KEYS = ("page_idxs", "pages", "page_list")
 _PAGE_END_KEYS = ("page_idx_end", "page_end")
 
 
+# ── Seam version gate (N6b) ──────────────────────────────────────────────
+#
+# The artifact's SHAPE version, as `major.minor`. Parsing owns the contract and
+# bumps `SCHEMA_VERSION` in `knowledge_parsing/contracts.py`; this is the range
+# extraction knows how to read.
+#
+# Deliberately a literal rather than an import: extraction must never depend on
+# the parsing package at runtime — that independence is the whole point of the
+# seam. Drift is caught instead by a local seam test that imports
+# `knowledge_parsing.contracts` directly and asserts the two agree, so a bump on
+# either side fails loudly in tests rather than silently at read time.
+SUPPORTED_SCHEMA = (0, 3)
+
+
+class IncompatibleArtifactError(ValueError):
+    """The artifact declares a shape this code cannot read.
+
+    Raised rather than degraded on purpose. Every other seam in this repo
+    tolerates missing structure, because a chunk without a heading is still
+    usable — but a shape we do not understand is not a smaller version of the
+    right input, it is a different input. Reading it anyway produces entries
+    that look fine and are wrong, which is the single most expensive failure
+    this pipeline can have.
+    """
+
+
+def _parse_version(declared: str) -> tuple[int, int] | None:
+    parts = str(declared).split(".")
+    try:
+        return int(parts[0]), int(parts[1])
+    except (IndexError, ValueError):
+        return None
+
+
+def check_schema_version(declared: Any) -> None:
+    """Gate one artifact's declared `schema_version`. Raises or returns None.
+
+    - **Major mismatch → reject.** A major bump is by definition breaking.
+    - **Newer minor → reject.** The artifact carries structure this code has
+      never seen; guessing at it is how a silent misread starts.
+    - **Older minor, or any patch → accept.** Minor bumps have been additive by
+      convention (0.3.0 → 0.3.3 added `source_title`, `normaliser_version` and
+      `page_no`), and the committed eval fixture is deliberately an older minor
+      than the current parser, so rejecting those would break the baseline
+      measurement for no safety gain.
+    - **Absent → accept with a warning.** Bare chunk lists and pre-envelope
+      fixtures carry no version; the CLI already refuses unlabelled artifacts
+      where labelling matters.
+    """
+    if declared in (None, ""):
+        logger.warning(
+            "artifact_schema_version_missing",
+            extra={"supported": ".".join(map(str, SUPPORTED_SCHEMA))},
+        )
+        return
+
+    parsed = _parse_version(declared)
+    if parsed is None:
+        raise IncompatibleArtifactError(
+            f"artifact schema_version {declared!r} is not a major.minor version"
+        )
+
+    major, minor = parsed
+    supported_major, supported_minor = SUPPORTED_SCHEMA
+    if major != supported_major or minor > supported_minor:
+        raise IncompatibleArtifactError(
+            f"artifact schema_version {declared} is not readable by this "
+            f"extraction build (supports {supported_major}.{supported_minor}.x). "
+            "Re-parse the document, or update the adapter to the new shape."
+        )
+
+    if minor < supported_minor:
+        logger.info(
+            "artifact_schema_version_older",
+            extra={"declared": str(declared), "supported": f"{supported_major}.{supported_minor}"},
+        )
+
+
 def chunk_from_dict(raw: dict[str, Any], doc_id: str, ordinal: int = 0) -> Chunk:
     """Map one artifact item onto the internal chunk.
 
@@ -106,6 +188,8 @@ def parsed_doc_from_artifact(
         backend = artifact.get("parser_backend") or ""
         if backend:
             parser_version = f"{parser_version}/{backend}" if parser_version else backend
+        # Gate the shape BEFORE reading any of it (N6b).
+        check_schema_version(artifact.get("schema_version"))
         declared_hash = artifact.get("content_hash")
         declared_pages = artifact.get("n_pages")
     else: