core-runtime 0.1.1__py3-none-any.whl

shared/infrastructure/intent/operational_mode.py

@@ -0,0 +1,66 @@
+# src/shared/infrastructure/intent/operational_mode.py
+"""
+Operational-mode accessor (ADR-079 D4 placeholder).
+
+The chokepoint reads ``current_mode()`` once per ``check_transaction``
+call to decide whether mode-conditional capability entries authorize
+a write. The interface this module declares is stable; the implementation
+in this file is the **placeholder** ADR-079 D4 documents — env-var
+sourced, default-on-uncertainty=`live`.
+
+Issue #492 will replace the body with provenance-guaranteed source
+resolution (signed manifest, bootstrap config, conflict-resolution rules).
+Consumers depend on the *interface*, not the *implementation* — the
+accessor's signature does not change when #492 lands.
+
+Paper §6's "default on uncertainty is *live*" semantics fail closed: a
+forged dev signal requires successfully setting ``CORE_OPERATIONAL_MODE``
+to the exact string ``"dev"``, not merely being in the absence of
+provenance. Any other value — missing, empty, mistyped, mixed-case —
+collapses to ``"live"``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_MODE_ENV_VAR = "CORE_OPERATIONAL_MODE"
+_VALID_MODES: frozenset[str] = frozenset({"dev", "live"})
+
+_first_call_logged = False
+
+
+# ID: 50389c43-7c80-4e9a-a8cc-01b27535ca8a
+def current_mode() -> Literal["dev", "live"]:
+    """
+    Return the current operational mode.
+
+    Reads ``CORE_OPERATIONAL_MODE``. Returns ``"dev"`` only when the env
+    var holds the exact string ``"dev"``; returns ``"live"`` for the
+    exact string ``"live"`` and for every other case (missing, empty,
+    mistyped) per paper §6.
+
+    Logs at INFO on first call only — the resolved value and the source
+    consulted — so the operational signal is observable without
+    per-call noise.
+    """
+    global _first_call_logged
+    raw = os.environ.get(_MODE_ENV_VAR)
+    if raw in _VALID_MODES:
+        resolved: Literal["dev", "live"] = "dev" if raw == "dev" else "live"
+        source = _MODE_ENV_VAR
+    else:
+        resolved = "live"
+        source = "default" if raw is None else f"{_MODE_ENV_VAR}=<rejected:{raw!r}>"
+
+    if not _first_call_logged:
+        logger.info("Operational mode resolved: %s (source: %s).", resolved, source)
+        _first_call_logged = True
+
+    return resolved

shared/infrastructure/intent/task_type_phases.py

@@ -0,0 +1,180 @@
+# src/shared/infrastructure/intent/task_type_phases.py
+"""
+Task-type to governance-phase mapping helper.
+
+Single source of truth for the ExecutionTask.task_type vocabulary and
+its mapping to the governance PhaseType. Both the mapping and the
+closed vocabulary are owned by
+.intent/enforcement/config/task_type_phases.yaml.
+
+Authority: policy. The governing document is
+.intent/enforcement/config/task_type_phases.yaml, accessed exclusively
+via IntentRepository. No other module may hardcode the task_type ->
+phase mapping — all call sites route through this helper. See ADR-004.
+
+The _FALLBACK_* constants below are last-resort graceful degradation
+for the narrow case where the policy document cannot be loaded (e.g.
+bootstrap races, corrupt YAML). They MUST NOT be treated as
+defaults-in-logic — when the policy loads successfully, it always wins.
+
+LAYER: shared/infrastructure/intent — pure helper. No imports from
+will/, body/, or cli/.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from shared.infrastructure.intent.errors import GovernanceError
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.infrastructure.context.models import PhaseType
+
+
+logger = getLogger(__name__)
+
+
+_FALLBACK_DEFAULT_PHASE = "execution"
+_FALLBACK_MAPPING: dict[str, str] = {
+    "code_generation": "execution",
+    "code_modification": "execution",
+    "test_generation": "audit",
+    "test.generate": "audit",
+    "conversational": "runtime",
+}
+
+
+def _valid_phases() -> frozenset[str]:
+    """Canonical `component_phase` membership from .intent/META/enums.json.
+
+    Sourced from the canonical enum store rather than inlined here so the
+    Python and JSON schema sides cannot drift (closed-enum discipline,
+    issue #460). Lazy so callers reaching this module at import time of
+    other modules do not force IntentRepository construction.
+    """
+    from shared.infrastructure.intent.canonical_enums import get_enum_members
+
+    return get_enum_members("component_phase")
+
+
+def _validate_config(config: dict[str, Any]) -> None:
+    """
+    Validate at load time that every phase value in the config is a
+    member of the canonical `component_phase` enum. Raises ValueError
+    with a clear message on the first offending key/value encountered.
+    """
+    valid = _valid_phases()
+    default_phase = config.get("default_phase")
+    if default_phase is None or default_phase not in valid:
+        raise ValueError(
+            f"task_type_phases: default_phase {default_phase!r} is not a "
+            f"valid PhaseType; allowed values are {sorted(valid)}"
+        )
+
+    mapping = config.get("mapping")
+    if not isinstance(mapping, dict):
+        raise ValueError(
+            "task_type_phases: 'mapping' must be a dict of task_type -> phase"
+        )
+
+    for task_type, phase in mapping.items():
+        if phase not in valid:
+            raise ValueError(
+                f"task_type_phases: mapping[{task_type!r}] = {phase!r} is not "
+                f"a valid PhaseType; allowed values are {sorted(valid)}"
+            )
+
+
+# ID: c1d2e3f4-a5b6-4708-9c1d-2e3f4a5b6c7d
+def load_task_type_phases() -> dict[str, Any]:
+    """
+    Load .intent/enforcement/config/task_type_phases.yaml via IntentRepository.
+
+    Returns the parsed policy dict on success. On any failure — missing
+    file, parse error, unexpected top-level type — returns fallback
+    defaults and logs a warning so callers degrade gracefully rather
+    than halting.
+
+    The loader validates every phase value against the canonical
+    `component_phase` enum (sourced from `.intent/META/enums.json`)
+    before returning. A YAML that maps a task_type to a phase outside
+    that enum raises ValueError at load time, not at the call site.
+    If the canonical enum is unreachable or empty, GovernanceError
+    propagates (no silent fallback — closed-enum discipline, #460).
+    """
+    try:
+        from shared.infrastructure.intent.intent_repository import (
+            get_intent_repository,
+        )
+
+        repo = get_intent_repository()
+        config_path = repo.resolve_rel("enforcement/config/task_type_phases.yaml")
+        config = repo.load_document(config_path)
+        if isinstance(config, dict):
+            _validate_config(config)
+            return config
+        logger.warning(
+            "task_type_phases: task_type_phases.yaml did not parse as a dict "
+            "— using fallback defaults."
+        )
+    except ValueError:
+        raise
+    except GovernanceError:
+        # Canonical enum store unreachable or empty — propagate per
+        # closed-enum discipline (issue #460). Falling back here would
+        # silently mask a META authoring failure.
+        raise
+    except Exception as exc:
+        logger.warning(
+            "task_type_phases: could not load .intent/enforcement/config/"
+            "task_type_phases.yaml (%s) — using fallback defaults.",
+            exc,
+        )
+    return {
+        "default_phase": _FALLBACK_DEFAULT_PHASE,
+        "mapping": dict(_FALLBACK_MAPPING),
+    }
+
+
+# ID: d2e3f4a5-b6c7-4819-ad2e-3f4a5b6c7d8e
+def resolve_phase(
+    task_type: str,
+    config: dict[str, Any] | None = None,
+) -> PhaseType:
+    """
+    Return the governance phase for a task_type.
+
+    Falls back to config['default_phase'] when task_type is not in the
+    mapping. If config is None, load_task_type_phases() is called.
+
+    The returned value is typed as PhaseType: the loader has already
+    validated that every phase value is a member of the PhaseType
+    Literal set, so callers may pass the result directly to
+    ContextBuildRequest(phase=...) without a type: ignore.
+    """
+    if config is None:
+        config = load_task_type_phases()
+
+    mapping = config.get("mapping", {})
+    default_phase: str = config.get("default_phase", _FALLBACK_DEFAULT_PHASE)
+    phase: str = mapping.get(task_type, default_phase)
+    return phase  # type: ignore[return-value]
+
+
+# ID: e3f4a5b6-c7d8-491a-be3f-4a5b6c7d8e9f
+def allowed_task_types(
+    config: dict[str, Any] | None = None,
+) -> frozenset[str]:
+    """
+    Return the closed vocabulary — the keys of config['mapping'].
+
+    Used by shared.models.execution_models at import time to populate
+    the ExecutionTask.task_type field_validator's allowed set. If
+    config is None, load_task_type_phases() is called.
+    """
+    if config is None:
+        config = load_task_type_phases()
+    mapping = config.get("mapping", {})
+    return frozenset(mapping.keys())

