create-egregore 0.21.6 → 0.22.0

package/runtime/pi/egregore_runtime/knowledge.py

@@ -8,18 +8,19 @@ knowledge artifact.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import UTC, datetime
 import json
 import os
 from pathlib import Path
 import re
-from typing import Callable, Iterable
+from typing import Any, Callable, Iterable, Iterator, Mapping
 
 from .artifacts import (
     ARTIFACT_SCHEMA_VERSION,
     CanonicalDocument,
     artifact_id_from_path,
+    canonical_artifact_id,
     content_digest,
     normalize_markdown_body,
     split_frontmatter,
@@ -32,8 +33,9 @@ from .contracts import (
     SourceProvenance,
     WritebackEvent,
 )
+from . import held
 from .errors import AuthorizationDenied
-from .policy import scope_allows_path
+from .policy import allows, check, action_for
 from .runtime import EgregoreRuntime
 
 
@@ -41,6 +43,11 @@ KNOWLEDGE_SCHEMA_VERSION = "egregore-knowledge/v1"
 PRIVATE_NOTE_SCHEMA_VERSION = "egregore-private-note/v1"
 KNOWLEDGE_TYPES = frozenset({"decision", "finding", "pattern"})
 NOTE_TYPES = frozenset({"thought", "session", "retrospective", "journal"})
+# Knowledge has two linked layers: a pattern states a general motif, and an
+# evidence record (a finding with subtype ``evidence``) keeps the specific,
+# dated, sourced case and points at its pattern with ``instance-of``.
+RELATIONSHIP_VOCABULARY = ("instance-of", "responds-to", "applies", "supersedes", "relates-to")
+SITUATION_KEYS = ("domains", "paths", "activities")
 
 
 class KnowledgeCaptureError(ValueError):
@@ -56,6 +63,165 @@ def _iso(value: datetime) -> str:
     return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
 
 
+def relationship_warnings(relationships: Iterable[ArtifactRelationship]) -> tuple[str, ...]:
+    """Unknown relations are kept as written and reported, never rejected."""
+
+    known = ", ".join(RELATIONSHIP_VOCABULARY)
+    return tuple(
+        f"relationship '{row.relation}' is not in the vocabulary ({known}); kept as written"
+        for row in relationships
+        if row.relation.strip().casefold() not in RELATIONSHIP_VOCABULARY
+    )
+
+
+def normalize_situations(value: Mapping[str, Iterable[str]] | None) -> dict[str, list[str]]:
+    """Return ``{domains, paths, activities}`` or ``{}`` when nothing is given."""
+
+    if not value:
+        return {}
+    unknown = sorted(set(value) - set(SITUATION_KEYS))
+    if unknown:
+        raise KnowledgeCaptureError(f"unknown situation keys: {', '.join(unknown)}")
+    result = {
+        key: list(dict.fromkeys(" ".join(str(item).split()) for item in value.get(key, ()) if str(item).strip()))
+        for key in SITUATION_KEYS
+    }
+    for glob in result["paths"]:
+        if glob.startswith("/") or ".." in glob.split("/"):
+            raise KnowledgeCaptureError("situation paths are repository-relative globs")
+    return result if any(result.values()) else {}
+
+
+def _relations(fields: Mapping[str, Any]) -> Iterator[tuple[str, str]]:
+    value = fields.get("relationships")
+    for item in value if isinstance(value, list) else ():
+        if isinstance(item, Mapping):
+            relation = str(item.get("relation") or item.get("type") or "")
+            target = str(item.get("target_id") or item.get("target") or item.get("id") or "")
+            if relation and target:
+                yield relation.strip().casefold(), target.strip()
+
+
+def _relative(value: str) -> str:
+    return value.strip().replace("\\", "/").removeprefix("memory/")
+
+
+# Situated patterns: a deterministic match of a pattern's situations against
+# the paths someone is changing and the words they use. No model calls.
+SITUATED_HINT_PREFIX = "Patterns that may apply: "
+_STOPWORDS = frozenset(
+    "about after again also and any are been before being but can could did does doing for from had has have"
+    " how into its just more most not off once only other our out over own same should some such than that the"
+    " their them then there these they this those through too under until very was were what when where which"
+    " while who why will with would you your".split()
+)
+
+
+def _stem(token: str) -> str:
+    if token.endswith("sses"):
+        return token[:-2]
+    if len(token) > 5 and token.endswith("ing"):
+        return token[:-3]
+    if len(token) > 3 and token.endswith("s") and not token.endswith("ss"):
+        return token[:-1]
+    return token
+
+
+def situation_tokens(text: str) -> frozenset[str]:
+    """Casefolded word stems of three or more letters, without stopwords."""
+
+    words = re.findall(r"[^\W_]+", str(text).casefold(), re.UNICODE)
+    return frozenset(_stem(word) for word in words if len(word) >= 3 and word not in _STOPWORDS)
+
+
+def situation_glob_matches(glob: str, path: str) -> bool:
+    """Repository-relative glob: ``**`` crosses directories, ``*`` and ``?`` do not.
+
+    Only ``*``, ``**`` and ``?`` are wildcards; ``[`` is a literal character.
+    A glob without wildcards names a file or a directory prefix.
+    """
+
+    glob = glob.strip().strip("`").removeprefix("./")
+    path = path.strip().replace("\\", "/").removeprefix("./")
+    if not glob or not path:
+        return False
+    if not any(char in glob for char in "*?"):
+        prefix = glob.rstrip("/")
+        return path == prefix or path.startswith(prefix + "/")
+    parts, index = [], 0
+    while index < len(glob):
+        if glob.startswith("**/", index):
+            parts.append("(?:.*/)?")
+            index += 3
+        elif glob.startswith("**", index):
+            parts.append(".*")
+            index += 2
+        else:
+            char = glob[index]
+            parts.append("[^/]*" if char == "*" else "[^/]" if char == "?" else re.escape(char))
+            index += 1
+    return re.fullmatch("".join(parts), path) is not None
+
+
+def _section(body: str, heading: str) -> str:
+    """Text under the first ``## <heading>…`` up to the next level-2 heading."""
+
+    match = re.search(rf"^##\s+{re.escape(heading)}[^\n]*\n(.*?)(?=^##\s|\Z)", body, re.I | re.M | re.S)
+    return match.group(1).strip() if match else ""
+
+
+def motif_sentence(body: str, limit: int = 240) -> str:
+    """The first sentence of the Motif section, or of the first paragraph."""
+
+    text = _section(body, "Motif")
+    if not text:
+        paragraphs = [part for part in re.split(r"\n\s*\n", body) if part.strip() and not part.lstrip().startswith("#")]
+        text = paragraphs[0] if paragraphs else ""
+    text = " ".join(text.replace("*", "").split())
+    sentence = re.split(r"(?<=[.!?])\s+", text, maxsplit=1)[0]
+    return sentence if len(sentence) <= limit else sentence[: limit - 1].rstrip() + "…"
+
+
+def _body_situations(body: str) -> dict[str, list[str]]:
+    """Read the template's ``Situations (for discovery)`` section for patterns
+    written before situations were structured frontmatter."""
+
+    lines: list[str] = []
+    for line in _section(body, "Situations").splitlines():
+        if re.match(r"^\s*[-*]\s", line) or not lines:
+            lines.append(line)
+        else:
+            lines[-1] += " " + line.strip()
+    result: dict[str, list[str]] = {}
+    for line in lines:
+        match = re.match(r"^\s*[-*]\s*(domains|paths|activities)\s*:\s*(.+)$", line, re.I)
+        if not match:
+            continue
+        key, value = match.group(1).casefold(), match.group(2)
+        items = re.findall(r"`([^`]+)`", value) if key == "paths" else re.split(r"[;,]", value)
+        result[key] = [item.strip() for item in items if item.strip() and not item.strip().startswith("-")]
+    return result
+
+
+def _instances_any(fields: Mapping[str, Any], keys: set[str]) -> bool:
+    return any(
+        relation == "instance-of" and (target in keys or _relative(target) in keys)
+        for relation, target in _relations(fields)
+    )
+
+
+def situated_hint_line(title: str, canonical_path: str, limit: int = 200) -> str:
+    """One offer line within ``limit`` characters, or "" when the path alone is too long."""
+
+    room = limit - len(SITUATED_HINT_PREFIX) - len(canonical_path) - 3
+    title = " ".join(str(title).split())
+    if room < 8:
+        return ""
+    if len(title) > room:
+        title = title[: room - 1].rstrip() + "…"
+    return f"{SITUATED_HINT_PREFIX}{title} ({canonical_path})"
+
+
 def _authorized(runtime: EgregoreRuntime, actor: ActorContext, permission: Permission, resource: str) -> None:
     decision = runtime.authorize(actor, permission, (resource,))
     if not decision.allowed:
@@ -105,10 +271,17 @@ class CanonicalKnowledgeService:
         supersedes: Iterable[str] = (),
         source_provenance: Iterable[SourceProvenance] = (),
         policy_hints: dict[str, object] | None = None,
+        situations: Mapping[str, Iterable[str]] | None = None,
     ) -> WritebackEvent:
         kind = artifact_type.strip().casefold()
         if kind not in KNOWLEDGE_TYPES:
             raise KnowledgeCaptureError("knowledge type must be decision, finding, or pattern")
