Bridge Library API (bridge.api)

bridge.api is the only supported entry point for consuming Bridge as a library. Everything else under bridge.* is internal and may change in any commit without notice.

The surface is deliberately an honest list: it contains exactly the operations the reference consumer — the Vis bridge extension (vis-foundation-bridge) — needs, with each var tagged by how much you can rely on it. It is not an aspirational "everything Bridge can do" surface. New vars are added when a consumer demonstrates a need, not preemptively.

Call (bridge.api/contract) at a REPL to get this inventory as data ({:name :stability :arglists :doc} per var).

0.2.x contract

Every public var in bridge.api carries :bridge.api/stability :stable. The test suite pins the exact public membership, and every contract change must update the tests, this document, and the changelog together.

Public API

Var	Purpose
load-profile	Read, validate, and normalize a project profile (all paths absolute).
profile-summary	Small fixed summary map of a loaded profile.
load-policy	Read and validate a verification policy.
init!	Bootstrap a .bridge/ layout with starter profile + policy. The output is heuristic starter state — consumers must not treat it as authoritative project semantics.
normalize-evidence-kind	Canonicalize an evidence-kind string/keyword (e.g. "unit" → "unit-tests").
list-commands	Flat descriptors of the profile's canonical evidence commands.
run-command	Execute one evidence command, write captures + a schema-validated evidence-run receipt, return the receipt. Supports :dry-run? and exact candidate selection with :index? or :tree plus :frontier.
check	Run the verification status check and return the canonical status summary (:summary-version 1) — flattened required/recommended obligations (failed first), evidence receipts, counts, and next action. Supports explicit candidate selection and :approve?. Same shape as bb bridge check --format json. The supported way to consume check status.
status-summary	Project an existing build-status result into the canonical summary.
find-artifacts	Read all Bridge artifacts under a directory, with :_path back-references.
resolve-path, relativize-path, exists?, read-data	Path/data utilities with the same semantics Bridge uses internally — for profile discovery and policy reading on the consumer side.
contract	The API inventory as data.

check and status-summary expose the canonical summary used by both library consumers and bb bridge check --format json. Raw status and action-planning structures remain internal.

Bare check retains working-snapshot semantics. Candidate opts are explicit:

(check profile {:index? true})
(check profile {:tree "HEAD" :frontier "origin/main" :approve? true})
(run-command profile "unit" {:tree candidate-tree :frontier frontier-tree})

Candidate checks read verification governance from the frontier, return candidate/frontier identity under :change-detection, and accept approvals only for a clear, unchanged candidate. See Exact Candidate Verification.

What is deliberately NOT in the API

• Schema internals (bridge.schema) — consumers see validation results through load-profile/load-policy errors and receipt validation, not the validator itself.
• Policy evaluation (bridge.policy rule matching, obligation derivation) — that is kernel semantics; consumers receive its results via check. A consumer needing rule matching directly is a design smell (a second policy engine growing outside Bridge).
• Workflow phases, brief/observable generation, eval, adapters — CLI-level orchestration. If a library consumer needs these, that is a new contract conversation, not a casual import.
• Rendering (bridge.next/render-plain, bridge.tui) — presentation belongs to consumers.

If you find yourself requiring a bridge.* namespace other than bridge.api, file the gap rather than depending on internals — the honest list only stays honest if it grows through declared needs.

Versioning and change policy

• Bridge is pre-1.0; patch releases in the 0.2.x line preserve this contract.
• Removing or renaming a public var, changing argument forms, or changing the meaning or type of an existing return field requires the next minor version.
• Additive return fields may appear without breaking the 0.2.x contract. Consumers should ignore unknown map keys.
• The exact public membership is pinned by bridge.api-test; changing it requires updating the test, this document, and the changelog together.