rememberstack 0.1.0__py3-none-any.whl

rememberstack/model/retrieval_spikes.py

@@ -0,0 +1,62 @@
+"""Typed results for the WP-5.6 retrieval spike battery."""
+
+from typing import Annotated
+from typing import get_args
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import model_validator
+
+RetrievalSpikeName = Literal[
+    "lance_filtered_search",
+    "hub_pagination",
+    "rerank_weights",
+    "envelope_overhead",
+    "hydration_batching",
+    "resolve_context",
+]
+
+RETRIEVAL_SPIKE_NAMES = frozenset(get_args(RetrievalSpikeName))
+"""The six WP-5.6 measurements; S58 and as-of graph cost closed earlier."""
+
+
+class RetrievalSpikeMeasurement(BaseModel):
+    """One measured question, its selected setting, and honest limitations."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: RetrievalSpikeName
+    scale: Annotated[int, Field(ge=1)]
+    metrics: dict[str, object]
+    selected: dict[str, object]
+    limitations: tuple[str, ...] = ()
+    passed: bool
+
+
+class RetrievalSpikeReport(BaseModel):
+    """The complete six-spike WP-5.6 result written to ``eval_runs``."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    measurements: Annotated[
+        tuple[RetrievalSpikeMeasurement, ...], Field(min_length=6, max_length=6)
+    ]
+
+    @model_validator(mode="after")
+    def complete_battery(self) -> "RetrievalSpikeReport":
+        """Reject duplicate or missing measurements; absence is not compliance."""
+        names = {measurement.name for measurement in self.measurements}
+        if names != RETRIEVAL_SPIKE_NAMES:
+            missing = sorted(RETRIEVAL_SPIKE_NAMES - names)
+            extra = sorted(names - RETRIEVAL_SPIKE_NAMES)
+            raise ValueError(
+                f"retrieval spike names mismatch: missing={missing}, extra={extra}"
+            )
+        return self
+
+    @property
+    def passed(self) -> bool:
+        """The battery passes only when every measured invariant holds."""
+        return all(measurement.passed for measurement in self.measurements)

rememberstack/model/sections.py

@@ -0,0 +1,120 @@
+"""Section-structure values (D39/D57): the LLM's proposal and the snapped truth.
+
+Two deliberately different trust levels share this module. `ProposedSection` /
+`StructureResponse` are the structurer LLM's raw output — free-hand character
+spans that may overlap, gap, nest wrongly, or point outside the document; they
+are never persisted. `SnappedSection` is what the deterministic snap
+(`core/section_snap.py`) makes of them: a well-formed partition on the block
+grid, the only form that reaches `document_sections`.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import model_validator
+
+
+class ProposedSection(BaseModel):
+    """One LLM-proposed section span (pre-snap): untrusted free-hand geometry."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    title: str = ""
+    role: str = "body"
+    char_start: int = 0
+    char_end: int = 0
+    summary: str = ""
+    children: tuple[ProposedSection, ...] = ()
+
+
+class StructureResponse(BaseModel):
+    """The structurer's structured output: a proposed tree + placement hint."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    sections: tuple[ProposedSection, ...] = ()
+    placement: str = ""
+
+
+class SnappedSection(BaseModel):
+    """One well-formed section after the deterministic snap (block coordinates).
+
+    ``block_end`` is inclusive; the empty document's root carries the empty
+    range ``0..-1`` on the block grid (D57) with a zero-width char span.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    node_path: str  # materialized path, e.g. '0.2.1'; the root is '0'
+    parent_path: str | None
+    title: str
+    role: str
+    block_start: int = Field(ge=0)
+    block_end: int = Field(ge=-1)
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    summary: str
+    ordinal: int = Field(ge=0)
+
+
+class SectionTreeRecord(BaseModel):
+    """The complete write input for one representation's section tree.
+
+    ``sections`` is in depth-first document order with the root first — the
+    catalog resolves each row's parent id from the paths as it inserts, so
+    the record refuses any ordering or path structure that would silently
+    persist a disconnected tree (an orphan row would reach E1 as a second
+    root and double-chunk its range).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    representation_id: UUID
+    sections: tuple[SnappedSection, ...] = Field(min_length=1)
+    placement_path: str | None
+    structurer_name: str
+    structurer_version: str
+
+    @model_validator(mode="after")
+    def _tree_is_connected(self) -> SectionTreeRecord:
+        """Root first; every node extends a parent that appeared before it."""
+        root = self.sections[0]
+        if root.node_path != "0" or root.parent_path is not None:
+            raise ValueError("the first section must be the root '0'")
+        seen = {root.node_path}
+        for section in self.sections[1:]:
+            if section.node_path in seen:
+                raise ValueError(f"duplicate section path {section.node_path!r}")
+            if section.parent_path not in seen:
+                raise ValueError(
+                    f"section {section.node_path!r} appears before its parent"
+                )
+            if section.node_path.rsplit(".", 1)[0] != section.parent_path:
+                raise ValueError(
+                    f"section {section.node_path!r} does not extend its"
+                    f" parent path {section.parent_path!r}"
+                )
+            seen.add(section.node_path)
+        return self
+
+
+class PersistedSectionTree(BaseModel):
+    """What one representation's section-tree write actually landed.
+
+    On a retried attempt the FIRST write wins row by row, so the caller must
+    treat this — not its own input — as the truth (the sidecar is derived
+    from it, never from a fresher LLM proposal).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    sections: tuple[SnappedSection, ...] = Field(min_length=1)
+    placement_path: str | None
+    structurer_version: str

