bridge.api — com.blockether/bridge 0.3.0

Public library API for Bridge.

This namespace is the only supported entry point for external library consumers. The reference consumer is the Vis bridge extension (vis-foundation-bridge); the surface below is exactly the set of operations that integration needs, no more. Everything not exposed here — including every other bridge.* namespace — is internal and may change without notice.

Every public var carries a :bridge.api/stability :stable tag. Argument and return shapes follow the 0.3.x compatibility contract; breaking changes require the next minor version and a CHANGELOG entry.

Call (contract) for this inventory as data. See docs/api.md for the prose version, stability policy, and migration notes.

check clj

(check profile)

(check profile opts)

Run the full verification status check for a profile and return the canonical machine-readable status summary (:summary-version 2) — the same shape bb bridge check --format json prints. opts keys: :changed-files, :git-diff-spec, :policy (preloaded policy data), or candidate selection :index? / :tree with optional :frontier, :policy-path, and explicit :approve?.

The summary contains :project, :status ("clear" or "attention-required"), :issue-count, :changed-files, :change-detection, :counts, :required-obligations (flattened, failed first then open), :recommended-obligations, :stale-artifacts, :subject-problems, :evidence-receipts, :convergence-summary, and :next-action. See docs/api.md for the field-level contract. This is the only supported public way to consume check status.

contract clj

(contract)

The API inventory as data: a vector of {:name :stability :arglists :doc}, sorted by name. This is the machine-readable form of the honest list in docs/api.md.

exists? clj

(exists? path)

True when a file or directory exists at path.

find-artifacts clj

(find-artifacts root)

Read data maps containing an :artifact field under directory root. Returns each map with a :_path back-reference. Discovery is syntactic; call validate-artifact through the CLI when validity must be established.

init! clj

(init! opts)

Bootstrap Bridge in the directory (:root opts) (default "."). Creates the .bridge/ layout, a starter profile with heuristically inferred canonical commands, a default verification policy, and a .gitignore entry for .bridge/ephemeral/. Throws when a profile or policy already exists. Returns {:created [...] :updated [...] :next-actions [...]}.

Note: the generated profile is a starter state, not project-specific verification semantics. Consumers should treat heuristic bootstrap output as requiring review or remediation, not as authoritative.

list-commands clj

(list-commands profile)

List the profile's canonical evidence commands as flat descriptors: :id, :kind, :role, :description, :command, :cwd, :profile-root, :output-path, :subject, :default-output-root, :default-artifact-path, :timeout-ms, :result-parser (type only).

load-policy clj

(load-policy path)

Read and schema-validate a verification policy from path (YAML or EDN). Returns the policy data unmodified. Throws ex-info with :validation data when the policy is invalid.

load-profile clj

(load-profile path)

Read, schema-validate, and normalize a project profile from path (EDN or YAML). Returns the normalized profile map: :root-path, configured surface paths, :artifact-paths, verification-policy path, command cwds/output paths, and subsystem artifact roots are resolved to absolute paths. Throws ex-info with :validation data when the profile is invalid.

normalize-evidence-kind clj

(normalize-evidence-kind kind)

Normalize an evidence-kind string/keyword to its canonical evidence-kind string (resolving aliases, case, keywords). Unknown kinds pass through lowercased. The canonical vocabulary may grow, but existing kinds keep their meaning.

profile-summary clj

(profile-summary profile)

Small fixed summary of a loaded profile: :project-name, :root-path, and :subsystem-count / :command-count / :requirement-source-count.

read-data clj

(read-data path)

Read and parse a data file by extension: EDN or YAML to Clojure data (keywordized), anything else as a raw string.

relativize-path clj

(relativize-path root path)

Relativize path against root; both are canonicalized first. Returns the relative path as a string.

resolve-path clj

(resolve-path root path)

Resolve path against root to a canonical absolute path. Absolute paths pass through (canonicalized); nil/blank paths return nil.

run-command clj

(run-command profile id)

(run-command profile id opts)

Execute one canonical evidence command by id. Writes stdout/stderr captures and a schema-validated evidence-run receipt under the profile's evidence output root, and returns the receipt map (:evidence-id, :execution-status, :evidence-status, :exit-code, :failure-signals, :parsed-metrics, paths, timing).

opts keys: :out-dir, :out-path, :subject, :timeout-seconds, :dry-run?, and the candidate selection :index? or :tree plus optional :frontier / :policy-path. Candidate execution runs in an ephemeral worktree for the exact selected tree. With :dry-run? true nothing executes and the execution plan is returned with :dry-run? true. Nonzero exits and timeouts return receipts describing the failure. Throws ex-info when the command cannot be planned, started, validated, or recorded.