core-runtime 2.15.1__tar.gz → 2.16.0__tar.gz

{core_runtime-2.15.1 → core_runtime-2.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-runtime
-Version: 2.15.1
+Version: 2.16.0
 Summary: CORE: executable constitutional governance for AI-assisted software development.
 License-Expression: MIT
 License-File: LICENSE
@@ -58,10 +58,10 @@ Description-Content-Type: text/markdown
 > **Executable constitutional governance for AI-assisted software development.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE)
-[![Release](https://img.shields.io/badge/Release-v2.15.1-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![Release](https://img.shields.io/badge/Release-v2.16.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
 [![Docs](https://img.shields.io/badge/Docs-online-green)](https://dariusznewecki.github.io/CORE/)
 
-**Current Release:** v2.15.1 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
+**Current Release:** v2.16.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 
@@ -70,8 +70,17 @@ violation, proposes fixes, and logs the chain from finding to commit. AI
 assistants and CORE's own loop can propose changes; only the human governor
 approves them. What it is for, in plain words: [What CORE does](https://dariusznewecki.github.io/CORE/what-core-does/).
 
+The `pip install` below gives you the offline audit, CORE's audit on every pull
+request (GitHub Action) and, for your AI assistant, the rules and a verdict on
+its change before it commits. Recording findings, proposing fixes, CORE's own
+loop and changes submitted for your approval need the full local runtime (last
+block of this section).
+
 ## Install and first run
 
+You need Python 3.12 or later and git. On Debian and Ubuntu, `python3 -m venv`
+also needs the `python3-venv` package (`sudo apt install python3-venv git`).
+
 ```bash
 python3 -m venv .venv && . .venv/bin/activate
 pip install core-runtime
@@ -90,14 +99,21 @@ To bring CORE into an existing repository, no services are needed either:
 
 ```bash
 cd your-repo
-core-admin project init . --write
+core-admin project init . --write --yes
 core-admin project adopt-pack core/starter-python --write
-git add .intent && git commit -m "Adopt CORE"
+git add .intent .github && git commit -m "Adopt CORE"
 core-admin code audit --offline
 ```
 
+`project init --write` asks for confirmation at a terminal; `--yes` skips the
+question, and without a terminal (CI, scripts, AI agents) it stops at once
+unless `--yes` is given.
+
 The audit judges the law committed at `HEAD`, so commit `.intent/` first;
-uncommitted law reads DEGRADED, never PASS.
+uncommitted law reads DEGRADED, never PASS. `project init` also writes CORE's
+GitHub Action (`.github/workflows/core-audit.yml`); commit it with the law. The
+audit lists blocking and high findings; reporting and advisory ones are only
+counted. Add `--severity info` to list them too.
 
 Connect your AI assistant (Claude Code shown; any MCP client works) so it asks
 CORE about your project's rules and checks its change before committing; see
@@ -107,6 +123,11 @@ CORE about your project's rules and checks its change before committing; see
 claude mcp add --scope project core -- core-admin mcp run
 ```
 
+Claude Code starts `core-admin` itself, so it must be on `PATH` in the shell
+you start `claude` from: activate the virtual environment first, or install
+with `pipx install core-runtime` (then `pipx ensurepath`) so it is on `PATH` in
+every shell. Everyone who uses the committed `.mcp.json` needs the same.
+
 A new project:
 
 ```bash
@@ -118,7 +139,9 @@ git add -A && git commit -m "Adopt core/starter-python"
 core-admin code audit --offline
 ```
 
-To run the full local runtime (Postgres + Qdrant) from a clone:
+To run the full local runtime (Postgres + Qdrant) from a clone (it also needs
+Docker with Compose v2 and Poetry; every prerequisite is in
+[Run the full runtime](https://dariusznewecki.github.io/CORE/getting-started/)):
 
 ```bash
 git clone https://github.com/DariuszNewecki/CORE.git

{core_runtime-2.15.1 → core_runtime-2.16.0}/README.md

@@ -3,10 +3,10 @@
 > **Executable constitutional governance for AI-assisted software development.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE)
-[![Release](https://img.shields.io/badge/Release-v2.15.1-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![Release](https://img.shields.io/badge/Release-v2.16.0-blue)](https://github.com/DariuszNewecki/CORE/releases)
 [![Docs](https://img.shields.io/badge/Docs-online-green)](https://dariusznewecki.github.io/CORE/)
 
-**Current Release:** v2.15.1 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
+**Current Release:** v2.16.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 
@@ -15,8 +15,17 @@ violation, proposes fixes, and logs the chain from finding to commit. AI
 assistants and CORE's own loop can propose changes; only the human governor
 approves them. What it is for, in plain words: [What CORE does](https://dariusznewecki.github.io/CORE/what-core-does/).
 
+The `pip install` below gives you the offline audit, CORE's audit on every pull
+request (GitHub Action) and, for your AI assistant, the rules and a verdict on
+its change before it commits. Recording findings, proposing fixes, CORE's own
+loop and changes submitted for your approval need the full local runtime (last
+block of this section).
+
 ## Install and first run
 
+You need Python 3.12 or later and git. On Debian and Ubuntu, `python3 -m venv`
+also needs the `python3-venv` package (`sudo apt install python3-venv git`).
+
 ```bash
 python3 -m venv .venv && . .venv/bin/activate
 pip install core-runtime
@@ -35,14 +44,21 @@ To bring CORE into an existing repository, no services are needed either:
 
 ```bash
 cd your-repo
-core-admin project init . --write
+core-admin project init . --write --yes
 core-admin project adopt-pack core/starter-python --write
-git add .intent && git commit -m "Adopt CORE"
+git add .intent .github && git commit -m "Adopt CORE"
 core-admin code audit --offline
 ```
 
+`project init --write` asks for confirmation at a terminal; `--yes` skips the
+question, and without a terminal (CI, scripts, AI agents) it stops at once
+unless `--yes` is given.
+
 The audit judges the law committed at `HEAD`, so commit `.intent/` first;
-uncommitted law reads DEGRADED, never PASS.
+uncommitted law reads DEGRADED, never PASS. `project init` also writes CORE's
+GitHub Action (`.github/workflows/core-audit.yml`); commit it with the law. The
+audit lists blocking and high findings; reporting and advisory ones are only
+counted. Add `--severity info` to list them too.
 
 Connect your AI assistant (Claude Code shown; any MCP client works) so it asks
 CORE about your project's rules and checks its change before committing; see
@@ -52,6 +68,11 @@ CORE about your project's rules and checks its change before committing; see
 claude mcp add --scope project core -- core-admin mcp run
 ```
 
+Claude Code starts `core-admin` itself, so it must be on `PATH` in the shell
+you start `claude` from: activate the virtual environment first, or install
+with `pipx install core-runtime` (then `pipx ensurepath`) so it is on `PATH` in
+every shell. Everyone who uses the committed `.mcp.json` needs the same.
+
 A new project:
 
 ```bash
@@ -63,7 +84,9 @@ git add -A && git commit -m "Adopt core/starter-python"
 core-admin code audit --offline
 ```
 
-To run the full local runtime (Postgres + Qdrant) from a clone:
+To run the full local runtime (Postgres + Qdrant) from a clone (it also needs
+Docker with Compose v2 and Poetry; every prerequisite is in
+[Run the full runtime](https://dariusznewecki.github.io/CORE/getting-started/)):
 
 ```bash
 git clone https://github.com/DariuszNewecki/CORE.git

{core_runtime-2.15.1 → core_runtime-2.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "core-runtime"
-version = "2.15.1"
+version = "2.16.0"
 description = "CORE: executable constitutional governance for AI-assisted software development."
 authors = [
     { name = "Dariusz Newecki", email = "d.newecki@gmail.com" },

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/api/v1/inspect_routes.py

@@ -45,6 +45,7 @@ from will.governance.inspect_runner import (
     get_refusals_stats,
     get_search_capabilities,
     get_search_commands,
+    get_spend,
 )
 
 
@@ -116,6 +117,25 @@ async def status_health(session: AsyncSession = Depends(get_api_session)) -> dic
     return await get_health(session)
 
 
+@status_router.get(
+    "/spend",
+    summary="What CORE's LLM calls cost (ADR-172)",
+    description=(
+        "Read-only: LLM spend over the last `days` days from "
+        "core.llm_exchange_log, in total, per UTC day, and per cognitive role "
+        "and model (calls, tokens, USD, USD per call, calls without a price). "
+        "core-admin runtime spend and the MCP tool core_status read this."
+    ),
+)
+# ID: e4b7a2c9-3f18-4d6e-b05a-8c1d9f2e7a34
+async def status_spend(
+    days: int = Query(7, ge=1, le=366),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return LLM spend for the last `days` days."""
+    return await get_spend(session, days)
+
+
 @status_router.get(
     "/drift",
     summary="Knowledge-graph drift snapshot",

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/api/v1/proposals_routes.py

@@ -22,9 +22,11 @@ CONSTITUTIONAL:
 
 GOVERNOR GATE (ADR-132 D10.11 step 4): approve, reject, execute and create
 need the governor on CORE's Unix socket; approve is stamped from that
-identity (D10.4). Submitting a producer's change (ADR-168) and reading
-proposals are open: a submission is only a pending proposal, and nothing
-lands without the governor's approval.
+identity (D10.4). Submitting a producer's change (ADR-168) needs a producer
+or the governor identified on the Unix socket, and the producer recorded is
+that account, never the request's word (review M2: over TCP any local
+account could name any producer and fill the governor's queue). Reading
+proposals is open.
 """
 
 from __future__ import annotations
@@ -37,9 +39,12 @@ from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from api.dependencies import (
+    CallerPrincipal,
     ConsequenceLogDep,
+    caller_principal,
     get_api_session,
     require_governor,
+    require_identified_producer,
 )
 from api.v1.schemas import (
     GovernanceChainResponse,
@@ -123,10 +128,21 @@ class SubmitChangeRequest(BaseModel):
     goal: str
     anchor_kind: str
     anchor_refs: list[str]
-    producer: str
+    # The caller's own name for itself; the recorded producer is the
+    # socket-identified account (see recorded_producer).
+    producer: str | None = None
     retires: list[str] = []
 
 
+# ID: 0e5b9c27-4a81-4f36-9d2e-6c1a8f3b7d54
+def recorded_producer(account: str, claimed: str | None) -> str:
+    """The producer stamped on a submission: the identified account, with the
+    caller's own label kept beside it when it differs."""
+    if not claimed or claimed == account:
+        return account
+    return f"{account} as {claimed}"
+
+
 # ID: 71caa34a-1661-4178-b982-626bff254539
 class CreateProposalRequest(BaseModel):
     """Body for POST /proposals.
@@ -162,13 +178,19 @@ class CreateProposalRequest(BaseModel):
         "which CORE re-reads. CORE answers step 0 (what it retires, related "
         "decisions, similar existing code) and creates a PENDING proposal "
         "carrying the anchor, problem owner (the governor) and producer. "
+        "Only on CORE's Unix socket, from an account bound to a producer or the "
+        "governor; the producer recorded is that account (403 otherwise). "
         "Approval is always required; this route never approves. 422 when the "
         "run does not bind the patch or the submission is malformed."
     ),
 )
 # ID: 1ea37180-f337-40c5-aa43-2283da29e563
-async def submit_change(payload: SubmitChangeRequest) -> dict:
+async def submit_change(
+    payload: SubmitChangeRequest,
+    principal: CallerPrincipal = caller_principal,
+) -> dict:
     """Route a producer's validated change to the Will-layer submission service."""
+    account = require_identified_producer(principal)
     from shared.models.validated_remediation_candidate import (
         CandidateConstructionError,
     )
@@ -184,7 +206,7 @@ async def submit_change(payload: SubmitChangeRequest) -> dict:
             goal=payload.goal,
             anchor_kind=payload.anchor_kind,
             anchor_refs=payload.anchor_refs,
-            producer=payload.producer,
+            producer=recorded_producer(account, payload.producer),
             retires=payload.retires,
             created_by="api.proposals_submit",
         )

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/body/atomic/action_audit.py

@@ -5,8 +5,9 @@ Action audit-trail persistence for the ActionExecutor gateway.
 Moved verbatim out of ``ActionExecutor._audit_log`` (ADR-095 split of the
 too-large executor class; zero behavior change). ``ActionAuditRecorder``
 writes one ``core.action_results`` row per executed action — step 7 of
-``ActionExecutor.execute`` — with bounded retry/backoff, and surfaces an
-``AUDIT_GAP`` error for write actions whose row could not be persisted.
+``ActionExecutor.execute`` — with bounded retry/backoff, and returns an
+``AUDIT_GAP`` error for write actions whose row could not be persisted; the
+executor then fails the run (F4).
 
 This module defines no atomic action and never invokes ``ActionExecutor``;
 it is a plain persistence helper the executor delegates to.
@@ -44,10 +45,15 @@ class ActionAuditRecorder:
     # ID: 454c8ccb-ece8-4ef8-baf1-13c9c19f4300
     async def record(
         self, definition: ActionDefinition, result: ActionResult, write: bool
-    ) -> None:
+    ) -> str | None:
         """
         Log action execution to database audit trail (SSOT).
 
+        Returns None when the row persisted. When every attempt failed, returns
+        the AUDIT_GAP message for a write action (F4: the executor turns the
+        run into a failure; a lost record is not a success) and None for a
+        read action, whose lost record stays a best-effort warning.
+
         Retries the INSERT up to _AUDIT_MAX_ATTEMPTS times with exponential
         backoff before declaring an AUDIT_GAP. Each attempt opens a fresh
         session so a rolled-back transaction from a prior attempt does not
@@ -90,7 +96,7 @@ class ActionAuditRecorder:
                 async with self.core_context.registry.session() as session:
                     async with session.begin():
                         await session.execute(stmt, params)
-                return  # persisted successfully
+                return None  # persisted successfully
             except Exception as e:
                 last_exc = e
                 if attempt < self._AUDIT_MAX_ATTEMPTS:
@@ -105,17 +111,17 @@ class ActionAuditRecorder:
         # failure mode — action_type/ok are always supplied).
         assert last_exc is not None
         if write:
-            logger.error(
-                "AUDIT_GAP: write action %s executed but its "
-                "core.action_results row failed to persist after %d attempts "
-                "(%s) — mutation stands, audit trail incomplete (#634/#752)",
-                definition.action_id,
-                self._AUDIT_MAX_ATTEMPTS,
-                last_exc,
-            )
-        else:
-            logger.warning(
-                "Non-blocking audit log failure (read) after %d attempts: %s",
-                self._AUDIT_MAX_ATTEMPTS,
-                last_exc,
+            gap = (
+                f"AUDIT_GAP: write action {definition.action_id} executed but its "
+                f"core.action_results row failed to persist after "
+                f"{self._AUDIT_MAX_ATTEMPTS} attempts ({last_exc}) — mutation "
+                f"stands, audit trail incomplete, run reported failed (#634/#752, F4)"
             )
+            logger.error(gap)
+            return gap
+        logger.warning(
+            "Non-blocking audit log failure (read) after %d attempts: %s",
+            self._AUDIT_MAX_ATTEMPTS,
+            last_exc,
+        )
+        return None

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/body/atomic/assisted_actions.py

@@ -610,9 +610,16 @@ def _general_test_targets(wt_path: Path, touched_py: list[str]) -> list[str]:
 
 
 async def _run_test_files(aid: str, wt_path: Path, targets: list[str]) -> bool:
-    """True when every test file in *targets* passes in *wt_path*."""
+    """True when every test file in *targets* passes in *wt_path*.
+
+    No targets is False: zero tests collected verified nothing, so it is a
+    failure, not a pass. A target that collects no test is already not ok
+    (``run_tests`` reports it ``not_run``).
+    """
     from body.sandbox.repo_tests import run_tests
 
+    if not targets:
+        return False
     passed = True
     for target in targets:
         result = await run_tests(

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/body/atomic/executor.py

@@ -19,6 +19,7 @@ CRITICAL: This enforces the "single execution contract" principle.
 from __future__ import annotations
 
 import contextlib
+import dataclasses
 import inspect
 import time
 from pathlib import Path
@@ -504,7 +505,19 @@ class ActionExecutor:
         await self._post_execute_hooks(definition, result)
 
         # 7. Audit logging (persistence lives in body.atomic.action_audit)
-        await ActionAuditRecorder(self.core_context).record(definition, result, write)
+        audit_gap = await ActionAuditRecorder(self.core_context).record(
+            definition, result, write
+        )
+        if isinstance(audit_gap, str):
+            # F4: a write run whose record was lost is a failure, not "success
+            # with a lost record". The action's own data, ok and error are kept.
+            lost: dict[str, Any] = {**result.data, "action_ok": result.ok}
+            for key in ("error", "error_type"):
+                if key in result.data:
+                    lost[f"action_{key}"] = result.data[key]
+            lost["error"] = audit_gap
+            lost["error_type"] = "AuditRecordLost"
+            result = dataclasses.replace(result, ok=False, data=lost)
 
         return result
 

{core_runtime-2.15.1 → core_runtime-2.16.0}/src/body/atomic/sandbox_lifecycle.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import dataclasses
 from collections.abc import Iterable
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from body.atomic.registry import ActionDefinition
@@ -55,6 +56,63 @@ logger = getLogger(__name__)
 _SANDBOXED_IMPACTS = frozenset({ActionImpact.WRITE_CODE, ActionImpact.WRITE_METADATA})
 
 
+def _missing_parent_dirs(root: Path, rel_paths: Iterable[str]) -> list[str]:
+    """Repo-relative parent directories of *rel_paths* that do not exist yet,
+    deepest first, so a rollback can remove the ones a write created."""
+    missing: set[str] = set()
+    for rel in rel_paths:
+        for parent in Path(rel).parents:
+            if str(parent) in ("", ".") or (root / parent).exists():
+                break
+            missing.add(parent.as_posix())
+    return sorted(missing, key=lambda d: d.count("/"), reverse=True)
+
+
+def _roll_back(
+    file_handler: Any,
+    root: Path,
+    touched: list[str],
+    originals: dict[str, bytes | None],
+    new_dirs: list[str],
+) -> None:
+    """Return every touched path to its snapshot bytes (F3).
+
+    A path that did not exist is removed; one that did is rewritten with its
+    original bytes; one already equal to its snapshot is left alone. Each
+    restore is attempted even if another fails, and a failed restore is
+    logged loudly — the caller re-raises the original error either way.
+    """
+    for rel in reversed(touched):
+        path = root / rel
+        original = originals.get(rel)
+        try:
+            current = path.read_bytes() if path.is_file() else None
+            if current == original:
+                continue
+            if original is None:
+                file_handler.remove_file(rel)
+            else:
+                file_handler.write(rel, original)
+        except Exception as exc:
+            logger.error(
+                "SandboxLifecycle: rollback of %s FAILED (%s); main tree may "
+                "differ from its pre-propagation state at this path",
+                rel,
+                exc,
+            )
+    for rel_dir in new_dirs:
+        abs_dir = root / rel_dir
+        try:
+            if abs_dir.is_dir() and not any(abs_dir.iterdir()):
+                file_handler.remove_tree(rel_dir)
+        except Exception as exc:
+            logger.error(
+                "SandboxLifecycle: rollback could not remove new directory %s (%s)",
+                rel_dir,
+                exc,
+            )
+
+
 def _flow_has_sandboxable_step(
     flow_id: str, _visited: frozenset[str] = frozenset()
 ) -> bool:
@@ -332,6 +390,11 @@ class SandboxLifecycle:
         ADR-168 Amendment 2026-10-10 A3: a patch's deleted files are applied
         and committed. An undeclared sandbox deletion is still logged and
         skipped — an action never deletes from the main tree by accident.
+
+        The copy is all or nothing (F3): if any write or delete raises, every
+        path already touched is restored to its pre-propagation bytes (new
+        files and the directories they created are removed) and the error is
+        re-raised, so the caller reports failure on an unchanged main tree.
         """
         sandbox_root = scoped_git.repo_path
         file_handler = self.core_context.file_handler
@@ -427,20 +490,43 @@ class SandboxLifecycle:
 
         self._refuse_if_main_moved_under_targets(scoped_git, target_paths)
 
+        # F3: all or nothing. Snapshot the main tree's bytes for every target
+        # before the first write; a failure on any file restores the files
+        # already replaced, removes the ones newly created, and re-raises —
+        # the main tree is never left half-propagated.
+        main_root = file_handler.repo_path
+        originals = {
+            rel: (main_root / rel).read_bytes() if (main_root / rel).is_file() else None
+            for rel in target_paths
+        }
+        new_dirs = _missing_parent_dirs(main_root, target_paths)
+        touched: list[str] = []
         copied = 0
-        for rel in sorted(target_paths):
-            if rel in deletions:
-                file_handler.remove_file(rel)
-                continue
-            src = sandbox_root / rel
-            if not src.exists():
-                logger.warning(
-                    "SandboxLifecycle: sandbox entry %s missing on disk; skipping",
-                    rel,
-                )
-                continue
-            file_handler.write(rel, src.read_bytes())
-            copied += 1
+        try:
+            for rel in sorted(target_paths):
+                touched.append(rel)
+                if rel in deletions:
+                    file_handler.remove_file(rel)
+                    continue
+                src = sandbox_root / rel
+                if not src.exists():
+                    logger.warning(
+                        "SandboxLifecycle: sandbox entry %s missing on disk; skipping",
+                        rel,
+                    )
+                    continue
+                file_handler.write(rel, src.read_bytes())
+                copied += 1
+        except Exception as exc:
+            logger.error(
+                "SandboxLifecycle: propagation failed at %s (%s); rolling back "
+                "%d file(s) in the main tree",
+                touched[-1] if touched else "?",
+                exc,
+                len(touched),
+            )
+            _roll_back(file_handler, main_root, touched, originals, new_dirs)
+            raise
 
         logger.info(
             "SandboxLifecycle: propagated %d file(s) and %d deletion(s) from "