calva-backseat-driver: Skill for Claude Code

Backseat Driver Extension Internals

Subsystem contracts, state architecture, and temporal sequences for the Backseat Driver extension.

Key Namespaces

Subsystem Contracts

λ app_db_contract.
  db/!app-db ≡ atom {
    :vscode/extension-context    ExtensionContext     ;; set before dispatch, circular refs
    :app/getConfiguration        fn                   ;; VS Code config reader

    ;; From init-db
    :extension/disposables       [Disposable]         ;; VS Code subscriptions
    :extension/when-contexts     {:calva-mcp-extension/activated? bool
                                  :calva-backseat-driver/started? bool
                                  :calva-backseat-driver/starting? bool
                                  :calva-backseat-driver/stopping? bool}
    :calva/output-line-counter   int                  ;; monotonic for output entities

    ;; From initial-state (extension.cljs)
    :app/log-file-uri            Uri                  ;; log location
    :app/min-log-level           keyword              ;; :debug/:info/:warn/:error
    :mcp/wrapper-config-path     string               ;; ~/.config/calva/backseat-driver
    :calva/history-storage-uri   Uri|nil              ;; eval-history.transit.json

    ;; Runtime
    :app/log-dir-initialized+    promise              ;; resolved when log dir exists
    :app/server-info             {:server/instance Server
                                  :server/port int
                                  :server/port-file-uri Uri
                                  :server/port-note string?}
  }
  | inspection: always(dissoc :vscode/extension-context) | circular_ref_guard
  | mutation: only_through_dispatch! | ¬direct_swap!

λ ex_dispatcher_contract.
  dispatch!(context, actions) ≡ the_only_state_entry_point
  | ~16 lines of code | the entire framework
  |
  | flow:
  |   ax/handle-actions(@!app-db, context, actions)
  |     reduce_over_actions:
  |       1. enrich-from-context(action, context)    → :context/x.y → js-get-in
  |       2. enrich-from-state(action, state)        → [:db/get k], :vscode/config.x
  |       3. route_by(namespace action-kw) → domain_handler
  |       4. handler_returns {:ex/db, :ex/fxs, :ex/dxs}
  |     accumulate: merge_db, into_fxs(enriched_from_state), into_dxs
  |   when db → reset!(!app-db)
  |   when dxs → recursive dispatch!(context, dxs)
  |   when fxs → for_each: enrich_from_context → route → execute

λ enrichment_contract.
  context_enrichment:
    :context/x.y.z → js-get-in(context, ["x" "y" "z"])
    | applied_to: actions ∧ effects
  state_enrichment:
    [:db/get key] → (get state key)
    :vscode/config.settingName → VS Code configuration API
    | applied_to: actions_only (effects get context enrichment only)
  args_enrichment:
    :ex/action-args → entire_result_from_effect
    :ex/action-args%N → (nth result (dec N))
    | applied_to: continuation_actions_via :ex/then

λ action_routing.
  (namespace action-kw) → handler_namespace:
    "app"      → app.axs
    "mcp"      → mcp.axs
    "db"       → db.axs
    "vscode"   → integrations.vscode (via axs)
    "node"     → integrations.node (via axs)
    "calva"    → integrations.calva (via axs)
  | new_domain → add_case_in ex/ax.cljs handle-action

λ effect_routing.
  (namespace fx-kw) → handler_namespace:
    "app"      → app.fxs
    "mcp"      → mcp.fxs
    "vscode"   → integrations.vscode (via fxs)
    "node"     → integrations.node (via fxs)
    "calva"    → integrations.calva (via fxs)
  | effects_receive(dispatch!, context, enriched-fx)
  | new_domain → add_case_in ex/fx.cljs perform-effect!

λ datascript_contract.
  !output-conn ≡ session_scoped | schemaless | cap: 1000 entities
    | all_output_categories: evaluationResults, evaluatedCode, evaluationOutput,
    |   evaluationErrorOutput, otherOutput, otherErrorOutput
  !history-conn ≡ persistent | schema: {:output/line {:db/unique :db.unique/identity}}
    | cap: 10000 | evaluatedCode_only
    | serialized_to: eval-history.transit.json | cognitect.transit JSON
    | format: {:format-version 1 :entities [...]}
  entity_attributes:
    :output/line        int (monotonic, from :calva/output-line-counter)
    :output/category    string
    :output/text        string
    :output/who         string?
    :output/timestamp   inst
    :output/ns          string?
    :output/repl-session-key string?

λ mcp_server_contract.
  socket_server: TCP | net.createServer | localhost_only
  | port: configured(default 1664) | 0 ≡ random | EADDRINUSE → fallback_to_0
  | port_file: ${workspaceFolder}/.calva/mcp-server/port
  | protocol: newline_delimited_JSON | buffered_partial_reads
  | active_sockets: atom | tracks_connected_clients
  | notifications: broadcast_to_all_active_sockets

  stdio_wrapper: dist/calva-mcp-server.js
  | reads_port_from_port_file → TCP_connect → relay(stdio ↔ socket)
  | one_server_per_workspace_folder

λ calva_api_contract.
  calva-api ≡ {
    :repl     {:evaluateCode, :currentSessionKey, :onOutputLogged}
    :ranges   {:currentTopLevelForm, :currentEnclosingForm, ...}
    :editor   {:replace}
    :document {:getNamespace, :getNamespaceAndNsForm}
    :info     {:getSymbolInfo, :getClojureDocsDotOrg}
  }
  | accessed_at: integrations.calva.api/calva-api
  | capability_gated: tools_appear_disappear_based_on_calva_support

λ structural_editing_contract.
  editing_unit ≡ top_level_form | ¬lines_of_text
  | parinfer: bracket_balancing | integrations/parinfer.cljs
  | targeting: targetLineText + line ±2 scan_window
  | rich_comments: forms_inside(comment ...) ≡ top_level
  | diagnostic_context: 21_line_window | line_numbers | → arrow_marker
  | bottom_to_top: multiple_edits_highest_line_first