codec-cortex 0.3.2__py3-none-any.whl

cortex/crud/mutations.py

@@ -0,0 +1,342 @@
+"""Mutations — add / update / delete / move entries in a :class:`CortexDocument`.
+
+All mutations operate on the AST in memory; persistence (atomic write)
+is handled by :mod:`cortex.crud.transactions`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Union
+
+from ..core.ast import CortexDocument, Entry, normalize_section_id
+from ..core.errors import (
+    DuplicateEntryError,
+    InvalidValueError,
+    NotFoundError,
+    ProtectedEntryError,
+)
+from ..core.parser import build_entry_from_value, parse_attrs_body
+from ..core.validator import is_protected_entry
+from .selectors import select_one
+
+
+# ---------------------------------------------------------------------------
+# Add
+# ---------------------------------------------------------------------------
+
+def add_entry(
+    doc: CortexDocument,
+    section: str,
+    sigil: str,
+    name: str,
+    value: Union[str, Dict[str, Any]],
+    *,
+    create_section: bool = False,
+    allow_duplicate: bool = False,
+    allow_unknown_sigil: bool = False,
+) -> Entry:
+    """Add a new entry to ``doc``.
+
+    ``value`` may be:
+      - a dict (used as-is for attrs)
+      - a string (parsed as attrs body for attrs, or stored verbatim for
+        cuerpo / bloque)
+
+    Re-audit H-RA-06: by default the sigil MUST exist in ``$0``.  If it
+    doesn't, :class:`~cortex.core.errors.UnknownSigilError` is raised.
+    Pass ``allow_unknown_sigil=True`` (or CLI ``--allow-unknown-sigil``)
+    to permit undeclared sigils (recovery/debug scenarios).
+
+    v1.1.5 P0-4: adding operational entries to ``$0`` is rejected.
+    ``$0`` is structural metadata only (SKILL.md §4.1); only glossary
+    declaration sigils (GSIG/GTYP/GMIC/GCON) are allowed there.
+    """
+
+    # Resolve section
+    sec_id = normalize_section_id(section)
+
+    # v1.1.5 P0-4: $0 is reserved for glossary declarations, not memory.
+    GLOSSARY_ENTRY_SIGILS = frozenset({"GSIG", "GTYP", "GMIC", "GCON"})
+    if sec_id == "$0" and sigil not in GLOSSARY_ENTRY_SIGILS:
+        from ..core.errors import CortexError
+        raise CortexError(
+            "E033_ZERO_SECTION_MEMORY_ENTRY",
+            f"$0 MUST NOT contain operational entries; refusing to add "
+            f"{sigil}:{name} to $0.  $0 is structural metadata only "
+            "(SKILL.md §4.1).  Use $1 or later sections for operational memory.",
+        )
+
+    target = doc.get_section(sec_id)
+    if target is None:
+        if not create_section:
+            raise NotFoundError(f"section {sec_id}")
+        target = doc.get_or_create_section(sec_id)
+
+    # Check for duplicates
+    existing = doc.find_entries(sigil=sigil, name=name, section=sec_id)
+    if existing and not allow_duplicate:
+        raise DuplicateEntryError(sigil, name, section=sec_id)
+
+    # Determine type from glossary
+    sigil_def = doc.glossary.sigils.get(sigil)
+    if sigil_def is None and not allow_unknown_sigil:
+        from ..core.errors import UnknownSigilError
+        raise UnknownSigilError(sigil)
+    type_ = sigil_def.type if sigil_def else "attrs"
+
+    # Build value
+    if isinstance(value, dict):
+        v = value
+    elif isinstance(value, str):
+        if type_ == "attrs":
+            try:
+                v = parse_attrs_body(value)
+            except Exception as e:
+                raise InvalidValueError(f"cannot parse attrs body: {e}")
+        elif type_ in ("cuerpo", "bloque", "relación"):
+            v = value
+        else:
+            v = value
+    else:
+        raise InvalidValueError(f"unsupported value type: {type(value).__name__}")
+
+    entry = build_entry_from_value(sec_id, sigil, name, type_, v)
+    target.entries.append(entry)
+    return entry
+
+
+# ---------------------------------------------------------------------------
+# Update
+# ---------------------------------------------------------------------------
+
+def update_entry(
+    doc: CortexDocument,
+    selector: str,
+    *,
+    set_: Optional[Dict[str, Any]] = None,
+    replace_body: Optional[str] = None,
+    append: bool = False,
+) -> Entry:
+    """Update an entry selected by ``selector``.
+
+    For ``attrs`` / ``attrs-pos`` entries, ``set_`` merges key/value
+    pairs into the existing dict.  For ``cuerpo`` / ``bloque`` entries,
+    ``replace_body`` replaces the body (or appends if ``append=True``).
+    """
+
+    entry = select_one(doc, selector)
+    if entry.type in ("attrs", "attrs-pos"):
+        if set_ is None:
+            return entry
+        if not isinstance(entry.value, dict):
+            entry.value = {}
+        for k, v in set_.items():
+            entry.value[k] = v
+        # Recompute raw + hash
+        from ..core.writer import serialize_entry_value
+        body = serialize_entry_value(entry.value, entry.type)
+        entry.raw = f"{entry.sigil}:{entry.name}{{{body}}}"
+        from ..core.ast import compute_entry_hash
+        entry.hash = compute_entry_hash(entry)
+        entry.entry_id = entry.hash
+        return entry
+    elif entry.type in ("cuerpo", "bloque", "relación"):
+        if replace_body is None:
+            return entry
+        if append:
+            entry.value = str(entry.value or "") + "\n" + str(replace_body)
+        else:
+            entry.value = str(replace_body)
+        from ..core.writer import serialize_entry_value
+        body = serialize_entry_value(entry.value, entry.type)
+        entry.raw = f"{entry.sigil}:{entry.name}{{{body}}}"
+        from ..core.ast import compute_entry_hash
+        entry.hash = compute_entry_hash(entry)
+        entry.entry_id = entry.hash
+        return entry
+    else:
+        raise InvalidValueError(f"cannot update entry of type {entry.type!r}")
+
+
+# ---------------------------------------------------------------------------
+# Delete
+# ---------------------------------------------------------------------------
+
+def delete_entry(
+    doc: CortexDocument,
+    selector: str,
+    *,
+    force: bool = False,
+) -> Entry:
+    """Delete the entry matching ``selector`` from ``doc``.
+
+    Protected entries (P0 / ``severity:blocking`` / ``survive:min`` on
+    FCS, OBJ, CNST) require ``force=True``.
+    """
+
+    entry = select_one(doc, selector)
+    if is_protected_entry(entry) and not force:
+        raise ProtectedEntryError(entry.sigil, entry.name)
+
+    sec = doc.get_section(entry.section)
+    if sec is None:
+        raise NotFoundError(f"section {entry.section}")
+    sec.entries = [e for e in sec.entries if not (
+        e.sigil == entry.sigil and e.name == entry.name and e.section == entry.section
+    )]
+    return entry
+
+
+# ---------------------------------------------------------------------------
+# Move
+# ---------------------------------------------------------------------------
+
+def move_entry(
+    doc: CortexDocument,
+    selector: str,
+    to_section: str,
+) -> Entry:
+    """Move an entry from its current section to ``to_section``."""
+
+    entry = select_one(doc, selector)
+    old_sec = doc.get_section(entry.section)
+    if old_sec is None:
+        raise NotFoundError(f"section {entry.section}")
+    new_sec_id = normalize_section_id(to_section)
+    new_sec = doc.get_section(new_sec_id)
+    if new_sec is None:
+        new_sec = doc.get_or_create_section(new_sec_id)
+    # Remove from old
+    old_sec.entries = [e for e in old_sec.entries if not (
+        e.sigil == entry.sigil and e.name == entry.name and e.section == entry.section
+    )]
+    # Add to new
+    entry.section = new_sec_id
+    new_sec.entries.append(entry)
+    return entry
+
+
+# ---------------------------------------------------------------------------
+# Glossary mutations
+# ---------------------------------------------------------------------------
+
+def add_sigil_to_glossary(
+    doc: CortexDocument,
+    sigil: str,
+    name: str,
+    type_: str,
+    risk: str = "M",
+    layer: str = "Semantic",
+    description: str = "",
+    *,
+    force_governance: bool = False,
+) -> None:
+    """Add a new sigil to ``$0``.
+
+    Refuses to silently REDEFINE a sigil that's already declared in $0.
+    Canonical sigils that are not yet declared MAY be added (the user is
+    extending a minimal glossary to include canonical sigils they need).
+    ``force_governance`` is required only to redefine an existing sigil
+    with a different type/contract.
+    """
+
+    from ..core.errors import ProtectedSigilError
+    existing = doc.glossary.sigils.get(sigil)
+    if existing is not None:
+        # Refuse to redefine without explicit governance override
+        if not force_governance:
+            raise ProtectedSigilError(sigil)
+        # With --force-governance, allow replacement if type is unchanged
+        if existing.type != type_:
+            raise ProtectedSigilError(sigil)
+    from ..core.ast import SigilDef
+    doc.glossary.add_sigil(SigilDef(
+        sigil=sigil, name=name, type=type_, risk=risk,
+        layer=layer, description=description,
+    ))
+
+
+def update_sigil_in_glossary(
+    doc: CortexDocument,
+    sigil: str,
+    *,
+    description: Optional[str] = None,
+    risk: Optional[str] = None,
+    layer: Optional[str] = None,
+    force_governance: bool = False,
+) -> None:
+    """Update a sigil's metadata (NOT its type if used)."""
+
+    sd = doc.glossary.sigils.get(sigil)
+    if sd is None:
+        raise NotFoundError(f"sigil {sigil}")
+    if description is not None:
+        sd.description = description
+    if risk is not None:
+        sd.risk = risk
+    if layer is not None:
+        sd.layer = layer
+
+
+def delete_sigil_from_glossary(
+    doc: CortexDocument,
+    sigil: str,
+    *,
+    force: bool = False,
+) -> None:
+    """Remove a sigil from ``$0``.
+
+    Refuses to remove sigils that are used by entries (unless ``force``).
+    """
+
+    from ..core.errors import SigilInUseError
+    usage = sum(1 for _, e in doc.iter_entries() if e.sigil == sigil)
+    if usage > 0 and not force:
+        raise SigilInUseError(sigil, usage)
+    doc.glossary.sigils.pop(sigil, None)
+
+
+# ---------------------------------------------------------------------------
+# Micro-token mutations
+# ---------------------------------------------------------------------------
+
+def add_micro_to_glossary(
+    doc: CortexDocument,
+    token: str,
+    value: str,
+) -> None:
+    from ..core.ast import MicroDef
+    existing = doc.glossary.micro.get(token)
+    if existing is not None and existing.value != value:
+        from ..core.errors import CortexError
+        raise CortexError(
+            "E021_INVALID_VALUE",
+            f"micro-token {token!r} already declared with value {existing.value!r}",
+        )
+    doc.glossary.add_micro(MicroDef(token=token, value=value))
+
+
+def update_micro_in_glossary(
+    doc: CortexDocument,
+    token: str,
+    value: str,
+) -> None:
+    existing = doc.glossary.micro.get(token)
+    if existing is None:
+        from ..core.errors import NotFoundError
+        raise NotFoundError(f"micro-token {token}")
+    existing.value = value
+
+
+def delete_micro_from_glossary(
+    doc: CortexDocument,
+    token: str,
+    *,
+    force: bool = False,
+) -> None:
+    from ..glossary.resolver import is_micro_used
+    from ..core.errors import MicroInUseError
+    all_entries = [e for _, e in doc.iter_entries()]
+    if is_micro_used(all_entries, token) and not force:
+        raise MicroInUseError(token)
+    doc.glossary.micro.pop(token, None)

