bin/bvtctl

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
CMD="${1:-help}"
shift || true

print_help() {
  cat <<'EOF'
bvtctl - one conversational control CLI

Primary path:
  bvtctl "summarise the current runtime"
  bvtctl ask "run the demo manifest" runtime/examples/demo_manifest.json
  bvtctl chat

Operator commands:
  bvtctl bootstrap
    Build the bootstrap hotgraph from the source registry.

  bvtctl run [usecase] [goal]
    Run bootstrap + bounded packet generation in one pass.

  bvtctl compile
    Compile the canonical system file into the live API, runtime, control, and inference surfaces.

  bvtctl governance
    Show the compiled user-governed next moves from data_prep reduction surfaces.

  bvtctl continuity-status
    Show the primary continuity runtime state from the live NextGen provider, with local fallback only if needed.

  bvtctl continuity-lineage [version_id]
    Show the continuity lineage packet from the provider-first continuity surface.

  bvtctl continuity-surfaces
    Show the materialized continuity surfaces from the provider-first continuity surface.

  bvtctl continuity-flow [version_id]
    Collapse continuity status, lineage, and activation guidance into one operator packet.

  bvtctl continuity-resume [version_id]
    Return the continuity desk packet for the current live version, optimized for resume and next action.

  bvtctl pm-products
    Show the product candidate registry compiled from reduced user-data governance.

  bvtctl pm-resume
    Return the PM operator desk packet.

  bvtctl pm-next
    Return the PM operator packet focused on the next bounded delivery move.

  bvtctl pm-verify
    Run the PM verification path through the benchmark gate.

  bvtctl memory-readiness
    Show the compiled deterministic-memory readiness read for exact lookup, hologram retrieval, and typed ledger gaps.

  bvtctl memory-runtime
    Show the compiled typed memory runtime artifact.

  bvtctl memory-get <unit_id>
    Deterministically retrieve one typed memory unit by exact id.

  bvtctl memory-as-of <unit_id_or_logical_id> <timestamp>
    Deterministically retrieve the typed memory unit that was effective at a given time.

  bvtctl memory-expand <unit_id>
    Expand one typed memory unit through its deterministic relation edges.

  bvtctl continuity-activate <surface_id> [version_id]
    Activate one continuity surface through the live provider.

  bvtctl continuity-materialize [manifest]
    Instantiate the continuity runtime through the live provider, with local materialization only as fallback.

  bvtctl continuity-materialize-local [manifest]
    Materialize the local fallback continuity slice through the existing runtime and receipts.

  bvtctl execute [manifest]
    Run one bounded local work manifest and emit a receipt.

  bvtctl benchmark
    Run the standalone control benchmark.

  bvtctl corpus-packets
    Build the pilot corpus reasoning packets for the golden abstractions.

  bvtctl self-improve "<goal>"
    Propose one bounded repo improvement through Codex CLI.

  bvtctl self-improve-apply "<goal>"
    Propose, apply, and benchmark one bounded repo improvement.

Inspect surfaces:
  bvtctl packet [usecase] [goal]
  bvtctl policy
  bvtctl scorecard
  bvtctl runtime
  bvtctl api
  bvtctl inference
  bvtctl context
  bvtctl bootstrap-context
  bvtctl ux
  bvtctl kernel-plan

Why:
  the default front door is conversation; the other commands are explicit operator tools.
EOF
}

render_turn_response() {
  local response_path="$1"
  jq -r '
    [
      "Answer: " + .answer_text,
      "Lane: " + .lane,
      "Frontier: " + .tensor_surface.frontier_read,
      "Execution gate: " + (if .execution_gate.allowed then "open" else "closed" end),
      (if .inference.backend == null then empty else "Inference backend: " + .inference.backend.id + " (" + .inference.backend.model + ")" end),
      "System entry: " + .system_context.current_position.slice_id,
      "Profile: " + .system_context.current_position.default_profile,
      "Decision: " + .decision_brief,
      (if .receipt_path == null then empty else "Receipt: " + .receipt_path end),
      (if .runtime_summary == null then empty else "Runtime summary: " + .runtime_summary end),
      "Response packet: " + $response_path
    ] | .[]
  ' --arg response_path "$response_path" "$response_path"
}

