rememberstack 0.1.0__py3-none-any.whl

rememberstack/core/extension_packs.py

@@ -0,0 +1,124 @@
+"""System-shipped extension packs (registries §4, D15): the Work pack.
+
+Extensions are not second-class: a pack type lives in the same entity space,
+graph, ER machinery, and relations as core types — the tier is a governance
+distinction (stability commitment, golden-set obligation), not a capability
+one. Every pack type anchors to a core parent (extend-never-fork); the
+installer refuses a pack whose anchors don't exist.
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+_CORE_ROOTS: Final = (
+    "Person",
+    "Organization",
+    "Place",
+    "Document",
+    "Event",
+    "Concept",
+    "Project",
+    "Product",
+)
+
+
+@dataclass(frozen=True)
+class PackEntityType:
+    """One extension entity type anchored to a core parent."""
+
+    type: str
+    parent_type: str
+    description: str
+    examples: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PackPredicate:
+    """One extension predicate with its domain/range signatures (D18)."""
+
+    predicate: str
+    description: str
+    signatures: tuple[tuple[str, str], ...]
+    synonyms: tuple[str, ...] = ()
+    is_change_prone: bool = False
+
+
+@dataclass(frozen=True)
+class ExtensionPack:
+    """A predefined bundle a deployment enables as one unit."""
+
+    pack_id: str
+    name: str
+    description: str
+    entity_types: tuple[PackEntityType, ...] = ()
+    predicates: tuple[PackPredicate, ...] = ()
+
+
+def _to_any(*subjects: str) -> tuple[tuple[str, str], ...]:
+    """Signatures pairing each subject with every core root ("→ any")."""
+    return tuple(
+        (subject, object_root) for subject in subjects for object_root in _CORE_ROOTS
+    )
+
+
+WORK_PACK: Final = ExtensionPack(
+    pack_id="work",
+    name="Work",
+    description=(
+        "Work-shaped concepts for assistant, agency, and project-management "
+        "deployments: tasks, decisions, and goals as first-class entities."
+    ),
+    entity_types=(
+        PackEntityType(
+            type="Task",
+            parent_type="Event",
+            description="an intended occurrence with a lifecycle",
+            examples=("migrate the billing tables", "draft the Q3 report"),
+        ),
+        PackEntityType(
+            type="Decision",
+            parent_type="Event",
+            description="a commitment made at a point in time",
+            examples=("adopt PostgreSQL", "freeze the API surface"),
+        ),
+        PackEntityType(
+            type="Goal",
+            parent_type="Concept",
+            description="a desired state — held, not occurring",
+            examples=("sub-second p99 latency", "SOC 2 compliance"),
+        ),
+    ),
+    predicates=(
+        PackPredicate(
+            predicate="blocks",
+            description="the subject task prevents progress on the object task",
+            signatures=(("Task", "Task"),),
+        ),
+        PackPredicate(
+            predicate="depends_on",
+            description="the subject task requires the object task first",
+            signatures=(("Task", "Task"),),
+        ),
+        PackPredicate(
+            predicate="concerns",
+            description="the subject task or decision is about the object",
+            signatures=_to_any("Task", "Decision"),
+        ),
+        PackPredicate(
+            predicate="decided_by",
+            description="who made the decision",
+            signatures=(("Decision", "Person"), ("Decision", "Organization")),
+        ),
+        PackPredicate(
+            predicate="assigned_to",
+            description="who is responsible for the task",
+            signatures=(("Task", "Person"), ("Task", "Organization")),
+            is_change_prone=True,
+        ),
+        PackPredicate(
+            predicate="pursues",
+            description="the project or organization works toward the goal",
+            signatures=(("Project", "Goal"), ("Organization", "Goal")),
+        ),
+    ),
+)

rememberstack/core/forget.py

@@ -0,0 +1,17 @@
+"""Pure canonical identity helpers for D74 hard-forget guards."""
+
+import hashlib
+import json
+from uuid import UUID
+
+
+def source_identity_hash(
+    *, deployment_id: UUID, source_kind: str, source_ref: str
+) -> str:
+    """Hash one unambiguous deployment-owned connector identity tuple."""
+    canonical = json.dumps(
+        [str(deployment_id), source_kind, source_ref],
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()

rememberstack/core/knowledge_authored.py

@@ -0,0 +1,276 @@
+"""Pure authored-frontmatter parsing and declaration-lint helpers."""
+
+import json
+from pathlib import PurePosixPath
+from typing import TypeAlias
+from uuid import UUID
+
+from pydantic import TypeAdapter
+from pydantic import ValidationError
+
+from rememberstack.model import CommunityRuleParams
+from rememberstack.model import DocSetRuleParams
+from rememberstack.model import EntityRuleParams
+from rememberstack.model import KnowledgeAuthoredDeclaration
+from rememberstack.model import KnowledgeCitation
+from rememberstack.model import KnowledgeEvidenceRole
+from rememberstack.model import KnowledgeRuleParams
+from rememberstack.model import PredicateBeatRuleParams
+
+_RULE_ADAPTER = TypeAdapter(KnowledgeRuleParams)
+_FrontmatterItem: TypeAlias = str | dict[str, object]
+
+
+class KnowledgeAuthoredDeclarationError(ValueError):
+    """An authored page carries malformed ``cites`` or ``watch`` declarations."""
+
+
+def parse_knowledge_authored_frontmatter(
+    *, markdown: str
+) -> KnowledgeAuthoredDeclaration:
+    """Parse the strict JSON-compatible YAML subset used by authored pages.
+
+    ``cites`` and ``watch`` accept an inline JSON list or an indented list whose
+    items are shorthands/JSON objects. Other frontmatter keys are left to their
+    owning surface and ignored here.
+    """
+    lines = _frontmatter_lines(markdown=markdown)
+    if lines is None:
+        return KnowledgeAuthoredDeclaration()
+    declared = _declared_lists(lines=lines)
+    citations = (
+        None
+        if declared["cites"] is None
+        else tuple(_citation(item=item) for item in declared["cites"] or ())
+    )
+    watch_rules: tuple[KnowledgeRuleParams, ...] | None = None
+    page_paths: tuple[str, ...] | None = None
+    if declared["watch"] is not None:
+        rules: list[KnowledgeRuleParams] = []
+        paths: list[str] = []
+        for item in declared["watch"] or ():
+            rule, page_path = _watch(item=item)
+            if rule is not None:
+                rules.append(rule)
+            if page_path is not None:
+                paths.append(page_path)
+        watch_rules = tuple(rules)
+        page_paths = tuple(paths)
+    return KnowledgeAuthoredDeclaration(
+        citations=citations, watch_rules=watch_rules, watched_page_paths=page_paths
+    )
+
+
+def authored_declaration_is_empty(
+    *, citation_count: int, watch_rule_count: int, page_watch_count: int
+) -> bool:
+    """Return whether an authored page has no ground and can never be alerted."""
+    if min(citation_count, watch_rule_count, page_watch_count) < 0:
+        raise ValueError("declaration counts must be non-negative")
+    return citation_count + watch_rule_count + page_watch_count == 0
+
+
+def knowledge_citation_reference(*, citation: KnowledgeCitation) -> str:
+    """Render one citation as a stable delta identifier."""
+    if citation.claim_lineage_id is not None:
+        target = (
+            f"claim:{citation.claim_lineage_id}:{citation.claim_chunk_content_hash}"
+        )
+    elif citation.relation_id is not None:
+        target = f"relation:{citation.relation_id}"
+    else:
+        target = f"doc:{citation.doc_id}"
+    return f"{citation.role.value}:{target}"
+
+
+def _frontmatter_lines(*, markdown: str) -> tuple[str, ...] | None:
+    """Return frontmatter lines, distinguishing no header from an unclosed one."""
+    lines = markdown.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    try:
+        end = next(
+            index
+            for index, line in enumerate(lines[1:], start=1)
+            if line.strip() == "---"
+        )
+    except StopIteration as error:
+        raise KnowledgeAuthoredDeclarationError(
+            "authored frontmatter is missing its closing delimiter"
+        ) from error
+    return tuple(lines[1:end])
+
+
+def _declared_lists(
+    *, lines: tuple[str, ...]
+) -> dict[str, tuple[_FrontmatterItem, ...] | None]:
+    """Extract the two owned list keys without parsing unrelated frontmatter."""
+    result: dict[str, tuple[_FrontmatterItem, ...] | None] = {
+        "cites": None,
+        "watch": None,
+    }
+    seen: set[str] = set()
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if not line or line[0].isspace() or ":" not in line:
+            index += 1
+            continue
+        key, inline = line.split(":", maxsplit=1)
+        if key not in result:
+            index += 1
+            continue
+        if key in seen:
+            raise KnowledgeAuthoredDeclarationError(
+                f"authored frontmatter repeats {key!r}"
+            )
+        seen.add(key)
+        inline = inline.strip()
+        if inline:
+            result[key] = _inline_list(key=key, value=inline)
+            index += 1
+            continue
+        values: list[_FrontmatterItem] = []
+        index += 1
+        while index < len(lines):
+            nested = lines[index]
+            if nested and not nested[0].isspace():
+                break
+            stripped = nested.strip()
+            index += 1
+            if not stripped or stripped.startswith("#"):
+                continue
+            if not stripped.startswith("- "):
+                raise KnowledgeAuthoredDeclarationError(
+                    f"{key!r} must be a flat list of shorthands or JSON objects"
+                )
+            values.append(_list_item(key=key, value=stripped[2:].strip()))
+        result[key] = tuple(values)
+    return result
+
+
+def _inline_list(*, key: str, value: str) -> tuple[_FrontmatterItem, ...]:
+    """Parse one inline JSON list for a declaration key."""
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as error:
+        raise KnowledgeAuthoredDeclarationError(
+            f"inline {key!r} must be valid JSON"
+        ) from error
+    if not isinstance(parsed, list):
+        raise KnowledgeAuthoredDeclarationError(f"{key!r} must be a list")
+    return tuple(_require_item(key=key, value=item) for item in parsed)
+
+
+def _list_item(*, key: str, value: str) -> _FrontmatterItem:
+    """Parse JSON-looking list items and retain plain shorthands verbatim."""
+    if not value:
+        raise KnowledgeAuthoredDeclarationError(f"{key!r} contains an empty item")
+    if value[0] not in ('"', "{"):
+        return value
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as error:
+        raise KnowledgeAuthoredDeclarationError(
+            f"{key!r} contains invalid JSON"
+        ) from error
+    return _require_item(key=key, value=parsed)
+
+
+def _require_item(*, key: str, value: object) -> _FrontmatterItem:
+    """Reject declaration values outside the supported scalar/object shapes."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict) and all(isinstance(name, str) for name in value):
+        return value
+    raise KnowledgeAuthoredDeclarationError(
+        f"{key!r} items must be strings or JSON objects"
+    )
+
+
+def _citation(*, item: _FrontmatterItem) -> KnowledgeCitation:
+    """Validate one citation object or compact evidence-reference string."""
+    if isinstance(item, dict):
+        try:
+            return KnowledgeCitation.model_validate(item)
+        except ValidationError as error:
+            raise KnowledgeAuthoredDeclarationError(
+                "invalid authored citation object"
+            ) from error
+    parts = item.split(":")
+    role = KnowledgeEvidenceRole.CITES
+    if parts[0] in {value.value for value in KnowledgeEvidenceRole}:
+        role = KnowledgeEvidenceRole(parts.pop(0))
+    if len(parts) == 2 and parts[0] in {"relation", "doc"}:
+        try:
+            target_id = UUID(parts[1])
+        except ValueError as error:
+            raise KnowledgeAuthoredDeclarationError(
+                "citation shorthand contains an invalid UUID"
+            ) from error
+        if parts[0] == "relation":
+            return KnowledgeCitation(role=role, relation_id=target_id)
+        return KnowledgeCitation(role=role, doc_id=target_id)
+    if len(parts) == 3 and parts[0] == "claim" and parts[2]:
+        try:
+            lineage_id = UUID(parts[1])
+        except ValueError as error:
+            raise KnowledgeAuthoredDeclarationError(
+                "claim citation contains an invalid lineage UUID"
+            ) from error
+        return KnowledgeCitation(
+            role=role, claim_lineage_id=lineage_id, claim_chunk_content_hash=parts[2]
+        )
+    raise KnowledgeAuthoredDeclarationError(
+        "citation shorthand must target claim, relation, or doc evidence"
+    )
+
+
+def _watch(*, item: _FrontmatterItem) -> tuple[KnowledgeRuleParams | None, str | None]:
+    """Validate one rich rule object or compact evidence/page watch."""
+    if isinstance(item, dict):
+        try:
+            return _RULE_ADAPTER.validate_python(item), None
+        except ValidationError as error:
+            raise KnowledgeAuthoredDeclarationError(
+                "invalid authored watch-rule object"
+            ) from error
+    prefix, separator, raw_value = item.partition(":")
+    if not separator or not raw_value:
+        raise KnowledgeAuthoredDeclarationError(
+            "watch shorthand must contain a kind and value"
+        )
+    try:
+        if prefix == "entity":
+            return EntityRuleParams(entity_id=UUID(raw_value)), None
+        if prefix == "community":
+            return CommunityRuleParams(community_id=UUID(raw_value)), None
+    except ValueError as error:
+        raise KnowledgeAuthoredDeclarationError(
+            "watch shorthand contains an invalid UUID"
+        ) from error
+    if prefix == "predicate":
+        return PredicateBeatRuleParams(predicate=raw_value), None
+    if prefix == "doc_source":
+        return DocSetRuleParams(source_kind=raw_value), None
+    if prefix == "page":
+        return None, _page_watch_path(value=raw_value)
+    raise KnowledgeAuthoredDeclarationError(f"unsupported watch shorthand {prefix!r}")
+
+
+def _page_watch_path(*, value: str) -> str:
+    """Normalize the design's extension-optional ``page:<path>`` shorthand."""
+    path = PurePosixPath(value)
+    if path.suffix == "":
+        path = path.with_suffix(".md")
+    normalized = str(path)
+    if (
+        path.is_absolute()
+        or ".." in path.parts
+        or normalized != (f"{value}.md" if PurePosixPath(value).suffix == "" else value)
+        or path.suffix != ".md"
+    ):
+        raise KnowledgeAuthoredDeclarationError(
+            "page watch must be a normalized relative Markdown path"
+        )
+    return normalized

