Phase 1.2 (c): chio-pack registers as a real kb-engine plugin

End-to-end engine ↔ pack boundary now exercised. chio-pack imports
kb_engine; kb_engine never imports chio_pack (verified by AST-level
test + ops/ci/check-imports.py).

  chio_pack/schema.py
    Namespaced labels: ChioCapability, ChioReceipt, ChioGuard,
    ChioPolicy, ChioProtocol, ChioStandard (concept), ChioFile,
    ChioSymbol, ChioCrate, ChioDoc, ChioSpec, ChioSection
    (structural), ChioConcept, ChioEntity (hubs).
    Edge types: CONTAINS, CALLS, IMPORTS, DEPENDS_ON, DOCUMENTED_IN,
    HAS_DOC, CANONICAL_DOC, IMPLEMENTS, TESTED_BY, HAS_TEST, DEFINES,
    GUARDS, VALIDATES, SUPERSEDES, OWNED_BY, VALIDATED_BY,
    USES_CONCEPT, MENTIONS.
    Plus GRAPHITI_TYPES / NEO4J_TYPES vault-note vocabulary and a
    label_for_chio_node() lookup.

  chio_pack/plugin.py
    Four hook implementations:
      rust_source_ingester      .rs files; stubs symbol extraction
                                until Phase 1.3+ tree-sitter
      chio_graph_projector      emits ChioFile + ChioCrate + CONTAINS
                                edge per parsed Rust file
      chio_tool_registrar       stub (Phase 1.3+ registers 10 kb_* tools)
      chio_frontmatter_handler  routes vault frontmatter:
                                  episode-* types       → graphiti target
                                  spec/adr/playbook +   → neo4j target
                                    chio-node           (with namespaced
                                                        label resolution)
    Per AGENTS.md hard rule #1, returns DerivedRecord objects ONLY.
    Vault-sync daemon (Phase 1.4) is the lone Graphiti writer.
    `register(registry)` is the entry point declared in pyproject.toml.

  chio-pack/pyproject.toml
    [project.entry-points."kb_engine.plugins"]
    chio = "chio_pack.plugin"
    [tool.uv.sources]
    kb-engine = { path = "../kb-engine", editable = true }
    Version bumped 0.1.0 → 0.2.0 (first release with kb-engine
    integration). Added kb-engine to runtime dependencies.

  chio-pack/tests/test_plugin.py
    11 tests covering: register populates all four hook types, Rust
    ingester recognizes/skips, graph projector emits ChioFile and
    ChioCrate with CONTAINS, frontmatter handler routes episodes to
    graphiti and chio-node-bearing specs to neo4j with correct labels,
    unknown chio-node skipped, unknown type produces no records,
    AST-level boundary check (kb_engine doesn't import chio_*),
    entry-point loading via Registry.load_entry_points().

Total chio-pack tests: 26 passing (8 heuristic + 4 fixture-runner +
11 plugin + 3 session_log).

The boundary is now load-bearing in three independent ways:
  1. ops/ci/check-imports.py (CI step, fails the build on violation)
  2. test_engine_does_not_import_chio_modules (unit test, AST-based)
  3. Type system: kb_engine.types contains no Chio* symbols by
     construction (the namespaced labels live in chio_pack/schema.py)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bb-connor

chio-pack/chio_pack/plugin.py

@@ -0,0 +1,169 @@
+"""Registration of chio-pack's hooks against kb_engine.Registry.
+
+Per PLAN.md "kb-engine ↔ chio-pack boundary", chio-pack is the canonical
+schema pack. This module registers four hook implementations:
+
+  - SourceIngester for Rust files (.rs) — minimal today; Phase 1.3+
+    uses tree-sitter for symbol extraction.
+  - GraphProjector emitting ChioFile/ChioCrate nodes + CONTAINS edges.
+  - ToolRegistrar — stub today; Phase 1.3+ registers 10 kb_* tools.
+  - FrontmatterHandler routing vault-note frontmatter to the right
+    derived-store target (graphiti / neo4j) based on `type` and
+    `chio-node` fields.
+
+The `register(registry)` entry point is declared in
+chio-pack/pyproject.toml under [project.entry-points."kb_engine.plugins"]
+so kb_engine.Registry.load_entry_points() picks it up automatically
+when chio-pack is installed.
+
+This module proves the engine ↔ pack boundary works end-to-end:
+chio_pack imports kb_engine; kb_engine never imports chio_pack
+(enforced by ops/ci/check-imports.py).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from kb_engine import (
+    DerivedRecord,
+    Edge,
+    Node,
+    ParsedFile,
+    Registry,
+)
+
+from . import schema
+
+
+# === SourceIngester ===
+
+
+def rust_source_ingester(file_path: str) -> ParsedFile | None:
+    """Recognize .rs files. Today returns a stub ParsedFile so the
+    GraphProjector has something to project. Phase 1.3+ reads file
+    content and extracts symbols via tree-sitter.
+    """
+    if not file_path.endswith(".rs"):
+        return None
+    return ParsedFile(
+        path=file_path,
+        language="rust",
+        text="",  # Phase 1.3+
+        symbols=[],  # Phase 1.3+
+        properties={"crate": _crate_from_path(file_path)},
+    )
+
+
+def _crate_from_path(path: str) -> str:
+    """Best-effort crate name from path 'crates/<name>/src/...'."""
+    parts = path.split("/")
+    if len(parts) >= 2 and parts[0] == "crates":
+        return parts[1]
+    return "unknown"
+
+
+# === GraphProjector ===
+
+
+def chio_graph_projector(parsed: ParsedFile) -> list[Node | Edge]:
+    """Emit ChioFile + ChioCrate nodes plus a CONTAINS edge.
+
+    Phase 1.3+ extends to ChioSymbol nodes (one per parsed.symbols
+    entry) plus CALLS/IMPORTS/DEFINES edges where the parser surfaces
+    them.
+    """
+    if parsed.language != "rust":
+        return []
+    out: list[Node | Edge] = []
+    file_id = f"file:{parsed.path}"
+    out.append(Node(
+        id=file_id,
+        label=schema.FILE,
+        properties={"path": parsed.path},
+    ))
+    crate = parsed.properties.get("crate", "unknown")
+    if crate != "unknown":
+        crate_id = f"crate:{crate}"
+        out.append(Node(
+            id=crate_id,
+            label=schema.CRATE,
+            properties={"name": crate},
+        ))
+        out.append(Edge(
+            src_id=crate_id,
+            dst_id=file_id,
+            relationship=schema.CONTAINS,
+        ))
+    return out
+
+
+# === ToolRegistrar ===
+
+
+def chio_tool_registrar(server: object) -> None:
+    """Phase 1.3+: register kb_search_code, kb_search_docs, kb_neighbors,
+    kb_context, kb_impact, kb_brief_feature, kb_eval, kb_add_episode,
+    kb_find_tests, kb_find_docs on the MCP server framework.
+
+    Today stub — the MCP server framework is Phase 1.3+. Stub keeps the
+    registration call from erroring at boot so the rest of the pipeline
+    can be tested end-to-end.
+    """
+    # Future: server.register_tool("kb_search_code", ...)
+    pass
+
+
+# === FrontmatterHandler ===
+
+
+def chio_frontmatter_handler(
+    type: str, frontmatter: dict[str, Any]
+) -> list[DerivedRecord]:
+    """Route a vault-note frontmatter to derived-store targets.
+
+    Per AGENTS.md hard rule #1, this MUST NOT write directly to
+    Graphiti. It returns DerivedRecord objects; the vault-sync daemon
+    (Phase 1.4) is the only writer.
+    """
+    out: list[DerivedRecord] = []
+    if type in schema.GRAPHITI_TYPES:
+        out.append(DerivedRecord(
+            target="graphiti",
+            payload={
+                "name": frontmatter.get(
+                    "graphiti_episode_name", frontmatter.get("title", "")
+                ),
+                "type": type,
+                "scope": frontmatter.get("scope", "chio-repo"),
+                "source_description": frontmatter.get("source_description", ""),
+                "frontmatter": frontmatter,
+            },
+        ))
+    if type in schema.NEO4J_TYPES:
+        label = schema.label_for_chio_node(frontmatter.get("chio-node"))
+        if label:
+            out.append(DerivedRecord(
+                target="neo4j",
+                payload={
+                    "id": frontmatter.get("id", ""),
+                    "label": label,
+                    "properties": frontmatter,
+                },
+            ))
+    return out
+
+
+# === Registry entry point ===
+
+
+def register(registry: Registry) -> None:
+    """Called by `kb_engine.Registry.load_entry_points()`.
+
+    Wired in chio-pack/pyproject.toml under
+    `[project.entry-points."kb_engine.plugins"]`.
+    """
+    registry.register_source_ingester(rust_source_ingester)
+    registry.register_graph_projector(chio_graph_projector)
+    registry.register_tool_registrar(chio_tool_registrar)
+    for type_ in schema.GRAPHITI_TYPES | schema.NEO4J_TYPES:
+        registry.register_frontmatter_handler(type_, chio_frontmatter_handler)

chio-pack/chio_pack/schema.py

@@ -0,0 +1,104 @@
+"""chio-pack schema: namespaced labels and edge types for the Chio property graph.
+
+Per AGENTS.md hard rule #3, `kb_engine` cannot import `chio_*`. The
+dependency flows the OTHER way: chio_pack imports kb_engine to declare
+its own schema using the engine's plugin protocols.
+
+All node labels are namespaced with the `Chio` prefix to prevent
+collisions if other adopter packs (platform-pack, opus-pack, etc.) join
+the same Neo4j instance later.
+"""
+from __future__ import annotations
+
+# === High-level concept nodes ===
+CAPABILITY = "ChioCapability"
+RECEIPT = "ChioReceipt"
+GUARD = "ChioGuard"
+POLICY = "ChioPolicy"
+PROTOCOL = "ChioProtocol"
+STANDARD = "ChioStandard"
+
+# === Structural nodes (from source-code projector) ===
+FILE = "ChioFile"
+SYMBOL = "ChioSymbol"
+CRATE = "ChioCrate"
+DOC = "ChioDoc"
+SPEC = "ChioSpec"
+SECTION = "ChioSection"
+
+# === Concept hubs ===
+CONCEPT = "ChioConcept"
+ENTITY = "ChioEntity"
+
+ALL_NODE_LABELS = {
+    CAPABILITY, RECEIPT, GUARD, POLICY, PROTOCOL, STANDARD,
+    FILE, SYMBOL, CRATE, DOC, SPEC, SECTION,
+    CONCEPT, ENTITY,
+}
+
+# === Edge relationship vocabulary ===
+
+# Structural
+CONTAINS = "CONTAINS"
+CALLS = "CALLS"
+IMPORTS = "IMPORTS"
+DEPENDS_ON = "DEPENDS_ON"
+
+# Documentation
+DOCUMENTED_IN = "DOCUMENTED_IN"
+HAS_DOC = "HAS_DOC"
+CANONICAL_DOC = "CANONICAL_DOC"
+
+# Implementation
+IMPLEMENTS = "IMPLEMENTS"
+TESTED_BY = "TESTED_BY"
+HAS_TEST = "HAS_TEST"
+DEFINES = "DEFINES"
+
+# Chio-protocol-specific
+GUARDS = "GUARDS"
+VALIDATES = "VALIDATES"
+SUPERSEDES = "SUPERSEDES"
+OWNED_BY = "OWNED_BY"
+VALIDATED_BY = "VALIDATED_BY"
+USES_CONCEPT = "USES_CONCEPT"
+MENTIONS = "MENTIONS"
+
+
+def is_chio_label(label: str) -> bool:
+    """True if the label is in this pack's namespace."""
+    return label in ALL_NODE_LABELS
+
+
+# === Vault-note type → graph-target mapping ===
+
+# Episode types are derived to Graphiti (temporal memory).
+GRAPHITI_TYPES = frozenset({
+    "episode-architecture-summary",
+    "episode-architecture-decision",
+    "episode-workflow-constraint",
+    "episode-release-note",
+    "episode-pr-repair",
+    "episode-session-note",
+})
+
+# Spec/ADR/playbook types are derived to Neo4j (the property graph).
+NEO4J_TYPES = frozenset({
+    "spec",
+    "adr",
+    "playbook",
+})
+
+
+def label_for_chio_node(chio_node: str | None) -> str | None:
+    """Map a vault-note `chio-node` frontmatter value to its graph label."""
+    if not chio_node:
+        return None
+    return {
+        "Capability": CAPABILITY,
+        "Receipt": RECEIPT,
+        "Guard": GUARD,
+        "Policy": POLICY,
+        "Protocol": PROTOCOL,
+        "Standard": STANDARD,
+    }.get(chio_node)

chio-pack/pyproject.toml

@@ -1,13 +1,20 @@
 [project]
 name = "chio-pack"
-version = "0.1.0"
+version = "0.2.0"
 description = "Chio-specific schema, MCP tools, and outcome evals for chio-developer-base"
 requires-python = ">=3.11"
 authors = [{ name = "Backbay" }]
 dependencies = [
     "pyyaml>=6.0",
+    "kb-engine",
 ]
 
+[project.entry-points."kb_engine.plugins"]
+chio = "chio_pack.plugin"
+
+[tool.uv.sources]
+kb-engine = { path = "../kb-engine", editable = true }
+
 [project.scripts]
 # Phase 0+: outcome eval runner (skeleton; runners are Phase 1).
 chio-pack-eval = "chio_pack.eval.runner:main"