loopx 0.4.8__py3-none-any.whl

loopx/capabilities/decision_context/catalog_entry.py

@@ -0,0 +1,195 @@
+"""Capability-owned catalog entry for Decision Context."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+DECISION_CONTEXT_CATALOG_ENTRY: dict[str, Any] = {
+    "id": "decision-context",
+    "origin": "builtin",
+    "visibility": "public",
+    "provider_id": "loopx-core",
+    "title": "Goal-scoped decision evidence, review, and outcome contract",
+    "status": "experimental",
+    "default_enabled": False,
+    "real_world_anchor": (
+        "incremental authority rebase before long-running agent decisions"
+    ),
+    "user_value": (
+        "Separate current evidence, advisory proposals, owner review, and "
+        "verified outcomes while keeping providers replaceable and Core "
+        "authority unchanged."
+    ),
+    "entry_command": (
+        "loopx decision-context inspect-profile "
+        "--goal-id <goal-id> --agent-id <agent-id> --format json"
+    ),
+    "commands": [
+        {
+            "command": "loopx decision-context architecture --format json",
+            "purpose": "Render the default-off packet, source, provider, and lifecycle boundaries.",
+            "write_boundary": "stateless contract output only; no provider, source, goal state, or external write",
+        },
+        {
+            "command": (
+                "loopx decision-context inspect-profile "
+                "--goal-id <goal-id> --agent-id <agent-id> "
+                "[--profile <private-local-profile>] --format json"
+            ),
+            "purpose": (
+                "Resolve the default-off goal and agent route while projecting "
+                "only public-safe provider availability."
+            ),
+            "write_boundary": (
+                "reads an optional private local profile; never emits source "
+                "locators, provider config, raw content, cursors, or credentials"
+            ),
+        },
+        {
+            "command": (
+                "loopx decision-context source-manifest "
+                "--goal-id <goal-id> --agent-id <agent-id> "
+                "--profile <private-local-profile> --format json"
+            ),
+            "purpose": (
+                "Project an enabled source profile into a public-safe manifest "
+                "before any provider access."
+            ),
+            "write_boundary": (
+                "read-only local projection; no provider access, cursor write, "
+                "goal mutation, or external action"
+            ),
+        },
+        {
+            "command": (
+                "loopx decision-context prepare-evidence "
+                "--goal-id <goal-id> --agent-id <agent-id> "
+                "--profile <private-local-profile> --decision-id <decision-id> "
+                "[--cursor-state <private-cursor-json>] "
+                "[--source-id <on-demand-source>] --format json"
+            ),
+            "purpose": (
+                "Run bounded scans and exact reads and emit a public-safe "
+                "evidence preparation packet for domain rebase."
+            ),
+            "write_boundary": (
+                "read-only provider access; changed-source cursors remain "
+                "preserved until semantic rebase and validated writeback"
+            ),
+        },
+        {
+            "command": (
+                "loopx decision-context prepare-review "
+                "--goal-id <goal-id> --agent-id <agent-id> "
+                "--profile <private-local-profile> --decision-id <decision-id> "
+                "--rebase-json <private-rebase> "
+                "--pending-settlement <private-pending> [--execute] --format json"
+            ),
+            "purpose": (
+                "Validate a domain semantic rebase and optionally persist an "
+                "unapplied private cross-turn settlement checkpoint."
+            ),
+            "write_boundary": (
+                "execute writes only the selected private pending checkpoint; "
+                "active cursors and Core state remain unchanged"
+            ),
+        },
+        {
+            "command": (
+                "loopx decision-context settle-review "
+                "--goal-id <goal-id> --agent-id <agent-id> "
+                "--profile <private-local-profile> --cursor-state <private-cursors> "
+                "--pending-settlement <private-pending> --event-log <event-log> "
+                "[--proposal-json <proposal> --source-event-id <gate-event>] "
+                "--actor-ref <actor> --reason-code <reason> --summary <summary> "
+                "[--execute] --format json"
+            ),
+            "purpose": (
+                "Settle approve, reject, defer, or explicit semantic no-change "
+                "and CAS-commit consumed-source cursors."
+            ),
+            "write_boundary": (
+                "execute appends one validated local rollout event and atomically "
+                "updates private cursors; no external action or authority change"
+            ),
+        },
+    ],
+    "implemented_protocols": [
+        {
+            "schema_version": schema_version,
+            "module": module,
+            "doc": "docs/reference/protocols/decision-context-architecture-v0.md",
+        }
+        for schema_version, module in (
+            (
+                "decision_context_architecture_v0",
+                "loopx.capabilities.decision_context.architecture",
+            ),
+            (
+                "decision_evidence_packet_v0",
+                "loopx.capabilities.decision_context.packets",
+            ),
+            (
+                "decision_proposal_v0",
+                "loopx.capabilities.decision_context.packets",
+            ),
+            (
+                "decision_review_receipt_v0",
+                "loopx.capabilities.decision_context.packets",
+            ),
+            (
+                "decision_outcome_receipt_v0",
+                "loopx.capabilities.decision_context.packets",
+            ),
+            (
+                "decision_source_manifest_v0",
+                "loopx.capabilities.decision_context.sources",
+            ),
+            (
+                "decision_source_scan_receipt_v0",
+                "loopx.capabilities.decision_context.sources",
+            ),
+            (
+                "decision_context_profile_v0",
+                "loopx.capabilities.decision_context.profile",
+            ),
+            (
+                "decision_context_activation_status_v0",
+                "loopx.capabilities.decision_context.profile",
+            ),
+            (
+                "decision_cursor_commit_receipt_v0",
+                "loopx.capabilities.decision_context.cursor_commit",
+            ),
+            (
+                "decision_semantic_rebase_receipt_v0",
+                "loopx.capabilities.decision_context.assembler",
+            ),
+            (
+                "decision_context_pending_settlement_v0",
+                "loopx.capabilities.decision_context.private_state",
+            ),
+            (
+                "decision_review_settlement_v0",
+                "loopx.capabilities.decision_context.review_settlement",
+            ),
+        )
+    ],
+    "smokes": ["python3 examples/decision-context-contract-smoke.py"],
+    "docs": [
+        "docs/reference/protocols/decision-context-architecture-v0.md",
+        "docs/reference/protocols/decision-context-architecture-v0.zh-CN.md",
+    ],
+    "boundaries": [
+        "The capability is default-off and cannot create action authority or mutate Core state.",
+        "Private locators, cursors, raw content, provider payloads, tool output, and credentials stay outside public packets.",
+        "DecisionSourceProvider rebases current authority; ContextProvider supplies advisory recall only.",
+        "Prepare-evidence is read-only; prepare-review writes only private unapplied state when explicitly executed.",
+        "Cursor commit requires a canonical review receipt, exact gate or semantic no-change proof, lifecycle-event readback, private-state CAS, and atomic verified write; future outcome observation is separate.",
+    ],
+    "next_real_step": (
+        "Exercise one private source profile through approve, reject, defer, and "
+        "quiet no-change settlement, then observe later outcomes."
+    ),
+}

loopx/capabilities/decision_context/cli.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Callable, Collection
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .assembler import DecisionEvidenceRecords
+from .architecture import build_decision_context_architecture_packet
+from .profile import resolve_decision_context_activation
+from .private_state import (
+    load_private_pending_decision_settlement,
+    write_private_pending_decision_settlement,
+)
+from .review_settlement import settle_profile_decision_review
+from .runtime import (
+    assemble_profile_decision_evidence,
+    decision_evidence_records_from_mapping,
+)
+from .sources import build_decision_source_manifest
+
+PrintPayload = Callable[
+    [dict[str, object], str, Callable[[dict[str, object]], str]],
+    None,
+]
+FormatSelector = Callable[..., str]
+AddFormat = Callable[[argparse.ArgumentParser], None]
+
+
+def _load_json_mapping(path: str, *, label: str) -> dict[str, object]:
+    try:
+        payload = json.loads(Path(path).expanduser().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{label} is unavailable") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{label} must be an object")
+    return payload
+
+
+def _collection_size(value: object) -> int:
+    if isinstance(value, Collection) and not isinstance(value, (str, bytes)):
+        return len(value)
+    return 0
+
+
+def _render(payload: dict[str, object]) -> str:
+    capability = payload.get("capability")
+    capability_id = (
+        capability.get("capability_id")
+        if isinstance(capability, dict)
+        else "decision_context"
+    )
+    return "\n".join(
+        [
+            "# Decision Context",
+            "",
+            f"- status: `{payload.get('status')}`",
+            f"- capability_id: `{capability_id}`",
+            f"- packet_schemas: `{_collection_size(payload.get('packet_schemas'))}`",
+            f"- source_schemas: `{_collection_size(payload.get('source_schemas'))}`",
+            f"- source_count: `{payload.get('source_count', 0)}`",
+            "",
+        ]
+    )
+
+
+def register_decision_context_commands(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    add_subcommand_format: AddFormat,
+) -> None:
+    parser = subparsers.add_parser(
+        "decision-context",
+        help="Inspect the provider-neutral decision evidence and outcome contract.",
+    )
+    commands = parser.add_subparsers(dest="decision_context_command", required=True)
+    architecture = commands.add_parser(
+        "architecture",
+        help="Render the default-off Stage-0 Decision Context contract.",
+    )
+    add_subcommand_format(architecture)
+    status = commands.add_parser(
+        "inspect-profile",
+        help="Inspect a default-off goal profile without provider access.",
+    )
+    add_subcommand_format(status)
+    status.add_argument("--goal-id", required=True)
+    status.add_argument("--agent-id", required=True)
+    status.add_argument(
+        "--profile",
+        help="Private local profile. Omit it to prove the default-off route.",
+    )
+
+    manifest = commands.add_parser(
+        "source-manifest",
+        help="Project an enabled private source profile into a public-safe manifest.",
+    )
+    add_subcommand_format(manifest)
+    manifest.add_argument("--goal-id", required=True)
+    manifest.add_argument("--agent-id", required=True)
+    manifest.add_argument("--profile", required=True)
+    manifest.add_argument(
+        "--observed-at",
+        help="Optional timezone-aware ISO-8601 time for a reproducible manifest.",
+    )
+    prepare = commands.add_parser(
+        "prepare-evidence",
+        help=(
+            "Run bounded source scans and exact reads without applying private "
+            "cursor proposals."
+        ),
+    )
+    add_subcommand_format(prepare)
+    prepare.add_argument("--goal-id", required=True)
+    prepare.add_argument("--agent-id", required=True)
+    prepare.add_argument("--profile", required=True)
+    prepare.add_argument("--decision-id", required=True)
+    prepare.add_argument(
+        "--cursor-state",
+        help="Optional private JSON object mapping source ids to opaque cursors.",
+    )
+    prepare.add_argument(
+        "--source-id",
+        action="append",
+        help=(
+            "Explicit enabled source to scan. Repeat to include on-demand "
+            "sources; omit to scan automatic sources only."
+        ),
+    )
+    prepare.add_argument(
+        "--observed-at",
+        help="Optional timezone-aware ISO-8601 assembly time.",
+    )
+    prepare.add_argument(
+        "--before",
+        help="Optional timezone-aware upper bound for source changes.",
+    )
+    prepare.add_argument(
+        "--timeout-seconds",
+        type=float,
+        help="Optional bounded provider timeout override.",
+    )
+    prepare_review = commands.add_parser(
+        "prepare-review",
+        help=(
+            "Validate a domain semantic rebase and optionally persist one private "
+            "pending settlement without applying active cursors."
+        ),
+    )
+    add_subcommand_format(prepare_review)
+    prepare_review.add_argument("--goal-id", required=True)
+    prepare_review.add_argument("--agent-id", required=True)
+    prepare_review.add_argument("--profile", required=True)
+    prepare_review.add_argument("--decision-id", required=True)
+    prepare_review.add_argument("--rebase-json", required=True)
+    prepare_review.add_argument("--pending-settlement", required=True)
+    prepare_review.add_argument("--cursor-state")
+    prepare_review.add_argument("--source-id", action="append")
+    prepare_review.add_argument("--observed-at")
+    prepare_review.add_argument("--before")
+    prepare_review.add_argument("--timeout-seconds", type=float)
+    prepare_review.add_argument(
+        "--execute",
+        action="store_true",
+        help="Write the private pending settlement; active cursors stay unchanged.",
+    )
+
+    settle_review = commands.add_parser(
+        "settle-review",
+        help=(
+            "Exact-read a user-gate event or semantic no-change result, append "
+            "validated writeback, and CAS-commit private cursors."
+        ),
+    )
+    add_subcommand_format(settle_review)
+    settle_review.add_argument("--goal-id", required=True)
+    settle_review.add_argument("--agent-id", required=True)
+    settle_review.add_argument("--profile", required=True)
+    settle_review.add_argument("--cursor-state", required=True)
+    settle_review.add_argument("--pending-settlement", required=True)
+    settle_review.add_argument("--event-log", required=True)
+    settle_review.add_argument("--proposal-json")
+    settle_review.add_argument("--source-event-id")
+    settle_review.add_argument("--actor-ref", required=True)
+    settle_review.add_argument("--reason-code", required=True)
+    settle_review.add_argument("--summary", required=True)
+    settle_review.add_argument(
+        "--execute",
+        action="store_true",
+        help="Append settlement evidence and apply the private cursor CAS.",
+    )
+
+
+def handle_decision_context_command(
+    args: argparse.Namespace,
+    *,
+    output_format: FormatSelector,
+    print_payload: PrintPayload,
+) -> int | None:
+    if args.command != "decision-context":
+        return None
+    if args.decision_context_command == "architecture":
+        payload = build_decision_context_architecture_packet()
+    elif args.decision_context_command in {"prepare-evidence", "prepare-review"}:
+        now = datetime.now(timezone.utc).isoformat()
+        observed_at = str(getattr(args, "observed_at", None) or "").strip() or now
+        before = str(getattr(args, "before", None) or "").strip() or observed_at
+        prepare_review = args.decision_context_command == "prepare-review"
+        records = (
+            decision_evidence_records_from_mapping(
+                _load_json_mapping(args.rebase_json, label="rebase JSON")
+            )
+            if prepare_review
+            else DecisionEvidenceRecords()
+        )
+        activation, assembly = assemble_profile_decision_evidence(
+            goal_id=args.goal_id,
+            agent_id=args.agent_id,
+            profile_path=Path(args.profile),
+            decision_id=args.decision_id,
+            observed_at=observed_at,
+            before=before,
+            cursor_path=(
+                Path(args.cursor_state)
+                if str(getattr(args, "cursor_state", None) or "").strip()
+                else None
+            ),
+            source_ids=(
+                tuple(args.source_id)
+                if getattr(args, "source_id", None) is not None
+                else None
+            ),
+            rebase=lambda _collection: records,
+            timeout_seconds=getattr(args, "timeout_seconds", None),
+        )
+        settlement_required = bool(
+            assembly is not None and assembly.proposed_cursors
+        )
+        pending_written = False
+        if prepare_review and settlement_required and bool(args.execute):
+            write_private_pending_decision_settlement(
+                Path(args.pending_settlement),
+                assembly,
+            )
+            pending_written = True
+        payload = activation | {
+            "assembly": assembly.public_packet() if assembly is not None else None,
+            "semantic_rebase_performed": prepare_review,
+            "validated_writeback_required": (
+                settlement_required if prepare_review else assembly is not None
+            ),
+            "cursor_commit_allowed": False,
+            "cursor_state_mutated": False,
+            "pending_settlement_written": pending_written,
+        }
+    elif args.decision_context_command == "settle-review":
+        assembly = load_private_pending_decision_settlement(
+            Path(args.pending_settlement)
+        )
+        proposal = (
+            _load_json_mapping(args.proposal_json, label="proposal JSON")
+            if str(args.proposal_json or "").strip()
+            else None
+        )
+        payload = settle_profile_decision_review(
+            goal_id=args.goal_id,
+            agent_id=args.agent_id,
+            profile_path=Path(args.profile),
+            cursor_path=Path(args.cursor_state),
+            assembly=assembly,
+            lifecycle_event_log_path=Path(args.event_log),
+            actor_ref=args.actor_ref,
+            reason_code=args.reason_code,
+            summary=args.summary,
+            proposal=proposal,
+            source_event_id=(
+                str(args.source_event_id).strip()
+                if args.source_event_id is not None
+                else None
+            ),
+            execute=bool(args.execute),
+        )
+    elif args.decision_context_command in {"inspect-profile", "source-manifest"}:
+        profile_value = str(getattr(args, "profile", None) or "").strip()
+        status, profile = resolve_decision_context_activation(
+            goal_id=args.goal_id,
+            agent_id=args.agent_id,
+            profile_path=Path(profile_value) if profile_value else None,
+        )
+        if args.decision_context_command == "inspect-profile":
+            payload = status
+        else:
+            observed_at = str(getattr(args, "observed_at", None) or "").strip()
+            payload = status | {
+                "source_manifest": (
+                    build_decision_source_manifest(
+                        goal_id=args.goal_id,
+                        observed_at=(
+                            observed_at or datetime.now(timezone.utc).isoformat()
+                        ),
+                        sources=profile.sources,
+                    )
+                    if status["available"] and profile is not None
+                    else None
+                )
+            }
+    else:
+        raise ValueError("decision-context requires a supported subcommand")
+    print_payload(payload, output_format(args), _render)
+    return 0