cortex/crud/selectors.py

@@ -0,0 +1,95 @@
+"""Selectors — locate entries in a :class:`CortexDocument`.
+
+Selector grammar (Section 12.1 of the spec):
+
+    $SECTION/SIGIL:NAME     exact match
+    SIGIL:NAME              match any section
+    SIGIL:*                 all entries with that sigil
+    $SECTION/*              all entries in a section
+
+Wildcards ``*`` are supported on name and section.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..core.ast import CortexDocument, Entry, normalize_section_id
+from ..core.errors import AmbiguousSelectorError, NotFoundError
+
+
+@dataclass
+class Selector:
+    section: Optional[str]   # "$2" or "*" or None
+    sigil: str               # "FCS" or "*"
+    name: str                # "primary" or "*"
+
+    def __str__(self) -> str:
+        s = ""
+        if self.section:
+            s += f"{self.section}/"
+        s += f"{self.sigil}:{self.name}"
+        return s
+
+
+def parse_selector(s: str) -> Selector:
+    """Parse a selector string into a :class:`Selector`."""
+
+    s = s.strip()
+    if not s:
+        raise ValueError("empty selector")
+    # Split on /
+    if "/" in s:
+        section_part, rest = s.split("/", 1)
+    else:
+        section_part, rest = None, s
+    # section_part may be "$2" or "*"
+    if section_part == "*":
+        section = "*"
+    elif section_part:
+        section = normalize_section_id(section_part)
+    else:
+        section = None
+    # rest is "SIGIL:NAME" or "SIGIL:*" or "*"
+    if ":" in rest:
+        sigil, name = rest.split(":", 1)
+    else:
+        sigil, name = rest, "*"
+    if sigil == "":
+        sigil = "*"
+    if name == "":
+        name = "*"
+    return Selector(section=section, sigil=sigil, name=name)
+
+
+def select(doc: CortexDocument, selector_str: str) -> List[Entry]:
+    """Return all entries that match ``selector_str``."""
+
+    sel = parse_selector(selector_str)
+    out: List[Entry] = []
+    for sec, entry in doc.iter_entries():
+        if sel.section and sel.section != "*":
+            if sec.id != normalize_section_id(sel.section):
+                continue
+        if sel.sigil != "*" and entry.sigil != sel.sigil:
+            continue
+        if sel.name != "*" and entry.name != sel.name:
+            continue
+        out.append(entry)
+    return out
+
+
+def select_one(doc: CortexDocument, selector_str: str) -> Entry:
+    """Return exactly one matching entry or raise.
+
+    Raises :class:`NotFoundError` if 0 matches and
+    :class:`AmbiguousSelectorError` if >1 matches.
+    """
+
+    matches = select(doc, selector_str)
+    if not matches:
+        raise NotFoundError(selector_str)
+    if len(matches) > 1:
+        raise AmbiguousSelectorError(selector_str, len(matches))
+    return matches[0]

cortex/crud/transactions.py

@@ -0,0 +1,213 @@
+"""Transactions — atomic write with backup, dry-run and diff support.
+
+Per Section 15 of the spec:
+
+    atomic_write(path, content):
+        tmp = path + ".tmp"
+        bak = path + ".bak"
+        write tmp
+        parse tmp
+        validate tmp
+        copy path to bak
+        replace path with tmp
+
+The writer NEVER overwrites the target if validation fails.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from typing import Optional
+
+from ..core.ast import CortexDocument
+from ..core.errors import AtomicWriteError
+from ..core.parser import parse_cortex
+from ..core.writer import write_cortex
+from ..core.validator import validate
+
+
+@dataclass
+class WriteResult:
+    path: str
+    backup: Optional[str]
+    bytes_written: int
+    diagnostics: list
+    dry_run: bool
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "backup": self.backup,
+            "bytes_written": self.bytes_written,
+            "diagnostics": self.diagnostics,
+            "dry_run": self.dry_run,
+        }
+
+
+def atomic_write_cortex(
+    doc: CortexDocument,
+    path: str,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+    keep_backup: bool = True,
+    unsafe_allow_secret_forensics: bool = False,
+) -> WriteResult:
+    """Serialise ``doc`` and atomically write it to ``path``.
+
+    The workflow:
+      1. Serialise to canonical text.
+      2. Re-parse the text and validate.
+      3. If validation produces error-severity diagnostics and ``force``
+         is False, abort.
+      4. Write to ``path + ".tmp"``.
+      5. Copy the original file to ``path + ".bak"`` (if it existed).
+      6. Rename ``.tmp`` → ``path``.
+      7. If ``dry_run`` is True, do not touch the filesystem; just report.
+
+    v1.1.3 P0-2: ``unsafe_allow_secret_forensics=True`` allows bypassing
+    ``E031_SECRET_NOT_BYPASSABLE`` for forensic recovery ONLY.  It does
+    NOT bypass ``E032_CRITICAL_SIGIL_INCOMPLETE``.
+    """
+
+    text = write_cortex(doc)
+    # Re-parse to verify roundtrip-ability
+    reparsed = parse_cortex(text, path=path)
+    diagnostics = validate(reparsed)
+    errors = [d for d in diagnostics if d.get("severity") == "error"]
+    # v1.1.3 P0-2/P0-3: non-bypassable errors (secrets, critical sigil
+    # incompleteness) CANNOT be overridden by --force.
+    non_bypassable = [d for d in errors if d.get("bypassable") is False]
+    bypassable = [d for d in errors if d.get("bypassable") is not False]
+    # v1.1.3 P0-2: --unsafe-allow-secret-forensics can bypass secret errors ONLY
+    if unsafe_allow_secret_forensics:
+        non_bypassable = [
+            d for d in non_bypassable
+            if d.get("code") != "E031_SECRET_NOT_BYPASSABLE"
+        ]
+    if non_bypassable:
+        raise AtomicWriteError(
+            f"{len(non_bypassable)} non-bypassable error(s) prevent write; "
+            "--force cannot override security/governance rules: "
+            + "; ".join(d.get("code", "") + ": " + d.get("message", "")[:80] for d in non_bypassable[:3]),
+        )
+    if bypassable and not force:
+        raise AtomicWriteError(
+            f"validation failed with {len(bypassable)} bypassable error(s); "
+            "use --force to override",
+        )
+
+    if dry_run:
+        return WriteResult(
+            path=path,
+            backup=None,
+            bytes_written=len(text.encode("utf-8")),
+            diagnostics=diagnostics,
+            dry_run=True,
+        )
+
+    # Ensure parent directory exists
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+
+    tmp_path = path + ".tmp"
+    bak_path = path + ".bak"
+
+    # Write tmp
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as f:
+            f.write(text)
+    except OSError as e:
+        raise AtomicWriteError(f"cannot write tmp file: {e}")
+
+    # Backup original
+    backup_created = None
+    if keep_backup and os.path.exists(path):
+        try:
+            shutil.copy2(path, bak_path)
+            backup_created = bak_path
+        except OSError as e:
+            # Clean up tmp
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+            raise AtomicWriteError(f"cannot create backup: {e}")
+
+    # Rename tmp → path
+    try:
+        os.replace(tmp_path, path)
+    except OSError as e:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise AtomicWriteError(f"cannot replace target file: {e}")
+
+    return WriteResult(
+        path=path,
+        backup=backup_created,
+        bytes_written=len(text.encode("utf-8")),
+        diagnostics=diagnostics,
+        dry_run=False,
+    )
+
+
+def atomic_write_text(
+    text: str,
+    path: str,
+    *,
+    dry_run: bool = False,
+    keep_backup: bool = True,
+) -> WriteResult:
+    """Atomic write for arbitrary text (used by render/compile)."""
+
+    if dry_run:
+        return WriteResult(
+            path=path, backup=None,
+            bytes_written=len(text.encode("utf-8")),
+            diagnostics=[], dry_run=True,
+        )
+
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+
+    tmp_path = path + ".tmp"
+    bak_path = path + ".bak"
+
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as f:
+            f.write(text)
+    except OSError as e:
+        raise AtomicWriteError(f"cannot write tmp file: {e}")
+
+    backup_created = None
+    if keep_backup and os.path.exists(path):
+        try:
+            shutil.copy2(path, bak_path)
+            backup_created = bak_path
+        except OSError as e:
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+            raise AtomicWriteError(f"cannot create backup: {e}")
+
+    try:
+        os.replace(tmp_path, path)
+    except OSError as e:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise AtomicWriteError(f"cannot replace target file: {e}")
+
+    return WriteResult(
+        path=path, backup=backup_created,
+        bytes_written=len(text.encode("utf-8")),
+        diagnostics=[], dry_run=False,
+    )

