rememberstack 0.1.0__py3-none-any.whl

rememberstack/model/consumption.py

@@ -0,0 +1,88 @@
+"""Typed values for the deployment-rendered D51 consumption skill."""
+
+from typing import Annotated
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from rememberstack.model.envelope import Grain
+from rememberstack.model.mounts import PublishedMounts
+from rememberstack.model.recipes import RecipeAnswerIntent
+
+_NonEmptyText = Annotated[str, Field(min_length=1)]
+
+
+class ConsumptionScope(BaseModel):
+    """One deployment scope the rendered skill can name to a cold agent."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    slug: _NonEmptyText
+    name: _NonEmptyText
+    description: str | None = None
+    git_path: str | None = None
+
+
+class ConsumptionRecipe(BaseModel):
+    """One latest active recipe advertised by the rendered skill."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: _NonEmptyText
+    description: _NonEmptyText
+    output_grain: Grain
+    answer_intent: RecipeAnswerIntent
+
+
+class ConsumptionDeployment(BaseModel):
+    """Deployment-owned data that varies between rendered skill revisions."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    slug: _NonEmptyText
+    name: _NonEmptyText
+    description: str | None = None
+    default_language: _NonEmptyText
+    scopes: tuple[ConsumptionScope, ...] = ()
+    knowledge_page_count: int = Field(ge=0)
+
+
+class ConsumptionSkillContext(BaseModel):
+    """Complete typed input to the pure consumption-skill renderer."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment: ConsumptionDeployment
+    recipes: tuple[ConsumptionRecipe, ...]
+    mounts: PublishedMounts | None = None
+
+
+class RenderedConsumptionSkill(BaseModel):
+    """One versioned, deployment-specific ``SKILL.md`` artifact."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    version: _NonEmptyText
+    filename: Literal["SKILL.md"] = "SKILL.md"
+    content: _NonEmptyText
+
+
+class S58Answer(BaseModel):
+    """A cold harness's structured choices for the S58 consumption protocol."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    orientation: Literal["knowledge", "facts", "claims_as_of"]
+    empty_knowledge: Literal["fallback_p3_or_search", "stop", "invent_summary"]
+    current_truth: Literal["fact_lookup", "claim_search", "claims_as_of"]
+    grain_handling: Literal["separate", "blend", "drop_evidence_label"]
+    withdrawn_support: Literal["caveat_and_transcript", "trust", "discard"]
+    claims_as_of: Literal["assertion_history_only", "current_truth", "compiled_truth"]
+    contradictions: Literal["report_co_members", "pick_one", "ignore"]
+    readable_content: Literal["prefer_mounts", "prefer_api", "prefer_raw"]
+    audit: Literal["hydrate_to_sources", "read_k_only", "use_claims_as_fact"]

rememberstack/model/conversion.py

@@ -0,0 +1,31 @@
+"""D38 conversion-module values: converter output and its typed failures."""
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+
+class ConversionResult(BaseModel):
+    """What a converter route produced from one raw input.
+
+    `document_md` is the clean Markdown rendering — the immutable coordinate
+    system everything downstream references by offset (D57). Source maps and
+    derived assets (media routes, D65) extend this model when their routes
+    arrive; every converter can always deliver the Markdown itself.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    document_md: str
+    warnings: tuple[str, ...] = ()
+
+
+class ConversionError(Exception):
+    """A converter could not produce Markdown from the input bytes.
+
+    Deterministic for given bytes, so retrying cannot help — handlers treat
+    this as non-retryable and dead-letter the work with the cause chained.
+    """
+
+
+class UnroutableMimeError(Exception):
+    """No configured conversion route accepts the input's MIME type (D38)."""

rememberstack/model/deployment.py

@@ -0,0 +1,53 @@
+"""Typed values and conflicts for deployment bootstrap."""
+
+from typing import Annotated
+from typing import TypeAlias
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import StringConstraints
+
+NonEmptyStrictString: TypeAlias = Annotated[
+    str, StringConstraints(strict=True, min_length=1)
+]
+
+
+class DeploymentBootstrapInput(BaseModel):
+    """Explicit profile-owned values required to bootstrap one deployment."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    slug: NonEmptyStrictString
+    name: NonEmptyStrictString
+    description: str | None = None
+    default_language: NonEmptyStrictString
+    raw_bucket: NonEmptyStrictString
+    artifacts_bucket: NonEmptyStrictString
+    corpusfs_bucket: NonEmptyStrictString
+    knowledge_repo_uri: str | None = None
+
+
+class DeploymentBootstrapResult(BaseModel):
+    """Verified deployment and universal-core counts after bootstrap."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    deployment_created: bool
+    entity_types_count: int
+    predicates_count: int
+    predicate_signatures_count: int
+
+
+class DeploymentBootstrapConflictError(RuntimeError):
+    """Base class for a known bootstrap state conflict."""
+
+
+class DeploymentConflictError(DeploymentBootstrapConflictError):
+    """A deployment identity or mapped profile value conflicts with input."""
+
+
+class CoreManifestConflictError(DeploymentBootstrapConflictError):
+    """Stored core registry state conflicts with the immutable manifest."""

