rememberstack 0.1.0__py3-none-any.whl

rememberstack/core/blockizer.py

@@ -0,0 +1,189 @@
+"""The deterministic blockizer: document.md → the block sequence (D57, e1 §2).
+
+One shared code path regardless of which converter produced the Markdown. The
+parser profile is pinned (GFM: CommonMark + the table extension, via
+markdown-it-py); normalization order is fixed (join hard-wrapped lines → NFC →
+collapse internal whitespace → hash). Determinism is regression-tested by the
+golden corpus in CI per `BLOCKIZER_VERSION` — drift is a version bump, never a
+silent change.
+"""
+
+import hashlib
+from typing import Final
+import unicodedata
+
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+
+from rememberstack.model import Block
+from rememberstack.model import BlockType
+
+BLOCKIZER_VERSION: Final = "blockizer-2026.07:markdown-it-py-4:gfm-tables"
+"""Pins the parser library generation and enabled-extension set (e1 §2)."""
+
+_ATOMIC_CONTAINERS: Final = {
+    "table_open": ("table_close", BlockType.TABLE),
+    "blockquote_open": ("blockquote_close", BlockType.QUOTE),
+}
+_LIST_OPENERS: Final = frozenset({"bullet_list_open", "ordered_list_open"})
+
+
+def blockize(*, document_md: str) -> tuple[Block, ...]:
+    """Derive the deterministic block sequence from a document.md rendering.
+
+    Blocks are CommonMark block-level elements: paragraphs, headings, list
+    items, atomic tables, code fences, and block quotes. Offsets slice
+    `document_md` exactly; the hash is over the normalized text, so a pure
+    reflow (hard-wrap change) does not change identity.
+    """
+    tokens = _parser().parse(document_md)
+    line_offsets = _line_offsets(document_md=document_md)
+    blocks: list[Block] = []
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        consumed, block = _emit(
+            tokens=tokens,
+            index=index,
+            document_md=document_md,
+            line_offsets=line_offsets,
+            ordinal=len(blocks),
+        )
+        if block is not None:
+            blocks.append(block)
+        index += consumed
+        del token
+    return tuple(blocks)
+
+
+def normalized_block_text(*, raw: str) -> str:
+    """Apply the fixed normalization order: join lines → NFC → collapse spaces."""
+    joined = " ".join(line.strip() for line in raw.splitlines())
+    composed = unicodedata.normalize("NFC", joined)
+    return " ".join(composed.split())
+
+
+def block_hash(*, raw: str) -> str:
+    """The block identity: sha256 over the normalized text."""
+    digest = hashlib.sha256(normalized_block_text(raw=raw).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def _parser() -> MarkdownIt:
+    """The pinned GFM-profile parser: CommonMark plus the table extension."""
+    return MarkdownIt("commonmark").enable("table")
+
+
+def _line_offsets(*, document_md: str) -> tuple[int, ...]:
+    """Char offset of each line start, plus the end-of-document sentinel."""
+    offsets = [0]
+    for line in document_md.splitlines(keepends=True):
+        offsets.append(offsets[-1] + len(line))
+    return tuple(offsets)
+
+
+def _emit(
+    *,
+    tokens: list[Token],
+    index: int,
+    document_md: str,
+    line_offsets: tuple[int, ...],
+    ordinal: int,
+) -> tuple[int, Block | None]:
+    """Emit at most one block starting at tokens[index]; return tokens consumed.
+
+    List containers recurse into their items; each top-level list item is one
+    atomic block whose span includes any nested sub-list (deliberate: emitting
+    nested items separately would create overlapping spans, and chunks require
+    non-overlapping whole-block runs — e1 §4). Other containers and leaves map
+    directly. Unknown structural tokens are skipped one at a time — the golden
+    corpus locks the observable result.
+    """
+    token = tokens[index]
+    if token.type in _LIST_OPENERS:
+        return 1, None  # items are emitted individually; the wrapper is not a block
+    if token.type == "list_item_open":
+        close = _matching_close(
+            tokens=tokens, index=index, close_type="list_item_close"
+        )
+        return (
+            close - index + 1,
+            _block_from_lines(
+                token=token,
+                block_type=BlockType.LIST_ITEM,
+                document_md=document_md,
+                line_offsets=line_offsets,
+                ordinal=ordinal,
+            ),
+        )
+    if token.type in _ATOMIC_CONTAINERS:
+        close_type, block_type = _ATOMIC_CONTAINERS[token.type]
+        close = _matching_close(tokens=tokens, index=index, close_type=close_type)
+        return (
+            close - index + 1,
+            _block_from_lines(
+                token=token,
+                block_type=block_type,
+                document_md=document_md,
+                line_offsets=line_offsets,
+                ordinal=ordinal,
+            ),
+        )
+    if token.type == "heading_open":
+        return 3, _block_from_lines(
+            token=token,
+            block_type=BlockType.HEADING,
+            document_md=document_md,
+            line_offsets=line_offsets,
+            ordinal=ordinal,
+        )
+    if token.type == "paragraph_open":
+        return 3, _block_from_lines(
+            token=token,
+            block_type=BlockType.PARAGRAPH,
+            document_md=document_md,
+            line_offsets=line_offsets,
+            ordinal=ordinal,
+        )
+    if token.type in ("fence", "code_block"):
+        return 1, _block_from_lines(
+            token=token,
+            block_type=BlockType.CODE,
+            document_md=document_md,
+            line_offsets=line_offsets,
+            ordinal=ordinal,
+        )
+    return 1, None
+
+
+def _matching_close(*, tokens: list[Token], index: int, close_type: str) -> int:
+    """Index of the container's matching close token at the same nesting level."""
+    level = tokens[index].level
+    for probe in range(index + 1, len(tokens)):
+        if tokens[probe].type == close_type and tokens[probe].level == level:
+            return probe
+    raise ValueError(f"unbalanced container at token {index}: no {close_type}")
+
+
+def _block_from_lines(
+    *,
+    token: Token,
+    block_type: BlockType,
+    document_md: str,
+    line_offsets: tuple[int, ...],
+    ordinal: int,
+) -> Block:
+    """Build the block record from a token's source line map."""
+    if token.map is None:
+        raise ValueError(f"token {token.type} carries no source map")
+    start_line, end_line = token.map
+    char_start = line_offsets[start_line]
+    char_end = line_offsets[end_line]
+    raw = document_md[char_start:char_end].rstrip("\r\n")
+    return Block(
+        ordinal=ordinal,
+        type=block_type,
+        char_start=char_start,
+        char_end=char_start + len(raw),
+        block_hash=block_hash(raw=raw),
+    )

rememberstack/core/chunker.py

@@ -0,0 +1,216 @@
+"""The deterministic E1 chunker: anchor-stabilized packing of whole blocks (D58).
+
+A chunk is an ordered run of whole blocks within one section, packed to a
+token budget. Boundaries are stabilized by content anchors: a block whose hash
+satisfies the anchor predicate forces a boundary before it, so an early edit
+perturbs packing only up to the next anchor instead of rippling through the
+document (e1 §4). Chunks never overlap and never split a block; an oversized
+block becomes its own oversized chunk rather than being cut.
+
+chunks = f(blocks, sections, budget, anchors, CHUNKER_VERSION): a parameter
+change is a version bump and a cheap repack of existing atoms.
+"""
+
+import hashlib
+from typing import Final
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from rememberstack.model import Block
+from rememberstack.model import PackedChunk
+from rememberstack.model import SectionSpan
+
+CHUNKER_VERSION: Final = "e1-chunker-2026.07b:whitespace-tokens:anchored:owner-runs"
+"""Pins the packing algorithm and the token counter; the full packing
+generation additionally encodes the parameter values — see `chunker_version`."""
+
+
+class ChunkerParams(BaseModel):
+    """The bound packing parameters (e1 §4). Values are starting points to
+    measure (spike 3), never committed constants; changing them is a
+    CHUNKER_VERSION bump."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    token_budget: int = Field(default=400, ge=1)
+    anchor_modulus: int = Field(default=24, ge=1)
+    anchor_min_gap_tokens: int = Field(default=200, ge=0)
+
+
+def chunker_version(*, params: "ChunkerParams") -> str:
+    """The complete packing-generation identity: algorithm + parameter values.
+
+    chunks = f(blocks, sections, budget, anchors, version) — so changing any
+    parameter re-keys packing automatically instead of silently replaying
+    rows produced under different numbers (D58).
+    """
+    return (
+        f"{CHUNKER_VERSION}"
+        f":b{params.token_budget}"
+        f"-m{params.anchor_modulus}"
+        f"-g{params.anchor_min_gap_tokens}"
+    )
+
+
+def pack_blocks(
+    *,
+    blocks: tuple[Block, ...],
+    sections: tuple[SectionSpan, ...],
+    document_md: str,
+    params: ChunkerParams,
+) -> tuple[PackedChunk, ...]:
+    """Pack the block grid into chunks, deepest-owner run by run.
+
+    Every block belongs to exactly one DEEPEST section (D57): a leaf owns
+    its whole range, and a parent directly owns the blocks none of its
+    children cover (content before the first child, and gaps between
+    children — the snap assigns those to the parent, never to a child).
+    Each contiguous run of same-owner blocks packs independently, so no
+    block is chunked twice and none is silently dropped (Codex review: a
+    leaf-only walk lost every parent's direct content). Within a run,
+    blocks accumulate greedily to the token budget; a chunk boundary is
+    forced before every anchor block, and a block that alone exceeds the
+    budget ships as its own oversized chunk. Sections are never crossed
+    (§3 makes the partition well-defined).
+    """
+    chunks: list[PackedChunk] = []
+    for section, run_start, run_end in _owner_runs(sections=sections):
+        run_blocks = tuple(
+            block for block in blocks if run_start <= block.ordinal <= run_end
+        )
+        chunks.extend(
+            _pack_section(
+                section=section,
+                blocks=run_blocks,
+                document_md=document_md,
+                params=params,
+                first_ordinal=len(chunks),
+            )
+        )
+    return tuple(chunks)
+
+
+def _owner_runs(
+    *, sections: tuple[SectionSpan, ...]
+) -> tuple[tuple[SectionSpan, int, int], ...]:
+    """Every contiguous block run with its deepest-owning section, in
+    document order: a section's runs are its range minus its direct
+    children's ranges."""
+    runs: list[tuple[SectionSpan, int, int]] = []
+    for section in sections:
+        prefix = f"{section.node_path}."
+        child_ranges = sorted(
+            (other.block_start, other.block_end)
+            for other in sections
+            if other.node_path.startswith(prefix)
+            and "." not in other.node_path.removeprefix(prefix)
+        )
+        cursor = section.block_start
+        for child_start, child_end in child_ranges:
+            if child_start > cursor:
+                runs.append((section, cursor, child_start - 1))
+            cursor = max(cursor, child_end + 1)
+        if cursor <= section.block_end:
+            runs.append((section, cursor, section.block_end))
+    return tuple(sorted(runs, key=lambda run: run[1]))
+
+
+def chunk_content_hash(*, block_hashes: tuple[str, ...]) -> str:
+    """The chunk identity: sha256 over the ordered block-hash sequence (D58)."""
+    digest = hashlib.sha256("\n".join(block_hashes).encode("utf-8"))
+    return digest.hexdigest()
+
+
+def extraction_input_hash(
+    *,
+    own_block_hashes: tuple[str, ...],
+    neighbor_block_hashes: tuple[str, ...],
+    header_facts: tuple[str, ...],
+    extractor_version: str,
+    structurer_version: str,
+) -> str:
+    """The D56 reuse key: stable inputs of the E2 bundle, no LLM output.
+
+    Own blocks + neighbor blocks + deterministic document metadata + the
+    extractor and structurer versions. Prefixes, summaries, and section paths
+    are carried forward on reuse, never keyed — so an unchanged key within a
+    lineage means the prior claims are re-attached instead of re-extracted.
+    """
+    payload = "\x1e".join(
+        (
+            "\n".join(own_block_hashes),
+            "\n".join(neighbor_block_hashes),
+            "\n".join(header_facts),
+            extractor_version,
+            structurer_version,
+        )
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def count_tokens(*, text: str) -> int:
+    """The pinned token counter: whitespace tokens (part of CHUNKER_VERSION)."""
+    return len(text.split())
+
+
+def is_anchor(*, block_hash: str, params: ChunkerParams) -> bool:
+    """The anchor predicate's hash half: uint64(block_hash) mod M == 0 (e1 §4)."""
+    return int(block_hash[:16], 16) % params.anchor_modulus == 0
+
+
+def _pack_section(
+    *,
+    section: SectionSpan,
+    blocks: tuple[Block, ...],
+    document_md: str,
+    params: ChunkerParams,
+    first_ordinal: int,
+) -> tuple[PackedChunk, ...]:
+    """Pack one section's blocks; boundaries never leave the section."""
+    chunks: list[PackedChunk] = []
+    run: list[tuple[Block, int]] = []
+    run_tokens = 0
+    tokens_since_anchor = params.anchor_min_gap_tokens  # first anchor never suppressed
+
+    def flush() -> None:
+        nonlocal run, run_tokens
+        if not run:
+            return
+        run_blocks = tuple(block for block, _ in run)
+        chunks.append(
+            PackedChunk(
+                ordinal=first_ordinal + len(chunks),
+                section_id=section.section_id,
+                block_start=run_blocks[0].ordinal,
+                block_end=run_blocks[-1].ordinal,
+                char_start=run_blocks[0].char_start,
+                char_end=run_blocks[-1].char_end,
+                chunk_content_hash=chunk_content_hash(
+                    block_hashes=tuple(block.block_hash for block in run_blocks)
+                ),
+                token_count=run_tokens,
+            )
+        )
+        run = []
+        run_tokens = 0
+
+    for block in blocks:
+        tokens = count_tokens(text=document_md[block.char_start : block.char_end])
+        anchored = (
+            is_anchor(block_hash=block.block_hash, params=params)
+            and tokens_since_anchor >= params.anchor_min_gap_tokens
+        )
+        if anchored:
+            flush()  # packing after an anchor is independent of everything before
+            tokens_since_anchor = 0
+        elif run and run_tokens + tokens > params.token_budget:
+            flush()  # budget boundary: the block starts the next run
+        run.append((block, tokens))
+        run_tokens += tokens
+        tokens_since_anchor += tokens
+        if run_tokens > params.token_budget:
+            flush()  # a single oversized block ships as its own oversized chunk
+    flush()
+    return tuple(chunks)

rememberstack/core/consumption_skill.py

@@ -0,0 +1,275 @@
+"""Pure renderer for the versioned D51 agent-consumption skill."""
+
+import json
+from typing import Final
+
+from rememberstack.model import ConsumptionRecipe
+from rememberstack.model import ConsumptionScope
+from rememberstack.model import ConsumptionSkillContext
+from rememberstack.model import PublishedMounts
+from rememberstack.model import RenderedConsumptionSkill
+
+CONSUMPTION_SKILL_VERSION: Final = "1.0.0"
+
+
+def render_consumption_skill(
+    *, context: ConsumptionSkillContext
+) -> RenderedConsumptionSkill:
+    """Render one complete ``SKILL.md`` from typed deployment state."""
+    deployment = context.deployment
+    sections = (
+        _header(),
+        _deployment(context=context),
+        _default_motion(
+            knowledge_page_count=deployment.knowledge_page_count,
+            recipes=context.recipes,
+        ),
+        _grains(),
+        _testimony(recipes=context.recipes),
+        _time_and_media(),
+        _envelope(),
+        _mounts(mounts=context.mounts),
+        _recipes(recipes=context.recipes),
+        _working_rules(),
+    )
+    return RenderedConsumptionSkill(
+        deployment_id=deployment.deployment_id,
+        version=CONSUMPTION_SKILL_VERSION,
+        content="\n\n".join(sections).rstrip() + "\n",
+    )
+
+
+def _header() -> str:
+    """The stable skill identity and revision."""
+    return (
+        "---\n"
+        "name: rememberstack\n"
+        "description: Use one configured RememberStack deployment without "
+        "mixing facts, testimony, and compiled knowledge.\n"
+        "---\n\n"
+        "# Use RememberStack\n\n"
+        f"Skill revision: `{CONSUMPTION_SKILL_VERSION}`. Follow these instructions "
+        "when a task depends on the configured memory."
+    )
+
+
+def _deployment(*, context: ConsumptionSkillContext) -> str:
+    """Render deployment identity, language, scopes, and current K state."""
+    deployment = context.deployment
+    description = (
+        f"\n- Purpose: {_literal(value=deployment.description)}"
+        if deployment.description
+        else ""
+    )
+    scopes = _scope_lines(scopes=deployment.scopes)
+    knowledge_state = (
+        "known empty: no K pages are registered"
+        if deployment.knowledge_page_count == 0
+        else f"{deployment.knowledge_page_count} K page(s) are registered"
+    )
+    return (
+        "## This deployment\n\n"
+        f"- Name: {_literal(value=deployment.name)}\n"
+        f"- Slug: `{deployment.slug}`\n"
+        f"- Deployment id: `{deployment.deployment_id}`\n"
+        f"- Default language: `{deployment.default_language}`"
+        f"{description}\n"
+        f"- Plane K state: {knowledge_state}.\n"
+        f"- Special-purpose scopes:\n{scopes}"
+    )
+
+
+def _default_motion(
+    *, knowledge_page_count: int, recipes: tuple[ConsumptionRecipe, ...]
+) -> str:
+    """Teach the one progressive-disclosure motion and honest empty-K fallback."""
+    orientation_route = (
+        "Read the knowledge checkout or use the active `pages_about` orientation "
+        "recipe."
+        if any(recipe.name == "pages_about" for recipe in recipes)
+        else "Read the knowledge checkout, or use an orientation-intent recipe if "
+        "one is enabled."
+    )
+    empty_instruction = (
+        "This deployment currently has no K pages. The orientation attempt is still "
+        "correct, but an empty/`known_empty` result means: fall back to the P3 corpus "
+        "tree when mounted, or to search when unmounted. Never invent the missing "
+        "summary."
+        if knowledge_page_count == 0
+        else "If K returns `known_empty`, fall back to P3 or search; never turn an "
+        "empty orientation layer into an invented summary."
+    )
+    return (
+        "## Default motion: orient, verify, audit\n\n"
+        f"1. **Orient on plane K.** {orientation_route} K is cheap, pre-paid "
+        "synthesis, not live-confirmed truth.\n"
+        "2. **Verify on the spine.** For anything load-bearing, query the fact layer "
+        "(relations or observations). A fact lookup re-checks live PostgreSQL state.\n"
+        "3. **Audit on evidence.** When the stakes or ambiguity demand it, hydrate "
+        "the fact to claims, source spans, documents, and finally the original.\n\n"
+        f"{empty_instruction}"
+    )
+
+
+def _grains() -> str:
+    """Teach the claim-to-fact-to-compiled terminology ladder."""
+    return (
+        "## Keep the grains separate\n\n"
+        "- A **claim** is immutable testimony: what one source asserted. It is "
+        "evidence grain and may be stale, superseded, or contradicted.\n"
+        "- A **relation** links two entities; an **observation** records a value or "
+        "statement about one entity. Together they are the **fact layer**: the "
+        "system's adjudicated, validity-filtered holdings. Questions of the form "
+        '"is this true now?" go here by default.\n'
+        "- A **compiled K page** is pre-paid synthesis. It is compiled grain and "
+        "must be read with its compile time, stale flag, and open-flag count.\n"
+        "- A **core belief** is a stricter configured K tier, not a new source of "
+        "truth.\n\n"
+        "Never blend evidence and facts into one unlabeled answer. If a task asks "
+        "both what someone said and what the system believes, return separate "
+        "evidence-grain and fact-grain parts."
+    )
+
+
+def _testimony(*, recipes: tuple[ConsumptionRecipe, ...]) -> str:
+    """Teach current testimony, historical opt-in, and withdrawn support."""
+    recipe_names = {recipe.name for recipe in recipes}
+    history_surface = (
+        "This deployment enables `claims_as_of`; use it only for assertion "
+        "history, never for current truth."
+        if "claims_as_of" in recipe_names
+        else "This deployment does not enable a `claims_as_of` recipe. Its current "
+        "query surfaces do not expose superseded testimony, so do not attempt an "
+        "undeclared history option."
+    )
+    return (
+        "## Testimony currency and shaky support\n\n"
+        "Claim search defaults to **current testimony**. Claims left behind by a "
+        "living document's newer version or by a newer extraction generation are "
+        "history, not current search results. `claims_as_of` means **what sources "
+        "asserted as of a past system time**; it never means what is true now. "
+        f"{history_surface}\n\n"
+        "A fact with `support: withdrawn` has lost all current-testimony support "
+        "because a toolchain re-read did not re-derive it. It still stands while "
+        "review is open, but it is shaky: report the caveat, inspect its transcript "
+        "and evidence, and do not make it load-bearing without verification."
+    )
+
+
+def _time_and_media() -> str:
+    """Keep the three media/time coordinates and derivation labels distinct."""
+    return (
+        "## Time and media\n\n"
+        'Do not collapse these into "the timestamp":\n\n'
+        "- a source locator such as `start_ms` says **where in a file** evidence "
+        "occurs;\n"
+        "- `valid_from` / `valid_until` say **when a fact held in the world**;\n"
+        "- `ingested_at` / `believed_at` say **when the system knew it**.\n\n"
+        "For media-derived evidence, read `evidence_mode`: `source_expression` is "
+        "rendered speech/text, `model_observation` is what a model reports seeing, "
+        "and `model_interpretation` is the model's interpretation. When tone or a "
+        "visual detail matters, follow the source locator to the raw interval or "
+        "region. The transcript is a map, not the territory."
+    )
+
+
+def _envelope() -> str:
+    """Teach response honesty fields and the distinct negative reactions."""
+    return (
+        "## Read the whole response envelope\n\n"
+        "Check `grain`, applied `valid_at`/`believed_at`, identity regime, per-store "
+        "freshness, truncation/continuation, and `dropped_by_hydration`. A result "
+        "inside a live contradiction group must include or point to its co-members; "
+        "report the competing sides instead of silently picking one.\n\n"
+        "Negative results require different moves:\n\n"
+        "- `unknown_entity`: widen resolution or search;\n"
+        "- `known_empty`: the entity exists but no matching result is known within "
+        "the stated freshness;\n"
+        "- `boundary`: re-plan using the named workaround.\n\n"
+        "Hard-forgotten material is intentionally indistinguishable from content "
+        "that never existed."
+    )
+
+
+def _mounts(*, mounts: PublishedMounts | None) -> str:
+    """Render exact mount paths or the unmounted parity rule."""
+    if mounts is None:
+        availability = (
+            "No mounts are available in this harness. Use API, CLI, or MCP for "
+            "orientation, readable artifacts, and query operations."
+        )
+    else:
+        availability = (
+            "The four read-only mounts are available:\n\n"
+            f"- P3 corpus tree: `{mounts.p3}`\n"
+            f"- E0 artifacts: `{mounts.artifacts}`\n"
+            f"- raw originals (off the navigation path; audited): `{mounts.raw}`\n"
+            f"- plane K checkout: `{mounts.knowledge}`"
+        )
+    return (
+        "## Filesystem first\n\n"
+        f"{availability}\n\n"
+        "When mounts exist, prefer them for navigation, reading, and grep. Reserve "
+        "API/CLI/MCP for operations with no filesystem equivalent: semantic search, "
+        "graph traversal, temporal as-of queries, hydration, transcripts, and "
+        "deltas. Start in P3 or K, not raw. Follow an explicit raw pointer only "
+        "when the original is needed, and use the deployment's audited raw-access "
+        "mechanism."
+    )
+
+
+def _recipes(*, recipes: tuple[ConsumptionRecipe, ...]) -> str:
+    """Render only this deployment's latest active recipe versions."""
+    if not recipes:
+        rows = "No recipes are enabled. Use the primitive API directly."
+    else:
+        rows = "\n".join(
+            f"- `{recipe.name}` — `{recipe.output_grain}` / "
+            f"`{recipe.answer_intent}`: {_one_line(value=recipe.description)}"
+            for recipe in recipes
+        )
+    return (
+        "## Enabled recipes and surfaces\n\n"
+        f"{rows}\n\n"
+        "Discover the current set with `remember query list`, `GET /recipes`, or MCP "
+        "tool listing. Run one with `remember query run <name> --arg key=value`, "
+        "`POST /recipe/<name>`, or the same-named MCP tool. Recipe grain and intent "
+        "are part of the contract; a recipe adds no capability beyond its primitive "
+        "chain."
+    )
+
+
+def _working_rules() -> str:
+    """End with a compact operational checklist for the consuming agent."""
+    return (
+        "## Before acting on a memory answer\n\n"
+        "1. Did I use facts, not claims, for a current-truth question?\n"
+        "2. Did I keep fact, evidence, and compiled grains labeled separately?\n"
+        "3. Did I inspect freshness, truncation, contradictions, and withdrawn "
+        "support?\n"
+        "4. Did I verify load-bearing K statements on the spine?\n"
+        "5. Did I hydrate to evidence or raw source when the stakes required it?"
+    )
+
+
+def _scope_lines(*, scopes: tuple[ConsumptionScope, ...]) -> str:
+    """Render special-purpose scope rows without inventing a default K page."""
+    if not scopes:
+        return "  - none registered"
+    return "\n".join(
+        f"  - `{scope.slug}` ({_one_line(value=scope.name)})"
+        + (f" at `{scope.git_path}`" if scope.git_path else "")
+        + (f": {_one_line(value=scope.description)}" if scope.description else "")
+        for scope in scopes
+    )
+
+
+def _literal(*, value: str) -> str:
+    """Render deployment-controlled prose as one explicit JSON string literal."""
+    literal = json.dumps(value, ensure_ascii=False).replace("`", "'")
+    return f"`{literal}`"
+
+
+def _one_line(*, value: str) -> str:
+    """Collapse deployment-controlled display text to one Markdown-safe line."""
+    return " ".join(value.split()).replace("`", "'")