@spec assert_catalog_closed!(keyword()) :: :ok

Walks the real shipped sources and raises on the first violated criterion, with the six-step recipe for legitimately adding the next control.

Returns :ok when the catalog line holds.

Options — all defaulting to the real shipped values

• :root — the tree the source, native-enum, and native-denial walks read from. Defaults to File.cwd!().
• :commands — defaults to Crosswake.Bridge.Contract.commands/0.
• :command_capability_map — defaults to shipped_command_capability_map/0.
• :catalog_capability_ids — defaults to bounded_bridge_capability_ids/0.

assert_catalog_closed!() with no options is the merge-blocking gate, unchanged. See the moduledoc's "injection seam" section for why the options exist.

@spec bounded_bridge_capability_ids() :: [String.t()]

The bounded-bridge capability families declared in Manifest.Builder's capability catalog — the attestation file that already exists (D-42).

@spec bridge_sources(String.t()) :: [String.t()]

The lib/ sources the catalog line is enforced over.

root defaults to File.cwd!() — the shipped tree. It is parameterised only so the recipe-followability proof can point the same walk at a temp fixture tree.

@spec check_attestation([String.t()], %{required(String.t()) => String.t() | nil}, [
  String.t()
]) ::
  :ok | {:violation, list()}

Criterion (a): every catalog entry maps to a shipped command and every shipped command maps to a catalog entry.

Rejecting only gaps would let a command ship with no owner, no rebuild cost, and no declared denial — an undeclared control wearing a declared one's badge. Rejecting only orphans would let a catalog entry claim a control that does not exist. Both directions or neither.

@spec check_command_list_literal(String.t()) :: :ok | {:violation, list()}

Criterion (d): the command vocabulary must be a compile-time literal.

A ~w sigil or a plain list of string literals is a literal. A list built with ++, a comprehension, an Enum call, or string interpolation is not — that is a runtime-constructed vocabulary, which is the plugin-catalog road under a different name. A source with no @commands attribute is clean; not every file declares a vocabulary.

@spec check_denial_allowlist_liveness(String.t()) :: :ok | {:violation, list()}

Asserts every allowlist entry is still emitted by at least one of its declared sites. An entry whose string has been fixed or deleted is rot: it makes the allowlist look larger than the real debt and quietly widens the gate.

@spec check_native_denial_reasons(String.t()) :: :ok | {:violation, list()}

Asserts every statically extractable native denial reason is either in the closed Crosswake.Shell.Denial vocabulary or on the eight-entry seeded allowlist. A NINTH out-of-vocabulary string is a violation.

@spec check_native_enum_parity(String.t(), [String.t()]) :: :ok | {:violation, list()}

Criterion (d): native command enum parity, asserted in BOTH directions.

A GAP is an Elixir command absent from the native enum. An ORPHAN is a native enum case with no Elixir command, excluding the enumerated outbound-only pushes. Checking one direction only would let a native shell ship a command the server has never heard of — which is the same hole as a dynamic registration seam, opened from the other end.

An unlocatable enum block is a violation, never a vacuous pass.

@spec check_no_atom_minting(String.t()) :: :ok | {:violation, list()}

Criterion (d): no atom minting. String.to_atom/1 and List.to_atom/1 grow the atom table from wire input. String.to_existing_atom/1 is on the frozen allowlist — it cannot mint, only resolve.

@spec check_no_dynamic_registration(String.t()) :: :ok | {:violation, list()}

Criterion (d): no dynamic-registration seam.

Any def/defp/defmacro whose name starts with register_ is a violation. Prefix match, not substring: registry_lookup/1 is fine.

@spec check_no_external_sdk(String.t()) :: :ok | {:violation, list()}

Criterion (c): zero external SDK. An allowlist walk over every alias/import/require/use declaration; anything rooted outside [:Crosswake, :Phoenix, :Logger, :Jason, :Kernel] is an external SDK reaching into the bounded bridge.

@spec check_no_runtime_apply(String.t()) :: :ok | {:violation, list()}

Criterion (d): no runtime function application. apply/2, apply/3, and Kernel.apply/3 all let a command name become a call target.

@spec check_no_streaming_seam(String.t()) :: :ok | {:violation, list()}

Criterion (b), in the negative only: no streaming or back-pressure seam ([:Stream, :GenStage, :Flow, :Broadway]) in the bridge tree.

This proves no streaming seam EXISTS. It does not prove nobody calls a control in a loop — see the moduledoc's honest labelling.

@spec check_source(String.t()) :: :ok | {:violation, list()}

Runs every source-level mechanical sub-assertion over source_string and returns the COMPLETE SET of violations.

A source violating five criteria reports all five. Short-circuiting on the first would make a five-violation control look like a one-violation control, and the fix-one-rerun loop is exactly how a structural gate degrades into a nuisance.

Returns :ok, or {:violation, [{criterion_atom, node_or_detail}]}. An empty or trivially small source is clean. An UNPARSEABLE source is a violation, not a pass — the guard fails closed.

@spec closed_vocabulary() :: [String.t()]

The closed denial vocabulary as wire strings.

@spec extract_native_command_enum(String.t()) :: {:ok, [String.t()]} | :error

Extracts the wire values from a native BridgeCommand enum block.

Returns {:ok, wire_values} or :error. :error when the enum block cannot be located at all — carrying forward Phase 134's guard that a job not found is a FAILURE, not a pass. An extractor that silently returns [] for a renamed enum turns the parity check green at exactly the moment it should be red.

@spec extract_native_denial_reasons(String.t()) :: [String.t()]

Extracts denial reason string literals from native (Swift/Kotlin) source.

Recognises three emission shapes, each anchored on a real call site rather than a bare regex over every literal in the file:

1. The FIRST reason-shaped literal inside a balanced deny( / Denied( / unavailable( call — covers both the Swift labelled-argument form (reason: "x") and the Kotlin positional form.
2. Every reason-shaped literal in a let/val/var reason = assignment expression — covers ternary-assigned reasons.
3. Nothing at all when the reason argument is a VARIABLE. That is not a miss; it is the unbounded host-supplied seam, which is not statically bounded and is carried by SEED-008 (see the moduledoc's non-mechanical exclusion).

"Reason-shaped" means lowercase with at least one underscore — see the moduledoc's known extractor limitation.

@spec native_command_enum_sources(String.t()) :: [String.t()]

The two native command-enum sources checked for bidirectional parity.

@spec native_denial_sources(String.t()) :: [String.t()]

The native sources whose emitted denial reason strings are checked against the closed vocabulary. Enumerated, not globbed: a source that has moved must be noticed, not silently skipped.

@spec out_of_vocabulary_denial_allowlist() :: [map()]

The eight enumerated out-of-vocabulary native denial reason strings, each with its shipping sites, an individual justification, and the SEED-008 id (D-16, resolved as option-b with amendment).

A NINTH string turns check_native_denial_reasons/1 red. Padding this list is the failure mode the individual justifications exist to make visible: adding an entry means writing down, in review, why the closed vocabulary could not answer.

@spec outbound_only_native_commands() :: [String.t()]

Native enum cases exempt from orphan detection because they are outbound server -> shell pushes with no inbound bounded-bridge request seam.

@spec shipped_command_capability_map() :: %{required(String.t()) => String.t() | nil}

The shipped command -> capability family map, read from Crosswake.Bridge.Registry.