shared/infrastructure/intent/test_coverage_paths.py

@@ -0,0 +1,181 @@
+# src/shared/infrastructure/intent/test_coverage_paths.py
+"""
+Source-to-test path mapping helper.
+
+Single source of truth for mapping repo-relative source paths to their
+governed repo-relative test paths. Both the mapping rule and the
+filename conventions are owned by
+.intent/enforcement/config/test_coverage.yaml.
+
+Authority: policy. The governing document is
+.intent/enforcement/config/test_coverage.yaml, accessed exclusively via
+IntentRepository. No other module may hardcode the source->test
+mapping — all call sites route through this helper.
+
+The _FALLBACK_* constants below are last-resort graceful degradation
+for the narrow case where the policy document cannot be loaded (e.g.
+bootstrap races, corrupt YAML). They MUST NOT be treated as
+defaults-in-logic — when the policy loads successfully, it always wins.
+
+LAYER: shared/infrastructure/intent — pure helper. No imports from
+will/, body/, or cli/.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_FALLBACK_SOURCE_ROOT = "src"
+_FALLBACK_TEST_ROOT = "tests"
+_FALLBACK_TEST_FILE_SUFFIX = "/test_generated.py"
+_FALLBACK_EXCLUDED_FILENAMES: list[str] = ["__init__.py"]
+
+
+# ID: 6d7e2c9a-4b5f-4801-9e13-a2b3c4d5e6f7
+def load_test_coverage_config() -> dict[str, Any]:
+    """
+    Load .intent/enforcement/config/test_coverage.yaml via IntentRepository.
+
+    Returns the parsed policy dict on success. On any failure — missing
+    file, parse error, unexpected top-level type — returns fallback
+    defaults and logs a warning so callers degrade gracefully rather
+    than halting.
+    """
+    try:
+        from shared.infrastructure.intent.intent_repository import (
+            get_intent_repository,
+        )
+
+        repo = get_intent_repository()
+        config_path = repo.resolve_rel("enforcement/config/test_coverage.yaml")
+        config = repo.load_document(config_path)
+        if isinstance(config, dict):
+            return config
+        logger.warning(
+            "test_coverage_paths: test_coverage.yaml did not parse as a dict "
+            "— using fallback defaults."
+        )
+    except Exception as exc:
+        logger.warning(
+            "test_coverage_paths: could not load .intent/enforcement/config/"
+            "test_coverage.yaml (%s) — using fallback defaults.",
+            exc,
+        )
+    return {
+        "source_root": _FALLBACK_SOURCE_ROOT,
+        "test_root": _FALLBACK_TEST_ROOT,
+        "test_file_suffix": _FALLBACK_TEST_FILE_SUFFIX,
+        "excluded_filenames": list(_FALLBACK_EXCLUDED_FILENAMES),
+    }
+
+
+# ID: 7e8f3d0b-5c6a-4912-af24-b3c4d5e6f708
+def source_to_test_path(
+    source_file: str,
+    config: dict[str, Any] | None = None,
+) -> str:
+    """
+    Map a repo-relative source path to its governed repo-relative test path.
+
+    Mapping:
+        {source_root}/foo/bar.py
+          -> {test_root}/foo/bar{test_file_suffix}
+
+    Args:
+        source_file: repo-relative path to a Python source file, e.g.
+            "src/foo/bar.py". Callers must pass repo-relative paths.
+        config: optional pre-loaded policy dict. If None,
+            load_test_coverage_config() is invoked.
+
+    Returns:
+        Repo-relative path to the governed test file, e.g.
+            "tests/foo/bar/test_generated.py".
+
+    Raises:
+        ValueError: if source_file does not start with "{source_root}/".
+    """
+    if config is None:
+        config = load_test_coverage_config()
+
+    source_root: str = config.get("source_root", _FALLBACK_SOURCE_ROOT)
+    test_root: str = config.get("test_root", _FALLBACK_TEST_ROOT)
+    test_file_suffix: str = config.get("test_file_suffix", _FALLBACK_TEST_FILE_SUFFIX)
+
+    prefix = f"{source_root}/"
+    if not source_file.startswith(prefix):
+        raise ValueError(
+            f"source_file {source_file!r} does not start with configured "
+            f"source_root prefix {prefix!r}"
+        )
+
+    return (
+        source_file.replace(prefix, f"{test_root}/", 1).removesuffix(".py")
+        + test_file_suffix
+    )
+
+
+# ID: 8f9a4e1c-6d7b-4a23-be35-c4d5e6f7a819
+def uncovered_source_files(
+    repo_root: Path,
+    config: dict[str, Any] | None = None,
+) -> list[str]:
+    """
+    Walk source_root and return repo-relative paths for in-scope Python
+    source files that have no corresponding test file.
+
+    Shared between TestCoverageSensor (which posts test.run_required for
+    these sources) and TestRunnerSensor (which uses the same set as
+    current_subjects for the test.missing quarantine drain — ADR-072 D5).
+
+    The mapping and scoping rules are entirely owned by
+    .intent/enforcement/config/test_coverage.yaml:
+      - source_root, test_root, test_file_suffix
+      - excluded_filenames (skip-list)
+      - include_files (scope limiter; if non-empty, only these are scanned)
+    """
+    if config is None:
+        config = load_test_coverage_config()
+
+    source_root_rel: str = config.get("source_root", _FALLBACK_SOURCE_ROOT)
+    excluded: frozenset[str] = frozenset(
+        config.get("excluded_filenames", _FALLBACK_EXCLUDED_FILENAMES)
+    )
+    include_files: frozenset[str] = frozenset(config.get("include_files") or [])
+
+    src_root = repo_root / source_root_rel
+    if not src_root.exists():
+        logger.warning(
+            "test_coverage_paths.uncovered_source_files: source root not found at %s",
+            src_root,
+        )
+        return []
+
+    uncovered: list[str] = []
+
+    for py_file in src_root.rglob("*.py"):
+        if py_file.name in excluded:
+            continue
+
+        rel = py_file.relative_to(repo_root)
+        source_file = str(rel)
+
+        if include_files and source_file not in include_files:
+            continue
+
+        try:
+            test_rel = source_to_test_path(source_file, config)
+        except ValueError:
+            continue
+
+        test_path = repo_root / test_rel
+
+        if not test_path.exists():
+            uncovered.append(source_file)
+
+    return uncovered

shared/infrastructure/intent/vocabulary_projection.py

@@ -0,0 +1,241 @@
+# src/shared/infrastructure/intent/vocabulary_projection.py
+"""
+Vocabulary projection loader (ADR-023 D4).
+
+Sole sanctioned reader of .intent/META/vocabulary.json. Returns one of:
+
+- VocabularyProjection(state="healthy")
+- VocabularyProjection(state="drift", drift_detected=True)
+- VocabularyProjectionError(state="broken", reason=...)
+
+The loader does not fall back to defaults on broken state — that is
+instrument failure and callers must enter governance-DEGRADED mode.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import jsonschema
+from jsonschema import RefResolver
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+CANONICAL_HEADING = "## Canonical Vocabulary (Machine Section)"
+VOCABULARY_PAPER_REL = ".specs/papers/CORE-Vocabulary.md"
+VOCABULARY_JSON_REL = ".intent/META/vocabulary.json"
+VOCABULARY_SCHEMA_REL = ".intent/META/vocabulary.schema.json"
+
+# src/shared/infrastructure/intent/vocabulary_projection.py
+#   parents[0] = intent
+#   parents[1] = infrastructure
+#   parents[2] = shared
+#   parents[3] = src
+#   parents[4] = repo root
+_REPO_ROOT_DEFAULT = Path(__file__).resolve().parents[4]
+
+
+@dataclass(frozen=True)
+# ID: 4d8c2e7a-9b3f-4a1c-b6d2-7e8f3c1a5b06
+class VocabularyTerm:
+    """A single vocabulary entry, projection-shape (frozen)."""
+
+    term: str
+    definition: str
+    not_: str
+    authoritative_paper: str
+    aliases: tuple[str, ...] = ()
+    see_also: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+# ID: 6c1f3a8e-2d7b-4f9c-a4e1-8b9c2d5f1e07
+class VocabularyProjection:
+    """A successfully loaded projection. state is 'healthy' or 'drift'."""
+
+    terms: tuple[VocabularyTerm, ...]
+    drift_detected: bool
+    state: Literal["healthy", "drift"]
+    source_hash: str
+
+
+@dataclass(frozen=True)
+# ID: 8a4d2e6c-1f9b-4c3d-b8e2-5d7f1a4c9e08
+class VocabularyProjectionError:
+    """A broken projection. Sentinel — not an exception."""
+
+    state: Literal["broken"]
+    reason: str
+
+
+# ID: fcc64fd7-f36e-41b8-be7a-2b1062946287
+def normalize_vocabulary_cell(value: str) -> str:
+    """
+    Produce the identity form of a canonical-vocabulary-table cell.
+
+    The canonical section in CORE-Vocabulary.md is a markdown table; cells
+    routinely carry presentation decoration that is not part of the value's
+    identity. Today the only such decoration is a surrounding pair of
+    backticks (markdown inline-code formatting) around path-shaped cells, plus
+    leading/trailing whitespace. Both the sync writer (producing
+    vocabulary.json) and the audit gate (validating canonical paths) must
+    parse the same identity, so this normalization is the single shared
+    contract.
+
+    Behavior: strip leading/trailing whitespace; if the trimmed value is
+    wrapped in a single pair of backticks, drop them and strip again.
+    """
+    v = value.strip()
+    if v.startswith("`") and v.endswith("`") and len(v) >= 2:
+        return v[1:-1].strip()
+    return v
+
+
+# ID: 3f8c1b4a-7d2e-4f9b-a6c1-9d3e2b5f8a09
+def locate_canonical_section(text: str) -> tuple[int, int] | None:
+    """
+    Return (start_idx, end_idx) of the canonical-section line range, or None.
+
+    The slice text.splitlines()[start_idx:end_idx] spans the heading line
+    through the last line before the terminating '---' separator or next
+    '## ' heading.
+    """
+    lines = text.splitlines()
+    start = next(
+        (i for i, line in enumerate(lines) if line.rstrip() == CANONICAL_HEADING),
+        None,
+    )
+    if start is None:
+        return None
+    end = len(lines)
+    for i in range(start + 1, len(lines)):
+        if lines[i].strip() == "---" or lines[i].startswith("## "):
+            end = i
+            break
+    return start, end
+
+
+# ID: 2c9e1f7b-4d8a-4e3c-b9f2-6a8c3e1d4b0a
+def compute_canonical_section_hash(repo_root: Path) -> str | None:
+    """
+    SHA-256 hex of the canonical section in CORE-Vocabulary.md.
+
+    Returns None if the paper is missing or the section heading cannot be
+    located. Bytes hashed are exactly text.splitlines()[start:end] joined
+    by '\\n', matching the regen command in sync_vocabulary.py.
+    """
+    paper = repo_root / VOCABULARY_PAPER_REL
+    if not paper.is_file():
+        return None
+    try:
+        text = paper.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    rng = locate_canonical_section(text)
+    if rng is None:
+        return None
+    start, end = rng
+    section = "\n".join(text.splitlines()[start:end])
+    return hashlib.sha256(section.encode("utf-8")).hexdigest()
+
+
+# ID: 9d3a5c1e-7b2f-4a8d-b1c3-4e7f8a2d5c0b
+def _validate_schema(instance: dict, schema_path: Path, schema: dict) -> str | None:
+    """Validate instance against schema with $ref resolution. Returns error string or None."""
+    base_uri = schema_path.parent.as_uri() + "/"
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=DeprecationWarning)
+        resolver = RefResolver(base_uri=base_uri, referrer=schema)
+        try:
+            jsonschema.validate(instance, schema, resolver=resolver)
+        except jsonschema.ValidationError as e:
+            path = "/".join(str(p) for p in e.absolute_path) or "<root>"
+            return f"schema validation failed at {path}: {e.message}"
+    return None
+
+
+# ID: 1b8e4c2f-9a3d-4f7c-b2e8-6c1d4f9a3e0c
+def load_vocabulary_projection(
+    repo_root: Path | None = None,
+) -> VocabularyProjection | VocabularyProjectionError:
+    """
+    Load and validate the vocabulary projection.
+
+    Returns VocabularyProjection on healthy/drift; VocabularyProjectionError
+    on broken (missing file, malformed JSON, schema validation failure, or
+    canonical source paper not parseable).
+    """
+    root = (repo_root or _REPO_ROOT_DEFAULT).resolve()
+    json_path = root / VOCABULARY_JSON_REL
+    schema_path = root / VOCABULARY_SCHEMA_REL
+
+    if not json_path.is_file():
+        return VocabularyProjectionError(
+            state="broken", reason=f"projection missing: {VOCABULARY_JSON_REL}"
+        )
+    if not schema_path.is_file():
+        return VocabularyProjectionError(
+            state="broken", reason=f"schema missing: {VOCABULARY_SCHEMA_REL}"
+        )
+
+    try:
+        instance = json.loads(json_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        return VocabularyProjectionError(
+            state="broken", reason=f"malformed JSON in {VOCABULARY_JSON_REL}: {e.msg}"
+        )
+    except OSError as e:
+        return VocabularyProjectionError(
+            state="broken", reason=f"unreadable projection: {e}"
+        )
+
+    try:
+        schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        return VocabularyProjectionError(
+            state="broken", reason=f"unreadable schema: {e}"
+        )
+
+    schema_error = _validate_schema(instance, schema_path, schema)
+    if schema_error is not None:
+        return VocabularyProjectionError(state="broken", reason=schema_error)
+
+    recomputed_hash = compute_canonical_section_hash(root)
+    if recomputed_hash is None:
+        return VocabularyProjectionError(
+            state="broken",
+            reason=(
+                f"cannot recompute hash: canonical section not found in "
+                f"{VOCABULARY_PAPER_REL}"
+            ),
+        )
+
+    stored_hash = instance["metadata"].get("source_hash", "")
+    drift = stored_hash != recomputed_hash
+
+    terms = tuple(
+        VocabularyTerm(
+            term=t["term"],
+            definition=t["definition"],
+            not_=t["not"],
+            authoritative_paper=t["authoritative_paper"],
+            aliases=tuple(t.get("aliases") or ()),
+            see_also=tuple(t.get("see_also") or ()),
+        )
+        for t in instance["terms"]
+    )
+
+    return VocabularyProjection(
+        terms=terms,
+        drift_detected=drift,
+        state="drift" if drift else "healthy",
+        source_hash=stored_hash,
+    )