rememberstack 0.1.0__py3-none-any.whl

rememberstack/workers/knowledge_writer.py

@@ -0,0 +1,393 @@
+"""Stock-harness prose compiler for deterministic two-band Plane-K pages."""
+
+from collections.abc import Callable
+from datetime import datetime
+from datetime import UTC
+import json
+from pathlib import PurePosixPath
+import re
+import traceback
+from typing import Final
+from typing import Protocol
+from uuid import UUID
+from uuid import uuid4
+
+from pydantic import Field
+from pydantic import field_validator
+from pydantic import TypeAdapter
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from rememberstack.core import cap_knowledge_writer_bundle
+from rememberstack.core import compose_knowledge_page
+from rememberstack.core import knowledge_content_hash
+from rememberstack.core import knowledge_inputs_hash
+from rememberstack.core import knowledge_summary_hash
+from rememberstack.core import knowledge_writer_coverage
+from rememberstack.core import render_knowledge_fact_sheet
+from rememberstack.core import render_knowledge_writer_bundle
+from rememberstack.model import KnowledgeCitation
+from rememberstack.model import KnowledgeCompilationFailure
+from rememberstack.model import KnowledgeCompilationWrite
+from rememberstack.model import KnowledgeCompileContext
+from rememberstack.model import KnowledgePageCompileOutput
+from rememberstack.model import KnowledgePageCompileRequest
+from rememberstack.model import KnowledgeWriterBundle
+from rememberstack.model import KnowledgeWriterSessionRequest
+from rememberstack.model import KnowledgeWriterSessionResult
+from rememberstack.model import KnowledgeWriterSuggestion
+from rememberstack.model import ObjectKey
+from rememberstack.model import UTCDateTime
+from rememberstack.ports import MountPublisherPort
+from rememberstack.ports import ObjectStorePort
+from rememberstack.spine.knowledge import KnowledgeControlPlane
+from rememberstack.workers.knowledge_fact_sheet import KnowledgeFactSheetCompiler
+
+KNOWLEDGE_WRITER_VERSION: Final = "k-writer-2026.07"
+
+_WRITER_PROMPT: Final = """You compile exactly one Plane-K prose band.
+Your working directory is the declared output/ surface. Read ../INSTRUCTIONS.md and every
+prepared input under ../bundle/ and ../context/. Memory mount locations are listed in
+../context/memory_mounts.json and are read-only. Do not use the
+internet, initialize git, commit, or edit outside this temporary workspace.
+
+Write only these declared files in the current directory (archived under output/):
+- prose.md: non-empty prose band; do not reproduce the generated fact sheet.
+- citations.json: JSON array of objects with role supports|contradicts|cites and exactly one
+  target: claim_lineage_id + claim_chunk_content_hash together, relation_id, or doc_id. Copy
+  stable claim coordinates and IDs exactly from available evidence.
+- summary.md: a two- or three-sentence page summary for parent compilers.
+- suggestions.json: JSON array of optional planner suggestions with action,
+  rationale, and payload. Use [] when there are none. Suggestions never take action.
+
+Treat curation exclusions as binding. The driver will independently validate every file,
+citation, link, count, and final content hash before anything can enter git.
+"""
+
+_CITATIONS_ADAPTER = TypeAdapter(tuple[KnowledgeCitation, ...])
+_SUGGESTIONS_ADAPTER = TypeAdapter(tuple[KnowledgeWriterSuggestion, ...])
+_UTC_ADAPTER = TypeAdapter(UTCDateTime)
+
+
+def _utc_now() -> datetime:
+    """Return the current aware UTC time for production compilation metadata."""
+    return datetime.now(tz=UTC)
+
+
+class KnowledgeWriterSettings(BaseSettings):
+    """Settings-owned model, timeout, cap, and transcript-key policy."""
+
+    model_config = SettingsConfigDict(env_prefix="REMEMBERSTACK_K_WRITER_")
+
+    model: str = Field(min_length=1)
+    timeout_seconds: int = Field(gt=0)
+    residue_claim_limit: int = Field(ge=0)
+    evidence_claims_per_fact: int = Field(ge=0)
+    transcript_prefix: str = Field(min_length=1)
+
+    @field_validator("transcript_prefix")
+    @classmethod
+    def require_safe_transcript_prefix(cls, value: str) -> str:
+        """Keep immutable transcript objects under one normalized relative prefix."""
+        path = PurePosixPath(value)
+        if path.is_absolute() or ".." in path.parts or str(path) != value:
+            raise ValueError("transcript_prefix must be a normalized relative path")
+        return value.rstrip("/")
+
+
+class KnowledgeWriterError(RuntimeError):
+    """A writer session failed before producing acceptable declared output."""
+
+
+class KnowledgeWriterSession(Protocol):
+    """The narrow stock-harness seam used only by the Plane-K writer."""
+
+    def run_session(
+        self, *, request: KnowledgeWriterSessionRequest
+    ) -> "KnowledgeWriterSessionResult":
+        """Return raw declared files and a transcript without accepting output."""
+        ...
+
+
+class KnowledgeProseCompiler:
+    """Compile one prose page from an exact capped bundle and generated fact sheet."""
+
+    def __init__(
+        self,
+        *,
+        control_plane: KnowledgeControlPlane,
+        writer_session: KnowledgeWriterSession,
+        transcript_store: ObjectStorePort,
+        mount_publisher: MountPublisherPort,
+        settings: KnowledgeWriterSettings,
+        clock: Callable[[], datetime] = _utc_now,
+    ) -> None:
+        """Bind authoritative hydration, stock harness, ledger store, and settings."""
+        self._control_plane = control_plane
+        self._writer_session = writer_session
+        self._transcript_store = transcript_store
+        self._mount_publisher = mount_publisher
+        self._settings = settings
+        self._clock = clock
+        self.writer_version = _writer_version(settings=settings)
+
+    def compile_page(
+        self, *, request: KnowledgePageCompileRequest
+    ) -> KnowledgePageCompileOutput:
+        """Run one writer, archive its transcript, then build validated two-band output."""
+        artifact = request.artifact
+        if artifact.artifact_kind == "fact_sheet":
+            raise KnowledgeWriterError(
+                "prose compiler cannot compile a fact-sheet-only page"
+            )
+        _validate_curation_input(request=request)
+        child_summary_hashes = tuple(
+            knowledge_summary_hash(summary=summary)
+            for summary in request.child_summaries.values()
+        )
+        shared_model_summary_hash = (
+            None
+            if request.shared_model_summary is None
+            else knowledge_summary_hash(summary=request.shared_model_summary)
+        )
+        hydrated = self._control_plane.writer_bundle(
+            artifact_id=artifact.artifact_id,
+            context=KnowledgeCompileContext(
+                curation_hash=request.curation_hash,
+                shared_model_summary_hash=shared_model_summary_hash,
+                writer_version=self.writer_version,
+            ),
+            child_summary_hashes=child_summary_hashes,
+        )
+        bundle = cap_knowledge_writer_bundle(
+            bundle=hydrated,
+            exclusions=request.exclusions,
+            residue_claim_limit=self._settings.residue_claim_limit,
+            evidence_claims_per_fact=self._settings.evidence_claims_per_fact,
+        )
+        compilation_id = uuid4()
+        transcript_uri: str | None = None
+        candidate_count = len(bundle.fact_sheet.facts) + len(bundle.claim_groups)
+        try:
+            mounts = self._mount_publisher.publish(deployment_id=artifact.deployment_id)
+            if mounts.deployment_id != artifact.deployment_id:
+                raise KnowledgeWriterError("mount publisher crossed deployments")
+            session_id = uuid4()
+            result = self._writer_session.run_session(
+                request=KnowledgeWriterSessionRequest(
+                    session_id=session_id,
+                    model=self._settings.model,
+                    prompt=_WRITER_PROMPT,
+                    timeout_seconds=self._settings.timeout_seconds,
+                    input_files=_writer_inputs(
+                        request=request,
+                        bundle=bundle,
+                        mounts_json=mounts.model_dump_json(),
+                    ),
+                    mounts=mounts,
+                )
+            )
+            if result.session_id != session_id:
+                raise KnowledgeWriterError("writer returned a different session ID")
+            transcript_uri = self._archive_transcript(
+                request=request, session_id=session_id, transcript=result.transcript
+            )
+            if result.timed_out:
+                raise KnowledgeWriterError("writer session timed out")
+            if result.exit_code != 0:
+                raise KnowledgeWriterError(
+                    f"writer session exited with status {result.exit_code}"
+                )
+            prose, citations, summary, suggestions = _parse_writer_outputs(
+                files=result.output_files
+            )
+            citations = _unique_citations(citations=citations)
+            self._control_plane.validate_citations(
+                deployment_id=artifact.deployment_id, citations=citations
+            )
+            coverage = knowledge_writer_coverage(bundle=bundle, citations=citations)
+            rendered = render_knowledge_fact_sheet(
+                snapshot=bundle.fact_sheet,
+                compiled_at=_UTC_ADAPTER.validate_python(self._clock()),
+                citation_count=len(citations),
+                candidate_count=coverage.candidate_count,
+            )
+            markdown = compose_knowledge_page(
+                prose_markdown=prose, fact_sheet_markdown=rendered.markdown
+            )
+            return KnowledgePageCompileOutput(
+                compilation=KnowledgeCompilationWrite(
+                    compilation_id=compilation_id,
+                    deployment_id=artifact.deployment_id,
+                    artifact_id=artifact.artifact_id,
+                    inputs_hash=knowledge_inputs_hash(
+                        snapshot=bundle.fact_sheet.input_snapshot
+                    ),
+                    candidate_count=coverage.candidate_count,
+                    uncited_count=coverage.uncited_count,
+                    claims_cut_count=bundle.claims_cut_count,
+                    citations=citations,
+                    suggestions=suggestions,
+                    writer_version=self.writer_version,
+                    page_summary=summary,
+                    content_hash=knowledge_content_hash(markdown=markdown),
+                    tokens=result.tokens,
+                    cost_usd=result.cost_usd,
+                    session_transcript_uri=transcript_uri,
+                ),
+                markdown=markdown,
+            )
+        except Exception as error:
+            failure_trace = traceback.format_exc()
+            try:
+                self._control_plane.record_failed_compilation(
+                    failure=KnowledgeCompilationFailure(
+                        compilation_id=compilation_id,
+                        deployment_id=artifact.deployment_id,
+                        artifact_id=artifact.artifact_id,
+                        inputs_hash=knowledge_inputs_hash(
+                            snapshot=bundle.fact_sheet.input_snapshot
+                        ),
+                        candidate_count=candidate_count,
+                        claims_cut_count=bundle.claims_cut_count,
+                        writer_version=self.writer_version,
+                        failure=failure_trace,
+                        session_transcript_uri=transcript_uri,
+                    )
+                )
+            except Exception as ledger_error:
+                raise ExceptionGroup(
+                    "writer compilation and failure-ledger recording both failed",
+                    (error, ledger_error),
+                ) from None
+            raise
+
+    def _archive_transcript(
+        self, *, request: KnowledgePageCompileRequest, session_id: UUID, transcript: str
+    ) -> str:
+        """Persist the complete session ledger before interpreting any writer file."""
+        key = ObjectKey(
+            f"{self._settings.transcript_prefix}/"
+            f"{request.artifact.deployment_id}/{request.artifact.artifact_id}/"
+            f"{session_id}.json"
+        )
+        self._transcript_store.write_bytes(key=key, content=transcript.encode("utf-8"))
+        return key.root
+
+
+class KnowledgePageCompilerRouter:
+    """Route fact-sheet-only pages away from the stock writer session entirely."""
+
+    def __init__(
+        self,
+        *,
+        fact_sheet_compiler: KnowledgeFactSheetCompiler,
+        prose_compiler: KnowledgeProseCompiler,
+    ) -> None:
+        """Bind the two page compilers behind the existing driver protocol."""
+        self._fact_sheet_compiler = fact_sheet_compiler
+        self._prose_compiler = prose_compiler
+
+    def compile_page(
+        self, *, request: KnowledgePageCompileRequest
+    ) -> KnowledgePageCompileOutput:
+        """Skip the writer exactly for artifacts designated as fact-sheet-only."""
+        if request.artifact.artifact_kind == "fact_sheet":
+            return self._fact_sheet_compiler.compile_page(request=request)
+        return self._prose_compiler.compile_page(request=request)
+
+
+def _writer_inputs(
+    *,
+    request: KnowledgePageCompileRequest,
+    bundle: KnowledgeWriterBundle,
+    mounts_json: str,
+) -> dict[str, str]:
+    """Prepare the fixed workspace inputs accepted by the stock harness adapter."""
+    children = {
+        str(artifact_id): summary
+        for artifact_id, summary in sorted(
+            request.child_summaries.items(), key=lambda item: str(item[0])
+        )
+    }
+    return {
+        "INSTRUCTIONS.md": _WRITER_PROMPT,
+        "bundle/evidence.json": render_knowledge_writer_bundle(bundle=bundle),
+        "context/curation.md": request.curation_markdown or "_No curation guidance._\n",
+        "context/previous_page.md": request.previous_markdown or "_No prior page._\n",
+        "context/child_summaries.json": f"{json.dumps(children, sort_keys=True, indent=2)}\n",
+        "context/shared_model.md": request.shared_model_summary
+        or "_No shared model summary._\n",
+        "context/memory_mounts.json": f"{mounts_json}\n",
+    }
+
+
+def _parse_writer_outputs(
+    *, files: dict[str, str]
+) -> tuple[
+    str, tuple[KnowledgeCitation, ...], str, tuple[KnowledgeWriterSuggestion, ...]
+]:
+    """Parse only declared writer files into the typed compiler contract."""
+    required = ("output/prose.md", "output/citations.json", "output/summary.md")
+    missing = tuple(path for path in required if path not in files)
+    if missing:
+        raise KnowledgeWriterError(
+            f"writer omitted required outputs: {', '.join(missing)}"
+        )
+    prose = files["output/prose.md"].strip()
+    summary = files["output/summary.md"].strip()
+    if not prose:
+        raise KnowledgeWriterError("writer prose output is empty")
+    if _sentence_count(text=summary) not in (2, 3):
+        raise KnowledgeWriterError("writer summary must contain two or three sentences")
+    try:
+        citations = _CITATIONS_ADAPTER.validate_json(files["output/citations.json"])
+        suggestions = _SUGGESTIONS_ADAPTER.validate_json(
+            files.get("output/suggestions.json", "[]")
+        )
+    except ValueError as error:
+        raise KnowledgeWriterError(
+            "writer JSON output violates the typed contract"
+        ) from error
+    return prose, citations, summary, suggestions
+
+
+def _validate_curation_input(*, request: KnowledgePageCompileRequest) -> None:
+    """Bind the raw sidecar supplied to the harness to its D45 hash input."""
+    expected = (
+        None
+        if request.curation_markdown is None
+        else knowledge_content_hash(markdown=request.curation_markdown)
+    )
+    if request.curation_hash != expected:
+        raise KnowledgeWriterError("curation markdown does not match curation hash")
+
+
+def _sentence_count(*, text: str) -> int:
+    """Count terminally punctuated summary sentences with one deterministic rule."""
+    return len(re.findall(r"[^.!?]+[.!?](?:\s|$)", text.strip()))
+
+
+def _unique_citations(
+    *, citations: tuple[KnowledgeCitation, ...]
+) -> tuple[KnowledgeCitation, ...]:
+    """Apply deterministic set semantics to repeated writer citations."""
+    keyed = {
+        (
+            item.role.value,
+            str(item.claim_lineage_id),
+            item.claim_chunk_content_hash or "",
+            str(item.relation_id),
+            str(item.doc_id),
+        ): item
+        for item in citations
+    }
+    return tuple(keyed[key] for key in sorted(keyed))
+
+
+def _writer_version(*, settings: KnowledgeWriterSettings) -> str:
+    """Make prompt, model, cap, and timeout settings hash-visible in D45 manifests."""
+    fingerprint = knowledge_summary_hash(
+        summary=f"{_WRITER_PROMPT}\n{settings.model_dump_json()}"
+    )
+    return f"{KNOWLEDGE_WRITER_VERSION}:{fingerprint[:16]}"

