# Blueprint AI Runtime `ai/runtime/` is the TypeScript foundation for Blueprint's deterministic AI engineering runtime. The target architecture is: ```text AI reasoning -> deterministic TypeScript runtime -> validators -> daemon/dispatcher execution -> canonical registries/schemas/state ``` This first slice is intentionally read-only. It establishes typed registry loading, shared runtime types, pure classifiers, rendering-preparation helpers, and a CLI that can inspect canonical policy without mutating runtime state. Chunk 000102 adds a local-only Runtime API daemon. The daemon exposes structured JSON-line requests over a Unix socket. It is intended for repeated, safe runtime inspection by Codex, operators, and shell wrappers without turning the runtime into a public service or arbitrary shell execution API. ## Commands ```sh ai/runtime/start-daemon.sh node ai/runtime/dist/cli.js request --method runtime.health node ai/runtime/dist/cli.js request --method registries.validate node ai/runtime/dist/cli.js batch --requests '[{"method":"runtime.health"},{"method":"operatorQuestions.summary"}]' node ai/runtime/dist/cli.js snapshot --tier fast node ai/runtime/dist/cli.js runtime snapshot --json node ai/runtime/dist/cli.js runtime snapshot-cached --json node ai/runtime/dist/cli.js runtime concurrency --json node ai/runtime/dist/cli.js runtime can-run --path validate --profile runtime-intrinsic --json node ai/runtime/dist/cli.js runtime execution-plan --path close_commit --chunk 000130 --fingerprint current --json node ai/runtime/dist/cli.js runtime lock-graph --json node ai/runtime/dist/cli.js runtime wait-graph --json node ai/runtime/dist/cli.js runtime scheduler-snapshot --json node ai/runtime/dist/cli.js runtime defaults --json node ai/runtime/dist/cli.js runtime execution-policy --json node ai/runtime/dist/cli.js runtime cache-stats --json node ai/runtime/dist/cli.js runtime build-info --json node ai/runtime/dist/cli.js runtime build-state --json node ai/runtime/dist/cli.js runtime atomic-build-status --json node ai/runtime/dist/cli.js runtime generations --json node ai/runtime/dist/cli.js runtime active-generation --json node ai/runtime/dist/cli.js runtime generation-status --json node ai/runtime/dist/cli.js runtime generation-graph --json node ai/runtime/dist/cli.js runtime atomic-activation-status --json node ai/runtime/dist/cli.js runtime daemon-freshness --json node ai/runtime/dist/cli.js runtime daemon-generation --json node ai/runtime/dist/cli.js validation graph --json node ai/runtime/dist/cli.js validation defaults --json node ai/runtime/dist/cli.js validation default-profile --json node ai/runtime/dist/cli.js validation default-tier --json node ai/runtime/dist/cli.js validation profile-defaults --json node ai/runtime/dist/cli.js validation auto-profile --json node ai/runtime/dist/cli.js validation execution-plan --profile runtime-intrinsic --tier chunk --changed-only --json node ai/runtime/dist/cli.js validation profiles --json node ai/runtime/dist/cli.js validation profile --profile runtime-intrinsic --json node ai/runtime/dist/cli.js validation run --profile runtime-intrinsic --tier chunk --changed-only --json node ai/runtime/dist/cli.js validation plan --changed-only --json node ai/runtime/dist/cli.js validation run --changed-only --json node ai/runtime/dist/cli.js validation explain --json node ai/runtime/dist/cli.js validation cache-verify --json node ai/runtime/dist/cli.js validation cache-invalidate --changed ai/runtime/src/api/runtime.ts --json node ai/runtime/dist/cli.js validation profile --tier full --json node ai/runtime/dist/cli.js validate --tier fast node ai/runtime/dist/cli.js validate --tier chunk --chunk 000122 node ai/runtime/dist/cli.js validate --tier full node ai/runtime/dist/cli.js validate --tier smoke node ai/runtime/dist/cli.js doctor --json node ai/runtime/dist/cli.js scorecard --json node ai/runtime/dist/cli.js audit snapshot --json node ai/runtime/dist/cli.js audit snapshot --historical --limit 250 --json node ai/runtime/dist/cli.js audit archive-plan --json node ai/runtime/dist/cli.js audit archive-execute --dry-run --json node ai/runtime/dist/cli.js audit current-index --json node ai/runtime/dist/cli.js audit historical-lookup --source operator_daemon_requests --limit 20 --json node ai/runtime/dist/cli.js timeline archive-plan --json node ai/runtime/dist/cli.js timeline archive-execute --dry-run --json node ai/runtime/dist/cli.js timeline current-index --json node ai/runtime/dist/cli.js timeline snapshot --json node ai/runtime/dist/cli.js timeline replay --limit 20 --json node ai/runtime/dist/cli.js timeline validate-bounded --json node ai/runtime/dist/cli.js summary schema --json node ai/runtime/dist/cli.js summary schema-default --json node ai/runtime/dist/cli.js summary validate --chunk 000122 --json node ai/runtime/dist/cli.js summary render --chunk 000122 --json node ai/runtime/dist/cli.js testing defaults --json node ai/runtime/dist/cli.js testing default-profile --json node ai/runtime/dist/cli.js orchestration defaults --json node ai/runtime/dist/cli.js orchestration default-close-gate --json node ai/runtime/dist/cli.js telegram status --json node ai/runtime/dist/cli.js telegram operator-surface --json node ai/runtime/dist/cli.js telegram details --json node ai/runtime/dist/cli.js governance validate --json node ai/runtime/dist/cli.js validation-matrix --dry-run --json node ai/runtime/dist/cli.js shell-entrypoints ai/runtime/stop-daemon.sh node ai/runtime/dist/cli.js health --json node ai/runtime/dist/cli.js validate-registries --json node ai/runtime/dist/cli.js carry-forward --json node ai/runtime/dist/cli.js permission --name runtime_api_requests --json node ai/runtime/dist/cli.js trusted-runtime --json node ai/runtime/dist/cli.js render-event --class runtime_note --title "Runtime note" --message "Bridge is healthy." ai/commands/service-readiness-check.sh --json ai/commands/service-readiness-check.sh --recover-runtime --json ``` `ai/runtime/request.sh` remains as a compatibility wrapper for older scripts. Codex and new automation should use the direct Node Runtime API CLI `request`/`batch` commands so multiple runtime facts can be fetched through one Unix socket client process. Canonical Codex query examples: ```sh node ai/runtime/dist/cli.js snapshot --tier fast node ai/runtime/dist/cli.js runtime snapshot-cached --json node ai/runtime/dist/cli.js validation profile --tier chunk --chunk 000125 --json node ai/runtime/dist/cli.js validate --tier chunk --chunk 000122 node ai/runtime/dist/cli.js batch --requests '[{"id":"health","method":"runtime.health"},{"id":"scorecard","method":"scorecard.summary"},{"id":"approvals","method":"approvals.fastSummary"},{"id":"audit","method":"audit.snapshot"}]' ``` Runtime concurrency, singleton, lease, replay, lock, and wait-graph semantics are Runtime-owned policy loaded from `ai/governance/registries/runtime-concurrency.yaml`. Shell scripts must not decide lease ownership, lock conflicts, singleton behavior, validation scheduling, approval consumption, lifecycle advancement, notification ordering, or runtime build coordination independently. Guarded mutation owners must acquire a Runtime lease before executing. The canonical lease surface is: ```sh node ai/runtime/dist/cli.js runtime lease-acquire --path close_commit --chunk --fingerprint --run-id --owner approved_action_dispatcher --json node ai/runtime/dist/cli.js runtime lease-release --operation-id --status succeeded --json node ai/runtime/dist/cli.js runtime lease-abort --operation-id --status failed --reason --json node ai/runtime/dist/cli.js runtime lease-conflicts --path close_commit --chunk --fingerprint --json node ai/runtime/dist/cli.js runtime leases --json ``` Integrated guarded owners include Runtime Executor lifecycle transitions, summary reconciliation, approval/question creation, dispatcher `close_commit`, timeline archive execution, and audit archive execution. Remaining process owners must either acquire Runtime leases or stay classified as pending deeper integration. Runtime throughput uses an incremental validation graph plus bounded in-daemon cache. Validators declare dependency, invalidation, fingerprint, snapshot, and cacheability metadata through: ```sh node ai/runtime/dist/cli.js validation graph --json node ai/runtime/dist/cli.js validation profiles --json node ai/runtime/dist/cli.js validation profile --profile runtime-intrinsic --json node ai/runtime/dist/cli.js validation run --profile runtime-intrinsic --tier chunk --changed-only --json node ai/runtime/dist/cli.js validation profile --tier fast --json node ai/runtime/dist/cli.js validation profile --tier chunk --chunk --json node ai/runtime/dist/cli.js validation profile --tier full --json node ai/runtime/dist/cli.js validation plan --changed-only --json node ai/runtime/dist/cli.js validation run --changed-only --json node ai/runtime/dist/cli.js validation cache-verify --json node ai/runtime/dist/cli.js runtime daemon-freshness --json node ai/runtime/dist/cli.js runtime cache-stats --json node ai/runtime/dist/cli.js validation invalidate --reason manual --json ``` The cache is bounded by `AI_RUNTIME_CACHE_MAX_ENTRIES`, default `64`, and expires entries using `AI_RUNTIME_CACHE_TTL_MS`, default `60000`. Cache fingerprints are derived from canonical registry, chunk, approval, dispatcher, timeline, and audit-index state. Runtime methods must not use hidden shell wrappers to populate the cache. Changed-only validation uses the same graph metadata. If `--changed` or `--changed-files` is supplied, that explicit list is authoritative. Otherwise the Runtime CLI computes the current git working-tree change set. Impacted validators run and unrelated validators are reported as `skip` with a deterministic reason. Canonical validation, doctor, scorecard, batch, and cached runtime queries perform a daemon freshness handshake before using the Runtime API daemon. The daemon records a generation id, source hash, and build hash at startup. If Runtime source or built `dist` content changes after daemon startup, canonical CLI calls fail closed with `restart_required` instead of silently trusting stale daemon code. For local/dev work, use the command-bound readiness helper after disruptive operations: ```sh ai/commands/service-readiness-check.sh --json ai/commands/service-readiness-check.sh --recover-runtime --json ``` The helper checks Runtime daemon process status, Runtime generation freshness, Runtime services, managed backend/frontend reachability, and Socket.IO Runtime Health namespace reachability without adding a background polling loop. `--recover-runtime` restarts only the Runtime API daemon when the Runtime generation is stale or freshness cannot be trusted; other services remain under their canonical managed helper or trusted daemon ownership. Runtime builds use immutable generations. For AI/automation work, use the registered supervisor action `runtime_api_build_reload` after Runtime source changes so build/reload state, service-status evidence, journal events, and frontend invalidation remain canonical: ```sh node ai/runtime/dist/cli.js supervisor request --action runtime_api_build_reload --json node ai/runtime/dist/cli.js supervisor wait --request-id --json ``` Direct `yarn --cwd ai/runtime build` compiles into a staging generation, writes a manifest, moves the completed generation under `ai/runtime/.runtime-generations//`, and atomically points `ai/runtime/dist` at that immutable generation. It is last-resort human/emergency compatibility only when the Runtime/supervisor path is unavailable or is itself the failed component; record that exception in chunk evidence. The build state file under `.tmp/runtime-api/build-state.json` is set to `building` while compilation or activation is in progress, so canonical CLI/API freshness checks reject daemon responses during active build mutation. Runtime daemons pin their startup generation to the current source hash, build hash, build manifest generation, and immutable generation directory. Freshness-gated Runtime tests must use the Runtime testing wrappers. The canonical test entrypoints are: ```sh yarn --cwd ai/runtime test yarn --cwd ai/runtime test:daemon node ai/runtime/dist/cli.js testing runtime-broad-tests --json node ai/runtime/dist/cli.js testing runtime-daemon-tests --json node ai/runtime/dist/cli.js testing runtime-freshness-preflight-smoke --json ``` Those wrappers check daemon freshness before child test execution. If Runtime source, build output, or the active immutable generation changed after daemon startup, the wrapper runs the typed supervisor `runtime_api_build_reload` when safe, verifies `runtime daemon-freshness`, and only then starts the freshness-gated test. Direct raw `node ai/runtime/test/*.mjs` execution is a low-level development/debug path and is not the canonical stale-daemon-safe test entrypoint. Use these commands to inspect build/runtime coordination: ```sh node ai/runtime/dist/cli.js runtime build-info --json node ai/runtime/dist/cli.js runtime build-state --json node ai/runtime/dist/cli.js runtime atomic-build-status --json node ai/runtime/dist/cli.js runtime generations --json node ai/runtime/dist/cli.js runtime active-generation --json node ai/runtime/dist/cli.js runtime generation-status --json node ai/runtime/dist/cli.js runtime generation-graph --json node ai/runtime/dist/cli.js runtime atomic-activation-status --json node ai/runtime/dist/cli.js runtime daemon-generation --json node ai/runtime/dist/cli.js runtime daemon-freshness --json ``` Validation profiles are the canonical way to select validation for a work type. Prompts should name a profile instead of listing shell validator chains: ```sh node ai/runtime/dist/cli.js validation profiles --json node ai/runtime/dist/cli.js validation profile-defaults --json node ai/runtime/dist/cli.js validation auto-profile --changed ai/runtime/src/api/runtime.ts --json node ai/runtime/dist/cli.js validation profile --profile runtime-intrinsic --json node ai/runtime/dist/cli.js validation execution-plan --profile runtime-intrinsic --tier chunk --changed-only --json node ai/runtime/dist/cli.js validation run --profile runtime-intrinsic --tier chunk --changed-only --json node ai/runtime/dist/cli.js validate --tier full --json ``` The close/commit gate remains full validation. Compatibility shell wrappers may exist for humans, bootstrap, recovery, or smoke tests, but they are not canonical Runtime validation surfaces. Validator tiers: - `fast` target `<5s`: changed-file routing, registry/schema shape, current chunk status, fast question/approval counts, scheduler health, and bounded audit guard. It excludes historical audit scans, live Telegram probes, doctor/scorecard deep aggregation, and process/tmux probes. - `chunk` target `<15s`: fast checks plus current chunk evidence, Runtime Executor state, relevant approval/question state, run-path validation, permission validation, and bounded audit snapshot. - `full` target `<30s`: chunk checks plus bounded Runtime API snapshot, bounded scorecard/doctor summary, indexed reconciliation summary, governance, and shell-entrypoint classification. It still excludes unbounded historical scans and live transport smoke. - `smoke` / `expensive-smoke`: explicit only. Use for live Telegram bridge tests, process/tmux probes, dispatcher/operator-daemon integration tests, and explicit historical reconciliation. Normal validation reads audit counts and capped recent records only. Historical audit visibility remains available through: ```sh node ai/runtime/dist/cli.js audit snapshot --historical --limit 250 --json node ai/runtime/dist/cli.js request --method runtime.reconciliationHistorical --params '{"limit":250}' ``` Audit archive maintenance separates hot/current state from historical records. The current-state index is the normal runtime source for operator-daemon request/result summaries; archive queries are explicit: ```sh node ai/runtime/dist/cli.js audit archive-plan --json node ai/runtime/dist/cli.js audit archive-execute --dry-run --json node ai/runtime/dist/cli.js audit archive-execute --json node ai/runtime/dist/cli.js audit current-index --json node ai/runtime/dist/cli.js audit historical-lookup --source operator_daemon_requests --id --json ``` Operator-daemon hot records are retained under `.tmp/operator-daemon/` up to the configured current-state limit, default `100` records per source. Older records are moved to `.tmp/audit-archive/operator-daemon//YYYY-MM/`. The lightweight lookup index lives under `.tmp/audit-index/operator-daemon/`. Fast, chunk, full, scorecard, doctor, and normal reconciliation paths must not scan archive directories; historical mode is opt-in only. Action timeline/event-stream maintenance uses the same hot/current versus archive rule: ```sh node ai/runtime/dist/cli.js timeline archive-plan --json node ai/runtime/dist/cli.js timeline archive-execute --dry-run --json node ai/runtime/dist/cli.js timeline archive-execute --json node ai/runtime/dist/cli.js timeline current-index --json node ai/runtime/dist/cli.js timeline snapshot --json node ai/runtime/dist/cli.js timeline replay --limit 20 --json node ai/runtime/dist/cli.js timeline validate-bounded --json ``` The current event stream stays in `.tmp/action-timeline/timeline.jsonl`, bounded by `AI_RUNTIME_TIMELINE_KEEP_EVENTS` or the default `250` events. Historical events are preserved in `.tmp/action-timeline/archive/YYYY-MM-DD.timeline.jsonl`, with indexes under `.tmp/audit-index/action-timeline/`. Normal reconciliation consumes the bounded timeline snapshot; historical replay is explicit and deduplicates event ids for replay-safe inspection. Run summaries are canonical Runtime behavior. Operators and future prompts do not need to restate the section list. Runtime Core validates and renders the required sections for chunk markdown, recorded run summaries, Telegram compact messages, and `/details` payloads: ```sh node ai/runtime/dist/cli.js summary schema --json node ai/runtime/dist/cli.js summary schema-default --json node ai/runtime/dist/cli.js summary validate --chunk --json node ai/runtime/dist/cli.js summary render --chunk --json node ai/runtime/dist/cli.js telegram details --json ``` The required sections are exposed by Runtime Core; prompts should not repeat them. `summary validate` rejects duplicate canonical summary sections, and Ready validation rejects duplicate lifecycle evidence sections such as `Acceptance Criteria Verification`, `QA Review`, `Handoff`, and `Carry Forward`. Runtime defaults are Runtime-owned and machine-readable: ```sh node ai/runtime/dist/cli.js runtime defaults --json node ai/runtime/dist/cli.js runtime execution-policy --json node ai/runtime/dist/cli.js validation defaults --json node ai/runtime/dist/cli.js testing defaults --json node ai/runtime/dist/cli.js orchestration defaults --json ``` Prompts should describe work intent and only name explicit overrides. They should not restate validation command lists, testing strategy, summary sections, close gates, lifecycle sequencing, or profile selection. ## Runtime API Daemon The daemon is local-only: - transport: Unix socket JSON lines. - default socket: `.tmp/runtime-api/runtime.sock`. - default persistent session: `blueprint-runtime-api`. - default status files: `.tmp/runtime-api/status.json` and `.tmp/runtime-api/heartbeat`. Initial methods are read-only or read-mostly: - `runtime.health` - `runtime.snapshot` - `runtime.snapshotCached` - `runtime.profile` - `runtime.cacheStats` - `runtime.version` - `registries.list` - `registries.validate` - `carryForward.listOpen` - `approvals.listActionable` - `operatorQuestions.list` - `operatorQuestions.get` - `operatorQuestions.summary` - `approvals.list` - `approvals.get` - `approvals.classify` - `approvals.summary` - `approvedActions.list` - `approvedActions.listActionable` - `approvedActions.classify` - `approvedActions.summary` - `runtimeEvents.render` - `runtimeEvents.classify` - `notifications.render` - `notifications.classify` - `notifications.summary` - `notifications.details` - `telegram.renderMessage` - `telegram.commandSurface` - `telegram.details` - `telegram.runSummary` - `scorecard.snapshot` - `scorecard.summary` - `doctor.snapshot` - `doctor.health` - `doctor.trustedRuntime` - `runtime.services` - `runtime.pendingWork` - `runtime.debtSummary` - `dispatcher.status` - `dispatcher.results` - `dispatcher.summary` - `daemon.status` - `daemon.pendingActions` - `daemon.summary` - `supervisor.status` - `supervisor.summary` - `runtime.integrationStatus` - `runtime.trustedExecutionSummary` - `runtime.missingActions` - `runPaths.list` - `runPaths.describe` - `runPaths.schedule` - `runtime.schedule` - `runtime.nextPhases` - `runtime.phaseSummary` - `runtime.schedulerHealth` - `runtime.pendingLoops` - `harness.list` - `harness.describe` - `harness.plan` - `harness.runDry` - `harness.summary` - `harness.cutoverReadiness` - `audit.snapshot` - `audit.archivePlan` - `audit.archiveExecute` - `audit.currentIndex` - `audit.historicalLookup` - `audit.validateBounded` - `timeline.snapshot` - `timeline.currentIndex` - `timeline.archivePlan` - `timeline.archiveExecute` - `timeline.replay` - `timeline.validateBounded` - `timeline.reconcile` - `timeline.eventSummary` - `permissions.classify` - `permissions.trustedRuntime` - `governance.validate` - `schemas.validate` - `runtimeEvents.validate` - `carryForward.validate` - `permissions.validate` - `runPaths.validate` - `validators.list` - `validators.tiers` - `validation.graph` - `validation.profile` - `validation.invalidate` - `chunks.find` - `chunks.status` - `chunks.validateReady` - `chunks.validateTransition` - `chunks.lifecycleRules` - `chunks.evidenceSummary` - `lifecycle.validateTransition` - `lifecycle.allowedTransitions` - `approvalPolicy.classify` - `shellEntrypoints.classify` - `scorecard.snapshot` - `doctor.snapshot` The daemon intentionally does not expose arbitrary shell execution and does not cross approval boundaries. Mutating authority-state operations remain owned by their existing trusted runtime surfaces until a focused migration replaces them with typed adapters and equivalent validation. ## Shell Compatibility Strategy Existing shell tools remain authoritative where they already own side effects: - `ai/chunks/transition.sh` owns lifecycle mutation. - `ai/tools/approved-action-dispatcher/` owns approved action execution. - `ai/tools/operator-daemon/` owns trusted local/dev actions. - `ai/tools/runtime-supervisor/` owns persistent service restarts. - `ai/tools/telegram/` owns Telegram transport. Future chunks should migrate pure logic first and leave these shell entrypoints as compatibility wrappers until the TypeScript runtime owns equivalent behavior with tests and validators. ## Wrapper Compatibility Policy Shell entrypoints stay stable for operators and existing automation. The migration rule is: ```text shell entrypoint -> Runtime API method -> typed runtime module -> registry/state ``` for safe read-only behavior. Mutating authority-state behavior remains with the existing guarded owner until a focused migration supplies equivalent typed contracts, validation, and approval-boundary enforcement. Wrapper fallback behavior must be explicit: - read-only rendering/classification wrappers may fall back to local legacy registry parsing when the daemon is unavailable. - authority-state mutation wrappers must fail closed when the daemon, dispatcher, supervisor, or validation state is unavailable. - wrappers should expose their source when practical, for example `runtime-api` versus `legacy-fallback` in JSON output. Current migrated read-only wrapper: - `ai/tools/operator-notifications/render-event.mjs` tries `runtimeEvents.render` first and falls back to local registry parsing only because event rendering is non-mutating. ## Trusted Local Permission Policy Runtime permission classification is registry-backed by: ```sh ai/governance/registries/runtime-permissions.yaml ``` `permissions.classify` returns the operation trust level, operation class, Codex prompt expectation, Blueprint approval requirement, operator approval requirement, executor owner, wrapper inheritance, and docs. The important separation is: ```text Codex sandbox approval -> host execution/sandboxing Blueprint governance approval -> lifecycle, dispatcher, and authority state ``` Trusted local operations such as repo inspection, scoped repo-local edits, runtime tests, governance validators, doctor/scorecard queries, Runtime API requests, and wrapper tests are classified so the local/dev runtime can avoid ad hoc approval behavior. Authority-state mutation and external side effects remain approval-gated or forbidden by the same registry. ## Governance Validator Modules Runtime Core owns the migrated pure validator modules under: ```text ai/runtime/src/modules/governance/ ai/runtime/src/modules/validation/ ``` The migrated canonical validators cover schema/registry contracts, carry-forward debt, runtime event semantics, run paths, runtime permissions, and aggregate `governance-core` validation. Results use a normalized typed shape with status, code, message, severity, optional affected path, advisory count, and pending-enforcement visibility. Existing shell validator entrypoints remain compatibility wrappers. The first wrappers routed through Runtime Core are: - `ai/governance/validate-schemas.sh` - `ai/governance/validators/validate-carry-forward-debt.sh` - `ai/governance/validators/validate-runtime-event-semantics.sh` - `ai/governance/validators/validate-run-paths.sh` - `ai/governance/validators/validate-runtime-permissions.sh` Shell-heavy governance checks, including generated Telegram help/doc drift and operator command surface projection, remain in the MJS compatibility validator until focused migrations can preserve their process and filesystem behavior. ## Lifecycle And Chunk Modules Runtime Core owns the migrated read-only lifecycle and chunk validation module under: ```text ai/runtime/src/modules/chunks/ ``` The migrated logic covers chunk lookup/status, evidence summaries, Ready-for-Human-Review validation, lifecycle transition validation, QA verdict consistency, Developer/QA/Orchestrator role separation, carry-forward projection checks, stale post-transition `Next` detection, validation evidence checks, and lifecycle approval-side-effect reporting. Existing shell entrypoints remain human-only compatibility or process-adapter surfaces: - `ai/chunks/validate-ready-for-review.sh` - `ai/chunks/validate-transition.sh` - `ai/chunks/transition.sh` The read-only validators route through Runtime Core. `transition.sh` still owns the guarded status/evidence mutation after validation passes. Runtime API lifecycle/chunk methods are inspection and validation methods only; they do not complete chunks, stage files, commit, or cross approval boundaries. ## Operator Question And Approval State Modules Runtime Core owns the migrated read-only operator-question and approval-state classification module under: ```text ai/runtime/src/modules/operator-state/ ``` The migrated logic covers operator question listing, approval summaries, approved-action audit records, and deterministic classification of pending, approved, denied, consumed, stale, ignored, superseded, invalid, and resolved-stale approval state. Stale and inactive approved actions are not returned as actionable by default. Existing operator surfaces remain stable: - `ai/tools/operator-questions/list.sh` - `ai/tools/operator-questions/status.sh` - `ai/tools/operator-questions/list-approved-actions.sh` - `ai/tools/approved-action-dispatcher/dispatch.sh` - `ai/tools/operator-daemon/` - `ai/tools/telegram/` `list-approved-actions.sh` now routes its read-only classification through the Runtime Core CLI while preserving its shell entrypoint and output shape. Runtime Core does not execute approved actions, run `close_commit`, mutate lifecycle state, or resolve approvals. Dispatcher and trusted-daemon ownership remain the approval boundary for execution. ## Notification And Telegram Render Modules Runtime Core owns the migrated read-only notification and Telegram render semantics module under: ```text ai/runtime/src/modules/notifications/ ``` The migrated logic covers runtime event classification, notification render models, Telegram message render models, compact run-summary render models, details lookup, command-surface projection, actionability flags, and freeform/approval/reply boundaries. The Runtime API methods are render and inspection methods only; they do not send Telegram messages, poll Telegram, answer questions, create approvals, or execute dispatcher/daemon actions. Existing Telegram and notification entrypoints remain stable: - `ai/tools/operator-notifications/render-event.mjs` - `ai/tools/operator-notifications/send-event.sh` - `ai/tools/telegram/send-run-summary.mjs` - `ai/tools/telegram/bridge.sh` - `ai/tools/telegram/telegram-bridge.mjs` `render-event.mjs` now asks Runtime API `notifications.render` first and keeps its explicit legacy fallback. Telegram bridge remains the transport/operator surface, not a governance authority or execution owner. ## Scorecard And Doctor Modules Runtime Core owns the migrated read-only scorecard and doctor aggregation module under: ```text ai/runtime/src/modules/health/ ``` The migrated aggregation reuses Runtime Core operator-question, approval, notification, governance, permission, lifecycle, and carry-forward modules where practical. Shell/process-dependent probes remain isolated as adapters for tmux/session status, daemon status, dispatcher status, supervisor status, Telegram status, and Runtime API socket heartbeat. Existing doctor and scorecard shell entrypoints remain human-only compatibility surfaces. Codex/runtime validation must use `node ai/runtime/dist/cli.js doctor --json` and `node ai/runtime/dist/cli.js scorecard --json`. The Runtime API now exposes canonical read-only scorecard/doctor methods. These methods summarize trusted runtime services, pending questions, actionable/stale approvals, governance state, and carry-forward debt. They do not mutate runtime state, execute recovery actions, dispatch approved actions, or expose arbitrary shell execution. ## Dispatcher Daemon Supervisor Integration Runtime Core exposes read-only integration projections for the approved-action dispatcher, operator daemon, runtime supervisor, Runtime API daemon, and open missing-action records. The normalized states are `healthy`, `degraded`, `blocked`, `unknown`, `pending`, `executing`, `succeeded`, `failed`, `stale`, `consumed`, `missing`, and `restart_required`. Authority ownership does not move: the dispatcher owns approved execution, the operator daemon owns trusted local action execution, and the runtime supervisor owns service restarts. Runtime API methods only classify and expose state. They do not execute approved actions, restart services, perform `close_commit`, or mutate approvals. The integration summary preserves `cfd-0001` visibility by reporting failed dispatcher result records that are later associated with consumed/executed approved-action records. This is audit visibility only, not an idempotency or timeline reconciliation fix. ## Runtime Scheduling Run-path scheduling semantics are registry-backed in `ai/governance/registries/run-paths.yaml` under `runtime_scheduling`. Runtime Core exposes deterministic read-only schedule projections for loop ownership, phase order, next-run calculation, duplicate keys, bounded-autonomy stop conditions, and scheduler health. The scheduling methods are planning methods only. They do not claim loop ownership, execute run-path phases, dispatch approved actions, restart services, mutate approvals, or expose arbitrary shell execution. Execution authority remains with lifecycle tooling, approved-action dispatcher, trusted operator daemon, and runtime supervisor. ## Runtime Path Harness Runtime Core includes a deterministic runtime path harness under `ai/runtime/src/modules/harness/`. The harness consumes run-path scheduling, Runtime Core validators, permission policy, approval policy, notification rendering, and fixture flow definitions. It supports `dry_run`, `fixture`, `read_only_live`, and `blocked_mutation_expected` modes, with non-mutating dry-run behavior as the default. Harness methods may plan and assert flows, but they must not mutate lifecycle state, dispatch approved actions, run daemon actions, restart services, execute `close_commit`, or expose arbitrary shell execution. `ai/runtime/test-paths.sh` runs the focused harness tests. ## Shell Facades Runtime Core/API is the preferred implementation surface for migrated read-only behavior. Shell entrypoints remain stable for operators, CI, bootstrap, and recovery, but migrated wrappers should be thin facades around Runtime CLI/API instead of duplicating registry parsing or policy logic. See `ai/standards/shell-entrypoint-cutover.md` for converted facades, compatibility-only shell internals, and guardrails. ## Runtime Reconciliation Runtime Core owns read-only reconciliation semantics for stale approvals, dispatcher results, retry-succeeded actions, transient probe failures, and duplicate runtime artifacts. The reconciliation API classifies state for scorecard, doctor, operator surfaces, and carry-forward visibility without executing actions or mutating authority state. See `ai/standards/runtime-reconciliation.md` for stale-artifact policy and the canonical reconciliation states.