knowcode 0.1.0__py3-none-any.whl

runtime/services/__init__.py

@@ -0,0 +1 @@
+# Services subsystem.

runtime/services/ingest_service.py

@@ -0,0 +1,105 @@
+"""Ingest service.
+
+Handles the Runtime orchestration for the 'knowcode ingest-semantic' command.
+"""
+
+from __future__ import annotations
+
+import structlog
+from pathlib import Path
+from pydantic import BaseModel
+
+from runtime.exceptions.errors import KnowcodeError
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+from structural_engine.state.manager import StateManager
+
+logger = structlog.get_logger(__name__)
+
+
+class IngestSemanticResult(BaseModel):
+    """Result of a semantic ingestion."""
+    message: str
+    semantic_revision: str
+    deleted_files: list[str]
+
+
+def run_ingest(cwd: Path, target_file: str) -> IngestSemanticResult:
+    """Execute the semantic ingestion workflow.
+
+    1. Discover repository
+    2. Validate that the target_file is within the raw/ inbox
+    3. Delete the target file(s)
+    4. Increment the semantic_revision in state.yaml
+
+    Parameters
+    ----------
+    cwd : Path
+        Current working directory to start discovery.
+    target_file : str
+        The specific file to delete, or "." to empty the inbox.
+
+    Returns
+    -------
+    IngestSemanticResult
+        The result of the ingestion.
+        
+    Raises
+    ------
+    KnowcodeError
+        If the target_file resolves outside the raw directory sandbox.
+    """
+    repo = discover_repository(cwd)
+    paths = build_paths(repo)
+    
+    deleted_files = []
+    
+    if target_file == ".":
+        # Bulk deletion: safely iterate over raw directory
+        if paths.raw_knowledge_dir.exists():
+            for child in paths.raw_knowledge_dir.iterdir():
+                if child.is_file() and child.name != "README.md":
+                    child.unlink()
+                    deleted_files.append(child.name)
+        
+        if not deleted_files:
+            return IngestSemanticResult(
+                message="Inbox is already empty.",
+                semantic_revision="No change",
+                deleted_files=[]
+            )
+    else:
+        # Single file deletion: resolve and validate security boundary
+        # target_file could be an absolute path or relative to cwd.
+        target_path = Path(target_file).resolve()
+        raw_path = paths.raw_knowledge_dir.resolve()
+        
+        # Security validation: MUST be inside raw directory
+        if not target_path.is_relative_to(raw_path):
+            raise KnowcodeError(
+                f"Security Violation: Target '{target_file}' is not inside the raw inbox directory.\n"
+                f"Resolved target: {target_path}\n"
+                f"Allowed sandbox: {raw_path}"
+            )
+            
+        if not target_path.exists():
+            raise KnowcodeError(f"Target file does not exist: {target_path}")
+            
+        if target_path.name == "README.md":
+            raise KnowcodeError("Cannot delete the inbox README.md placeholder.")
+
+            
+        target_path.unlink()
+        deleted_files.append(target_path.name)
+        
+    # Commit the state update
+    state_manager = StateManager()
+    new_rev = state_manager.increment_semantic_revision(paths)
+    
+    logger.info("semantic_sync.ingest_flushed", deleted_count=len(deleted_files))
+    
+    return IngestSemanticResult(
+        message=f"Ingested {len(deleted_files)} file(s).",
+        semantic_revision=new_rev,
+        deleted_files=deleted_files
+    )

runtime/services/init_service.py

