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.3.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. Root, configured surface/artifact paths, policy path, command cwd/output paths, and subsystem artifact roots become absolute.
profile-summary	Small fixed map with project name, root path, and subsystem, command, and requirement-source counts.
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, and return it. Nonzero exits and timeouts are receipts, not exceptions. 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 2) — flattened required/recommended obligations (failed first), fresh 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.
find-artifacts	Read data maps containing :artifact under a directory, with :_path back-references. Discovery does not establish schema validity.
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 exposes the canonical summary used by both library consumers and bb bridge check --format json. Version 2 reports only the normalized, fresh receipts used to evaluate that status. Raw status, summary projection, and action-planning structures remain internal.

When a fresh stored receipt has evidence status unknown but records an executed zero-exit command, the current check projection normalizes it to passed. Configure a result parser whenever exit zero does not establish verification truth; run-command itself returns the stored receipt value unchanged.

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).
• Rendering (bridge.next/render-plain) — 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.3.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.3.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.

Migrating from 0.2

0.3 is an intentional profile and API break. Remove phases and artifact-paths.phases before loading a 0.2 profile, and replace calls to the removed public status-summary wrapper with check. migrate-profile converts an otherwise current EDN profile to YAML; it does not translate retired phase or artifact workflows. See the 0.3 migration notes in the changelog.