+        situated = normalize_situations(situations)
+        if situated and kind != "pattern":
+            raise KnowledgeCaptureError("situations describe patterns only; use --type pattern")
+        if subtype and subtype.strip().casefold() == "evidence" and kind != "finding":
+            raise KnowledgeCaptureError("evidence records are findings; use --type finding --subtype evidence")
+        relationships = tuple(relationships)
         clean_title = " ".join(title.split()).strip()
         if not clean_title:
             raise KnowledgeCaptureError("knowledge title is required")
@@ -126,7 +299,7 @@ class CanonicalKnowledgeService:
             raise AuthorizationDenied(
                 "; ".join(decision.reasons) or "knowledge write denied"
             )
-        if not scope_allows_path(f"memory/{relative}", decision.scopes):
+        if not allows(decision, f"memory/{relative}", action_for(decision.permission), root=self.runtime.canonical_root):
             raise AuthorizationDenied(
                 "knowledge path is outside the actor's authorized scope"
             )
@@ -166,7 +339,10 @@ class CanonicalKnowledgeService:
         }
         if subtype:
             legacy["subtype"] = subtype.strip()
-        return self.runtime.write_document(
+        if situated:
+            legacy["situations"] = situated
+        warnings = relationship_warnings(relationships) + self._instance_warnings(actor, relationships)
+        receipt = self.runtime.write_document(
             actor,
             CanonicalDocument(
                 artifact=artifact,
@@ -175,6 +351,156 @@ class CanonicalKnowledgeService:
                 legacy_fields=legacy,
             ),
         )
+        return replace(receipt, warnings=tuple(receipt.warnings) + warnings) if warnings else receipt
+
+    def _readable(self, actor: ActorContext, under: str = "") -> Iterator[tuple[str, dict[str, Any], str]]:
+        """Yield ``(memory/path, frontmatter, body)`` for knowledge the actor may read."""
+
+        decision = self.runtime.authorize(actor, Permission.READ)
+        if not decision.allowed:
+            raise AuthorizationDenied("; ".join(decision.reasons) or "knowledge read denied")
+        base = self.memory_root / "knowledge" / under if under else self.memory_root / "knowledge"
+        for path in sorted(base.rglob("*.md")) if base.is_dir() else ():
+            relative = path.relative_to(self.memory_root).as_posix()
+            canonical = f"memory/{relative}"
+            verdict = check(decision, canonical, "read", root=self.memory_root)
+            if not verdict.allowed:
+                continue
+            if not path.is_file():
+                continue
+            try:
+                text = verdict.resolved.read_text(encoding="utf-8")
+                fields, body = split_frontmatter(text)
+                artifact_id = canonical_artifact_id(text, canonical)
+            except (OSError, ValueError):
+                continue
+            # A grant limited to named artifacts reads only those artifacts.
+            if not self.runtime.authorize(actor, Permission.READ, (artifact_id,)).allowed:
+                continue
+            if fields:
+                fields["id"] = artifact_id
+                if not fields.get("type") and relative.startswith("knowledge/patterns/"):
+                    fields["type"] = "pattern"  # legacy patterns predate the typed envelope
+                yield canonical, fields, body
+
+    @staticmethod
+    def _patterns(rows: Iterable[tuple[str, dict[str, Any], str]]) -> dict[str, tuple[str, dict[str, Any]]]:
+        """Map each pattern's stable id and relative path to its record."""
+
+        index: dict[str, tuple[str, dict[str, Any]]] = {}
+        for canonical, fields, _ in rows:
+            if str(fields.get("type") or "").casefold() == "pattern":
+                index[str(fields["id"])] = index[_relative(canonical)] = (canonical, fields)
+        return index
+
+    def _instance_warnings(
+        self, actor: ActorContext, relationships: Iterable[ArtifactRelationship]
+    ) -> tuple[str, ...]:
+        targets = [row.target_id for row in relationships if row.relation.strip().casefold() == "instance-of"]
+        if not targets:
+            return ()
+        try:
+            known = self._patterns(self._readable(actor))
+        except AuthorizationDenied:
+            return ()
+        return tuple(
+            f"instance-of target '{target}' is not a readable pattern; check the pattern id"
+            for target in targets
+            if target not in known and _relative(target) not in known
+        )
+
+    def instances(self, actor: ActorContext, pattern: str) -> dict[str, object]:
+        """Reverse lookup: records whose ``instance-of`` points at ``pattern``.
+
+        A typed scan of canonical frontmatter under the actor's read scope; no
+        ranking, no graph. ``pattern`` is a stable id or a canonical path.
+        """
+
+        rows = list(self._readable(actor))
+        patterns = self._patterns(rows)
+        found = patterns.get(pattern.strip()) or patterns.get(_relative(pattern))
+        if found is None:
+            raise KnowledgeCaptureError(f"no readable pattern matches {pattern.strip()}")
+        canonical, fields = found
+        keys = {str(fields["id"]), _relative(canonical)}
+
+        def summary(path: str, values: Mapping[str, Any]) -> dict[str, object]:
+            return {
+                "id": str(values["id"]),
+                "title": str(values.get("title") or Path(path).stem),
+                "type": str(values.get("type") or ""),
+                "subtype": str(values.get("subtype") or "") or None,
+                "canonical_path": path,
+                "created_at": str(values.get("created_at") or values.get("date") or ""),
+            }
+
+        matches = [
+            summary(path, values)
+            for path, values, _ in rows
+            if _instances_any(values, keys)
+        ]
+        matches.sort(key=lambda row: (str(row["created_at"]), str(row["canonical_path"])), reverse=True)
+        return {"pattern": summary(canonical, fields), "count": len(matches), "instances": matches}
+
+    def situated(
+        self,
+        actor: ActorContext,
+        *,
+        paths: Iterable[str] = (),
+        text: str = "",
+        limit: int = 3,
+        count_instances: bool = True,
+    ) -> dict[str, object]:
+        """Patterns whose situations are live for these paths and this text.
+
+        Path globs match the given repository paths (3 points per glob);
+        domains, activities and topics match by shared word stems (1 point
+        per stem). A pattern needs a path match, or two shared stems from at
+        least two of its phrases where one phrase matches strongly (all of its
+        stems, or at least two). One compound topic alone never fires, and
+        common verbs scattered across phrases ("add", "design") do not either.
+        Ties order by title, then path. Deterministic; no model calls.
+        """
+
+        changed = list(dict.fromkeys(str(path).strip() for path in paths if str(path).strip()))
+        words = situation_tokens(text)
+        hits: list[dict[str, Any]] = []
+        for canonical, fields, body in self._readable(actor, "patterns"):
+            if str(fields.get("type") or "").casefold() != "pattern":
+                continue
+            given = fields.get("situations")
+            situations = given if isinstance(given, Mapping) and given else _body_situations(body)
+
+            def listed(key: str, source: Mapping[str, Any] = situations) -> list[str]:
+                value = source.get(key)
+                return [str(item) for item in value] if isinstance(value, list) else []
+
+            globs = sorted({glob for glob in listed("paths") for path in changed if situation_glob_matches(glob, path)})
+            stems = [situation_tokens(phrase) for phrase in
+                     (*listed("domains"), *listed("activities"), *listed("topics", fields))]
+            phrases = [phrase & words for phrase in stems]
+            shared = sorted(set().union(*phrases))
+            strong = any(len(hit) >= 2 or (hit and hit == full) for hit, full in zip(phrases, stems))
+            if not globs and (not strong or len(shared) < 2 or sum(1 for phrase in phrases if phrase) < 2):
+                continue
+            hits.append({
+                "id": str(fields["id"]),
+                "title": str(fields.get("title") or Path(canonical).stem),
+                "canonical_path": canonical,
+                "motif": motif_sentence(body),
+                "score": 3 * len(globs) + len(shared),
+                "matched": {"paths": globs, "words": shared},
+            })
+        hits.sort(key=lambda hit: (-hit["score"], hit["title"].casefold(), hit["canonical_path"]))
+        # Packaged here, so the prompt hook's offer line and the CLI hand out the same redacted hits.
+        selected = held.kept(self.runtime.authorize(actor, Permission.READ), hits[: max(0, limit)],
+                             root=self.memory_root, path="canonical_path")
+        if count_instances and selected:
+            rows = list(self._readable(actor))
+            for hit in selected:
+                keys = {hit["id"], _relative(hit["canonical_path"])}
+                hit["instances"] = sum(1 for _, values, _ in rows if _instances_any(values, keys))
+        return {"count": len(selected), "total": len(hits), "patterns": selected}
 
 
 @dataclass(frozen=True, slots=True)

package/runtime/pi/egregore_runtime/knowledge_cli.py

@@ -9,9 +9,11 @@ from pathlib import Path
 import sys
 from uuid import uuid4
 
+from . import held
 from .contracts import ArtifactRelationship
 from .errors import AuthorizationDenied
 from .knowledge import (
+    RELATIONSHIP_VOCABULARY,
     CanonicalKnowledgeService,
     KnowledgeCaptureError,
     PersonalNoteService,
@@ -36,6 +38,10 @@ def _context(*, push_remote: bool):
     return actor, knowledge, notes
 
 
+def _emit(knowledge, actor, value, **options) -> int:
+    return held.emit_for(knowledge.runtime, actor, value, **options)
+
+
 def _input(path: str) -> str:
     return read_and_consume(path, _root()).decode("utf-8")
 
@@ -76,39 +82,58 @@ def _create(args: argparse.Namespace) -> int:
         subtype=args.subtype,
         relationships=_relationships(args.relationship),
         supersedes=args.supersedes,
+        situations={
+            "domains": args.situation_domain,
+            "paths": args.situation_path,
+            "activities": args.situation_activity,
+        },
     )
-    print(json.dumps(_receipt(receipt), ensure_ascii=False))
-    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+    return _emit(knowledge, actor, _receipt(receipt)) or (0 if receipt.status.value in {"accepted", "partial"} else 1)
+
+
+def _instances(args: argparse.Namespace) -> int:
+    actor, knowledge, _ = _context(push_remote=False)
+    return _emit(knowledge, actor, knowledge.instances(actor, args.pattern))
+
+
+def _situated(args: argparse.Namespace) -> int:
+    if not args.paths and not (args.text or "").strip():
+        raise KnowledgeCaptureError("give --paths, --text, or both")
+    actor, knowledge, _ = _context(push_remote=False)
+    found = knowledge.situated(actor, paths=args.paths, text=args.text or "", limit=args.n)
+    return _emit(knowledge, actor, found)
+
+
+def _positive(value: str) -> int:
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
 
 
 def _note_create(args: argparse.Namespace) -> int:
-    actor, _, notes = _context(push_remote=False)
+    actor, knowledge, notes = _context(push_remote=False)
     note = notes.create(
         actor,
         title=args.title,
         body=_input(args.input),
         note_type=args.type,
     )
-    print(json.dumps(note.to_dict(), ensure_ascii=False))
-    return 0
+    return _emit(knowledge, actor, note.to_dict())
 
 
 def _note_list(args: argparse.Namespace) -> int:
-    actor, _, notes = _context(push_remote=False)
-    rows = notes.list(actor)
-    print(json.dumps({"notes": [row.to_dict() for row in rows]}, ensure_ascii=False))
-    return 0
+    actor, knowledge, notes = _context(push_remote=False)
+    return _emit(knowledge, actor, {"notes": [row.to_dict() for row in notes.list(actor)]})
 
 
 def _note_open(args: argparse.Namespace) -> int:
-    actor, _, notes = _context(push_remote=False)
-    note = notes.open(actor, args.path)
-    print(note.body, end="")
-    return 0
+    actor, knowledge, notes = _context(push_remote=False)
+    return _emit(knowledge, actor, notes.open(actor, args.path).body, render=str, end="")
 
 
 def _note_promote(args: argparse.Namespace) -> int:
-    actor, _, notes = _context(push_remote=not args.no_push)
+    actor, knowledge, notes = _context(push_remote=not args.no_push)
     receipt = notes.promote(
         actor,
         raw_path=args.path,
@@ -117,8 +142,7 @@ def _note_promote(args: argparse.Namespace) -> int:
         topics=args.topic,
         workstream=args.workstream,
     )
-    print(json.dumps(_receipt(receipt), ensure_ascii=False))
-    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+    return _emit(knowledge, actor, _receipt(receipt)) or (0 if receipt.status.value in {"accepted", "partial"} else 1)
 
 
 def _parser() -> argparse.ArgumentParser:
@@ -132,11 +156,27 @@ def _parser() -> argparse.ArgumentParser:
     create.add_argument("--topic", action="append", default=[])
     create.add_argument("--workstream")
     create.add_argument("--subtype")
-    create.add_argument("--relationship", action="append", default=[])
+    create.add_argument(
+        "--relationship", action="append", default=[], metavar="RELATION:TARGET",
+        help=f"repeatable; relations: {', '.join(RELATIONSHIP_VOCABULARY)} (others warn)",
+    )
     create.add_argument("--supersedes", action="append", default=[])
+    create.add_argument("--situation-domain", action="append", default=[], help="pattern only; repeatable")
+    create.add_argument("--situation-path", action="append", default=[], help="pattern only; repo-relative glob")
+    create.add_argument("--situation-activity", action="append", default=[], help="pattern only; repeatable")
     create.add_argument("--no-push", action="store_true")
     create.set_defaults(handler=_create)
 
+    instances = commands.add_parser("instances", help="records whose instance-of points at a pattern")
+    instances.add_argument("pattern", help="pattern id or canonical path")
+    instances.set_defaults(handler=_instances)
+
+    situated = commands.add_parser("situated", help="patterns whose situations match these paths or words")
+    situated.add_argument("--paths", nargs="+", action="extend", default=[], metavar="PATH")
+    situated.add_argument("--text", help="what is being worked on, in words")
+    situated.add_argument("-n", type=_positive, default=3, help="at most this many patterns (default 3)")
+    situated.set_defaults(handler=_situated)
+
     note_create = commands.add_parser("note-create")
     note_create.add_argument("--title", required=True)
     note_create.add_argument("--type", choices=("thought", "session", "retrospective", "journal"), default="thought")