rememberstack/model/documents.py

@@ -0,0 +1,168 @@
+"""E0 document-layer values: uploads, ledger records, and stage-load shapes (D36/D37).
+
+Object URIs in these models are provider-neutral object-store *keys*; which
+bucket a key resolves in (raw vs artifacts) is deployment configuration, and
+the composing profile binds one `ObjectStorePort` per bucket.
+"""
+
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from rememberstack.model.queue import UTCDateTime
+
+NonEmptyString = Annotated[str, Field(min_length=1)]
+
+
+class DocumentUpload(BaseModel):
+    """One file handed to the upload connector: bytes plus what the caller knows."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    filename: NonEmptyString
+    mime: NonEmptyString
+    content: bytes
+    title: str | None = None
+
+
+class IngestedVersion(BaseModel):
+    """What one ingest did: the lineage/version it landed on, and whether it was new.
+
+    `created=False` is the D55 content-hash no-op: identical bytes re-ingested
+    never create a second version or re-run the chain.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    content_hash: str
+    created: bool
+
+
+class UploadRecord(BaseModel):
+    """The complete row-write input for recording one upload in the spine."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    source_kind: NonEmptyString
+    source_ref: NonEmptyString
+    source_uri: str | None
+    title: str | None
+    content_hash: NonEmptyString
+    mime: NonEmptyString
+    byte_size: int = Field(ge=0)
+    raw_uri: NonEmptyString
+    versioning_mode: str = "snapshot"  # snapshot (fail-safe) | living (D55)
+    source_modified_at: UTCDateTime | None = None
+    source_version_ref: str | None = None
+    sync_cycle_id: UUID | None = None
+
+
+class ConvertSource(BaseModel):
+    """Everything the convert stage loads about its claimed document version."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    content_hash: str
+    mime: str
+    raw_uri: str
+    title: str | None
+
+
+class RepresentationRecord(BaseModel):
+    """One conversion run's immutable output row (D65): the reading of a version."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    representation_id: UUID
+    deployment_id: UUID
+    version_id: UUID
+    route: NonEmptyString
+    converter_name: NonEmptyString
+    converter_version: NonEmptyString
+    blockizer_version: NonEmptyString
+    markdown_uri: NonEmptyString
+    blocks_uri: NonEmptyString
+    conversion_uri: NonEmptyString
+    meta_uri: NonEmptyString
+    markdown_hash: NonEmptyString
+    manifest_hash: NonEmptyString
+
+
+class StructureSource(BaseModel):
+    """Everything the structure stage loads about its claimed representation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    representation_id: UUID
+    blocks_uri: str
+    markdown_uri: str
+    title: str | None
+
+
+class SyntheticRootRecord(BaseModel):
+    """The single full-document root section every document gets (D39).
+
+    The root spans the whole block grid and character range of `document.md`;
+    an empty document still gets the row (zero-width span) so E1/E2/P3 always
+    have a path and role to read.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    representation_id: UUID
+    block_count: int = Field(ge=0)
+    markdown_chars: int = Field(ge=0)
+    title: str | None
+    structurer_version: NonEmptyString
+
+
+class DocumentVersionNotFoundError(Exception):
+    """A stage referenced a document version the spine does not know."""
+
+
+class RepresentationNotFoundError(Exception):
+    """A stage referenced a document representation the spine does not know."""
+
+
+class SourceItem(BaseModel):
+    """One observation a watched source reports in a poll (lifecycle §2)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    source_ref: NonEmptyString  # connector-native stable id (path, file id)
+    revision: NonEmptyString  # revision/etag; unchanged revision = no fetch
+    modified_at: UTCDateTime
+    deleted: bool = False
+    filename: str = ""
+    mime: str = "text/markdown"
+
+
+class SyncCycleSummary(BaseModel):
+    """What one recorded sync cycle did (connector_sync_cycles, D55/F8)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    cycle_id: UUID
+    observed: int
+    ingested: tuple[UUID, ...] = ()  # version ids created this cycle
+    unchanged: int = 0
+    debounced: int = 0
+    deletions_observed: tuple[UUID, ...] = ()  # lineage ids tombstoned
+    failed: int = 0  # items lost to per-item errors; the cycle is lossy