cortex/glossary/__init__.py

@@ -0,0 +1,21 @@
+"""Glossary package — minimal sigil sets, resolver, contracts."""
+
+from .model import minimal_glossary, add_sigil, add_micro, add_contract, sigils_in_use
+from .minimal import (
+    brain_sigils, skill_sigils, package_sigils, generic_sigils, hdL_contract,
+)
+from .resolver import (
+    is_canonical, is_declared, type_of, contract_of,
+    expand_micro, sigil_usage_count, is_micro_used,
+)
+from .contracts import (
+    get_contract, require_contract, declare_contract, DEFAULT_CONTRACTS,
+)
+
+__all__ = [
+    "minimal_glossary", "add_sigil", "add_micro", "add_contract", "sigils_in_use",
+    "brain_sigils", "skill_sigils", "package_sigils", "generic_sigils", "hdL_contract",
+    "is_canonical", "is_declared", "type_of", "contract_of",
+    "expand_micro", "sigil_usage_count", "is_micro_used",
+    "get_contract", "require_contract", "declare_contract", "DEFAULT_CONTRACTS",
+]

cortex/glossary/contracts.py

@@ -0,0 +1,37 @@
+"""Positional contracts for ``attrs-pos`` sigils.
+
+A contract is the ordered list of field names that the parser must use
+when splitting a positional body.  Contracts live in ``$0`` and are
+declared via ``# contract: SIGIL | field1 | field2 | ...`` or via
+explicit ``GCON:SIGIL{sigil:"SIGIL", fields:"f1|f2"}`` entries.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..core.ast import AttrsPosContract, Glossary
+from ..core.errors import AttrsPosContractMissingError
+
+
+def get_contract(glossary: Glossary, sigil: str) -> Optional[AttrsPosContract]:
+    return glossary.contracts.get(sigil)
+
+
+def require_contract(glossary: Glossary, sigil: str) -> AttrsPosContract:
+    c = get_contract(glossary, sigil)
+    if c is None:
+        raise AttrsPosContractMissingError(sigil)
+    return c
+
+
+def declare_contract(glossary: Glossary, sigil: str, fields: List[str]) -> AttrsPosContract:
+    c = AttrsPosContract(sigil=sigil, fields=list(fields))
+    glossary.add_contract(c)
+    return c
+
+
+# Default contracts for canonical attrs-pos sigils (Section 6)
+DEFAULT_CONTRACTS = {
+    "HDL": ["operation", "status", "requires"],
+}