@@ -0,0 +1,45 @@
+"""Init service.
+
+Handles the Runtime orchestration for the 'know .' command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from runtime.artifact.builder import ArtifactBuilder
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+from runtime.repository.validator import validate_for_init
+from structural_engine.engine import StructuralEngine
+from structural_engine.results import InitializationResult
+
+
+def run_init(cwd: Path) -> InitializationResult:
+    """Execute the initialization workflow.
+
+    1. Discover repository
+    2. Validate preconditions
+    3. Build artifact directories and templates
+    4. Call StructuralEngine.initialize()
+
+    Parameters
+    ----------
+    cwd : Path
+        Current working directory to start discovery.
+
+    Returns
+    -------
+    InitializationResult
+        The result from the engine.
+    """
+    repo = discover_repository(cwd)
+    paths = build_paths(repo)
+    
+    validate_for_init(paths)
+    
+    builder = ArtifactBuilder(paths)
+    builder.build()
+    
+    engine = StructuralEngine()
+    return engine.initialize(paths)

runtime/services/semantic_sync_service.py

@@ -0,0 +1,55 @@
+"""Semantic Sync service.
+
+Handles the Runtime orchestration for the 'know sync-semantic' command.
+"""
+
+from __future__ import annotations
+
+import structlog
+from pathlib import Path
+from pydantic import BaseModel
+
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+from structural_engine.state.manager import StateManager
+
+logger = structlog.get_logger(__name__)
+
+
+class SemanticSyncResult(BaseModel):
+    """Result of a semantic synchronization."""
+    message: str
+    semantic_revision: str
+
+
+def run_semantic_sync(cwd: Path) -> SemanticSyncResult:
+    """Execute the semantic synchronization workflow.
+
+    1. Discover repository
+    2. Increment the semantic_revision in state.yaml
+    3. Delete the previous_context.md file, flushing the queue
+
+    Parameters
+    ----------
+    cwd : Path
+        Current working directory to start discovery.
+
+    Returns
+    -------
+    SemanticSyncResult
+        The result of the sync.
+    """
+    repo = discover_repository(cwd)
+    paths = build_paths(repo)
+    
+    state_manager = StateManager()
+    new_rev = state_manager.increment_semantic_revision(paths)
+    
+    if paths.previous_context_file.exists():
+        paths.previous_context_file.unlink()
+        logger.info("semantic_sync.memory_flushed", file=str(paths.previous_context_file))
+        
+    return SemanticSyncResult(
+        message="Semantic Knowledge Synchronized.",
+        semantic_revision=new_rev
+    )

runtime/services/status_service.py

@@ -0,0 +1,40 @@
+"""Status service.
+
+Handles the Runtime orchestration for the 'know status' command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+from runtime.repository.validator import validate_for_sync
+from structural_engine.engine import StructuralEngine
+from structural_engine.results import StructuralStatusResult
+
+
+def run_status(cwd: Path) -> StructuralStatusResult:
+    """Execute the status workflow.
+
+    1. Discover repository
+    2. Validate preconditions
+    3. Call StructuralEngine.status()
+
+    Parameters
+    ----------
+    cwd : Path
+        Current working directory to start discovery.
+
+    Returns
+    -------
+    StructuralStatusResult
+        The result from the engine.
+    """
+    repo = discover_repository(cwd)
+    paths = build_paths(repo)
+    
+    validate_for_sync(paths)
+    
+    engine = StructuralEngine()
+    return engine.status(paths)

runtime/services/sync_service.py