rememberstack/core/knowledge_compile.py

@@ -0,0 +1,215 @@
+"""Pure scheduling and output-validation rules for Plane-K cycles (D45)."""
+
+from collections.abc import Collection
+from collections.abc import Sequence
+import posixpath
+from urllib.parse import unquote
+from urllib.parse import urlsplit
+from uuid import UUID
+
+from markdown_it import MarkdownIt
+
+from rememberstack.core.knowledge_hashing import knowledge_content_hash
+from rememberstack.model import KnowledgeCitation
+from rememberstack.model import KnowledgeCompileArtifact
+from rememberstack.model import KnowledgeEvidenceTarget
+from rememberstack.model import KnowledgePageCompileOutput
+
+
+class KnowledgeCompileGraphError(ValueError):
+    """The persisted compiled-page parent graph cannot be scheduled safely."""
+
+
+class KnowledgePageValidationError(ValueError):
+    """A page compiler returned output that the driver must not publish."""
+
+
+def knowledge_compile_order(
+    *, artifacts: Sequence[KnowledgeCompileArtifact]
+) -> tuple[KnowledgeCompileArtifact, ...]:
+    """Order the potential stale/model propagation closure deterministically.
+
+    Active ancestors are traversed because a changed child summary can stale them
+    inside this cycle. Likewise, a stale shared model can stale every page in its
+    scope. The driver skips those potential dependants when the freshly compiled
+    summary is unchanged.
+    """
+    by_id = {artifact.artifact_id: artifact for artifact in artifacts}
+    if len(by_id) != len(artifacts):
+        raise KnowledgeCompileGraphError(
+            "compile graph contains duplicate artifact IDs"
+        )
+    deployments = {artifact.deployment_id for artifact in artifacts}
+    if len(deployments) > 1:
+        raise KnowledgeCompileGraphError("compile graph crosses deployments")
+    model_scopes = [
+        artifact.scope_id
+        for artifact in artifacts
+        if artifact.artifact_kind == "model_page"
+    ]
+    if len(model_scopes) != len(set(model_scopes)):
+        raise KnowledgeCompileGraphError(
+            "compile graph has multiple model pages for one scope"
+        )
+
+    depths: dict[UUID, int] = {}
+    visiting: set[UUID] = set()
+
+    def depth(*, artifact_id: UUID) -> int:
+        """Resolve one node's root distance while detecting parent cycles."""
+        known = depths.get(artifact_id)
+        if known is not None:
+            return known
+        if artifact_id in visiting:
+            raise KnowledgeCompileGraphError("compile graph contains a parent cycle")
+        visiting.add(artifact_id)
+        parent_id = by_id[artifact_id].parent_artifact_id
+        value = (
+            0
+            if parent_id is None or parent_id not in by_id
+            else depth(artifact_id=parent_id) + 1
+        )
+        visiting.remove(artifact_id)
+        depths[artifact_id] = value
+        return value
+
+    for artifact_id in by_id:
+        depth(artifact_id=artifact_id)
+
+    selected = {artifact.artifact_id for artifact in artifacts if artifact.stale}
+    stale_model_scopes = {
+        artifact.scope_id
+        for artifact in artifacts
+        if artifact.stale and artifact.artifact_kind == "model_page"
+    }
+    selected.update(
+        artifact.artifact_id
+        for artifact in artifacts
+        if artifact.scope_id in stale_model_scopes
+    )
+    frontier = list(selected)
+    while frontier:
+        artifact_id = frontier.pop()
+        parent_id = by_id[artifact_id].parent_artifact_id
+        if parent_id is not None and parent_id in by_id and parent_id not in selected:
+            selected.add(parent_id)
+            frontier.append(parent_id)
+
+    scheduled = (artifact for artifact in artifacts if artifact.artifact_id in selected)
+    return tuple(
+        sorted(
+            scheduled,
+            key=lambda artifact: (
+                (
+                    0
+                    if artifact.artifact_kind == "model_page" and artifact.stale
+                    else 2
+                    if artifact.parent_artifact_id is None
+                    and artifact.git_path == "_index.md"
+                    else 1
+                ),
+                -depths[artifact.artifact_id],
+                artifact.git_path,
+                str(artifact.artifact_id),
+            ),
+        )
+    )
+
+
+def validate_knowledge_page_output(
+    *,
+    artifact: KnowledgeCompileArtifact,
+    output: KnowledgePageCompileOutput,
+    known_git_paths: Collection[str],
+    exclusions: Collection[KnowledgeEvidenceTarget],
+) -> None:
+    """Enforce artifact binding, content hash, exclusions, and internal links."""
+    compilation = output.compilation
+    if compilation.deployment_id != artifact.deployment_id:
+        raise KnowledgePageValidationError("compilation crosses deployments")
+    if compilation.artifact_id != artifact.artifact_id:
+        raise KnowledgePageValidationError("compilation targets a different artifact")
+    if compilation.content_hash != knowledge_content_hash(markdown=output.markdown):
+        raise KnowledgePageValidationError(
+            "compiled Markdown content hash does not match"
+        )
+
+    excluded = {_target_key(target=target) for target in exclusions}
+    used = {
+        _citation_target_key(citation=citation) for citation in compilation.citations
+    }
+    used.update(
+        target for target in excluded if f"{target[0]}:{target[1]}" in output.markdown
+    )
+    if overlap := excluded.intersection(used):
+        rendered = ", ".join(f"{kind}:{value}" for kind, value in sorted(overlap))
+        raise KnowledgePageValidationError(
+            f"compiled page uses excluded evidence: {rendered}"
+        )
+
+    unresolved = _unresolved_internal_links(
+        markdown=output.markdown,
+        source_path=artifact.git_path,
+        known_git_paths=known_git_paths,
+    )
+    if unresolved:
+        raise KnowledgePageValidationError(
+            f"compiled page has unresolved internal links: {', '.join(unresolved)}"
+        )
+
+
+def _target_key(*, target: KnowledgeEvidenceTarget) -> tuple[str, str]:
+    """Return the role-independent identity of one exclusion target."""
+    if target.claim_lineage_id is not None:
+        return (
+            "claim_coordinate",
+            f"{target.claim_lineage_id}:{target.claim_chunk_content_hash}",
+        )
+    if target.relation_id is not None:
+        return "relation", str(target.relation_id)
+    if target.doc_id is not None:
+        return "doc", str(target.doc_id)
+    raise AssertionError("validated evidence target has no ID")
+
+
+def _citation_target_key(*, citation: KnowledgeCitation) -> tuple[str, str]:
+    """Return the role-independent identity of one citation target."""
+    if citation.claim_lineage_id is not None:
+        return (
+            "claim_coordinate",
+            f"{citation.claim_lineage_id}:{citation.claim_chunk_content_hash}",
+        )
+    if citation.relation_id is not None:
+        return "relation", str(citation.relation_id)
+    if citation.doc_id is not None:
+        return "doc", str(citation.doc_id)
+    raise AssertionError("validated citation has no ID")
+
+
+def _unresolved_internal_links(
+    *, markdown: str, source_path: str, known_git_paths: Collection[str]
+) -> tuple[str, ...]:
+    """Return relative Markdown links that do not resolve to registered artifacts."""
+    known = set(known_git_paths)
+    unresolved: set[str] = set()
+    for block in MarkdownIt("commonmark").parse(markdown):
+        tokens = (block, *(block.children or ()))
+        for token in tokens:
+            if token.type != "link_open":
+                continue
+            href = token.attrGet("href")
+            if not isinstance(href, str):
+                continue
+            parsed = urlsplit(href)
+            if parsed.scheme or parsed.netloc or not parsed.path:
+                continue
+            raw_path = unquote(parsed.path)
+            if raw_path.startswith("/"):
+                resolved = posixpath.normpath(raw_path.lstrip("/"))
+            else:
+                resolved = posixpath.normpath(
+                    posixpath.join(posixpath.dirname(source_path), raw_path)
+                )
+            if resolved == ".." or resolved.startswith("../") or resolved not in known:
+                unresolved.add(href)
+    return tuple(sorted(unresolved))