@trac3r/oh-my-god 2.2.11

package/runtime/release_surface_registry.py

@@ -0,0 +1,283 @@
+"""Release surface registry contract for public-surface behavioral parity.
+
+Single source of truth for all PUBLIC behavioral surfaces in OMG — doc markers,
+launchers, check names, workflow entrypoints, and signed artifacts. Completely
+separate from the version-only runtime/release_surfaces.py.
+
+Consumers:
+    - runtime/contract_compiler.py  (drift gate, compile checks)
+    - tests/scripts/test_release_surface_registry.py (parity assertions)
+"""
+from typing import Any
+
+PublicSurface = dict[str, Any]
+
+
+GENERATED_SECTION_MARKERS: dict[str, str] = {
+    "install_fast_path": "<!-- OMG:GENERATED:install-fast-path -->",
+    "changelog_current": "<!-- OMG:GENERATED:changelog-v2.2.10 -->",
+    "command_surface_doc": "<!-- OMG:GENERATED:command-surface -->",
+    "install_intro": "<!-- OMG:GENERATED:install-intro -->",
+    "why_omg": "<!-- OMG:GENERATED:why-omg -->",
+    "proof_quickstart": "<!-- OMG:GENERATED:proof-quickstart -->",
+    "quick_reference_hosts": "<!-- OMG:GENERATED:quick-reference-hosts -->",
+    "verification_index_targets": "<!-- OMG:GENERATED:verification-index-targets -->",
+}
+
+_INSTALL_GUIDES: list[tuple[str, str]] = [
+    ("install_claude_code", "docs/install/claude-code.md"),
+    ("install_codex", "docs/install/codex.md"),
+    ("install_gemini", "docs/install/gemini.md"),
+    ("install_kimi", "docs/install/kimi.md"),
+    ("install_opencode", "docs/install/opencode.md"),
+    ("install_github_app", "docs/install/github-app.md"),
+]
+
+PUBLIC_SURFACES: list[PublicSurface] = [
+    {
+        "id": "release_notes_artifact",
+        "category": "docs",
+        "path": "artifacts/release/release-notes-v2.2.10.md",
+        "description": "release notes artifact for v2.2.10",
+    },
+    {
+        "id": "changelog_current_block",
+        "category": "docs",
+        "path": "CHANGELOG.md",
+        "marker": "<!-- OMG:GENERATED:changelog-v2.2.10 -->",
+        "description": "current release block in changelog",
+    },
+    *[
+        {
+            "id": guide_id,
+            "category": "docs",
+            "path": guide_path,
+            "marker": "<!-- OMG:GENERATED:install-fast-path -->",
+            "description": f"install fast-path section in {guide_path}",
+        }
+        for guide_id, guide_path in _INSTALL_GUIDES
+    ],
+    {
+        "id": "command_surface_doc",
+        "category": "docs",
+        "path": "docs/command-surface.md",
+        "marker": "<!-- OMG:GENERATED:command-surface -->",
+        "description": "command surface reference doc",
+    },
+    {
+        "id": "github_release_body_artifact",
+        "category": "release_body",
+        "path": "artifacts/release/github-release-body.md",
+        "description": "GitHub release body text for tag publish",
+    },
+    {
+        "id": "tag_body_artifact",
+        "category": "release_body",
+        "path": "artifacts/release/tag-body.md",
+        "description": "annotated tag body text for release",
+    },
+    {
+        "id": "install_intro",
+        "category": "docs",
+        "path": "README.md",
+        "marker": "<!-- OMG:GENERATED:install-intro -->",
+        "description": "authoritative install intro section in README",
+    },
+    {
+        "id": "why_omg",
+        "category": "docs",
+        "path": "README.md",
+        "marker": "<!-- OMG:GENERATED:why-omg -->",
+        "description": "authoritative why-omg section in README",
+    },
+    {
+        "id": "proof_quickstart",
+        "category": "docs",
+        "path": "docs/proof.md",
+        "marker": "<!-- OMG:GENERATED:proof-quickstart -->",
+        "description": "proof quickstart section in proof docs",
+    },
+    {
+        "id": "quick_reference_hosts",
+        "category": "docs",
+        "path": "QUICK-REFERENCE.md",
+        "marker": "<!-- OMG:GENERATED:quick-reference-hosts -->",
+        "description": "host table in quick reference",
+    },
+    {
+        "id": "verification_index_targets",
+        "category": "docs",
+        "path": "INSTALL-VERIFICATION-INDEX.md",
+        "marker": "<!-- OMG:GENERATED:verification-index-targets -->",
+        "description": "installation targets in verification index",
+    },
+    {
+        "id": "launcher_python",
+        "category": "launcher",
+        "launcher_name": "python3 scripts/omg.py",
+        "scope": "internal",
+        "description": "Python launcher",
+    },
+    {
+        "id": "launcher_shell",
+        "category": "launcher",
+        "launcher_name": "./OMG-setup.sh",
+        "scope": "internal",
+        "description": "Shell setup launcher",
+    },
+    {
+        "id": "launcher_npm_bin",
+        "category": "launcher",
+        "launcher_name": "omg",
+        "scope": "public",
+        "description": "npm bin launcher",
+    },
+    {
+        "id": "npm_bin_key",
+        "category": "npm",
+        "bin_key": "omg",
+        "description": "npm package.json bin key",
+    },
+    {
+        "id": "github_check_run_name",
+        "category": "check_name",
+        "check_name": "OMG PR Reviewer",
+        "description": "immutable GitHub check-run name",
+    },
+    {
+        "id": "workflow_release",
+        "category": "workflow",
+        "path": ".github/workflows/release.yml",
+        "description": "release workflow entrypoint",
+    },
+    {
+        "id": "workflow_evidence_gate",
+        "category": "workflow",
+        "path": ".github/workflows/evidence-gate.yml",
+        "description": "evidence gate workflow",
+    },
+    {
+        "id": "workflow_compat_gate",
+        "category": "workflow",
+        "path": ".github/workflows/omg-compat-gate.yml",
+        "description": "compat gate workflow",
+    },
+    {
+        "id": "action_yaml",
+        "category": "action",
+        "path": "action.yml",
+        "description": "GitHub Action entrypoint",
+    },
+    {
+        "id": "sign_locked_prod",
+        "category": "sign_artifact",
+        "path": "registry/policy-packs/locked-prod.signature.json",
+        "description": "locked-prod policy pack signature",
+    },
+    {
+        "id": "sign_fintech",
+        "category": "sign_artifact",
+        "path": "registry/policy-packs/fintech.signature.json",
+        "description": "fintech policy pack signature",
+    },
+    {
+        "id": "sign_airgapped",
+        "category": "sign_artifact",
+        "path": "registry/policy-packs/airgapped.signature.json",
+        "description": "airgapped policy pack signature",
+    },
+]
+
+_REQUIRED_IDS: frozenset[str] = frozenset({
+    "release_notes_artifact",
+    "changelog_current_block",
+    "install_claude_code",
+    "install_codex",
+    "install_gemini",
+    "install_kimi",
+    "install_opencode",
+    "install_github_app",
+    "command_surface_doc",
+    "github_release_body_artifact",
+    "tag_body_artifact",
+    "launcher_python",
+    "launcher_shell",
+    "launcher_npm_bin",
+    "npm_bin_key",
+    "github_check_run_name",
+    "workflow_release",
+    "workflow_evidence_gate",
+    "workflow_compat_gate",
+    "action_yaml",
+    "sign_locked_prod",
+    "sign_fintech",
+    "sign_airgapped",
+    "install_intro",
+    "why_omg",
+    "proof_quickstart",
+    "quick_reference_hosts",
+    "verification_index_targets",
+})
+
+_REQUIRED_CATEGORIES: frozenset[str] = frozenset({
+    "docs",
+    "launcher",
+    "check_name",
+    "workflow",
+    "sign_artifact",
+    "npm",
+    "action",
+    "release_body",
+})
+
+PROMOTED_PUBLIC_COMMANDS: list[str] = [
+    "omg ship",
+    "omg proof",
+    "omg blocked --last",
+    "omg explain run --run-id <id>",
+    "omg budget simulate --enforce",
+    "omg install --plan",
+    "omg install --apply",
+    "omg doctor",
+    "omg env doctor",
+]
+
+
+def get_public_surfaces() -> list[PublicSurface]:
+    return list(PUBLIC_SURFACES)
+
+
+def get_generated_section_markers() -> dict[str, str]:
+    return dict(GENERATED_SECTION_MARKERS)
+
+
+def get_promoted_public_commands() -> list[str]:
+    return list(PROMOTED_PUBLIC_COMMANDS)
+
+
+def validate_registry() -> list[str]:
+    blockers: list[str] = []
+
+    found_ids = {s["id"] for s in PUBLIC_SURFACES}
+    missing_ids = _REQUIRED_IDS - found_ids
+    if missing_ids:
+        blockers.append(f"missing required surface ids: {sorted(missing_ids)}")
+
+    found_categories = {s["category"] for s in PUBLIC_SURFACES}
+    missing_cats = _REQUIRED_CATEGORIES - found_categories
+    if missing_cats:
+        blockers.append(f"missing required categories: {sorted(missing_cats)}")
+
+    ids_list = [s["id"] for s in PUBLIC_SURFACES]
+    dupes = {sid for sid in ids_list if ids_list.count(sid) > 1}
+    if dupes:
+        blockers.append(f"duplicate surface ids: {sorted(dupes)}")
+
+    crazy_commands = [c for c in PROMOTED_PUBLIC_COMMANDS if "crazy" in c.lower()]
+    if crazy_commands:
+        blockers.append(
+            f"/OMG:crazy is compatibility-only and must not appear in "
+            f"PROMOTED_PUBLIC_COMMANDS: {crazy_commands}"
+        )
+
+    return blockers

