codec-cortex 0.3.2__py3-none-any.whl

cortex/core/validator.py

@@ -0,0 +1,268 @@
+"""Validator — checks an AST against the CODEC-CORTEX contract.
+
+The validator runs a series of structural rules:
+
+1. ``$0`` exists and is the first section (already enforced by parser).
+2. Every sigil used by an entry is declared in ``$0``.
+3. Every type referenced by a sigil is declared.
+4. ``attrs-pos`` sigils have a positional contract.
+5. Critical sigils (FCS, OBJ, WRK, STP, CNST, RSK, CLAIM, LIM, AUD,
+   SES, LNG, KNW, HDL) have their required fields.
+6. Status / severity / priority values are in the allowed sets.
+7. No duplicate entries (same sigil+name) unless explicitly allowed.
+8. **Cognitive governance** (1.1.0): level separation (Nivel 1 sin estado
+   vivo, Nivel 2 con FCS+OBJ, Nivel 3 sin WRK), ``survive`` domain,
+   ``CNST:blocking`` → ``survive:min``, secret scanning.
+
+Two modes are supported:
+  - ``validate(doc, strict=False)`` (default): warnings stay warnings,
+    errors stay errors.
+  - ``validate(doc, strict=True)``: all warnings are promoted to errors
+    so ``verify --strict`` fails on any contract violation.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .ast import CortexDocument, Entry
+from .errors import (
+    ALLOWED_PRIORITY,
+    ALLOWED_SEVERITY,
+    ALLOWED_STATUS,
+    E003_UNKNOWN_SIGIL,
+    E004_UNKNOWN_TYPE,
+    E007_ATTRS_POS_CONTRACT_MISSING,
+    E008_DUPLICATE_ENTRY,
+)
+from .document_kind import (
+    DocumentKind,
+    validate_level_policy,
+)
+
+
+# Required fields per critical sigil (Section 6 of SKILL.md)
+REQUIRED_FIELDS: Dict[str, List[str]] = {
+    "FCS":   ["what", "priority", "status", "survive"],
+    "OBJ":   ["goal", "status", "success", "survive"],
+    "WRK":   ["phase", "current", "blocked", "survive"],
+    "STP":   ["action", "reason", "owner", "status", "survive"],
+    "CNST":  ["rule", "severity", "survive"],
+    "CLAIM": ["statement", "evidence", "status"],
+    "LIM":   ["limit", "scope", "status"],
+    "RSK":   ["risk", "impact", "mitigation", "status", "survive"],
+    "AUD":   ["event", "evidence", "result", "date"],
+    "SES":   ["input", "output", "outcome", "date"],
+    "LNG":   ["type", "cause", "lesson", "prevention"],
+    "KNW":   ["topic", "content", "status"],
+}
+
+
+# Sigils protected from deletion without --force (P0 / blocking severity)
+def _is_protected(entry: Entry) -> bool:
+    if entry.sigil in ("FCS", "OBJ", "CNST"):
+        attrs = entry.value if isinstance(entry.value, dict) else {}
+        sev = attrs.get("severity", "")
+        if sev == "blocking":
+            return True
+        if attrs.get("survive") == "min":
+            return True
+    return False
+
+
+def is_protected_entry(entry: Entry) -> bool:
+    """Public wrapper used by the CRUD layer."""
+
+    return _is_protected(entry)
+
+
+def validate(
+    doc: CortexDocument,
+    strict: bool = False,
+    kind: Optional[DocumentKind] = None,
+) -> List[Dict]:
+    """Run all validators and return a list of diagnostic dicts.
+
+    Existing ``doc.diagnostics`` are preserved; new findings are appended.
+
+    Parameters
+    ----------
+    doc : CortexDocument
+        The document to validate.
+    strict : bool, default False
+        When True, all ``warning`` findings are promoted to ``error``
+        severity so that ``verify --strict`` fails on any contract
+        violation (audit gap M-02).
+    kind : DocumentKind, optional
+        Explicit document kind for level-policy checks.  When None, the
+        kind is inferred from the document (filename, IDN, sigil
+        signature).  Passing an explicit kind overrides inference so
+        ``verify --kind package`` actually applies Nivel-3 rules —
+        closing re-audit gap H-RA-01.
+    """
+
+    findings: List[Dict] = list(doc.diagnostics)
+
+    # 1. Unknown sigils (parser may already have flagged some)
+    for sec, entry in doc.iter_entries():
+        if entry.sigil in {"GSIG", "GTYP", "GMIC", "GCON"}:
+            continue
+        if entry.sigil not in doc.glossary.sigils:
+            findings.append({
+                "code": E003_UNKNOWN_SIGIL,
+                "message": f"sigil {entry.sigil!r} (entry {entry.name!r}) not declared in $0",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "error",
+            })
+            continue
+        sd = doc.glossary.sigils[entry.sigil]
+        if sd.type not in doc.glossary.types:
+            findings.append({
+                "code": E004_UNKNOWN_TYPE,
+                "message": f"type {sd.type!r} (sigil {entry.sigil!r}) not declared in $0",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "error",
+            })
+        if sd.type == "attrs-pos" and doc.glossary.contract_for(entry.sigil) is None:
+            findings.append({
+                "code": E007_ATTRS_POS_CONTRACT_MISSING,
+                "message": f"attrs-pos sigil {entry.sigil!r} has no positional contract",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "error",
+            })
+
+    # 2. Required fields for critical sigils
+    for sec, entry in doc.iter_entries():
+        required = REQUIRED_FIELDS.get(entry.sigil)
+        if not required:
+            continue
+        if not isinstance(entry.value, dict):
+            findings.append({
+                "code": "W001_MISSING_FIELDS",
+                "message": f"{entry.sigil}:{entry.name} value is not a dict; cannot check fields",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "warning",
+            })
+            continue
+        missing = [f for f in required if f not in entry.value]
+        if missing:
+            findings.append({
+                "code": "W001_MISSING_FIELDS",
+                "message": f"{entry.sigil}:{entry.name} missing required fields: {missing}",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "warning",
+            })
+
+    # 3. Status / severity / priority allowed values
+    for sec, entry in doc.iter_entries():
+        if not isinstance(entry.value, dict):
+            continue
+        status = entry.value.get("status")
+        if isinstance(status, str) and status not in ALLOWED_STATUS:
+            findings.append({
+                "code": "W002_INVALID_STATUS",
+                "message": f"{entry.sigil}:{entry.name} status={status!r} not in {sorted(ALLOWED_STATUS)}",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "warning",
+            })
+        severity = entry.value.get("severity")
+        if isinstance(severity, str) and severity not in ALLOWED_SEVERITY:
+            findings.append({
+                "code": "W003_INVALID_SEVERITY",
+                "message": f"{entry.sigil}:{entry.name} severity={severity!r} not in {sorted(ALLOWED_SEVERITY)}",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "warning",
+            })
+        priority = entry.value.get("priority")
+        if isinstance(priority, str) and priority not in ALLOWED_PRIORITY:
+            findings.append({
+                "code": "W004_INVALID_PRIORITY",
+                "message": f"{entry.sigil}:{entry.name} priority={priority!r} not in {sorted(ALLOWED_PRIORITY)}",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "warning",
+            })
+
+    # 4. Duplicate entries (same sigil+name) within the same section
+    seen: Dict[str, List[str]] = {}
+    for sec, entry in doc.iter_entries():
+        if entry.sigil in {"GSIG", "GTYP", "GMIC", "GCON"}:
+            continue
+        key = f"{sec.id}::{entry.sigil}::{entry.name}"
+        if key in seen:
+            findings.append({
+                "code": E008_DUPLICATE_ENTRY,
+                "message": f"duplicate entry {entry.sigil}:{entry.name} in {sec.id}",
+                "line": entry.line_start,
+                "section": sec.id,
+                "sigil": entry.sigil,
+                "entry": entry.name,
+                "severity": "error",
+            })
+        seen.setdefault(key, []).append(entry.name)
+
+    # 5. Cognitive governance (audit hardening, 1.1.0):
+    #    level separation, FCS/OBJ in brain, survive domain, blocking→min,
+    #    attrs-pos arity, secret scanning.
+    # Re-audit H-RA-01: pass explicit `kind` through so `verify --kind X`
+    # actually applies the right level-policy rules.
+    findings.extend(validate_level_policy(doc, kind=kind))
+
+    # 6. Strict mode: promote all warnings to errors
+    if strict:
+        for f in findings:
+            if f.get("severity") == "warning":
+                f["severity"] = "error"
+                f["message"] = f"[strict] {f.get('message', '')}"
+
+    # Deduplicate findings by (code, line, sigil, entry, message)
+    seen_keys = set()
+    deduped: List[Dict] = []
+    for f in findings:
+        k = (f.get("code"), f.get("line"), f.get("sigil"),
+             f.get("entry"), f.get("message"))
+        if k in seen_keys:
+            continue
+        seen_keys.add(k)
+        deduped.append(f)
+
+    return deduped
+
+
+def is_valid(
+    doc: CortexDocument,
+    strict: bool = False,
+    kind: Optional[DocumentKind] = None,
+) -> bool:
+    """Return True if the document has no error-severity diagnostics.
+
+    When ``strict=True``, warnings also count as failures.
+    """
+
+    for f in validate(doc, strict=strict, kind=kind):
+        if f.get("severity") == "error":
+            return False
+    return True

cortex/core/writer.py

@@ -0,0 +1,249 @@
+"""Canonical ``.cortex`` writer.
+
+Serialises a :class:`CortexDocument` AST back to ``.cortex`` source text.
+The writer is deterministic: the same AST always produces byte-identical
+output, which is what makes roundtrip verification meaningful.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+from .ast import (
+    AttrsPosContract,
+    CortexDocument,
+    Entry,
+    Glossary,
+    MicroDef,
+    SigilDef,
+)
+
+
+# ---------------------------------------------------------------------------
+# Value serialisation
+# ---------------------------------------------------------------------------
+
+def _escape_string(s: str) -> str:
+    """Escape a string for ``attrs`` double-quoted form."""
+
+    out = s.replace("\\", "\\\\").replace('"', '\\"')
+    out = out.replace("\n", "\\n").replace("\t", "\\t").replace("\r", "\\r")
+    return f'"{out}"'
+
+
+def serialize_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return _escape_string(value)
+    if value is None:
+        return '""'
+    # fallback: JSON
+    return _escape_string(json.dumps(value, ensure_ascii=False))
+
+
+def serialize_attrs(attrs: Dict[str, Any]) -> str:
+    """Serialise a dict to ``key:"value", key2:val2`` form."""
+
+    parts = []
+    for k, v in attrs.items():
+        parts.append(f"{k}:{serialize_value(v)}")
+    return ", ".join(parts)
+
+
+def serialize_attrs_pos(attrs: Dict[str, Any], contract: AttrsPosContract) -> str:
+    """Serialise positional attrs using the contract's field order.
+
+    Re-audit H-RA-05: ``|`` is the delimiter and CANNOT appear inside
+    values.  We raise :class:`~cortex.core.errors.InvalidValueError`
+    if any value contains ``|`` — the caller should use ``attrs`` form
+    instead for values that need pipes.
+    """
+
+    from .errors import InvalidValueError
+    parts = []
+    for field_name in contract.fields:
+        v = attrs.get(field_name)
+        if v is None:
+            parts.append("")
+            continue
+        s = serialize_value(v)
+        # Detect literal pipe inside the serialised value (after quote stripping)
+        # The serialised form is "..." for strings; check the inner content.
+        inner = s
+        if len(inner) >= 2 and inner[0] == '"' and inner[-1] == '"':
+            inner = inner[1:-1]
+        if "|" in inner:
+            raise InvalidValueError(
+                f"attrs-pos value for field {field_name!r} contains '|' "
+                f"({inner!r}); use 'attrs' type instead — pipes are forbidden "
+                "in attrs-pos values per SKILL.md §4.3"
+            )
+        parts.append(s)
+    return " | ".join(parts)
+
+
+def serialize_entry_value(value: Any, type_: str) -> str:
+    """Serialise the *body* of an entry (content between braces)."""
+
+    if type_ == "attrs":
+        return serialize_attrs(value) if isinstance(value, dict) else ""
+    if type_ == "attrs-pos":
+        # Without a contract we fall back to attrs form
+        return serialize_attrs(value) if isinstance(value, dict) else ""
+    if type_ == "cuerpo":
+        return str(value) if value is not None else ""
+    if type_ == "bloque":
+        text = str(value) if value is not None else ""
+        # Ensure a leading newline if the bloque spans multiple lines
+        if "\n" in text:
+            return "\n" + text + "\n"
+        return text
+    if type_ == "relación":
+        return str(value) if value is not None else ""
+    # Unknown type — fallback to attrs
+    return serialize_attrs(value) if isinstance(value, dict) else str(value or "")
+
+
+def serialize_entry(entry: Entry, glossary: Glossary | None = None) -> str:
+    """Serialise a single :class:`Entry` to canonical ``.cortex`` text."""
+
+    if entry.type == "attrs-pos" and glossary is not None:
+        contract = glossary.contract_for(entry.sigil)
+        if contract is not None:
+            body = serialize_attrs_pos(entry.value, contract)
+            return f"{entry.sigil}:{entry.name}{{{body}}}"
+    body = serialize_entry_value(entry.value, entry.type)
+    if entry.type == "bloque" and "\n" in body:
+        # Multi-line bloque: put braces on their own lines for readability
+        # Ensure body starts and ends with newline
+        if not body.startswith("\n"):
+            body = "\n" + body
+        if not body.endswith("\n"):
+            body = body + "\n"
+        return f"{entry.sigil}:{entry.name}{{{body}}}"
+    return f"{entry.sigil}:{entry.name}{{{body}}}"
+
+
+# ---------------------------------------------------------------------------
+# Glossary serialisation
+# ---------------------------------------------------------------------------
+
+def serialize_glossary(glossary: Glossary) -> str:
+    """Serialise the ``$0`` section.
+
+    Uses the pipe-separated comment form (canonical SKILL.md template).
+    All declaration lines are prefixed with ``#`` so the lexer classifies
+    them as comments and preserves them verbatim for roundtrip.
+    """
+
+    lines: List[str] = []
+    lines.append("# -- $0: MINIMAL LOCAL GLOSSARY --")
+    lines.append("# Required: every .cortex artifact must be locally self-contained.")
+    lines.append("# Sigil | Name | Type | Risk | Cognitive Layer | Description")
+    # Order sigils deterministically: canonical ones first, then custom
+    canonical_order = [
+        "IDN", "DOM", "KNW", "REF", "TAG", "AXM", "CNST", "!",
+        "CLAIM", "LIM", "AUD", "RSK", "FCS", "OBJ", "WRK", "STP",
+        "NXT", "SES", "LNG", "DIAG", "HDL", "PFL", "DEP", "DESC", "ERR",
+    ]
+    sigils_in_glossary = list(glossary.sigils.values())
+    # Sort: canonical first (in canonical order), then custom alphabetically
+    def _sort_key(sd: SigilDef) -> tuple:
+        if sd.sigil in canonical_order:
+            return (0, canonical_order.index(sd.sigil))
+        return (1, sd.sigil)
+    sigils_in_glossary.sort(key=_sort_key)
+    for sd in sigils_in_glossary:
+        lines.append(
+            f"# {sd.sigil:<5} | {sd.name:<10} | {sd.type:<10} | {sd.risk:<1} | "
+            f"{sd.layer:<14} | {sd.description}"
+        )
+    # Types
+    lines.append("#")
+    lines.append("# Types:")
+    for td in glossary.types.values():
+        lines.append(f"# {td.name} = {td.description}")
+    # Micro-tokens
+    lines.append("#")
+    lines.append("# Micro-glossary:")
+    micro_items = list(glossary.micro.values())
+    # Sort: canonical first (in canonical order), then custom
+    canonical_micro_order = list(CANONICAL_MICRO_ORDER)
+    def _micro_sort_key(md: MicroDef) -> tuple:
+        if md.token in canonical_micro_order:
+            return (0, canonical_micro_order.index(md.token))
+        return (1, md.token)
+    micro_items.sort(key=_micro_sort_key)
+    if micro_items:
+        line_parts = [f"{md.token}={md.value}" for md in micro_items]
+        # Group 4 per line for readability
+        for i in range(0, len(line_parts), 4):
+            lines.append("# " + " ".join(line_parts[i : i + 4]))
+    # Contracts
+    if glossary.contracts:
+        lines.append("#")
+        lines.append("# Positional contracts:")
+        for c in glossary.contracts.values():
+            lines.append(f"# contract: {c.sigil} | " + " | ".join(c.fields))
+    return "\n".join(lines)
+
+
+# Canonical order for micro-tokens (Section 4.1.1)
+CANONICAL_MICRO_ORDER = [
+    "cur", "pln", "fut", "blk", "min", "rec", "wrk", "full", "ok", "fail", "part",
+]
+
+
+# ---------------------------------------------------------------------------
+# Document serialisation
+# ---------------------------------------------------------------------------
+
+def write_cortex(doc: CortexDocument) -> str:
+    """Serialise a :class:`CortexDocument` to canonical ``.cortex`` text.
+
+    The ``$0`` glossary section is ALWAYS regenerated from
+    ``doc.glossary`` so mutations are reflected in the output.  Other
+    sections preserve their comments verbatim.
+    """
+
+    out: List[str] = []
+    # $0 first — always regenerated from glossary
+    if doc.sections and doc.sections[0].id == "$0":
+        sec0 = doc.sections[0]
+        glossary_text = serialize_glossary(doc.glossary)
+        header = "$0"
+        if sec0.title:
+            header = f"$0: {sec0.title}"
+        out.append(header)
+        out.append("")
+        out.append(glossary_text)
+        out.append("")
+        # Append any non-glossary entries from $0 section (rare, but supported)
+        for entry in sec0.entries:
+            if entry.sigil in {"GSIG", "GTYP", "GMIC", "GCON"}:
+                continue
+            out.append(serialize_entry(entry, doc.glossary))
+        out.append("")
+
+    # Other sections
+    for sec in doc.sections[1:]:
+        header = sec.id
+        if sec.title:
+            header = f"{sec.id}: {sec.title}"
+        out.append(header)
+        out.append("")
+        # Preserve section comments (after header, before entries)
+        if sec.comments:
+            out.extend(sec.comments)
+            out.append("")
+        for entry in sec.entries:
+            out.append(serialize_entry(entry, doc.glossary))
+        out.append("")
+
+    # Trailing newline
+    text = "\n".join(out).rstrip("\n") + "\n"
+    return text

cortex/crud/__init__.py

@@ -0,0 +1,17 @@
+"""CRUD package — selectors, mutations, atomic transactions."""
+
+from .selectors import Selector, parse_selector, select, select_one
+from .mutations import (
+    add_entry, update_entry, delete_entry, move_entry,
+    add_sigil_to_glossary, update_sigil_in_glossary, delete_sigil_from_glossary,
+    add_micro_to_glossary, update_micro_in_glossary, delete_micro_from_glossary,
+)
+from .transactions import atomic_write_cortex, atomic_write_text, WriteResult
+
+__all__ = [
+    "Selector", "parse_selector", "select", "select_one",
+    "add_entry", "update_entry", "delete_entry", "move_entry",
+    "add_sigil_to_glossary", "update_sigil_in_glossary", "delete_sigil_from_glossary",
+    "add_micro_to_glossary", "update_micro_in_glossary", "delete_micro_from_glossary",
+    "atomic_write_cortex", "atomic_write_text", "WriteResult",
+]