rememberstack/workers/operations.py

@@ -0,0 +1,42 @@
+"""Thin operational services that compose spine truth with delivery ports."""
+
+from datetime import datetime
+from uuid import UUID
+
+from rememberstack.model import DeadLetterReplayResult
+from rememberstack.model import ProcessingLane
+from rememberstack.ports.queue import TaskQueuePort
+from rememberstack.spine.work_ledger import WorkLedger
+
+
+class DeadLetterReplayer:
+    """Replay one row through the ledger, then announce its committed route."""
+
+    def __init__(self, *, ledger: WorkLedger, queue: TaskQueuePort) -> None:
+        """Bind authoritative mutation and non-authoritative delivery."""
+        self._ledger = ledger
+        self._queue = queue
+
+    def replay(
+        self,
+        *,
+        deployment_id: UUID,
+        processing_id: UUID,
+        attempt_allowance: int = 1,
+        lane: ProcessingLane | None = None,
+        not_before: datetime | None = None,
+    ) -> DeadLetterReplayResult:
+        """Commit one explicit replay transition, then wake its returned route."""
+        replayed = self._ledger.replay_dead_letter(
+            deployment_id=deployment_id,
+            processing_id=processing_id,
+            attempt_allowance=attempt_allowance,
+            lane=lane,
+            not_before=not_before,
+        )
+        self._queue.announce(
+            processing_id=replayed.processing_id,
+            route_snapshot=replayed.route,
+            not_before_snapshot=replayed.not_before,
+        )
+        return replayed

