clm-kernel 0.0.0__py3-none-any.whl

clm/schemas/abstract_face_schema.yaml

@@ -0,0 +1,77 @@
+# Abstract Face Schema (Face A)
+# ==============================
+# Validates the structure of computable_knowledge/Abstract/layer0/stageN_*.yaml.
+#
+# Sprint 134 — formalizes the `context.external_references` block that was
+# already deployed across all 6 Abstract face YAMLs but lived outside any
+# schema. Reuses the existing CEL `ref:` reserved word (replacing `path:`)
+# and adds two optional fields (`kind`, `content_hash`) drawn from existing
+# vocabulary. See docs/spec/external_references_grammar.md for the
+# keyword inventory and worked examples.
+#
+# Version: 1.0
+# Sprint: 134
+
+universe_level: 0
+version: "1.0"
+
+# ---------------------------------------------------------------------------
+# Top-level shape of an Abstract face YAML
+# ---------------------------------------------------------------------------
+abstract_face:
+  required: [version, clm]
+  clm:
+    required: [layer, stage, name, face, type, context, goal, success_criteria]
+    layer:
+      enum: ["0", "1", "2", "3"]
+    face:
+      enum: ["A"]
+    type:
+      enum: ["mcard"]
+    context:
+      required: [description]
+      optional: [dependencies, external_references]
+      dependencies:
+        type: list
+        items: { type: string }
+        description: "Inter-stage handle names (e.g. layer0_stage1_abstract)."
+      external_references:
+        type: list
+        description: >
+          External architecture / spec / standard docs that ground this
+          stage. Each entry is a pointer, not inlined content. Reuses the
+          CEL `ref:` reserved word (single source of truth for 'reference'
+          across the CLM grammar).
+        items:
+          required: [ref, relevance]
+          optional: [kind, content_hash]
+          ref:
+            type: string
+            description: >
+              Repo-relative filesystem path (e.g.
+              docs/architecture/directive_4_*.md), an mcard:// URI
+              (mcard://handle/<handle> or mcard://hash/<64hex>), or a
+              [[wikilink]] name. Reuses the CEL `ref:` reserved word.
+          kind:
+            enum: [directive, specification, architecture, comparison, standard, rationale]
+            description: >
+              Discriminator reusing existing docs/architecture/ naming
+              vocabulary. No new concepts introduced.
+          content_hash:
+            type: string
+            pattern: "^[a-fA-F0-9]{64}$"
+            description: >
+              Optional SHA-256 pin of the referenced content. If absent,
+              the reference floats (drift undetected). If present, the lint
+              gate recomputes the file hash and fails on drift. Reuses the
+              `content_hash` field name already on the Card model.
+          relevance:
+            type: string
+            min_length: 1
+            description: "Free-form prose explaining why this reference grounds this stage."
+    goal:
+      required: [description]
+    success_criteria:
+      type: list
+      items: { type: string }
+      min_items: 1

clm/schemas/cel_schema.yaml

@@ -0,0 +1,416 @@
+# CLM Expression Language (CEL) Schema
+# =====================================
+# Defines language-agnostic operation descriptors for Balanced (Face B) assertions.
+# Each 'actual' field in vcard_post can be either:
+#   - A legacy Python expression string (backward compatible)
+#   - A structured CEL operation dict (language-agnostic)
+#
+# Version: 1.1
+# Sprint: 119 (v1.0), 126.1 (v1.1 — added run_test_suite, string_concat, path_basename, string_join)
+
+universe_level: 0
+version: "1.1"
+
+# ---------------------------------------------------------------------------
+# Reference Syntax
+# ---------------------------------------------------------------------------
+# References use dot-notation to access context values:
+#   inputs.key        → inputs['key']
+#   outputs.key       → outputs['key']
+#   state.key         → retrieve('key')  (cross-assertion state)
+#   env.tmp_dir       → sandbox temporary directory
+#   env.clm_root      → workspace root directory
+#   env.rc            → return code from operation execution
+
+# ---------------------------------------------------------------------------
+# Primitive Types
+# ---------------------------------------------------------------------------
+# string   — UTF-8 text
+# integer  — whole number
+# boolean  — true / false
+# list     — ordered sequence
+# dict     — key-value mapping
+# any      — unspecified (runtime-determined)
+
+# ---------------------------------------------------------------------------
+# Operation Types
+# ---------------------------------------------------------------------------
+
+operations:
+
+  # === value_ref ===
+  # Look up a named value from the execution context.
+  value_ref:
+    required: [name]
+    optional: [returns]
+    description: "Reference a named context variable (e.g., rc, tmp_dir)."
+    example:
+      op: value_ref
+      name: rc
+      returns: integer
+
+  # === db_query ===
+  # Execute a SQL query against a named pillar database.
+  db_query:
+    required: [pillar, sql]
+    optional: [params, transform, returns]
+    description: "Execute SQL against a Tri-Database pillar."
+    defaults:
+      transform: strip
+      returns: string
+    example:
+      op: db_query
+      pillar: agent_identities
+      sql: "SELECT name FROM sqlite_master WHERE type='table' AND name='card';"
+      returns: string
+
+  # === call ===
+  # Invoke a registered function with arguments.
+  call:
+    required: [function]
+    optional: [args, kwargs, default, returns]
+    description: "Call a registered CLM function."
+    # Canonical list of Python-bound functions that are deprecated (Sprint 127.4).
+    # Both the CEL evaluator (cel_engine.py) and the lint gate (lint_cel_bindings.py)
+    # load this list at startup — single source of truth.
+    deprecated_functions:
+      - operator.add
+      - operator.sub
+      - operator.mul
+      - operator.truediv
+      - operator.mod
+      - str.join
+      - os.system
+    example:
+      op: call
+      function: classify_clm
+      args:
+        - ref: inputs.classify_string
+      returns: string
+
+  # === store ===
+  # Store a computed value in cross-assertion state.
+  store:
+    required: [key, value]
+    optional: [returns]
+    description: "Store a value for retrieval in subsequent assertions."
+    example:
+      op: store
+      key: v0_hash
+      value:
+        op: call
+        function: repo.resolve_handle_hash
+        args:
+          - ref: inputs.handle_name
+      returns: any
+
+  # === retrieve ===
+  # Retrieve a previously stored value.
+  retrieve:
+    required: [key]
+    optional: [returns]
+    description: "Retrieve a previously stored cross-assertion value."
+    example:
+      op: retrieve
+      key: v0_hash
+      returns: string
+
+  # === write_file ===
+  # Write content to a file in the sandbox.
+  write_file:
+    required: [path, content]
+    optional: [returns]
+    description: "Write content to a file path."
+    defaults:
+      returns: boolean
+    example:
+      op: write_file
+      path:
+        op: path_join
+        parts:
+          - ref: env.tmp_dir
+          - "sample.txt"
+      content:
+        ref: inputs.version_0_content
+      returns: boolean
+
+  # === set_env ===
+  # Set an environment variable.
+  set_env:
+    required: [var, value]
+    optional: [returns]
+    description: "Set an environment variable."
+    defaults:
+      returns: boolean
+    example:
+      op: set_env
+      var: CLM_POLYGLOT_RUNTIME
+      value: shell
+      returns: boolean
+
+  # === unset_env ===
+  # Remove an environment variable.
+  unset_env:
+    required: [var]
+    optional: [returns]
+    description: "Remove an environment variable."
+    defaults:
+      returns: boolean
+    example:
+      op: unset_env
+      var: CLM_POLYGLOT_RUNTIME
+      returns: boolean
+
+  # === sleep ===
+  # Pause execution for a specified duration.
+  sleep:
+    required: [seconds]
+    optional: [returns]
+    description: "Pause execution for N seconds."
+    defaults:
+      returns: boolean
+    example:
+      op: sleep
+      seconds: 1.1
+      returns: boolean
+
+  # === sequence ===
+  # Execute multiple operations in order, return the result of the last.
+  sequence:
+    required: [steps]
+    optional: [returns]
+    description: "Execute a sequence of operations. Returns result of last step."
+    max_depth: 2
+    example:
+      op: sequence
+      steps:
+        - op: set_env
+          var: CLM_POLYGLOT_RUNTIME
+          value: shell
+        - op: set_env
+          var: CLM_RUNTIME_BACKEND
+          value: shell
+      returns: boolean
+
+# ---------------------------------------------------------------------------
+# Utility Operations (composable within other ops)
+# ---------------------------------------------------------------------------
+
+  # === path_join ===
+  # Join path segments (platform-independent).
+  path_join:
+    required: [parts]
+    optional: [returns]
+    description: "Join filesystem path segments."
+    defaults:
+      returns: string
+    example:
+      op: path_join
+      parts:
+        - ref: env.tmp_dir
+        - "db"
+        - "agent_identities.db"
+
+  # === len ===
+  # Get the length of a value.
+  len:
+    required: [value]
+    optional: [returns]
+    description: "Get length of a string, list, or dict."
+    defaults:
+      returns: integer
+
+  # === compare ===
+  # Compare two values with an operator.
+  compare:
+    required: [left, operator, right]
+    optional: [returns]
+    description: "Compare two values. Operators: eq, ne, gt, gte, lt, lte, in, not_in."
+    defaults:
+      returns: boolean
+    example:
+      op: compare
+      left:
+        op: call
+        function: repo.resolve_handle_hash
+        args:
+          - ref: inputs.handle_name
+      operator: ne
+      right:
+        ref: state.v0_hash
+      returns: boolean
+
+  # === int_cast ===
+  # Cast a value to integer.
+  int_cast:
+    required: [value]
+    optional: [returns]
+    description: "Cast a value to integer."
+    defaults:
+      returns: integer
+
+  # === contains ===
+  # Check if a value is contained in another.
+  contains:
+    required: [haystack, needle]
+    optional: [returns]
+    description: "Check if needle is contained in haystack."
+    defaults:
+      returns: boolean
+
+  # === make_mcard_content ===
+  # Generate MCard YAML content string.
+  make_mcard_content:
+    required: [content_hash, content]
+    optional: [filename, mime_type, returns]
+    description: "Generate an MCard YAML content string."
+    defaults:
+      filename: "test.txt"
+      mime_type: "text/plain"
+      returns: string
+
+  # === copy_file ===
+  # Copy a file from source to destination.
+  copy_file:
+    required: [src, dest]
+    optional: [returns]
+    description: "Copy a file from source to destination."
+    defaults:
+      returns: boolean
+
+  # === not_null ===
+  # Assert value is not null/None.
+  not_null:
+    required: [value]
+    optional: [returns]
+    description: "Check that value is not null/None."
+    defaults:
+      returns: boolean
+
+  # === callable_check ===
+  # Check if a value is callable (a function).
+  callable_check:
+    required: [value]
+    optional: [returns]
+    description: "Check if a value is callable."
+    defaults:
+      returns: boolean
+
+  # === json_parse ===
+  # Parse a JSON string into a dict/list.
+  json_parse:
+    required: [value]
+    optional: [returns]
+    description: "Parse a JSON string into structured data."
+    defaults:
+      returns: any
+
+  # === dict_get ===
+  # Access a key from a dict value.
+  dict_get:
+    required: [value, key]
+    optional: [default, returns]
+    description: "Get a key from a dict, with optional default."
+    defaults:
+      returns: any
+
+  # === index ===
+  # Access an element by index from a list.
+  index:
+    required: [value, position]
+    optional: [returns]
+    description: "Get element at position from a list."
+    defaults:
+      returns: any
+
+  # === replace ===
+  # String replacement.
+  replace:
+    required: [value, old, new]
+    optional: [returns]
+    description: "Replace occurrences of 'old' with 'new' in a string."
+    defaults:
+      returns: string
+
+  # === read_file ===
+  read_file:
+    required: [path]
+    optional: [returns]
+    description: "Read the contents of a file as text."
+    defaults:
+      returns: string
+    example:
+      op: read_file
+      path:
+        op: path_join
+        parts:
+          - ref: env.clm_root
+          - "README.md"
+
+  # === capture_output ===
+  # Capture stdout/stderr from an operation.
+  capture_output:
+    required: [operation]
+    optional: [stream, returns]
+    description: "Capture stdout or stderr from an operation."
+    defaults:
+      stream: stdout
+      returns: string
+
+  # === run_test_suite ===  (Sprint 126.1)
+  # Execute a test file in the appropriate runtime, returning its exit code.
+  run_test_suite:
+    required: [test_file]
+    optional: [env, timeout, returns]
+    description: >
+      Execute a test file in the appropriate runtime, returning its exit code.
+      Runtime is auto-detected from file extension (.py → python, .sh → shell, .rs → cargo test).
+      Environment variables are injected declaratively via the 'env' dict.
+    defaults:
+      returns: integer
+      timeout: 300
+    example:
+      op: "run_test_suite"
+      test_file: "computable_knowledge/files/layer0/python/test_core_exclude.py"
+      env:
+        CLM_ROOT: { ref: "env.clm_root" }
+        PYTHONPATH: { op: "path_join", parts: [{ ref: "env.clm_root" }, "kernel/scripts"] }
+
+  # === string_concat ===  (Sprint 126.1)
+  # Concatenate a list of string parts into a single string (no separator).
+  string_concat:
+    required: [parts]
+    optional: [returns]
+    description: "Concatenate a list of string parts into a single string (no separator)."
+    defaults:
+      returns: string
+    example:
+      op: "string_concat"
+      parts:
+        - "ast:"
+        - { op: "retrieve", key: "stripped_hash" }
+
+  # === path_basename ===  (Sprint 126.1)
+  # Extract the last component of a filesystem path.
+  path_basename:
+    required: [value]
+    optional: [returns]
+    description: "Extract the last component of a filesystem path."
+    defaults:
+      returns: string
+    example:
+      op: "path_basename"
+      value: "db/agent_identities.db"
+
+  # === string_join ===  (Sprint 126.1)
+  # Join a list of string parts with a separator.
+  string_join:
+    required: [separator, parts]
+    optional: [returns]
+    description: "Join a list of string parts with a separator."
+    defaults:
+      returns: string
+    example:
+      op: "string_join"
+      separator: " "
+      parts: ["hello", "world"]

clm/schemas/lifecycle/__init__.py

@@ -0,0 +1,45 @@
+"""Lifecycle Sub-Lattice Schemas and Models (DV-376-01)."""
+
+from clm.schemas.lifecycle.models import (
+    ArtifactMCard,
+    ArtifactPayload,
+    CommitMCard,
+    CommitPayload,
+    DeliverableItem,
+    DesignDecisionMCard,
+    DesignDecisionPayload,
+    FeedbackMCard,
+    FeedbackPayload,
+    LifecycleBaseModel,
+    LifecycleMCard,
+    SprintStatusMCard,
+    SprintStatusPayload,
+)
+
+__all__ = [
+    "ArtifactMCard",
+    "ArtifactPayload",
+    "CommitMCard",
+    "CommitPayload",
+    "DeliverableItem",
+    "DesignDecisionMCard",
+    "DesignDecisionPayload",
+    "FeedbackMCard",
+    "FeedbackPayload",
+    "LifecycleBaseModel",
+    "LifecycleMCard",
+    "SprintStatusMCard",
+    "SprintStatusPayload",
+    "import_decisions_from_dir",
+    "query_decisions",
+    "emit_sprint_status",
+    "query_lifecycle_cards",
+]
+
+from clm.schemas.lifecycle.service import (
+    emit_sprint_status,
+    import_decisions_from_dir,
+    query_decisions,
+    query_lifecycle_cards,
+)
+

clm/schemas/lifecycle/models.py

@@ -0,0 +1,123 @@
+"""Pydantic v2 Models for Universal MCard Lifecycle Sub-Lattice Archetypes (DV-376-01).
+
+Implements strictly validated schemas for Commit, DesignDecision, Feedback,
+Artifact, and SprintStatus MCards.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class LifecycleBaseModel(BaseModel):
+    """Base immutable model for lifecycle archetype structures."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    def to_canonical_json(self) -> str:
+        """Produce canonical JSON representation with sorted keys and minimal separators."""
+        return json.dumps(
+            self.model_dump(mode="json", exclude_none=True),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+
+
+class CommitPayload(LifecycleBaseModel):
+    commit_id: str
+    diff_hash: str
+    author: str
+    message: str
+    g_time: str
+    parent_commits: list[str] = Field(default_factory=list)
+    changed_files: list[str] = Field(default_factory=list)
+
+
+class CommitMCard(LifecycleBaseModel):
+    archetype: Literal["CommitMCard"] = "CommitMCard"
+    version: str = "1.0.0"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    payload: CommitPayload
+
+
+class DesignDecisionPayload(LifecycleBaseModel):
+    decision_id: str
+    summary: str
+    rationale: str
+    status: Literal["proposed", "approved", "rejected", "superseded"]
+    alternatives: list[str] = Field(default_factory=list)
+    consequences: list[str] = Field(default_factory=list)
+    v_pre: list[dict[str, Any]] = Field(default_factory=list)
+    v_post: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class DesignDecisionMCard(LifecycleBaseModel):
+    archetype: Literal["DesignDecisionMCard"] = "DesignDecisionMCard"
+    version: str = "1.0.0"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    payload: DesignDecisionPayload
+
+
+class FeedbackPayload(LifecycleBaseModel):
+    feedback_id: str
+    source: Literal["human", "llm", "ci", "runtime"]
+    content: str
+    severity: Literal["info", "warning", "error", "fatal"]
+    target_ref: str | None = None
+    action_items: list[str] = Field(default_factory=list)
+
+
+class FeedbackMCard(LifecycleBaseModel):
+    archetype: Literal["FeedbackMCard"] = "FeedbackMCard"
+    version: str = "1.0.0"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    payload: FeedbackPayload
+
+
+class ArtifactPayload(LifecycleBaseModel):
+    artifact_id: str
+    name: str
+    uri: str
+    content_type: str
+    size_bytes: int = Field(ge=0)
+    content_hash: str
+    origin: Literal["ci", "build", "doc", "test", "manual", "package"]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ArtifactMCard(LifecycleBaseModel):
+    archetype: Literal["ArtifactMCard"] = "ArtifactMCard"
+    version: str = "1.0.0"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    payload: ArtifactPayload
+
+
+class DeliverableItem(LifecycleBaseModel):
+    id: str
+    name: str
+    status: str
+    commit_ref: str | None = None
+
+
+class SprintStatusPayload(LifecycleBaseModel):
+    sprint_id: str
+    title: str
+    status: Literal["planned", "in_progress", "review", "completed", "failed", "blocked"]
+    completion_ratio: float = Field(ge=0.0, le=1.0)
+    deliverables: list[DeliverableItem] = Field(default_factory=list)
+    quality_gate_passed: bool
+    g_time: str
+
+
+class SprintStatusMCard(LifecycleBaseModel):
+    archetype: Literal["SprintStatusMCard"] = "SprintStatusMCard"
+    version: str = "1.0.0"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    payload: SprintStatusPayload
+
+
+LifecycleMCard = CommitMCard | DesignDecisionMCard | FeedbackMCard | ArtifactMCard | SprintStatusMCard