rememberstack/model/telemetry.py

@@ -0,0 +1,30 @@
+"""Structured telemetry values that remain independent of exporter SDKs."""
+
+from typing import Annotated
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from rememberstack.model.queue import UTCDateTime
+
+TelemetryScalar = str | int | float | bool | None
+
+
+class TelemetryAttribute(BaseModel):
+    """One immutable structured attribute on a telemetry event."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: Annotated[str, Field(min_length=1)]
+    value: TelemetryScalar
+
+
+class TelemetryEvent(BaseModel):
+    """Provider-neutral structured event ready for export."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: Annotated[str, Field(min_length=1)]
+    occurred_at: UTCDateTime
+    attributes: tuple[TelemetryAttribute, ...]

rememberstack/ports/__init__.py

@@ -0,0 +1,29 @@
+"""Provider-neutral deployment substrate and store-capability protocols."""
+
+from rememberstack.ports.auth import AuthPerimeterPort
+from rememberstack.ports.forget import ForgetManifestPort
+from rememberstack.ports.git import KGitRemotePort
+from rememberstack.ports.model_provider import ModelProviderPort
+from rememberstack.ports.mounts import MountPublisherPort
+from rememberstack.ports.object_store import ObjectStorePort
+from rememberstack.ports.purge import KGitPurgePort
+from rememberstack.ports.purge import ObjectPurgePort
+from rememberstack.ports.purge import P1PurgePort
+from rememberstack.ports.purge import ProjectionPurgePort
+from rememberstack.ports.queue import TaskQueuePort
+from rememberstack.ports.telemetry import TelemetryPort
+
+__all__ = (
+    "AuthPerimeterPort",
+    "ForgetManifestPort",
+    "KGitPurgePort",
+    "KGitRemotePort",
+    "ModelProviderPort",
+    "MountPublisherPort",
+    "ObjectStorePort",
+    "ObjectPurgePort",
+    "P1PurgePort",
+    "ProjectionPurgePort",
+    "TaskQueuePort",
+    "TelemetryPort",
+)

rememberstack/ports/auth.py

@@ -0,0 +1,16 @@
+"""D50/D60 auth-perimeter seam for a single-deployment trust domain."""
+
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import AuthenticatedContext
+from rememberstack.model import PerimeterCredential
+
+
+@runtime_checkable
+class AuthPerimeterPort(Protocol):
+    """Authenticate perimeter credentials without introducing internal tenancy."""
+
+    def authenticate(self, *, credential: PerimeterCredential) -> AuthenticatedContext:
+        """Return the authenticated principal and its one deployment context."""
+        ...

rememberstack/ports/connector.py

@@ -0,0 +1,23 @@
+"""D61 seam for watched sources: poll observations, fetch bytes (lifecycle §2)."""
+
+from collections.abc import Mapping
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import SourceItem
+
+
+@runtime_checkable
+class WatchedSourcePort(Protocol):
+    """One watched source: enumerate current items and detect deletions."""
+
+    def poll(self, *, known: Mapping[str, str]) -> tuple[SourceItem, ...]:
+        """Report every current item plus a deleted-marked item for each
+        known source_ref no longer present. `known` maps source_ref → the
+        last ingested revision, so unchanged items can skip fetch entirely.
+        """
+        ...
+
+    def fetch(self, *, source_ref: str) -> bytes:
+        """The item's current bytes (called only for changed items)."""
+        ...