run_turn() {
  local user_input="$1"
  local manifest_path="${2:-}"
  local response_path
  response_path="$("$ROOT/api/run_turn.sh" "$user_input" "$manifest_path")"
  render_turn_response "$response_path"
}

run_chat() {
  local manifest_path="${1:-}"
  local prompt="bvtctl> "
  local user_input=""

  cat <<EOF
bvtctl chat - conversational control loop
Type 'exit' or 'quit' to leave.
EOF

  while true; do
    printf '%s' "$prompt"
    if ! IFS= read -r user_input; then
      printf '\n'
      break
    fi
    case "$user_input" in
      "" )
        continue
        ;;
      exit|quit)
        break
        ;;
      *)
        run_turn "$user_input" "$manifest_path"
        printf '\n'
        ;;
    esac
  done
}

case "$CMD" in
  bootstrap)
    "$ROOT/scripts/build_hotgraph.sh"
    ;;
  packet)
    USECASE="${1:-migration_brief}"
    GOAL="${2:-}"
    "$ROOT/scripts/generate_control_packet.sh" "$USECASE" "$GOAL"
    ;;
  run)
    USECASE="${1:-migration_brief}"
    GOAL="${2:-}"
    "$ROOT/scripts/run_v0.sh" "$USECASE" "$GOAL"
    ;;
  compile)
    "$ROOT/scripts/compile_system.sh" "${1:-$ROOT/canon/system.yml}"
    ;;
  governance)
    python3 "$ROOT/scripts/compile_user_governance.py"
    ;;
  continuity-status)
    "$ROOT/scripts/continuity_provider.sh" status
    ;;
  continuity-lineage)
    VERSION_ID="${1:-hv-continuity-control-plane-v1}"
    "$ROOT/scripts/continuity_provider.sh" lineage "$VERSION_ID"
    ;;
  continuity-surfaces)
    "$ROOT/scripts/continuity_provider.sh" surfaces
    ;;
  continuity-flow)
    VERSION_ID="${1:-hv-continuity-control-plane-v1}"
    "$ROOT/scripts/render_continuity_flow.sh" "$VERSION_ID"
    ;;
  continuity-resume)
    VERSION_ID="${1:-hv-continuity-control-plane-v1}"
    "$ROOT/scripts/render_continuity_flow.sh" "$VERSION_ID"
    ;;
  pm-products)
    cat "$ROOT/build/system/product_candidate_registry.json"
    ;;
  pm-resume)
    "$ROOT/scripts/render_pm_operator.sh" resume
    ;;
  pm-next)
    "$ROOT/scripts/render_pm_operator.sh" next
    ;;
  pm-verify)
    "$ROOT/scripts/render_pm_operator.sh" verify
    ;;
  memory-readiness)
    cat "$ROOT/build/system/memory_readiness.json"
    ;;
  memory-runtime)
    python3 "$ROOT/scripts/query_typed_memory.py" show
    ;;
  memory-get)
    UNIT_ID="${1:-}"
    if [ -z "$UNIT_ID" ]; then
      echo "usage: bvtctl memory-get <unit_id>" >&2
      exit 1
    fi
    python3 "$ROOT/scripts/query_typed_memory.py" exact "$UNIT_ID"
    ;;
  memory-as-of)
    UNIT_ID="${1:-}"
    AT_TIME="${2:-}"
    if [ -z "$UNIT_ID" ] || [ -z "$AT_TIME" ]; then
      echo "usage: bvtctl memory-as-of <unit_id_or_logical_id> <timestamp>" >&2
      exit 1
    fi
    python3 "$ROOT/scripts/query_typed_memory.py" as-of "$UNIT_ID" "$AT_TIME"
    ;;
  memory-expand)
    UNIT_ID="${1:-}"
    if [ -z "$UNIT_ID" ]; then
      echo "usage: bvtctl memory-expand <unit_id>" >&2
      exit 1
    fi
    python3 "$ROOT/scripts/query_typed_memory.py" expand "$UNIT_ID"
    ;;
  continuity-activate)
    SURFACE_ID="${1:-}"
    VERSION_ID="${2:-hv-continuity-control-plane-v1}"
    if [ -z "$SURFACE_ID" ]; then
      echo "usage: bvtctl continuity-activate <surface_id> [version_id]" >&2
      exit 1
    fi
    "$ROOT/scripts/continuity_provider.sh" activate "$SURFACE_ID" "$VERSION_ID"
    ;;
  continuity-materialize)
    ARG="${1:-}"
    if [ -n "$ARG" ] && [ -f "$ARG" ]; then
      "$ROOT/scripts/continuity_provider.sh" instantiate "$ARG"
    else
      "$ROOT/scripts/continuity_provider.sh" instantiate "${ARG:-hv-continuity-control-plane-v1}" "hv-conversational-control-plane-v0"
    fi
    ;;
  continuity-materialize-local)
    MANIFEST="${1:-$ROOT/runtime/examples/continuity_v1_manifest.json}"
    MATERIALIZED_MANIFEST="$("$ROOT/runtime/materialize_continuity_slice.sh" "$MANIFEST")"
    "$ROOT/runtime/execute_manifest.sh" "$MATERIALIZED_MANIFEST"
    ;;
  help|--help|-h)
    print_help
    ;;
  policy)
    cat "$ROOT/policy/control_language_v0.json"
    ;;
  scorecard)
    cat "$ROOT/benchmarks/control_scorecard_v0.md"
    ;;
  corpus-packets)
    python3 "$ROOT/scripts/build_corpus_reasoning_packets.py"
    ;;
  runtime)
    cat "$ROOT/runtime/work_manifest_v0.json"
    ;;
  api)
    cat "$ROOT/api/conversational_api_v0.json"
    ;;
  inference)
    cat "$ROOT/inference.yaml"
    ;;
  context)
    "$ROOT/api/build_system_context.sh"
    ;;
  bootstrap-context)
    "$ROOT/api/write_session_bootstrap.sh"
    ;;
  ux)
    cat "$ROOT/ux/orchestrator_ux_v0.md"
    ;;
  execute)
    MANIFEST="${1:-$ROOT/runtime/examples/demo_manifest.json}"
    "$ROOT/runtime/execute_manifest.sh" "$MANIFEST"
    ;;
  turn|ask)
    USER_INPUT="${1:-}"
    MANIFEST="${2:-}"
    if [ -z "$USER_INPUT" ]; then
      echo "usage: bvtctl ask \"<user_input>\" [manifest.json]" >&2
      exit 1
    fi
    run_turn "$USER_INPUT" "$MANIFEST"
    ;;
  chat)
    MANIFEST="${1:-}"
    run_chat "$MANIFEST"
    ;;
  kernel-plan)
    cat "$ROOT/docs/kernel_import_plan.md"
    ;;
  benchmark)
    "$ROOT/benchmarks/run_standalone_control_bench.sh"
    ;;
  self-improve)
    GOAL="${1:-}"
    if [ -z "$GOAL" ]; then
      echo "usage: bvtctl self-improve \"<goal>\"" >&2
      exit 1
    fi
    python3 "$ROOT/scripts/run_self_improve.py" --goal "$GOAL"
    ;;
  self-improve-apply)
    GOAL="${1:-}"
    if [ -z "$GOAL" ]; then
      echo "usage: bvtctl self-improve-apply \"<goal>\"" >&2
      exit 1
    fi
    python3 "$ROOT/scripts/run_self_improve.py" --goal "$GOAL" --apply --stage-on-pass
    ;;
  *)
    USER_INPUT="$CMD"
    if [ "$#" -gt 0 ]; then
      USER_INPUT="$USER_INPUT $*"
    fi
    run_turn "$USER_INPUT"
    ;;
esac