core-runtime 2.14.5__tar.gz → 2.15.0__tar.gz

{core_runtime-2.14.5 → core_runtime-2.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-runtime
-Version: 2.14.5
+Version: 2.15.0
 Summary: CORE: executable constitutional governance for AI-assisted software development.
 License-Expression: MIT
 License-File: LICENSE
@@ -57,26 +57,29 @@ Description-Content-Type: text/markdown
 
 > **Executable constitutional governance for AI-assisted software development.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Release](https://img.shields.io/badge/Release-v2.14.5-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![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.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.14.5 — see [CHANGELOG.md](CHANGELOG.md).
+**Current Release:** v2.15.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 
 CORE audits a codebase against declared rules in `.intent/`, records every
 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](docs/what-core-does.md).
+approves them. What it is for, in plain words: [What CORE does](https://dariusznewecki.github.io/CORE/what-core-does/).
 
 ## Install and first run
 
 ```bash
+python3 -m venv .venv && . .venv/bin/activate
 pip install core-runtime
 ```
 
-This gives you the `core-admin` CLI. In a repository that already has a
+Current Ubuntu and Debian refuse a bare `pip install` outside a virtual
+environment ("externally-managed-environment"); the first line creates one
+(`pipx install core-runtime` works too). This gives you the `core-admin` CLI. In a repository that already has a
 `.intent/` constitution, audit it with no services running:
 
 ```bash
@@ -89,9 +92,13 @@ To bring CORE into an existing repository, no services are needed either:
 cd your-repo
 core-admin project init . --write
 core-admin project adopt-pack core/starter-python --write
+git add .intent && git commit -m "Adopt CORE"
 core-admin code audit --offline
 ```
 
+The audit judges the law committed at `HEAD`, so commit `.intent/` first;
+uncommitted law reads DEGRADED, never PASS.
+
 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
 [Connect your AI assistant](https://dariusznewecki.github.io/CORE/connect-an-assistant/):
@@ -105,7 +112,9 @@ A new project:
 ```bash
 core-admin project new myproject --write
 cd myproject
+git init
 core-admin project adopt-pack core/starter-python --write
+git add -A && git commit -m "Adopt core/starter-python"
 core-admin code audit --offline
 ```
 
@@ -119,10 +128,10 @@ cd CORE
 
 ## More
 
-- Decisions: [.specs/DECISIONS.md](.specs/DECISIONS.md)
-- Documentation: [docs/](docs/index.md), published at [dariusznewecki.github.io/CORE](https://dariusznewecki.github.io/CORE/)
+- Decisions: [.specs/DECISIONS.md](https://github.com/DariuszNewecki/CORE/blob/main/.specs/DECISIONS.md)
+- Documentation: [docs/](https://github.com/DariuszNewecki/CORE/blob/main/docs/index.md), published at [dariusznewecki.github.io/CORE](https://dariusznewecki.github.io/CORE/)
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE).
 

{core_runtime-2.14.5 → core_runtime-2.15.0}/README.md

@@ -2,26 +2,29 @@
 
 > **Executable constitutional governance for AI-assisted software development.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Release](https://img.shields.io/badge/Release-v2.14.5-blue)](https://github.com/DariuszNewecki/CORE/releases)
+[![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.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.14.5 — see [CHANGELOG.md](CHANGELOG.md).
+**Current Release:** v2.15.0 — see [CHANGELOG.md](https://github.com/DariuszNewecki/CORE/blob/main/CHANGELOG.md).
 
 ## What CORE is
 
 CORE audits a codebase against declared rules in `.intent/`, records every
 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](docs/what-core-does.md).
+approves them. What it is for, in plain words: [What CORE does](https://dariusznewecki.github.io/CORE/what-core-does/).
 
 ## Install and first run
 
 ```bash
+python3 -m venv .venv && . .venv/bin/activate
 pip install core-runtime
 ```
 
-This gives you the `core-admin` CLI. In a repository that already has a
+Current Ubuntu and Debian refuse a bare `pip install` outside a virtual
+environment ("externally-managed-environment"); the first line creates one
+(`pipx install core-runtime` works too). This gives you the `core-admin` CLI. In a repository that already has a
 `.intent/` constitution, audit it with no services running:
 
 ```bash
@@ -34,9 +37,13 @@ To bring CORE into an existing repository, no services are needed either:
 cd your-repo
 core-admin project init . --write
 core-admin project adopt-pack core/starter-python --write
+git add .intent && git commit -m "Adopt CORE"
 core-admin code audit --offline
 ```
 
+The audit judges the law committed at `HEAD`, so commit `.intent/` first;
+uncommitted law reads DEGRADED, never PASS.
+
 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
 [Connect your AI assistant](https://dariusznewecki.github.io/CORE/connect-an-assistant/):
@@ -50,7 +57,9 @@ A new project:
 ```bash
 core-admin project new myproject --write
 cd myproject
+git init
 core-admin project adopt-pack core/starter-python --write
+git add -A && git commit -m "Adopt core/starter-python"
 core-admin code audit --offline
 ```
 
@@ -64,9 +73,9 @@ cd CORE
 
 ## More
 
-- Decisions: [.specs/DECISIONS.md](.specs/DECISIONS.md)
-- Documentation: [docs/](docs/index.md), published at [dariusznewecki.github.io/CORE](https://dariusznewecki.github.io/CORE/)
+- Decisions: [.specs/DECISIONS.md](https://github.com/DariuszNewecki/CORE/blob/main/.specs/DECISIONS.md)
+- Documentation: [docs/](https://github.com/DariuszNewecki/CORE/blob/main/docs/index.md), published at [dariusznewecki.github.io/CORE](https://dariusznewecki.github.io/CORE/)
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/DariuszNewecki/CORE/blob/main/LICENSE).

{core_runtime-2.14.5 → core_runtime-2.15.0}/pyproject.toml

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

{core_runtime-2.14.5 → core_runtime-2.15.0}/src/api/dependencies.py

@@ -40,7 +40,11 @@ from body.introspection.generate_capability_docs import (
 from body.services.blackboard_service.blackboard_service import BlackboardService
 from body.services.consequence_log_service import ConsequenceLogService
 from shared.infrastructure.database.session_manager import get_db_session, get_session
-from shared.infrastructure.principal_binding import GOVERNOR, load_principal_binding
+from shared.infrastructure.principal_binding import (
+    GOVERNOR,
+    PRODUCER,
+    load_principal_binding,
+)
 from shared.infrastructure.secrets_service import SecretsService
 from shared.infrastructure.secrets_service import (
     get_secrets_service as _get_secrets_svc,
@@ -127,6 +131,38 @@ async def get_governor(
 
 require_governor = Depends(get_governor)
 
+# Who may have CORE run code they hand it (external review F1).
+CANDIDATE_CODE_ROLES: frozenset[str] = frozenset({GOVERNOR, PRODUCER})
+
+
+# ID: daccba1b-8b1b-4324-9609-17346d28f56a
+def require_identified_producer(principal: CallerPrincipal) -> str:
+    """The caller's account when it is identified on a Unix socket and bound to
+    the governor or a producer; otherwise 403 (external review F1).
+
+    TCP carries no identity, so it never passes: any local account can reach
+    127.0.0.1:8000.
+    """
+    if principal.uid is None:
+        raise HTTPException(
+            status_code=403,
+            detail=(
+                "Running a candidate's code is accepted only on CORE's Unix socket "
+                "(CORE_API_URL=unix:///run/core/api-producer/api.sock for a "
+                "producer); TCP carries no identity."
+            ),
+        )
+    if principal.role not in CANDIDATE_CODE_ROLES or principal.account is None:
+        reason = principal.binding_error or (
+            f"account {principal.account or principal.uid!s} is bound to "
+            f"{principal.role or 'no role'}"
+        )
+        raise HTTPException(
+            status_code=403,
+            detail=f"Not a producer or the governor: {reason}.",
+        )
+    return principal.account
+
 
 # ID: 7854c52e-6493-402f-ba18-08ecdcf1fd2b
 def get_consequence_log_service() -> ConsequenceLogService:

{core_runtime-2.14.5 → core_runtime-2.15.0}/src/api/serve.py

@@ -17,6 +17,16 @@ pinned here and the API is launched with::
 
     python -m api.serve --uds <socket path> [--host 127.0.0.1] [--port 8000]
 
+``CORE_API_PRODUCER_UDS`` (a path, set in the unit) names a second
+identity-bearing socket in a directory whose group holds the producers (the
+coding assistant), never the governor's (external review F1): a producer
+reaches CORE with its identity without entering the governor's socket
+directory. The identity still comes only from the kernel; the variable only
+says where to listen. It is a variable, not an option, so a rollback to a
+release without it ignores it instead of refusing to start. When the
+socket's directory does not exist (the host step that creates it has not
+been taken) the socket is skipped with a warning, so the API still starts.
+
 The socket's directory and group are deployment concerns (D10.3 as amended:
 a ``core``-owned directory whose group excludes the assistant). This module
 only sets the socket's own mode to 0660.
@@ -41,6 +51,9 @@ from shared.logger import getLogger
 logger = getLogger(__name__)
 
 PEER_CRED_EXTENSION = "peer_cred"
+PRODUCER_UDS_ENV = "CORE_API_PRODUCER_UDS"
+# uvicorn's exit code for a failed startup (uvicorn.main.STARTUP_FAILURE).
+STARTUP_FAILURE = 3
 _UCRED = struct.Struct("3i")
 
 
@@ -101,6 +114,22 @@ def bind_unix_socket(path: Path) -> socket.socket:
     return sock
 
 
+# ID: b6d4023c-d0fc-4da4-853d-6661950e406c
+def producer_socket(path: Path | None) -> socket.socket | None:
+    """The producers' Unix socket at *path*, or None when there is none to bind:
+    no path given, or its directory not created yet (warned, not fatal)."""
+    if path is None:
+        return None
+    if not path.parent.is_dir():
+        logger.warning(
+            "core-api: producer socket skipped, %s does not exist", path.parent
+        )
+        return None
+    sock = bind_unix_socket(path)
+    logger.info("core-api listening for producers on %s", path)
+    return sock
+
+
 # ID: c01d3424-c64a-48ca-bf07-1a4fc2263ecb
 def bind_tcp_socket(host: str, port: int) -> socket.socket:
     """Bind a listening TCP socket on *host*:*port*."""
@@ -118,8 +147,14 @@ def build_config(app: Any = "api.main:app", log_level: str = "info") -> uvicorn.
 
 
 # ID: d1afafa9-7a13-4904-8263-2978ded03074
-def main(argv: list[str] | None = None) -> None:
-    """Serve the API on TCP (user-facing) and a Unix socket (identity-bearing)."""
+def main(argv: list[str] | None = None, app: Any = "api.main:app") -> None:
+    """Serve the API on TCP (user-facing) and a Unix socket (identity-bearing).
+
+    A startup that fails (the database not up yet after a boot, #1087) exits
+    with uvicorn's own code 3, not 0: ``Server.run`` returns quietly when the
+    lifespan startup fails (only ``uvicorn.run`` turns that into an exit
+    code), and systemd's ``Restart=on-failure`` never restarts an exit 0.
+    """
     parser = argparse.ArgumentParser(prog="python -m api.serve")
     parser.add_argument("--uds", type=Path, required=True)
     parser.add_argument("--host", default="127.0.0.1")
@@ -129,7 +164,17 @@ def main(argv: list[str] | None = None) -> None:
 
     sockets = [bind_tcp_socket(args.host, args.port), bind_unix_socket(args.uds)]
     logger.info("core-api listening on %s:%d and %s", args.host, args.port, args.uds)
-    uvicorn.Server(build_config(log_level=args.log_level)).run(sockets=sockets)
+    producer_path = os.environ.get(PRODUCER_UDS_ENV, "").strip()
+    producer = producer_socket(Path(producer_path) if producer_path else None)
+    if producer is not None:
+        sockets.append(producer)
+    server = uvicorn.Server(build_config(app, log_level=args.log_level))
+    server.run(sockets=sockets)
+    if not server.started:
+        logger.error(
+            "core-api did not start; exiting %d so systemd restarts it", STARTUP_FAILURE
+        )
+        raise SystemExit(STARTUP_FAILURE)
 
 
 if __name__ == "__main__":

{core_runtime-2.14.5 → core_runtime-2.15.0}/src/api/v1/fix_routes.py

@@ -16,7 +16,12 @@ Endpoints in this module fall into three groups:
 GOVERNOR GATE (ADR-132 D10.11 step 4): POST /fix/run/{fix_id} is open for a
 dry run (``write=false``, ADR-014) so the coding assistant can validate a
 patch (``assisted.validate_diff``, ADR-168); ``write=true`` is checked in the
-handler and needs the governor. Run status reads are open.
+handler and needs the governor. An action whose declared impact writes files
+(``action_mutates_files``) needs the governor whatever ``write`` says
+(external review F2). An action that runs code it is handed
+(``action_runs_candidate_code``: ``assisted.validate_diff``) is served only to
+an identified producer or the governor on a Unix socket, never over TCP
+(external review F1). Run status reads are open.
 
 * Synchronous dispatch — GET /fix/commands and GET /actions read the
   registry inline. POST /fix/ir writes a YAML scaffold via FileHandler
@@ -56,6 +61,7 @@ from api.dependencies import (
     get_governor,
     open_background_session,
     require_governor,
+    require_identified_producer,
 )
 from api.v1.schemas import (
     AsyncDispatchResponse,
@@ -66,6 +72,8 @@ from api.v1.schemas import (
 from shared.context import CoreContext
 from shared.logger import getLogger
 from will.governance.fix_runner import (
+    action_mutates_files,
+    action_runs_candidate_code,
     bootstrap_ir,
     list_action_definitions,
     list_registered_action_ids,
@@ -90,8 +98,12 @@ INTENTIONALLY_UNGATED: dict[str, str] = {
         "Dry run open, write gated in the handler: with write=false (the "
         "ADR-014 default) an action only reports; the coding assistant's "
         "validate_change runs assisted.validate_diff this way (ADR-168). "
-        "write=true calls get_governor and is refused (403) for anyone but "
-        "the governor on the Unix socket (ADR-132 D10.11 step 4)."
+        "write=true, or any action whose declared impact writes files "
+        "(action_mutates_files, external review F2), calls get_governor and "
+        "is refused (403) for anyone but the governor on the Unix socket "
+        "(ADR-132 D10.11 step 4). An action that runs code it is handed "
+        "(assisted.validate_diff) is refused over TCP and to any account not "
+        "bound to the producer or governor role (external review F1)."
     ),
 }
 # Top-level router for GET /actions (ADR-055 D2 places it outside the
@@ -161,8 +173,11 @@ class RunIRRequest(BaseModel):
         "`fix.format`, `fix.imports`, `fix.docstrings`). Returns 422 if "
         "`fix_id` is unknown — the response body includes a registered "
         "ids count. Valid ids return 202 + a `run_id` to poll. `write=false` "
-        "is the dry-run default (ADR-014) and is open; `write=true` needs the "
-        "governor on CORE's Unix socket (403 otherwise). `params` carries action-specific "
+        "is the dry-run default (ADR-014) and is open; `write=true`, or an "
+        "action whose declared impact writes files, needs the governor on "
+        "CORE's Unix socket (403 otherwise). An action that runs code it is "
+        "handed (`assisted.validate_diff`) is served only on a Unix socket to "
+        "a producer or the governor. `params` carries action-specific "
         "kwargs (e.g. `fix.docstrings`'s `limit`) and is forwarded as "
         "`**kwargs` to ActionExecutor.execute."
     ),
@@ -177,21 +192,23 @@ async def run_fix(
     session: AsyncSession = Depends(get_api_session),
     principal: CallerPrincipal = caller_principal,
 ) -> dict:
-    """Dispatch an atomic fix action by id; a write needs the governor.
+    """Dispatch an atomic fix action by id; a write or a file-mutating action needs the governor.
 
     Validates `fix_id` against the action registry — unknown ids return
     422 with the list of registered ids in the response body. Valid
     ids land a pending row in core.fix_runs and queue background
     execution via the will.governance.fix_runner facade.
     """
-    if payload.write:
-        await get_governor(principal)
     registered = list_registered_action_ids()
     if fix_id not in registered:
         raise HTTPException(
             status_code=422,
             detail=f"Unknown fix_id: {fix_id!r}. {len(registered)} registered actions.",
         )
+    if action_runs_candidate_code(fix_id):
+        require_identified_producer(principal)
+    if payload.write or action_mutates_files(fix_id):
+        await get_governor(principal)
 
     core_context: CoreContext = request.app.state.core_context
 

{core_runtime-2.14.5 → core_runtime-2.15.0}/src/api/v1/inspect_routes.py

@@ -40,6 +40,7 @@ from will.governance.inspect_runner import (
     get_decisions,
     get_decisions_patterns,
     get_drift_status,
+    get_health,
     get_refusals,
     get_refusals_stats,
     get_search_capabilities,
@@ -96,6 +97,25 @@ async def status_db(session: AsyncSession = Depends(get_api_session)) -> dict:
     return await get_db_status(session)
 
 
+@status_router.get(
+    "/health",
+    summary="Workers, blackboard and proposals at a glance (core status)",
+    description=(
+        "Read-only: workers with heartbeat ages and liveness, open blackboard "
+        "entries by type and status, the oldest open finding, stuck signals "
+        "(proposal.stuck_*, blackboard.entry_stale, worker.silent), live "
+        "proposals, findings created vs resolved in the last 7 days, and the "
+        "ten rules with the most findings abandoned in those days (created, "
+        "distinct subjects, resolved, abandoned per rule). The same answer as "
+        "the MCP tool core_status."
+    ),
+)
+# ID: 8a827edf-0511-40a9-a50d-ca26b91709bc
+async def status_health(session: AsyncSession = Depends(get_api_session)) -> dict:
+    """Return the runtime health picture."""
+    return await get_health(session)
+
+
 @status_router.get(
     "/drift",
     summary="Knowledge-graph drift snapshot",