rememberstack/ports/cost_meter.py

@@ -0,0 +1,17 @@
+"""Provider-neutral sink for attributing one worker attempt's model calls."""
+
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import ProviderCallUsage
+
+
+@runtime_checkable
+class CostMeterPort(Protocol):
+    """Record provider usage under a deterministic call key and cascade tier."""
+
+    def record(
+        self, *, call_key: str, tier: str | None, usage: ProviderCallUsage
+    ) -> None:
+        """Persist one successful provider call for the bound processing attempt."""
+        ...

rememberstack/ports/forget.py

@@ -0,0 +1,20 @@
+"""D74 durable intent boundary for portable hard-forget manifests."""
+
+from typing import Protocol
+from typing import runtime_checkable
+from uuid import UUID
+
+from rememberstack.model import ForgetManifest
+
+
+@runtime_checkable
+class ForgetManifestPort(Protocol):
+    """Append and enumerate immutable intent outside the protected restore set."""
+
+    def append(self, *, manifest: ForgetManifest) -> None:
+        """Durably append one manifest; identical bytes are idempotent."""
+        ...
+
+    def manifests(self, *, deployment_id: UUID) -> tuple[ForgetManifest, ...]:
+        """Return every manifest for a deployment in deterministic order."""
+        ...

rememberstack/ports/git.py

@@ -0,0 +1,20 @@
+"""D45/D61 remote interaction used by the single-writer Plane-K driver."""
+
+from pathlib import Path
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import KRevision
+
+
+@runtime_checkable
+class KGitRemotePort(Protocol):
+    """Checkout and publish driver-owned Plane-K commits through one remote."""
+
+    def checkout(self, *, destination: Path) -> KRevision:
+        """Create the driver's working checkout and return its current revision."""
+        ...
+
+    def publish(self, *, worktree: Path) -> KRevision:
+        """Publish the commit prepared by the K driver and return its revision."""
+        ...

rememberstack/ports/model_provider.py

@@ -0,0 +1,28 @@
+"""D52/D61 substrate seam for typed model and embedding provider calls."""
+
+from typing import Protocol
+from typing import runtime_checkable
+from typing import TypeVar
+
+from rememberstack.model import EmbeddingRequest
+from rememberstack.model import EmbeddingResponse
+from rememberstack.model import GeneratedResponse
+from rememberstack.model import ModelRequest
+from rememberstack.model import StructuredResponseModel
+
+ResponseT = TypeVar("ResponseT", bound=StructuredResponseModel)
+
+
+@runtime_checkable
+class ModelProviderPort(Protocol):
+    """Invoke configured models without owning prompts, cascades, or domain logic."""
+
+    def generate(
+        self, *, request: ModelRequest, response_type: type[ResponseT]
+    ) -> GeneratedResponse[ResponseT]:
+        """Return validated output plus the provider-reported usage for this call."""
+        ...
+
+    def embed(self, *, request: EmbeddingRequest) -> EmbeddingResponse:
+        """Return same-dimension embeddings for one caller-declared batch."""
+        ...

rememberstack/ports/mounts.py

@@ -0,0 +1,16 @@
+"""D51/D61 portable publication boundary for four read-only mount views."""
+
+from typing import Protocol
+from typing import runtime_checkable
+from uuid import UUID
+
+from rememberstack.model import PublishedMounts
+
+
+@runtime_checkable
+class MountPublisherPort(Protocol):
+    """Publish P3, artifact, raw, and Plane-K views without mount mechanics."""
+
+    def publish(self, *, deployment_id: UUID) -> PublishedMounts:
+        """Publish and return the exact four read-only deployment views."""
+        ...

rememberstack/ports/object_store.py

@@ -0,0 +1,27 @@
+"""D61 byte/object-key seam for immutable raw inputs, artifacts, and snapshots."""
+
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import ObjectKey
+
+
+@runtime_checkable
+class ObjectStorePort(Protocol):
+    """Read and create immutable objects without exposing storage-provider types."""
+
+    def read_bytes(self, *, key: ObjectKey) -> bytes:
+        """Read all bytes stored under an existing object key."""
+        ...
+
+    def write_bytes(
+        self, *, key: ObjectKey, content: bytes, storage_class: str | None = None
+    ) -> None:
+        """Create immutable bytes, failing rather than replacing an occupied key.
+
+        `storage_class` is the D51 mime routing decision made by the caller
+        (hot for media a harness reads, cold for originals kept only for
+        audit). Providers that have storage classes apply it; providers
+        that do not record it, so the routing is observable either way.
+        """
+        ...