@@ -0,0 +1,57 @@
+"""Sync service.
+
+Handles the Runtime orchestration for the 'know sync' command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+from runtime.repository.validator import validate_for_sync
+from structural_engine.engine import StructuralEngine
+from structural_engine.results import SyncResult
+
+
+def run_sync(cwd: Path) -> SyncResult:
+    """Execute the synchronization workflow.
+
+    1. Discover repository
+    2. Validate preconditions
+    3. Call StructuralEngine.sync()
+
+    Parameters
+    ----------
+    cwd : Path
+        Current working directory to start discovery.
+
+    Returns
+    -------
+    SyncResult
+        The result from the engine.
+    """
+    repo = discover_repository(cwd)
+    paths = build_paths(repo)
+    
+    validate_for_sync(paths)
+    
+    engine = StructuralEngine()
+    result = engine.sync(paths)
+    
+    # Rollover the active context memory if structural changes occurred
+    if result.changes_detected and paths.active_context_file.exists():
+        active_content = paths.active_context_file.read_text(encoding="utf-8")
+        
+        if paths.previous_context_file.exists():
+            with open(paths.previous_context_file, "a", encoding="utf-8") as f:
+                f.write("\n\n---\n\n" + active_content)
+        else:
+            paths.previous_context_file.write_text(active_content, encoding="utf-8")
+            
+        import jinja2
+        env = jinja2.Environment(loader=jinja2.PackageLoader("runtime", "templates"))
+        template = env.get_template("active_context.md.j2")
+        paths.active_context_file.write_text(template.render(), encoding="utf-8")
+        
+    return result

runtime/templates/KNOWCODE_LOADER.md.j2

@@ -0,0 +1,24 @@
+name: knowcode-loader
+description: Initializes Knowcode governance for the current session.
+trigger: /knowcode
+---
+
+# Knowcode Session Initialization
+
+You have just been invoked via the `/knowcode` command. You are now acting as the Knowcode Governance Agent for this repository.
+
+### Immediate Actions Required:
+1. **Load the Passive Tracker:** You must immediately read and internalize the rules defined in `.agent/skills/track_intent.md`. You must run this skill continuously in the background for every subsequent prompt in this session.
+2. **Acknowledge:** Reply to the user with exactly this message: 
+   > *"Knowcode governance active. I am now silently tracking your architectural intent. Code normally, and type `/know-sync` when you are ready to synchronize."*
+
+### Tool Boundary Constraint
+While you may explore external packages or documentation to assist the developer, you must **never** attempt to read, debug, or modify the source code of the `know` CLI itself (e.g., the directory where the `knowcode` package is installed). The internal logic of the Knowcode engine is strictly off-limits.
+
+### Knowcode CLI Reference
+You have access to the `know` CLI terminal utility to manage structural and semantic state. Do not invent arguments.
+
+- **`know sync`**: Computes structural diffs, generates a report (`R-XXX.md`), and rolls active memory over to `previous_context.md`. (Run this during `/know-sync`).
+- **`know sync-semantic`**: Commits semantic knowledge, increments `semantic_revision`, and flushes `previous_context.md`. (Run this after synthesis).
+- **`know ingest-semantic .`**: Wipes the `.knowcode/knowledge/raw/` inbox and increments the semantic revision. (Run this after legacy ingestion).
+- **`know status`**: Displays current revisions, sync timestamps, and artifact locations.

runtime/templates/README_KNOWLEDGE.md.j2

@@ -0,0 +1,12 @@
+# Knowledge Maintenance Protocol
+
+This directory contains the human-facing architectural guidelines, constraints, conventions, and component documentation for the repository.
+
+## Organization
+- `architecture/`: High-level system design, sub-system descriptions, and boundaries.
+- `decisions/`: ADRs (Architecture Decision Records) explaining *why* a particular path was chosen.
+- `constraints/`: System invariants and "Trap" documentation. These are rules that must not be broken.
+- `conventions/`: Style, formatting, and language-specific rules.
+- `components/`: Specific component contracts and behaviors.
+
+This structure allows AI agents to orient themselves, understand system boundaries, and avoid regressions by reading explicitly defined constraints.

runtime/templates/README_STRUCTURE.md.j2

@@ -0,0 +1,19 @@
+# KnowCode Instance: {{ project_name }}
+
+This directory (`.agent/`) is the active governance and behavior root for this repository. It defines how autonomous agents should interact with, maintain, and evolve the codebase.
+
+## The Dual-Folder Architecture
+
+* **`.agent/` (Behavior & Governance):** You are here. This directory contains instructions, workflows, and skills that dictate *how* the AI operates.
+* **`.knowcode/` (Passive Knowledge & State):** The sibling directory. It contains deterministic AST snapshots, reports, logs, and persistent semantic state. `.knowcode/` has no operational governance.
+
+## Subsystems
+
+* **Runtime:** Orchestrates operations and manages this artifact structure.
+* **Structural Engine:** Owns `state.yaml` and parses the repository into deterministic snapshots.
+
+## Directory Structure
+- `skills/`: Markdown definitions of agent capabilities and functions.
+- `workflows/`: Orchestration sequences defining how agents tackle complex, multi-step goals.
+
+**Note:** The state lockfile (`.knowcode/state.yaml`) is managed exclusively by the Structural Engine. Do not edit it manually.

runtime/templates/__init__.py

@@ -0,0 +1 @@
+# Brain artifact templates.

runtime/templates/active_context.md.j2

@@ -0,0 +1,3 @@
+# Active Session Context
+
+*(Append active context below this line)*

runtime/templates/ingest_legacy.md.j2

@@ -0,0 +1,15 @@
+---
+name: ingest_legacy
+description: Orchestrates the processing and cleanup of legacy knowledge documents.
+trigger: /know-ingest
+---
+
+# Legacy Ingestion Workflow
+
+When the user invokes `/know-ingest`, you must process the raw inbox.
+
+### Execution Sequence:
+1. **Inbox Check:** List the files in `.knowcode/knowledge/raw/`. If it is empty (or only contains `README.md`), stop the workflow and inform the user.
+2. **Synthesis:** Load the skill `.agent/skills/synthesize_knowledge.md` and execute its instructions to process the raw documents.
+3. **Semantic Commit & Cleanup:** Once synthesis is written to disk, run the terminal command `know ingest-semantic .`. This will bump the semantic revision and the CLI will delete all the raw files.
+4. **Completion:** Summarize the knowledge you extracted and which buckets you updated.

runtime/templates/raw_readme.md.j2

@@ -0,0 +1,9 @@
+# Raw Knowledge Inbox
+
+This directory (`.knowcode/knowledge/raw/`) is the inbox for legacy or unstructured documentation.
+
+## Workflow
+
+1. **Drop files here:** Drop your old PDFs, markdown files, or text documents into this folder.
+2. **Agent Synthesis:** Ask the Semantic Agent to read the files and distribute the knowledge into the proper architectural documents (e.g., `architecture.md`, `decisions.md`).
+3. **Commit & Cleanup:** Once the agent is done extracting information from a file, it will run `know ingest-semantic <filename>` to delete the file and safely bump the knowledge base revision. Alternatively, the agent can run `know ingest-semantic .` to wipe the entire inbox at once.

runtime/templates/sync_reconciliation.md.j2

@@ -0,0 +1,17 @@
+---
+name: sync_reconciliation
+description: Orchestrates the Knowcode sync and reconciliation loop.
+trigger: /know-sync
+---
+
+# Sync Reconciliation Workflow
+
+When the user invokes `/know-sync`, you must execute the complete reconciliation loop. Do not skip any steps.
+
+### Execution Sequence:
+1. **Structural Sync:** Run the terminal command `know sync`. Wait for it to complete.
+2. **Buffer Check:** Check if `.agent/memory/previous_context.md` exists. 
+   - *Note: If this file does not exist, it means there were no structural changes. Stop the workflow here and inform the user.*
+3. **Synthesis:** Load the skill `.agent/skills/synthesize_knowledge.md` and execute its instructions to synthesize the sync state.
+4. **Semantic Commit:** Once synthesis is written to disk, run the terminal command `know sync-semantic`. This will bump the semantic revision and the CLI will delete the previous context buffer.
+5. **Completion:** Summarize the architectural updates you just made to the user.

runtime/templates/synthesize_knowledge.md.j2

@@ -0,0 +1,32 @@
+---
+name: synthesize_knowledge
+description: Skill to reconcile staged intent or legacy documents and update the permanent knowledge base.
+---
+
+# Knowledge Synthesis & Classification
+
+When called upon to synthesize knowledge, you are acting as the Chief Architect. You must classify information and deposit it into the correct buckets.
+
+### Step 1: Branching Execution
+**If invoked by `/know-sync`:**
+1. Read `.agent/memory/previous_context.md` (The Intent/Why).
+2. Read the latest `.knowcode/reports/R-XXX.md` report (The Reality/What).
+3. Reconcile: Compare the intent against reality. Did the structural changes match the intent? If there is a contradiction, the structural report is the absolute truth.
+
+**If invoked by `/know-ingest`:**
+1. Read the raw documents located in `.knowcode/knowledge/raw/`. 
+2. Do NOT cross-reference structural reports. Simply extract the architectural knowledge from the legacy files.
+
+### Step 2: Knowledge Distribution
+Take the validated insights and append them to the appropriate Markdown files within `.knowcode/knowledge/`:
+
+- `architecture/architecture.md`: High-level system design, data flow, subsystem responsibilities, and boundaries.
+- `decisions/decisions.md`: Architecture Decision Records (ADRs). The choice made, alternatives considered, and the trade-off rationale.
+- `constraints/constraints.md`: System invariants, import firewalls, security boundaries, and strict rules that must not be broken.
+- `conventions/conventions.md`: Styling, naming patterns, file structure, and formatting rules.
+- `components/components.md`: Specific component behaviors, public API contracts, and state machines.
+
+### Formatting Rules:
+- Append to existing files. Do not overwrite.
+- Use clear markdown `##` headings for new topics.
+- Keep descriptions precise and factual.

runtime/templates/track_intent.md.j2

@@ -0,0 +1,14 @@
+---
+name: track_intent
+description: The passive skill for distilling developer intent into the active context buffer.
+---
+
+# Intent Tracking (The Prime Directive)
+
+This is a passive background skill. While you are pair-programming, writing code, and answering questions, you must continuously distill the *Why* behind the development session.
+
+### Rules for Tracking:
+1. **Listen for Intent:** Identify design decisions, architectural shifts, new constraints discovered, and the reasoning behind code changes.
+2. **Append Silently:** Write these insights as 1-2 sentence bullet points into `.agent/memory/active_context.md`. Do this silently in the background without asking the user for permission.
+3. **No Code:** Do NOT log raw code snippets. The physical code is tracked by Git. You are tracking the *Why*.
+4. **Append-Only:** Never overwrite or truncate `active_context.md`. Only append. Never flush this file manually.

structural_engine/__init__.py

@@ -0,0 +1,3 @@
+# Structural Engine — the deterministic computation layer of the KnowCode ecosystem.
+# Owns: snapshots, reports, logs, revisions, structural state, structural history.
+# Never owns: commands, CLI, output, semantic knowledge, conventions, constraints.

structural_engine/diff/__init__.py

@@ -0,0 +1 @@
+# Diff subsystem.

structural_engine/diff/generator.py

@@ -0,0 +1,92 @@
+"""Diff generator.
+
+Calculates the delta between two snapshots.
+"""
+
+from __future__ import annotations
+
+from structural_engine.diff.models import StructuralDiff
+from structural_engine.parser.models import Entity, Relationship, StructuralSnapshot
+
+
+def generate(previous: StructuralSnapshot, current: StructuralSnapshot) -> StructuralDiff:
+    """Generate the structural difference between two snapshots.
+
+    Parameters
+    ----------
+    previous : StructuralSnapshot
+        The older state.
+    current : StructuralSnapshot
+        The newer state.
+
+    Returns
+    -------
+    StructuralDiff
+        The computed delta.
+    """
+    prev_entities = {e.id: e for e in previous.entities}
+    curr_entities = {e.id: e for e in current.entities}
+
+    added_entities: list[Entity] = []
+    removed_entities: list[Entity] = []
+    modified_entities: list[Entity] = []
+    affected_components: set[str] = set()
+
+    def _track_component(entity_id: str) -> None:
+        """Extract top-level directory from an ID to mark component as affected."""
+        # e.g., src/auth.py::verify_token -> src
+        # or tests/test_auth.py -> tests
+        path_part = entity_id.split("::")[0]
+        if "/" in path_part:
+            component = path_part.split("/")[0]
+            affected_components.add(component)
+        else:
+            affected_components.add("root")
+
+    for e_id, e_curr in curr_entities.items():
+        if e_id not in prev_entities:
+            added_entities.append(e_curr)
+            _track_component(e_id)
+        else:
+            e_prev = prev_entities[e_id]
+            # Simple line or property shift check
+            if (
+                e_curr.start_line != e_prev.start_line
+                or e_curr.end_line != e_prev.end_line
+                or e_curr.type != e_prev.type
+                or e_curr.parent_id != e_prev.parent_id
+            ):
+                modified_entities.append(e_curr)
+                _track_component(e_id)
+
+    for e_id, e_prev in prev_entities.items():
+        if e_id not in curr_entities:
+            removed_entities.append(e_prev)
+            _track_component(e_id)
+
+    # Relationship diffs
+    # Relationships are identified by the tuple (source_id, target_id, type)
+    prev_rels = {(r.source_id, r.target_id, r.type.name): r for r in previous.relationships}
+    curr_rels = {(r.source_id, r.target_id, r.type.name): r for r in current.relationships}
+
+    added_rels: list[Relationship] = []
+    removed_rels: list[Relationship] = []
+
+    for key, r_curr in curr_rels.items():
+        if key not in prev_rels:
+            added_rels.append(r_curr)
+            _track_component(r_curr.source_id)
+
+    for key, r_prev in prev_rels.items():
+        if key not in curr_rels:
+            removed_rels.append(r_prev)
+            _track_component(r_prev.source_id)
+
+    return StructuralDiff(
+        entities_added=tuple(added_entities),
+        entities_removed=tuple(removed_entities),
+        entities_modified=tuple(modified_entities),
+        relationships_added=tuple(added_rels),
+        relationships_removed=tuple(removed_rels),
+        affected_components=frozenset(affected_components),
+    )

structural_engine/diff/models.py

@@ -0,0 +1,48 @@
+"""Diff domain models.
+
+Represents the structural delta between two snapshots.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from structural_engine.parser.models import Entity, Relationship
+
+
+@dataclass(frozen=True)
+class StructuralDiff:
+    """The delta between two structural states.
+
+    Identifies exactly what changed structurally, ignoring pure logic
+    modifications that don't shift AST bounds or signatures.
+    """
+
+    entities_added: tuple[Entity, ...] = field(default_factory=tuple)
+    """Entities present in current but not in previous."""
+
+    entities_removed: tuple[Entity, ...] = field(default_factory=tuple)
+    """Entities present in previous but not in current."""
+
+    entities_modified: tuple[Entity, ...] = field(default_factory=tuple)
+    """Entities whose lines shifted or properties changed, but ID matched."""
+
+    relationships_added: tuple[Relationship, ...] = field(default_factory=tuple)
+    """Relationships present in current but not in previous."""
+
+    relationships_removed: tuple[Relationship, ...] = field(default_factory=tuple)
+    """Relationships present in previous but not in current."""
+
+    affected_components: frozenset[str] = field(default_factory=frozenset)
+    """Top-level directories (components) affected by these changes."""
+
+    @property
+    def has_changes(self) -> bool:
+        """Return True if any structural change occurred."""
+        return bool(
+            self.entities_added
+            or self.entities_removed
+            or self.entities_modified
+            or self.relationships_added
+            or self.relationships_removed
+        )