codd-dev 2.76.0__tar.gz → 2.78.0__tar.gz

{codd_dev-2.76.0 → codd_dev-2.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.76.0
+Version: 2.78.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.76.0 → codd_dev-2.78.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.76.0"
+__version__ = "2.78.0"

{codd_dev-2.76.0 → codd_dev-2.78.0}/codd/implement_oracle.py

@@ -91,6 +91,26 @@ from codd.project_types import (
     resolve_layout_profile,
 )
 
+# Value-objects + evidence constants relocated to the LEAF module so the Contract
+# Kernel oracle adapters (and the generic command-sequence executor) can import
+# them without a cycle through this gate module. Re-imported + re-exported here so
+# every existing ``from codd.implement_oracle import ImplementOracleResult`` keeps
+# working and gets the SAME class object (identity preserved). See
+# ``codd/implement_oracle_types.py`` — pure relocation, zero behaviour change.
+from codd.implement_oracle_types import (  # noqa: F401 — re-exported for back-compat
+    EVIDENCE_BOUNDARY_VIOLATION,
+    EVIDENCE_CATEGORIES,
+    EVIDENCE_ENVIRONMENT_BUILD,
+    EVIDENCE_MISSING_SYMBOL,
+    EVIDENCE_MODULE_RESOLUTION,
+    EVIDENCE_OTHER,
+    EVIDENCE_TEST_NOT_COLLECTED,
+    ImplementOracleFinding,
+    ImplementOracleResult,
+    OracleScopeError,
+    _FEEDBACK_FINDING_CAP,
+)
+
 
 __all__ = [
     "EVIDENCE_CATEGORIES",
@@ -116,29 +136,12 @@ __all__ = [
 __test_exports__ = ["_execute_broad_campaign"]
 
 
-# ── evidence categories (language-neutral; the design's normalization target) ──
-#
-# The whole point of normalization: a Go/Rust adapter later emits the SAME
-# vocabulary so the SUT-facing feedback and any downstream policy are stack-
-# agnostic. ``boundary_violation`` (an e2e/modality contract breach) is in the
-# vocabulary for completeness but is NOT something a pure typechecker emits — the
-# existing AST e2e-contract gate owns that axis; it is here so the category set is
-# the full design set and a future composite/boundary adapter can use it.
-EVIDENCE_MISSING_SYMBOL = "missing_symbol"
-EVIDENCE_MODULE_RESOLUTION = "module_resolution_error"
-EVIDENCE_TEST_NOT_COLLECTED = "test_not_collected"
-EVIDENCE_ENVIRONMENT_BUILD = "environment_build_error"
-EVIDENCE_BOUNDARY_VIOLATION = "boundary_violation"
-EVIDENCE_OTHER = "type_error"  # a real coherence error not in the categories above
-
-EVIDENCE_CATEGORIES: tuple[str, ...] = (
-    EVIDENCE_MISSING_SYMBOL,
-    EVIDENCE_MODULE_RESOLUTION,
-    EVIDENCE_TEST_NOT_COLLECTED,
-    EVIDENCE_ENVIRONMENT_BUILD,
-    EVIDENCE_BOUNDARY_VIOLATION,
-    EVIDENCE_OTHER,
-)
+# NOTE: the language-neutral evidence categories (``EVIDENCE_*`` +
+# ``EVIDENCE_CATEGORIES``) now live in ``codd.implement_oracle_types`` (the leaf
+# module the oracle adapters share) and are re-imported at the top of this module —
+# see that import for the rationale (cycle-free adapter access). The TS-specific
+# code→category MAPS below stay here (they are TS normalizer internals, not shared
+# value-objects).
 
 
 #: TypeScript diagnostic codes → evidence category. The src↔src / test↔helper
@@ -180,111 +183,12 @@ _TS_DIAG_LINE = re.compile(
 _TS_NO_INPUTS_RE = re.compile(r"TS18003|No inputs were found in config file", re.IGNORECASE)
 
 
-class OracleScopeError(RuntimeError):
-    """The oracle's scope could not be CERTIFIED to cover source + tests.
-
-    Raised when ``tsconfig.json`` is missing/unparseable, when its
-    ``include``/``files`` provably excludes the test tree (or the source tree),
-    or when ``tsc`` reports it found no inputs. An uncertifiable scope is a HARD
-    FAIL — a green oracle over an unknown scope is a false-green, the #1 failure
-    mode the design calls out.
-    """
-
-
-@dataclass(frozen=True)
-class ImplementOracleFinding:
-    """One normalized oracle diagnostic."""
-
-    category: str
-    code: str
-    message: str
-    path: str | None = None
-
-
-@dataclass
-class ImplementOracleResult:
-    """Outcome of one implement-time oracle run (one ``tsc`` invocation)."""
-
-    passed: bool
-    executed: bool
-    command: str
-    findings: list[ImplementOracleFinding] = field(default_factory=list)
-    #: EDITABLE source/test targets the failure attributes to (for diagnostics).
-    failed_paths: list[str] = field(default_factory=list)
-    detail: str = ""
-    raw_output: str = ""
-    #: Structured diagnostics (code + primary file + symbol/module) for the SCOPED
-    #: rerun derivation + the loop-breaking signature. Empty for a pass / for a
-    #: non-TS oracle. Kept separate from ``findings`` (the SUT-facing normalized
-    #: evidence) because scope derivation needs the per-diagnostic counterpart
-    #: keys, not the language-neutral category. See ``codd.implement_oracle_scope``.
-    diagnostics: list[Any] = field(default_factory=list)
-    #: Orphan artifacts (generated source files no task owns) found by the global
-    #: orphan-artifact gate. Populated in WARN mode (observation; the gate does not
-    #: fail) and ENFORCE mode (the gate fails). Empty when the gate is off / no
-    #: scope index / no orphans. Project-relative paths, for the report + dashboard.
-    orphan_artifacts: list[str] = field(default_factory=list)
-
-    def category_counts(self) -> dict[str, int]:
-        counts: dict[str, int] = {}
-        for finding in self.findings:
-            counts[finding.category] = counts.get(finding.category, 0) + 1
-        return counts
-
-    def feedback_message(self) -> str:
-        """SUT-facing feedback: what the native oracle proved is incoherent.
-
-        Deliberately concrete and bounded — it names the offending files, the
-        diagnostic codes, and the language-neutral category, then directs the SUT
-        to make the demanded symbols/modules exist. It NEVER prescribes a verify
-        fix (the SUT owns the contents); it states the contract that was broken.
-        """
-        lines = [
-            "The implement-time coherence oracle REJECTED the generated code: "
-            "independently-generated files do not agree on the syntax, module "
-            "imports, or imported symbols they demand of each other. Nothing was "
-            "accepted. (TypeScript runs `tsc --noEmit`; Python runs an in-process "
-            "compile + a first-party import/symbol resolver + `pytest "
-            "--collect-only`.)",
-            "Fix the source AND tests so every file compiles, every import "
-            "resolves, and every imported symbol is actually defined/exported by "
-            "its module. Specifically:",
-        ]
-        for finding in self.findings[:_FEEDBACK_FINDING_CAP]:
-            where = f"{finding.path}: " if finding.path else ""
-            lines.append(f"  - [{finding.category}] {where}{finding.code}: {finding.message}")
-        extra = len(self.findings) - _FEEDBACK_FINDING_CAP
-        if extra > 0:
-            lines.append(f"  ... and {extra} more diagnostic(s).")
-        lines.append(
-            "Ensure: (a) every imported name actually exists in its module — "
-            'TypeScript `import { X } from "./mod.js"` imports a name `X` that '
-            "`mod` actually `export`s, and Python `from app.mod import X` imports "
-            "an `X` that `app/mod.py` actually defines or re-exports; (b) "
-            "test/helper files agree on the names they share (e.g. do not import "
-            "`repoRoot` when the helper exports `projectRoot`); (c) every imported "
-            "module path resolves (no `from .missing import ...` to a module that "
-            "does not exist)."
-        )
-        # (iii) Contract discipline — the anti-oscillation rule. A non-deterministic
-        # SUT, told only "symbol X is missing", tends to INVENT a new symbol/file
-        # each rerun (a different wrong guess every time → the diagnostics oscillate
-        # instead of converging). Forbid invention explicitly: reconcile to what
-        # ALREADY exists; a genuinely shared symbol goes in an OWNED module, not a
-        # newly-conjured file. (GPT-5.5 Pro consult, 2026-06-15: feedback iii.)
-        lines.append(
-            "Do NOT invent new symbols, helpers, or files to satisfy an import: "
-            "reconcile the import to a symbol the target module ALREADY exports (or "
-            "delete the import/usage if it is spurious). If two files must share a "
-            "symbol, add it to one OWNED module and import it — never duplicate it or "
-            "create an unowned shared file. Make the SMALLEST change that restores "
-            "coherence; do not rewrite unrelated code."
-        )
-        return "\n".join(lines)
-
+# NOTE: ``OracleScopeError`` / ``ImplementOracleFinding`` / ``ImplementOracleResult``
+# (and the ``_FEEDBACK_FINDING_CAP`` its ``feedback_message`` uses) now live in
+# ``codd.implement_oracle_types`` (the leaf the oracle adapters share) and are
+# re-imported at the top of this module — see that import for the cycle-free
+# rationale. Byte-for-byte the same definitions; only the home moved.
 
-#: How many individual diagnostics to surface in SUT feedback (bounded prompt).
-_FEEDBACK_FINDING_CAP = 12
 
 #: Total implement-oracle attempts: one initial check + bounded corrective
 #: retries, sized to the ESCALATION LADDER so every rung can actually be reached
@@ -3012,8 +2916,11 @@ def _resolve_registry_composite_oracle(
         lang_profile = default_registry.resolve(lang)
     except Exception:  # noqa: BLE001 — no registry profile ⇒ NO-OP, not a crash.
         return None
-    oracle_decl = lang_profile.extra.get("implement_oracle") if lang_profile.extra else None
-    if not isinstance(oracle_decl, Mapping) or oracle_decl.get("kind") != "composite":
+    # implement_oracle is now a modeled first-class field (Contract Kernel §1),
+    # no longer a raw mapping in ``.extra``. Behaviour is preserved: only a Go
+    # profile declaring kind="composite" synthesizes the composite spec below.
+    oracle_decl = lang_profile.implement_oracle
+    if oracle_decl is None or oracle_decl.kind != "composite":
         return None
     module_root = _norm(getattr(lang_profile.layout, "module_root", ".") or ".") or "."
     synthetic = LayoutProfile(

codd_dev-2.78.0/codd/implement_oracle_types.py

@@ -0,0 +1,174 @@
+"""Implement-oracle value-types — the LEAF module both the core gate and the
+Contract-Kernel oracle adapters import (Contract Kernel oracle dispatch §3).
+
+WHY A LEAF MODULE
+=================
+The oracle dispatch is moving toward ``LanguageProfile``-driven adapters (a
+``go-toolchain`` / ``typescript-tsc`` / ``python-composite`` adapter resolved from
+the profile). Those adapters — and the generic command-sequence executor that
+drives them — must produce the SAME ``ImplementOracleResult`` /
+``ImplementOracleFinding`` the core gate (:mod:`codd.implement_oracle`) consumes,
+and must raise the SAME ``OracleScopeError``. If those value-objects stayed in the
+gate module, an adapter importing them would create an import cycle
+(gate → adapter → gate). So they live HERE, in a leaf that imports only stdlib;
+the gate re-imports + RE-EXPORTS them (identity preserved — every existing
+``from codd.implement_oracle import ImplementOracleResult`` keeps working and gets
+the SAME class object), and the adapters import them straight from this leaf.
+
+This mirrors the ``RunnerExecution`` relocation (v2.71): the value-objects moved to
+:mod:`codd.languages.adapters.runner_report` (a leaf) and
+:mod:`codd.coverage_execution_coherence` re-exports them, so both the gate and the
+adapters share ONE definition with no cycle. ZERO behaviour change — this is a pure
+relocation; the bodies are byte-for-byte what they were in the gate module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── evidence categories (language-neutral; the design's normalization target) ──
+#
+# The whole point of normalization: a Go/Rust adapter later emits the SAME
+# vocabulary so the SUT-facing feedback and any downstream policy are stack-
+# agnostic. ``boundary_violation`` (an e2e/modality contract breach) is in the
+# vocabulary for completeness but is NOT something a pure typechecker emits — the
+# existing AST e2e-contract gate owns that axis; it is here so the category set is
+# the full design set and a future composite/boundary adapter can use it.
+EVIDENCE_MISSING_SYMBOL = "missing_symbol"
+EVIDENCE_MODULE_RESOLUTION = "module_resolution_error"
+EVIDENCE_TEST_NOT_COLLECTED = "test_not_collected"
+EVIDENCE_ENVIRONMENT_BUILD = "environment_build_error"
+EVIDENCE_BOUNDARY_VIOLATION = "boundary_violation"
+EVIDENCE_OTHER = "type_error"  # a real coherence error not in the categories above
+
+EVIDENCE_CATEGORIES: tuple[str, ...] = (
+    EVIDENCE_MISSING_SYMBOL,
+    EVIDENCE_MODULE_RESOLUTION,
+    EVIDENCE_TEST_NOT_COLLECTED,
+    EVIDENCE_ENVIRONMENT_BUILD,
+    EVIDENCE_BOUNDARY_VIOLATION,
+    EVIDENCE_OTHER,
+)
+
+
+#: How many individual diagnostics to surface in SUT feedback (bounded prompt).
+_FEEDBACK_FINDING_CAP = 12
+
+
+class OracleScopeError(RuntimeError):
+    """The oracle's scope could not be CERTIFIED to cover source + tests.
+
+    Raised when ``tsconfig.json`` is missing/unparseable, when its
+    ``include``/``files`` provably excludes the test tree (or the source tree),
+    or when ``tsc`` reports it found no inputs. An uncertifiable scope is a HARD
+    FAIL — a green oracle over an unknown scope is a false-green, the #1 failure
+    mode the design calls out.
+    """
+
+
+@dataclass(frozen=True)
+class ImplementOracleFinding:
+    """One normalized oracle diagnostic."""
+
+    category: str
+    code: str
+    message: str
+    path: str | None = None
+
+
+@dataclass
+class ImplementOracleResult:
+    """Outcome of one implement-time oracle run (one ``tsc`` invocation)."""
+
+    passed: bool
+    executed: bool
+    command: str
+    findings: list[ImplementOracleFinding] = field(default_factory=list)
+    #: EDITABLE source/test targets the failure attributes to (for diagnostics).
+    failed_paths: list[str] = field(default_factory=list)
+    detail: str = ""
+    raw_output: str = ""
+    #: Structured diagnostics (code + primary file + symbol/module) for the SCOPED
+    #: rerun derivation + the loop-breaking signature. Empty for a pass / for a
+    #: non-TS oracle. Kept separate from ``findings`` (the SUT-facing normalized
+    #: evidence) because scope derivation needs the per-diagnostic counterpart
+    #: keys, not the language-neutral category. See ``codd.implement_oracle_scope``.
+    diagnostics: list[Any] = field(default_factory=list)
+    #: Orphan artifacts (generated source files no task owns) found by the global
+    #: orphan-artifact gate. Populated in WARN mode (observation; the gate does not
+    #: fail) and ENFORCE mode (the gate fails). Empty when the gate is off / no
+    #: scope index / no orphans. Project-relative paths, for the report + dashboard.
+    orphan_artifacts: list[str] = field(default_factory=list)
+
+    def category_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for finding in self.findings:
+            counts[finding.category] = counts.get(finding.category, 0) + 1
+        return counts
+
+    def feedback_message(self) -> str:
+        """SUT-facing feedback: what the native oracle proved is incoherent.
+
+        Deliberately concrete and bounded — it names the offending files, the
+        diagnostic codes, and the language-neutral category, then directs the SUT
+        to make the demanded symbols/modules exist. It NEVER prescribes a verify
+        fix (the SUT owns the contents); it states the contract that was broken.
+        """
+        lines = [
+            "The implement-time coherence oracle REJECTED the generated code: "
+            "independently-generated files do not agree on the syntax, module "
+            "imports, or imported symbols they demand of each other. Nothing was "
+            "accepted. (TypeScript runs `tsc --noEmit`; Python runs an in-process "
+            "compile + a first-party import/symbol resolver + `pytest "
+            "--collect-only`.)",
+            "Fix the source AND tests so every file compiles, every import "
+            "resolves, and every imported symbol is actually defined/exported by "
+            "its module. Specifically:",
+        ]
+        for finding in self.findings[:_FEEDBACK_FINDING_CAP]:
+            where = f"{finding.path}: " if finding.path else ""
+            lines.append(f"  - [{finding.category}] {where}{finding.code}: {finding.message}")
+        extra = len(self.findings) - _FEEDBACK_FINDING_CAP
+        if extra > 0:
+            lines.append(f"  ... and {extra} more diagnostic(s).")
+        lines.append(
+            "Ensure: (a) every imported name actually exists in its module — "
+            'TypeScript `import { X } from "./mod.js"` imports a name `X` that '
+            "`mod` actually `export`s, and Python `from app.mod import X` imports "
+            "an `X` that `app/mod.py` actually defines or re-exports; (b) "
+            "test/helper files agree on the names they share (e.g. do not import "
+            "`repoRoot` when the helper exports `projectRoot`); (c) every imported "
+            "module path resolves (no `from .missing import ...` to a module that "
+            "does not exist)."
+        )
+        # (iii) Contract discipline — the anti-oscillation rule. A non-deterministic
+        # SUT, told only "symbol X is missing", tends to INVENT a new symbol/file
+        # each rerun (a different wrong guess every time → the diagnostics oscillate
+        # instead of converging). Forbid invention explicitly: reconcile to what
+        # ALREADY exists; a genuinely shared symbol goes in an OWNED module, not a
+        # newly-conjured file. (GPT-5.5 Pro consult, 2026-06-15: feedback iii.)
+        lines.append(
+            "Do NOT invent new symbols, helpers, or files to satisfy an import: "
+            "reconcile the import to a symbol the target module ALREADY exports (or "
+            "delete the import/usage if it is spurious). If two files must share a "
+            "symbol, add it to one OWNED module and import it — never duplicate it or "
+            "create an unowned shared file. Make the SMALLEST change that restores "
+            "coherence; do not rewrite unrelated code."
+        )
+        return "\n".join(lines)
+
+
+__all__ = [
+    "EVIDENCE_BOUNDARY_VIOLATION",
+    "EVIDENCE_CATEGORIES",
+    "EVIDENCE_ENVIRONMENT_BUILD",
+    "EVIDENCE_MISSING_SYMBOL",
+    "EVIDENCE_MODULE_RESOLUTION",
+    "EVIDENCE_OTHER",
+    "EVIDENCE_TEST_NOT_COLLECTED",
+    "ImplementOracleFinding",
+    "ImplementOracleResult",
+    "OracleScopeError",
+]

{codd_dev-2.76.0 → codd_dev-2.78.0}/codd/languages/__init__.py

@@ -21,6 +21,8 @@ from .profile import (
     CommandSpec,
     DependencyIntegrityFile,
     Identity,
+    ImplementOracleProfileSpec,
+    ImplementOracleStepSpec,
     ImportsSpec,
     LanguageProfile,
     LayoutSpec,
@@ -75,6 +77,8 @@ __all__ = [
     "CommandSpec",
     "DependencyIntegrityFile",
     "Identity",
+    "ImplementOracleProfileSpec",
+    "ImplementOracleStepSpec",
     "ImportsSpec",
     "LanguageProfile",
     "LayoutSpec",

codd_dev-2.78.0/codd/languages/adapters/implement_oracle.py

@@ -0,0 +1,188 @@
+"""Implement-oracle adapter PROTOCOL + context (Contract Kernel oracle dispatch §3).
+
+This is the seam the per-language oracle tool-semantics will plug into once the
+dispatch switch happens (steps 5–7): a ``go-toolchain`` / ``typescript-tsc`` /
+``python-composite`` adapter, resolved from the ``LanguageProfile``'s
+``implement_oracle`` declaration, that owns the language-specific knowledge the
+generic machinery deliberately does NOT have — how to certify the oracle's scope,
+how to turn one command's exit/stdout/stderr into normalized findings, and (for the
+``adapter`` kind) how to run a wholly in-process composite.
+
+ADDITIVE / UNCONNECTED. Nothing here is wired into the live oracle gate yet. The
+gate (:mod:`codd.implement_oracle`) still dispatches on ``profile.language`` and
+runs its own per-language executors; the concrete ``oracle_go`` / ``oracle_python``
+/ ``oracle_typescript`` adapters land WITH those switch steps. This module ships
+ONLY the Protocol, the context object, and the small value object the generic
+command-sequence executor (:mod:`codd.languages.oracle_executor`) consumes — so
+that executor + its fixtures can be written against a STABLE contract now.
+
+LEAF rule (no import cycle). This module imports ONLY:
+  * stdlib (``pathlib``, ``typing``),
+  * the oracle value-objects leaf (:mod:`codd.implement_oracle_types`), and
+  * the profile model (:mod:`codd.languages.profile`).
+It MUST NOT import :mod:`codd.implement_oracle` (the gate), the registry, or the
+generic executor — the dependency edge runs gate → executor → adapters → leaf
+types, never back up. (Mirrors the runner_report adapter leaf.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from codd.implement_oracle_types import ImplementOracleFinding, ImplementOracleResult
+from codd.languages.profile import (
+    CommandSpec,
+    ImplementOracleProfileSpec,
+    LanguageProfile,
+    LayoutSpec,
+)
+
+
+@dataclass(frozen=True)
+class OracleContext:
+    """Everything an oracle adapter needs to certify scope + normalize + execute.
+
+    It carries the ALREADY-RESOLVED ``LanguageProfile`` (the dispatch hands the
+    adapter the profile the resolver produced — the adapter never re-resolves a
+    language, so there is no ``resolve("go")`` inside an adapter), plus the project
+    root, the layout (for cwd/env placeholder substitution), the oracle declaration
+    (``kind`` + ``command``/``steps`` + ``adapter`` id), and the run config.
+
+    Frozen: a context is an immutable description of one oracle run.
+    """
+
+    project_root: Path
+    #: The resolved layout topology (``module_root`` / ``repo_root`` / ``manifest_root``
+    #: etc.). The generic executor substitutes these into a command's ``cwd``/``env``
+    #: placeholders before spawning. Held separately from ``language_profile`` (though
+    #: it is ``language_profile.layout``) so a caller can pass a layout VIEW.
+    layout_profile: LayoutSpec
+    #: The resolved language contract the dispatch already produced — the adapter
+    #: reads ``commands[command_id]`` from it; it NEVER re-resolves a language.
+    language_profile: LanguageProfile
+    #: The profile's implement-oracle declaration (kind + command/steps + adapter id).
+    oracle: ImplementOracleProfileSpec
+    #: The run config (``implement.*`` knobs: timeouts, etc.). ``None`` ⇒ defaults.
+    config: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class OracleStepObservation:
+    """One command step's normalized observation (the adapter's verdict on a step).
+
+    The adapter turns a raw ``(returncode, stdout, stderr)`` into this: the
+    language-neutral ``findings`` (each an :class:`ImplementOracleFinding`), the
+    editable ``failed_paths`` the findings attribute to, and whether — in the
+    adapter's judgement — the step was COHERENT (no incoherence proven).
+
+    The anti-false-green contract the generic executor relies on:
+
+    * ``is_clean`` is True ONLY when the adapter is positively satisfied the step
+      proved coherence (e.g. ``tsc`` exited 0 over a certified scope). An adapter
+      that cannot decide must return ``is_clean=False`` — never default to clean.
+    * A non-clean step with EMPTY ``findings`` is an OPAQUE failure: the command
+      did not pass but the adapter could not explain why. The executor turns that
+      into an ``environment_build_error`` RED (never a benign pass) — so "exited
+      nonzero, no parsed diagnostic" can never read as green.
+    """
+
+    is_clean: bool
+    findings: tuple[ImplementOracleFinding, ...] = ()
+    failed_paths: tuple[str, ...] = ()
+    #: The structured per-diagnostic objects (for the scoped-rerun derivation), if
+    #: the adapter produced any. Opaque to the executor; threaded into the result.
+    diagnostics: tuple[Any, ...] = ()
+    #: A short human reason (always populated for a non-clean observation).
+    detail: str = ""
+
+
+@runtime_checkable
+class ImplementOracleAdapter(Protocol):
+    """The tool-semantics an oracle stack plugs in (Contract Kernel §3).
+
+    Resolved from ``LanguageProfile.implement_oracle.adapter`` via the adapter
+    registry under kind ``"implement_oracle"``. The dispatch calls:
+
+    * :meth:`certify_scope` ALWAYS (before any command runs) — an uncertifiable
+      scope is an :class:`~codd.implement_oracle_types.OracleScopeError` (a green
+      oracle over an unknown/empty scope is the #1 false-green), so this method
+      either returns a human-readable certification detail or raises.
+    * :meth:`normalize_command_result` for EACH command of a ``command`` /
+      ``composite`` oracle — the generic command-sequence executor spawns the
+      command (argv/cwd/env from the referenced :class:`CommandSpec`) and hands the
+      raw result here for a language-neutral verdict.
+    * :meth:`execute` ONLY for a ``kind="adapter"`` oracle (Python's in-process
+      compile + import-resolver + collect-only composite) — there is no shell
+      command sequence; the adapter runs the whole oracle and returns the result.
+
+    A ``command`` / ``composite`` adapter does NOT need to implement ``execute``; an
+    ``adapter``-kind adapter MUST. The dispatch checks for ``execute`` and reds a
+    missing one (a declared ``kind="adapter"`` with no executor is an incomplete
+    contract, never a silent pass).
+    """
+
+    def certify_scope(self, ctx: OracleContext) -> str:
+        """Certify the oracle's scope covers what it must, else raise.
+
+        Returns a human-readable certification detail on success; raises
+        :class:`~codd.implement_oracle_types.OracleScopeError` when the scope
+        cannot be proven to cover source + tests (anti-false-green).
+        """
+        ...
+
+    def normalize_command_result(
+        self,
+        ctx: OracleContext,
+        *,
+        command_id: str,
+        command: CommandSpec,
+        returncode: int,
+        stdout: str,
+        stderr: str,
+    ) -> OracleStepObservation:
+        """Normalize one command's raw result → a language-neutral observation.
+
+        MUST be conservative: only report ``is_clean=True`` when the step
+        positively proved coherence. A non-zero exit with no recognizable
+        diagnostic should yield ``is_clean=False`` with EMPTY findings, which the
+        executor escalates to an opaque ``environment_build_error`` RED.
+        """
+        ...
+
+
+@runtime_checkable
+class ImplementOracleExecutorAdapter(ImplementOracleAdapter, Protocol):
+    """An :class:`ImplementOracleAdapter` that ALSO runs a ``kind="adapter"`` oracle.
+
+    The Python composite (compile + first-party import/symbol resolver +
+    ``pytest --collect-only``) is not a shell command sequence — it runs in-process
+    and inspects the file lists each layer observed. Such a stack declares
+    ``kind="adapter"`` and its adapter implements :meth:`execute`, which the
+    dispatch calls instead of the generic command-sequence executor.
+    """
+
+    def execute(self, ctx: OracleContext) -> ImplementOracleResult:
+        """Run the whole in-process composite oracle and return its result."""
+        ...
+
+
+def adapter_supports_execute(adapter: object) -> bool:
+    """True when ``adapter`` provides a callable ``execute`` (the kind=adapter check).
+
+    The dispatch uses this to fail-closed on a ``kind="adapter"`` declaration whose
+    registered adapter has no executor: a declared in-process oracle with no
+    ``execute`` is an incomplete contract (RED), never a silent pass.
+    """
+    candidate = getattr(adapter, "execute", None)
+    return callable(candidate)
+
+
+__all__ = [
+    "ImplementOracleAdapter",
+    "ImplementOracleExecutorAdapter",
+    "OracleContext",
+    "OracleStepObservation",
+    "adapter_supports_execute",
+]

{codd_dev-2.76.0 → codd_dev-2.78.0}/codd/languages/builtin_adapters.py

@@ -83,5 +83,37 @@ def ensure_builtin_adapters_registered(registry: AdapterRegistry | None = None)
     _register_once(target, "runner_report", "vitest-json", VitestJsonReportAdapter())
     _register_once(target, "runner_report", "go-test-json", GoTestJsonReportAdapter())
 
+    # Implement-oracle tool-semantics adapters (Contract Kernel oracle dispatch §3).
+    # The plumbing is wired now; the concrete oracle_go / oracle_python /
+    # oracle_typescript adapters register inside register_oracle_adapters WITH their
+    # dispatch switch steps. Today it registers NOTHING (additive scaffolding only).
+    register_oracle_adapters(target)
+
     if target is default_adapter_registry:
         _BUILTINS_REGISTERED = True
+
+
+def register_oracle_adapters(registry: AdapterRegistry) -> None:
+    """Register the built-in ``implement_oracle`` adapters on ``registry`` (lazy/idempotent).
+
+    The registry plumbing for the Contract Kernel oracle dispatch (§3): the concrete
+    per-language oracle adapters (``go-toolchain`` / ``typescript-tsc`` /
+    ``python-composite``) register HERE under kind
+    :data:`codd.languages.contract.KIND_IMPLEMENT_ORACLE`, each via the SAME
+    fail-closed :func:`_register_once` (a different adapter at an occupied
+    ``(kind, id)`` raises — a silent oracle override is exactly the false-green this
+    kernel forbids).
+
+    Currently registers NOTHING: the concrete adapters are still in the per-language
+    gate (:mod:`codd.implement_oracle`) and only relocate here with their dispatch
+    switch steps (5–7). This is the additive seam — wired, idempotent, collision-safe
+    — so those adapters drop in as one ``_register_once`` call each, no new plumbing.
+    The adapter classes will be imported INSIDE this function (lazy), never at module
+    load, preserving the leaf rule.
+    """
+    # No concrete implement_oracle adapters yet. When they land:
+    #   from codd.languages.adapters.oracle_go import GoToolchainOracleAdapter
+    #   from codd.languages.contract import KIND_IMPLEMENT_ORACLE
+    #   _register_once(registry, KIND_IMPLEMENT_ORACLE, "go-toolchain", GoToolchainOracleAdapter())
+    #   ... (typescript-tsc, python-composite)
+    return

{codd_dev-2.76.0 → codd_dev-2.78.0}/codd/languages/contract.py

@@ -42,6 +42,12 @@ KIND_TEST_SEMANTICS = "test_semantics"
 KIND_RUNNER_REPORT = "runner_report"
 KIND_IMPORT_RESOLVER = "import_resolver"
 KIND_SCAFFOLD = "scaffold"
+#: The implement-time oracle tool-semantics adapter kind (Contract Kernel oracle
+#: dispatch §3). A profile names its oracle adapter id in
+#: ``implement_oracle.adapter``; the registry keys it under this kind. The concrete
+#: oracle_go / oracle_python / oracle_typescript adapters register under it WITH
+#: their dispatch switch steps — none is registered yet (the plumbing is additive).
+KIND_IMPLEMENT_ORACLE = "implement_oracle"
 
 
 @dataclass(frozen=True)