rememberstack/ports/p1_index.py

@@ -0,0 +1,92 @@
+"""D61 seam for the P1 search indexes: chunks, claims, facts (D8)."""
+
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import P1ChunkRow
+from rememberstack.model import P1ClaimRow
+from rememberstack.model import P1EntityRow
+from rememberstack.model import P1FactRow
+
+
+@runtime_checkable
+class ChunkIndexPort(Protocol):
+    """Write the P1 chunk table without exposing vector-store types."""
+
+    def upsert_chunks(self, *, rows: tuple[P1ChunkRow, ...]) -> None:
+        """Insert or replace rows by chunk_id; re-runs are idempotent."""
+        ...
+
+    def chunk_vectors(
+        self, *, deployment_id: str, chunk_ids: tuple[str, ...]
+    ) -> dict[str, tuple[float, ...]]:
+        """Stored vectors for the requested ids (absent ids are omitted).
+
+        The D56 embedding-reuse read: an unchanged chunk in a new version
+        copies its predecessor's vector instead of re-embedding.
+        """
+        ...
+
+
+@runtime_checkable
+class ClaimIndexPort(Protocol):
+    """Write the P1 claims channel — the needle index (D58)."""
+
+    def upsert_claims(self, *, rows: tuple[P1ClaimRow, ...]) -> None:
+        """Insert or replace rows by claim_id; re-runs are idempotent."""
+        ...
+
+
+@runtime_checkable
+class FactIndexPort(Protocol):
+    """Write the P1 facts channel — relation/observation labels (D8)."""
+
+    def upsert_facts(self, *, rows: tuple[P1FactRow, ...]) -> None:
+        """Insert or replace rows by fact_id; re-runs are idempotent."""
+        ...
+
+
+@runtime_checkable
+class P1SearchPort(Protocol):
+    """Nominate candidates from the P1 indexes (D48: propose, never dispose)."""
+
+    def search_claims(
+        self,
+        *,
+        deployment_id: str,
+        vector: tuple[float, ...],
+        k: int,
+        current_only: bool,
+    ) -> tuple[str, ...]:
+        """Ranked claim-id nominations from the claims channel."""
+        ...
+
+    def search_facts(
+        self, *, deployment_id: str, vector: tuple[float, ...], k: int, kind: str | None
+    ) -> tuple[str, ...]:
+        """Ranked fact-id nominations from the facts channel."""
+        ...
+
+
+@runtime_checkable
+class EntityIndexPort(Protocol):
+    """The T3 profile-embedding home: entity vectors in P1 (D8/D17)."""
+
+    def upsert_entities(self, *, rows: tuple[P1EntityRow, ...]) -> None:
+        """Insert or replace entity profiles by entity_id; idempotent."""
+        ...
+
+    def entity_vectors(
+        self, *, deployment_id: str, entity_ids: tuple[str, ...]
+    ) -> dict[str, tuple[float, ...]]:
+        """Profile vectors for the requested ids (absent ids are omitted)."""
+        ...
+
+
+@runtime_checkable
+class P1IndexMaintenancePort(Protocol):
+    """Explicit post-bulk-load maintenance for the P1 search indexes."""
+
+    def build_search_indexes(self) -> None:
+        """Build or refresh search indexes after a backfill has drained."""
+        ...

rememberstack/ports/purge.py