rememberstack/workers/p1.py

@@ -0,0 +1,234 @@
+"""The P1 inline writers (D8, retrieval §5): the claims and facts channels.
+
+The claims channel is the needle index — every accepted claim embedded with
+its `is_current_testimony` scalar, so the DEFAULT claims search filters to
+current testimony without touching Postgres. The facts channel carries the
+human-readable labels of relations (generated once per label generation) and
+observations (their statements), embedded beside their status scalar.
+"""
+
+from typing import Final
+from uuid import UUID
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from rememberstack.model import ClaimedWork
+from rememberstack.model import EmbeddingRequest
+from rememberstack.model import FactLabelResponse
+from rememberstack.model import ModelRequest
+from rememberstack.model import NonRetryableHandlerError
+from rememberstack.model import P1ClaimRow
+from rememberstack.model import P1FactRow
+from rememberstack.ports.cost_meter import CostMeterPort
+from rememberstack.ports.model_provider import ModelProviderPort
+from rememberstack.ports.p1_index import ClaimIndexPort
+from rememberstack.ports.p1_index import FactIndexPort
+from rememberstack.spine.chunk_catalog import ChunkCatalog
+from rememberstack.spine.claim_catalog import ClaimCatalog
+from rememberstack.spine.fact_catalog import FactCatalog
+from rememberstack.workers.base import HandlerOutcome
+
+P1_EMBED_CLAIMS_VERSION: Final = "p1-embed-claims-2026.07"
+"""The claim-embed stage's component version (the model rides settings)."""
+
+FACT_LABEL_VERSION: Final = "p1-fact-label-2026.07"
+"""The fact-labeler prompt generation (regenerated only on version bump)."""
+
+_FACT_LABEL_PROMPT: Final = (
+    "Write one short natural sentence stating this fact, nothing else: "
+    "{subject} —[{predicate}]→ {object}"
+)
+
+
+class P1Settings(BaseSettings):
+    """The P1 writer model bindings (D61/D63/D70)."""
+
+    model_config = SettingsConfigDict(env_prefix="REMEMBERSTACK_P1_")
+
+    embedding_model: str = Field(default="qwen/qwen3-embedding-8b")
+    label_model: str = Field(default="openai/gpt-5.6-luna")
+
+
+class EmbedClaimsHandler:
+    """The claim-embed stage: one version's claims into the P1 claims channel."""
+
+    def __init__(
+        self,
+        *,
+        claim_catalog: ClaimCatalog,
+        chunk_catalog: ChunkCatalog,
+        model_provider: ModelProviderPort,
+        claim_index: ClaimIndexPort,
+        settings: P1Settings,
+        chunker_version: str,
+    ) -> None:
+        """Bind the handler to its catalogs, provider, index, and generation."""
+        self._claim_catalog = claim_catalog
+        self._chunk_catalog = chunk_catalog
+        self._model_provider = model_provider
+        self._claim_index = claim_index
+        self._settings = settings
+        self._chunker_version = chunker_version
+
+    def handle(self, *, work: ClaimedWork, meter: CostMeterPort) -> HandlerOutcome:
+        """Embed the version's not-yet-embedded claims as one document batch."""
+        source = self._chunk_catalog.chunk_source(
+            representation_id=_payload_uuid(work=work, field="representation_id")
+        )
+        chunks = self._chunk_catalog.chunks_for_embedding(
+            representation_id=source.representation_id,
+            chunker_version=self._chunker_version,
+        )
+        claims = self._claim_catalog.claims_for_embedding(
+            chunk_ids=tuple(chunk.chunk_id for chunk in chunks),
+            embedding_version=self._settings.embedding_model,
+        )
+        if not claims:
+            return HandlerOutcome()  # replay: refs already stamped (D7)
+        response = self._model_provider.embed(
+            request=EmbeddingRequest(
+                model=self._settings.embedding_model,
+                texts=tuple(claim.claim_text for claim in claims),
+            )
+        )
+        meter.record(call_key="embed_claims", tier="embedding", usage=response.usage)
+        self._claim_index.upsert_claims(
+            rows=tuple(
+                P1ClaimRow(
+                    claim_id=claim.claim_id,
+                    deployment_id=work.deployment_id,
+                    doc_id=claim.doc_id,
+                    chunk_id=claim.chunk_id,
+                    text=claim.claim_text,
+                    is_current_testimony=claim.is_current_testimony,
+                    is_attributed=claim.is_attributed,
+                    vector=vector,
+                )
+                for claim, vector in zip(claims, response.vectors, strict=True)
+            )
+        )
+        self._claim_catalog.record_claim_embeddings(
+            claim_ids=tuple(claim.claim_id for claim in claims),
+            embedding_version=self._settings.embedding_model,
+        )
+        return HandlerOutcome()
+
+
+class LabelFactsHandler:
+    """The fact-label stage: readable labels for relations, embedded with
+    observation statements into the P1 facts channel (D8)."""
+
+    def __init__(
+        self,
+        *,
+        facts: FactCatalog,
+        model_provider: ModelProviderPort,
+        fact_index: FactIndexPort,
+        settings: P1Settings,
+    ) -> None:
+        """Bind the handler to the fact catalog, provider, and facts index."""
+        self._facts = facts
+        self._model_provider = model_provider
+        self._fact_index = fact_index
+        self._settings = settings
+
+    def handle(self, *, work: ClaimedWork, meter: CostMeterPort) -> HandlerOutcome:
+        """Label and embed the document's facts still lacking this generation.
+
+        Ordering is the invariant (Codex review): the index write lands
+        BEFORE any PG stamp, so Postgres never advertises a Lance ref that
+        was not written — a crash mid-pass re-labels the remainder on retry.
+        The generation stamp folds in the embedding model (D63): a model
+        change re-labels and re-embeds instead of silently skipping.
+        Concurrent document jobs serialize on the deployment label lock.
+        """
+        doc_id = _payload_uuid(work=work, field="doc_id")
+        generation = f"{FACT_LABEL_VERSION}+{self._settings.embedding_model}"
+        with self._facts.label_lock(deployment_id=work.deployment_id):
+            rows: list[P1FactRow] = []
+            for relation in self._facts.relations_for_labeling(
+                deployment_id=work.deployment_id,
+                doc_id=doc_id,
+                label_version=generation,
+            ):
+                label_call = self._model_provider.generate(
+                    request=ModelRequest(
+                        model=self._settings.label_model,
+                        prompt=_FACT_LABEL_PROMPT.format(
+                            subject=relation.subject_name,
+                            predicate=relation.predicate,
+                            object=relation.object_name,
+                        ),
+                    ),
+                    response_type=FactLabelResponse,
+                )
+                meter.record(
+                    call_key=f"label_relation:{relation.relation_id}",
+                    tier="label",
+                    usage=label_call.usage,
+                )
+                label = label_call.output.label
+                rows.append(
+                    P1FactRow(
+                        fact_id=relation.relation_id,
+                        deployment_id=work.deployment_id,
+                        kind="relation",
+                        label=label,
+                        status=relation.status,
+                        vector=(0.0,),  # replaced below by the batch embedding
+                    )
+                )
+            rows.extend(
+                P1FactRow(
+                    fact_id=observation.observation_id,
+                    deployment_id=work.deployment_id,
+                    kind="observation",
+                    label=observation.obs_label,
+                    status=observation.status,
+                    vector=(0.0,),
+                )
+                for observation in self._facts.observations_for_embedding(
+                    deployment_id=work.deployment_id,
+                    doc_id=doc_id,
+                    label_version=generation,
+                )
+            )
+            if not rows:
+                return HandlerOutcome()
+            response = self._model_provider.embed(
+                request=EmbeddingRequest(
+                    model=self._settings.embedding_model,
+                    texts=tuple(row.label for row in rows),
+                )
+            )
+            meter.record(call_key="embed_facts", tier="embedding", usage=response.usage)
+            self._fact_index.upsert_facts(
+                rows=tuple(
+                    row.model_copy(update={"vector": vector})
+                    for row, vector in zip(rows, response.vectors, strict=True)
+                )
+            )
+            for row in rows:  # stamps only after the index write landed
+                if row.kind == "relation":
+                    self._facts.record_fact_label(
+                        relation_id=row.fact_id,
+                        label=row.label,
+                        label_version=generation,
+                    )
+                else:
+                    self._facts.record_observation_embedding(
+                        observation_id=row.fact_id, label_version=generation
+                    )
+        return HandlerOutcome()
+
+
+def _payload_uuid(*, work: ClaimedWork, field: str) -> UUID:
+    """Read a required UUID from the claimed payload; absence is non-retryable."""
+    value = (work.payload or {}).get(field)
+    if not isinstance(value, str):
+        raise NonRetryableHandlerError(
+            f"stage {work.stage} work {work.processing_id} carries no {field!r} payload"
+        )
+    return UUID(value)