package/runtime/release_surfaces.py

@@ -0,0 +1,320 @@
+"""Shared release surface inventory.
+
+Single audited source of truth for all version surfaces in the OMG project.
+This module describes WHERE version strings appear and HOW to find/update them.
+
+It does NOT import runtime.adoption or encode the canonical version value.
+The canonical version lives solely in runtime/adoption.py:CANONICAL_VERSION.
+
+Consumers:
+    - scripts/sync-release-identity.py  (sync/check flow)
+    - runtime/contract_compiler.py      (drift gate)
+    - tests/test_trust_release_identity.py (parity assertions)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Union
+
+# ── Valid surface type identifiers ──────────────────────────────────────────
+
+SURFACE_TYPES = frozenset({
+    "json_key_path",
+    "regex_line",
+    "yaml_line",
+    "frontmatter_field",
+    "changelog_header",
+    "shell_literal",
+    "js_literal",
+    "banner_literal",
+})
+
+
+@dataclass(frozen=True)
+class AuthoredSurface:
+    """A version surface in an authored source file.
+
+    Attributes:
+        file_path: Relative path from repo root.
+        surface_type: One of SURFACE_TYPES.
+        field: For json_key_path — list of str/int keys to navigate.
+               For regex_line/shell_literal/js_literal/banner_literal — regex pattern.
+               For yaml_line/frontmatter_field — the YAML field name.
+               For changelog_header — regex pattern matching the header.
+        description: Human-readable description of this surface.
+    """
+
+    file_path: str
+    surface_type: str
+    field: Union[list[Union[str, int]], str]
+    description: str = ""
+    source_only: bool = False
+
+
+# ── Explicit YAML bundle names (25 files) ──────────────────────────────────
+
+_BUNDLE_NAMES: tuple[str, ...] = (
+    "algorithms",
+    "api-twin",
+    "ast-pack",
+    "claim-judge",
+    "control-plane",
+    "data-lineage",
+    "delta-classifier",
+    "eval-gate",
+    "hash-edit",
+    "health",
+    "hook-governor",
+    "incident-replay",
+    "lsp-pack",
+    "mcp-fabric",
+    "plan-council",
+    "preflight",
+    "proof-gate",
+    "remote-supervisor",
+    "robotics",
+    "secure-worktree-pipeline",
+    "security-check",
+    "terminal-lane",
+    "test-intent-lock",
+    "tracebank",
+    "vision",
+)
+
+
+REQUIRED_PACKAGE_PARITY_SURFACES: tuple[str, ...] = (
+    "hash-edit",
+    "ast-pack",
+    "terminal-lane",
+)
+
+
+# ── Authored surfaces: explicit, no dynamic discovery ──────────────────────
+
+AUTHORED_SURFACES: list[AuthoredSurface] = [
+    # ── JSON key paths (10 fields across 7 files) ──
+    AuthoredSurface(
+        "package.json", "json_key_path", ["version"],
+        "npm package version",
+    ),
+    AuthoredSurface(
+        "settings.json", "json_key_path", ["_omg", "_version"],
+        "OMG settings version",
+    ),
+    AuthoredSurface(
+        "settings.json", "json_key_path", ["_omg", "generated", "contract_version"],
+        "OMG generated contract version",
+    ),
+    AuthoredSurface(
+        ".gemini/settings.json", "json_key_path", ["_omg", "_version"],
+        "Gemini settings OMG version",
+        source_only=False,
+    ),
+    AuthoredSurface(
+        ".gemini/settings.json", "json_key_path", ["_omg", "generated", "contract_version"],
+        "Gemini settings contract version",
+        source_only=False,
+    ),
+    AuthoredSurface(
+        ".kimi/mcp.json", "json_key_path", ["_omg", "_version"],
+        "Kimi MCP OMG version",
+        source_only=False,
+    ),
+    AuthoredSurface(
+        ".kimi/mcp.json", "json_key_path", ["_omg", "generated", "contract_version"],
+        "Kimi MCP contract version",
+        source_only=False,
+    ),
+    AuthoredSurface(
+        ".claude-plugin/plugin.json", "json_key_path", ["version"],
+        "Claude plugin version",
+    ),
+    AuthoredSurface(
+        ".claude-plugin/marketplace.json", "json_key_path", ["version"],
+        "marketplace top-level version",
+    ),
+    AuthoredSurface(
+        ".claude-plugin/marketplace.json", "json_key_path", ["metadata", "version"],
+        "marketplace metadata version",
+    ),
+    AuthoredSurface(
+        ".claude-plugin/marketplace.json", "json_key_path", ["plugins", 0, "version"],
+        "marketplace plugins[0] version",
+    ),
+    AuthoredSurface(
+        "plugins/core/plugin.json", "json_key_path", ["version"],
+        "core plugin version",
+    ),
+    AuthoredSurface(
+        "plugins/advanced/plugin.json", "json_key_path", ["version"],
+        "advanced plugin version",
+    ),
+    AuthoredSurface(
+        "registry/omg-capability.schema.json", "json_key_path", ["version"],
+        "capability schema version",
+    ),
+
+    # ── Regex line (pyproject.toml) ──
+    AuthoredSurface(
+        "pyproject.toml", "regex_line", r'^version = "(.+?)"',
+        "Python package version",
+    ),
+
+    # ── YAML bundles (25 files) ──
+    *[
+        AuthoredSurface(
+            f"registry/bundles/{name}.yaml", "yaml_line", "version",
+            f"{name} bundle version",
+        )
+        for name in _BUNDLE_NAMES
+    ],
+
+    # ── Changelog ──
+    AuthoredSurface(
+        "CHANGELOG.md", "changelog_header", r'^## \[?(\d+\.\d+\.\d+)\]?',
+        "latest release header",
+    ),
+
+    # ── 6 previously missing authored surfaces ──
+
+    # 1. OMG_COMPAT_CONTRACT.md — frontmatter version: field (line 3)
+    AuthoredSurface(
+        "OMG_COMPAT_CONTRACT.md", "frontmatter_field", "version",
+        "compat contract frontmatter version",
+    ),
+
+    # 2. CLI-ADAPTER-MAP.md — 3 docs example version markers
+    AuthoredSurface(
+        "CLI-ADAPTER-MAP.md", "regex_line",
+        r'^- \*\*Version:\*\* `(\d+\.\d+\.\d+)`',
+        "docs example: version badge (line 165)",
+    ),
+    AuthoredSurface(
+        "CLI-ADAPTER-MAP.md", "regex_line",
+        r'^\s*"version":\s*"(\d+\.\d+\.\d+)"',
+        "docs example: JSON version literal (line 209)",
+    ),
+    AuthoredSurface(
+        "CLI-ADAPTER-MAP.md", "regex_line",
+        r'^CANONICAL_VERSION\s*=\s*"(\d+\.\d+\.\d+)"',
+        "docs example: Python constant (line 241)",
+    ),
+
+    # 3. OMG-setup.sh — VERSION="..." shell literal (line 8)
+    AuthoredSurface(
+        "OMG-setup.sh", "shell_literal", r'^VERSION="(.+?)"',
+        "setup script version variable",
+    ),
+
+    # 4. hud/omg-hud.mjs — JS fallback literal (line 90)
+    AuthoredSurface(
+        "hud/omg-hud.mjs", "js_literal", r'return "(\d+\.\d+\.\d+)"',
+        "HUD fallback version literal",
+    ),
+
+    # 5. .claude-plugin/scripts/install.sh — installer banner literal (line 22)
+    AuthoredSurface(
+        ".claude-plugin/scripts/install.sh", "banner_literal",
+        r'v(\d+\.\d+\.\d+)',
+        "installer banner version",
+        source_only=True,
+    ),
+
+    # 6. runtime/omg_compat_contract_snapshot.json — contract_version field
+    AuthoredSurface(
+        "runtime/omg_compat_contract_snapshot.json", "json_key_path",
+        ["contract_version"],
+        "compat contract snapshot version",
+    ),
+
+    # 7. commands/OMG:validate.md — JSON example version field (line 39)
+    AuthoredSurface(
+        "commands/OMG:validate.md", "regex_line", r'^\s*"version":\s*"(\d+\.\d+\.\d+)"',
+        "validate command JSON example version",
+    ),
+
+    # 8. settings.json — banner comment literal (line 3)
+    AuthoredSurface(
+        "settings.json", "banner_literal", r'OMG (\d+\.\d+\.\d+)',
+        "settings banner comment version",
+    ),
+
+    # 9. INSTALL-VERIFICATION-INDEX.md — version string (line 6)
+    AuthoredSurface(
+        "INSTALL-VERIFICATION-INDEX.md", "regex_line",
+        r'\*\*Version:\*\* OMG (\d+\.\d+\.\d+)',
+        "install verification index version string",
+    ),
+]
+
+
+# ── Derived (generated) surface directories ────────────────────────────────
+# These are validation-only targets — not authored, but must be checked for
+# stale version residue after a bump.
+
+DERIVED_SURFACE_DIRS: list[str] = [
+    "dist/",
+    "artifacts/release/",
+    "build/lib/",
+]
+
+
+# ── Scoped residue targets ─────────────────────────────────────────────────
+# Specific files/dirs inside generated trees where stale version residue
+# must be rejected after a version bump.
+
+SCOPED_RESIDUE_TARGETS: list[str] = [
+    "dist/public/manifest.json",
+    "dist/enterprise/manifest.json",
+    "dist/public/bundle/",
+    "dist/enterprise/bundle/",
+    # Explicitly include accidental double-nesting outputs to prevent silent
+    # stale-version residue from surviving a misconfigured compile run.
+    "dist/dist/",
+    "artifacts/release/",
+    "build/lib/",
+]
+
+
+RUNTIME_BEHAVIOR_SURFACES: tuple[str, ...] = (
+    "execution_primitives",
+    "provider_host_parity",
+    "host_semantic_parity",
+)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+def get_authored_paths() -> list[str]:
+    """Return deduplicated list of file paths from AUTHORED_SURFACES.
+
+    Preserves insertion order; useful for disk-existence checks.
+    """
+    seen: set[str] = set()
+    paths: list[str] = []
+    for surface in AUTHORED_SURFACES:
+        if surface.file_path not in seen:
+            seen.add(surface.file_path)
+            paths.append(surface.file_path)
+    return paths
+
+
+def get_derived_dirs() -> list[str]:
+    """Return all generated directory paths."""
+    return list(DERIVED_SURFACE_DIRS)
+
+
+def get_runtime_behavior_surfaces() -> list[str]:
+    return list(RUNTIME_BEHAVIOR_SURFACES)
+
+
+def get_package_parity_surfaces() -> list[str]:
+    return list(REQUIRED_PACKAGE_PARITY_SURFACES)
+
+
+def surface_applies_to_root(surface: AuthoredSurface, root_dir: Path) -> bool:
+    """Return whether a surface should be enforced for the given root layout."""
+    if not surface.source_only:
+        return True
+    return (root_dir / ".git").exists()

package/runtime/remote_supervisor.py

@@ -0,0 +1,79 @@
+"""Local-only authenticated supervisor sessions."""
+from __future__ import annotations
+
+import base64
+from datetime import datetime, timezone
+import hashlib
+import hmac
+import json
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from runtime.exec_kernel import get_exec_kernel
+from runtime.release_run_coordinator import resolve_current_run_id
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def issue_local_supervisor_session(
+    project_dir: str,
+    *,
+    worker_id: str,
+    shared_secret: str,
+    run_id: str | None = None,
+) -> dict[str, Any]:
+    resolved_run_id = run_id or resolve_current_run_id(project_dir)
+    session_id = f"session-{uuid4().hex}"
+    issued_at = _now()
+    token_payload = {
+        "session_id": session_id,
+        "worker_id": worker_id,
+        "issued_at": issued_at,
+        "run_id": resolved_run_id,
+    }
+    payload_json = json.dumps(token_payload, sort_keys=True, separators=(",", ":"))
+    signature = hmac.new(shared_secret.encode("utf-8"), payload_json.encode("utf-8"), hashlib.sha256).hexdigest()
+    token = base64.urlsafe_b64encode(
+        json.dumps({"payload": token_payload, "signature": signature}, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).decode("ascii")
+
+    result = {
+        "schema": "RemoteSupervisorSession",
+        "status": "ok",
+        "session_id": session_id,
+        "worker_id": worker_id,
+        "issued_at": issued_at,
+        "run_id": resolved_run_id,
+        "local_only": True,
+        "token": token,
+    }
+
+    rel_path = Path(".omg") / "supervisor" / "sessions" / f"{session_id}.json"
+    path = Path(project_dir) / rel_path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({k: v for k, v in result.items() if k != "token"}, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    result["path"] = rel_path.as_posix()
+    if resolved_run_id:
+        get_exec_kernel(project_dir).record_supervisor_session(resolved_run_id, result)
+    return result
+
+
+def verify_local_supervisor_token(token: str, *, shared_secret: str) -> dict[str, Any]:
+    decoded = json.loads(base64.urlsafe_b64decode(token.encode("ascii")).decode("utf-8"))
+    payload = decoded["payload"]
+    payload_json = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    signature = str(decoded["signature"])
+    expected = hmac.new(shared_secret.encode("utf-8"), payload_json.encode("utf-8"), hashlib.sha256).hexdigest()
+    status = "ok" if hmac.compare_digest(signature, expected) else "error"
+    return {
+        "schema": "RemoteSupervisorTokenVerification",
+        "status": status,
+        "session_id": str(payload["session_id"]),
+        "worker_id": str(payload["worker_id"]),
+        "issued_at": str(payload["issued_at"]),
+        "run_id": str(payload.get("run_id") or ""),
+        "local_only": True,
+    }