@@ -0,0 +1,93 @@
+"""D74 erasure capabilities of the already-selected serving stores."""
+
+from typing import Protocol
+from typing import runtime_checkable
+from uuid import UUID
+
+from rememberstack.model import ObjectKey
+
+
+@runtime_checkable
+class ObjectPurgePort(Protocol):
+    """Idempotently erase manifest-nominated immutable objects."""
+
+    def purge_objects(
+        self, *, keys: tuple[ObjectKey, ...], prefixes: tuple[ObjectKey, ...]
+    ) -> None:
+        """Delete exact keys and every object below exact prefixes; absence succeeds."""
+        ...
+
+    def verify_objects_purged(
+        self, *, keys: tuple[ObjectKey, ...], prefixes: tuple[ObjectKey, ...]
+    ) -> None:
+        """Raise unless every exact key and prefix is absent from the active store."""
+        ...
+
+
+@runtime_checkable
+class P1PurgePort(Protocol):
+    """Idempotently erase manifest-nominated P1 rows by identity."""
+
+    def purge_rows(
+        self,
+        *,
+        deployment_id: UUID,
+        chunk_ids: tuple[UUID, ...],
+        claim_ids: tuple[UUID, ...],
+        fact_ids: tuple[UUID, ...],
+        entity_ids: tuple[UUID, ...],
+    ) -> None:
+        """Delete exact rows and compact affected P1 tables; absence succeeds."""
+        ...
+
+    def verify_rows_purged(
+        self,
+        *,
+        deployment_id: UUID,
+        chunk_ids: tuple[UUID, ...],
+        claim_ids: tuple[UUID, ...],
+        fact_ids: tuple[UUID, ...],
+        entity_ids: tuple[UUID, ...],
+    ) -> None:
+        """Raise unless every nominated row is absent from active P1 tables."""
+        ...
+
+
+@runtime_checkable
+class ProjectionPurgePort(Protocol):
+    """Erase old P2/P3 durable prefixes and local serving copies."""
+
+    def purge_projections(
+        self, *, deployment_id: UUID, prefixes: tuple[ObjectKey, ...]
+    ) -> None:
+        """Delete every nominated projection copy; absence succeeds."""
+        ...
+
+    def verify_projections_purged(
+        self, *, deployment_id: UUID, prefixes: tuple[ObjectKey, ...]
+    ) -> None:
+        """Raise unless durable old prefixes and local serving copies are absent."""
+        ...
+
+
+@runtime_checkable
+class KGitPurgePort(Protocol):
+    """Erase affected Plane-K paths from all reachable Git history."""
+
+    def blocking_redaction_paths(
+        self, *, deployment_id: UUID, doc_id: UUID
+    ) -> tuple[str, ...]:
+        """Return sorted authored-body or curation paths that still cite a lineage."""
+        ...
+
+    def purge_artifacts(
+        self, *, deployment_id: UUID, forget_id: UUID, artifact_ids: tuple[UUID, ...]
+    ) -> None:
+        """Erase affected history and retain only already-sanitized current files."""
+        ...
+
+    def verify_artifacts_purged(
+        self, *, deployment_id: UUID, forget_id: UUID, artifact_ids: tuple[UUID, ...]
+    ) -> None:
+        """Raise unless the store-local receipt and affected-path history are clean."""
+        ...

rememberstack/ports/queue.py

@@ -0,0 +1,23 @@
+"""D67 delivery-only announcement seam over committed Postgres work truth."""
+
+from typing import Protocol
+from typing import runtime_checkable
+from uuid import UUID
+
+from rememberstack.model import QueueRoute
+from rememberstack.model import UTCDateTime
+
+
+@runtime_checkable
+class TaskQueuePort(Protocol):
+    """Announce an existing row using non-authoritative route and due snapshots."""
+
+    def announce(
+        self,
+        *,
+        processing_id: UUID,
+        route_snapshot: QueueRoute,
+        not_before_snapshot: UTCDateTime,
+    ) -> None:
+        """Schedule at-least-once delivery without creating or mutating work state."""
+        ...

rememberstack/ports/telemetry.py

@@ -0,0 +1,21 @@
+"""D61 telemetry seam preserving structured data and real exception objects."""
+
+from typing import Protocol
+from typing import runtime_checkable
+
+from rememberstack.model import TelemetryEvent
+
+
+@runtime_checkable
+class TelemetryPort(Protocol):
+    """Export telemetry without importing a vendor SDK or hiding exporter failure."""
+
+    def export_event(self, *, event: TelemetryEvent) -> None:
+        """Export one structured event and let exporter failures propagate."""
+        ...
+
+    def export_exception(
+        self, *, event: TelemetryEvent, exception: BaseException
+    ) -> None:
+        """Export the event with the original exception object and cause chain."""
+        ...

rememberstack/profiles/__init__.py

@@ -0,0 +1,22 @@
+"""Explicit composition root package."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rememberstack.profiles.selfhost import SelfHostProfile
+    from rememberstack.profiles.selfhost import SelfHostSettings
+
+__all__ = ("SelfHostProfile", "SelfHostSettings")
+
+
+def __getattr__(name: str) -> object:
+    """Load a profile only when its explicit composition root is requested."""
+    if name == "SelfHostProfile":
+        from rememberstack.profiles.selfhost import SelfHostProfile
+
+        return SelfHostProfile
+    if name == "SelfHostSettings":
+        from rememberstack.profiles.selfhost import SelfHostSettings
+
+        return SelfHostSettings
+    raise AttributeError(name)