induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/bridge_ledger/network.py

@@ -0,0 +1,336 @@
+"""The bridge network — mounting external MCP servers into the ledger.
+
+This is the side-effecting half of bridge enrollment. The framework's
+:func:`indusagi.interop.mount_protocol_bridge` does the protocol work: it
+connects every configured server, lists each ready endpoint's tools, and hands
+back a :class:`~indusagi.interop.MountedProtocolBridge` whose ``box``
+(:class:`~indusagi.runtime.ToolBox`) advertises every grafted remote tool
+under its qualified ``"<server>__<tool>"`` name through ``descriptors()`` and
+whose shared ``runner`` routes a call back across the owning endpoint.
+
+What this module adds on top:
+
+- **Adaptation.** A ``ToolBox`` speaks the runtime's descriptor/runner
+  contract; the conductor and catalog speak :data:`Capability` (the framework
+  ``AgentTool``). :func:`bridge_box_to_capabilities` bridges the two, wrapping
+  each descriptor + the shared runner into an ``AgentTool`` whose ``execute``
+  invokes the runner and projects its opaque outcome onto an
+  :class:`AgentToolResult` (a single text block).
+- **Enrollment.** :func:`attach_bridge_capabilities` folds those adapted
+  capabilities into a :class:`BridgeLedger` as ``enroll`` events, returning
+  the new ledger, the live fleet (for teardown), and the typed status — never
+  mutating a shared list. A wholesale mount failure becomes a ``bridge``
+  :class:`DeckFault` ON the result, never raised, so a bad MCP configuration
+  degrades the deck instead of sinking session bootstrap.
+- **Cataloging.** :func:`bridge_capability_card` re-presents a grafted
+  capability as a :class:`CapabilityCard`, so dynamic MCP tools surface in
+  help/introspection beside the static catalog rows.
+
+Failure isolation comes for free from the fleet: a server that faulted on
+connect contributes no descriptors and is simply absent from the enrollment.
+
+Port note — cancellation tokens: the runtime ``ToolRunner.run`` requires a
+``CancelToken`` (the TS ``AbortSignal``); the framework exports no public
+constructor for one, so — like the workspace locator's use of
+``indusagi._internal.env`` — the adapter mints a placeholder from
+``indusagi._internal.cancel`` when the caller passes no signal (the analogue
+of the TS ``new AbortController().signal``).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from indusagi._internal.cancel import CancelToken
+from indusagi.ai import TextContent
+from indusagi.interop import (
+    BridgeConfig,
+    FleetStatus,
+    ServerConfig,
+    ServerFleet,
+    is_protocol_fault,
+)
+from indusagi.interop import mount_protocol_bridge as _mount_protocol_bridge
+from indusagi.runtime import ToolBox, ToolCall
+
+from ..contract import (
+    AgentToolResult,
+    AnyCapability,
+    CapabilityCard,
+    DeckFault,
+    Schema,
+    capability_id,
+    deck_fault,
+)
+from .ledger import BridgeLedger, EnrollRequest, enroll_bridge_card, withdraw_server
+
+__all__ = [
+    "AttachResult",
+    "attach_bridge_capabilities",
+    "bridge_box_to_capabilities",
+    "bridge_capability_card",
+    "bridge_config",
+    "detach_bridge",
+]
+
+
+def _server_of_qualified(name: str) -> str:
+    """One descriptor's server id, recovered from its qualified name."""
+    sep = name.find("__")
+    return name[:sep] if sep > 0 else ""
+
+
+def _safe_stringify(value: object) -> str:
+    """JSON-encode a value, degrading to ``str(value)`` if it is not
+    serializable (the TS ``JSON.stringify`` try/catch)."""
+    try:
+        return json.dumps(value, indent=2, ensure_ascii=False)
+    except Exception:
+        return str(value)
+
+
+def _project_outcome(output: object, is_error: bool) -> AgentToolResult:
+    """Project a remote tool's opaque outcome onto an :class:`AgentToolResult`.
+
+    The bridged ``ToolBox`` runner returns a runtime ``ToolOutcome`` whose
+    ``output`` is opaque (an MCP server may return text, structured JSON, or a
+    mix of content blocks). The capability contract requires content blocks,
+    so we render the output into a single text block, preserving plain strings
+    verbatim and JSON-encoding anything structured. The ``is_error`` flag
+    rides straight through.
+
+    :param output: the runner's opaque tool output
+    :param is_error: whether the remote tool reported its own failure
+    """
+    if isinstance(output, str):
+        text = output
+    elif output is None:
+        text = ""
+    else:
+        text = _safe_stringify(output)
+    return AgentToolResult(
+        content=(TextContent(text=text),),
+        details=output,
+        isError=is_error,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Adaptation: ToolBox descriptor/runner → AgentTool capability
+# ---------------------------------------------------------------------------
+
+
+class _BridgedCapability:
+    """One grafted remote tool, adapted to the ``AgentTool`` shape.
+
+    The descriptor's qualified name, description, and parameter schema are
+    carried verbatim; ``execute`` defers to the box's shared runner — passing
+    the cancel token through and projecting the outcome with
+    :func:`_project_outcome`. The runner already knows how to route a call by
+    name back to the owning endpoint, so the wrapper stays a thin shim.
+    """
+
+    __slots__ = ("name", "label", "description", "parameters", "_runner")
+
+    def __init__(
+        self, name: str, description: str, parameters: Schema, runner: object
+    ) -> None:
+        self.name = name
+        # The model-facing label doubles as the qualified name; it is unique
+        # across servers so it serves as a stable display handle too.
+        self.label = name
+        self.description = description
+        # The bridge already normalized the remote schema to the provider-safe
+        # subset; we thread it through as the capability's parameters mapping.
+        self.parameters = parameters
+        self._runner = runner
+
+    async def execute(
+        self,
+        tool_call_id: str,
+        params: object,
+        signal: object = None,
+        on_update: object = None,
+    ) -> AgentToolResult:
+        del on_update
+        cancel = signal if isinstance(signal, CancelToken) else CancelToken()
+        outcome = await self._runner.run(  # type: ignore[attr-defined]
+            ToolCall(id=tool_call_id, name=self.name, input=params), cancel
+        )
+        return _project_outcome(outcome.output, outcome.is_error)
+
+
+def bridge_box_to_capabilities(box: ToolBox) -> list[AnyCapability]:
+    """Adapt every tool a mounted :class:`~indusagi.runtime.ToolBox`
+    advertises into a list of :data:`Capability` objects the conductor and
+    ledger consume.
+
+    Each box descriptor becomes one ``AgentTool``: its qualified name,
+    description, and parameter schema are carried verbatim, and its
+    ``execute`` defers to the box's shared ``runner``.
+
+    :param box: the tool box returned by ``mount_protocol_bridge``
+    """
+    runner = box.runner
+    return [
+        _BridgedCapability(
+            name=descriptor.name,
+            description=descriptor.description,
+            parameters=descriptor.parameters,
+            runner=runner,
+        )
+        for descriptor in box.descriptors()
+    ]
+
+
+def bridge_capability_card(capability: AnyCapability) -> CapabilityCard:
+    """Re-present a grafted bridge capability as a :class:`CapabilityCard`.
+
+    Lets dynamic MCP tools appear in the same catalog/help surface as the
+    static cards: the card's ``build`` simply returns the already-live
+    capability (the graft happened at mount time, so there is nothing further
+    to construct). The owning server id is recovered from the qualified name
+    for the summary.
+
+    :param capability: a capability produced by
+        :func:`bridge_box_to_capabilities`
+    """
+    server = _server_of_qualified(capability.name)
+    summary = (
+        f'{capability.description} (bridged from MCP server "{server}")'
+        if server
+        else capability.description
+    )
+    return CapabilityCard(
+        id=capability_id(capability.name),
+        title=capability.label,
+        summary=summary,
+        build=lambda _ctx: capability,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Enrollment: mount + fold into the ledger
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AttachResult:
+    """The outcome of attaching one or more MCP servers to a ledger.
+
+    Bundles the new :class:`BridgeLedger` (with every reachable tool
+    enrolled), the live :class:`~indusagi.interop.ServerFleet` the caller owns
+    and must eventually tear down, the aggregate
+    :data:`~indusagi.interop.FleetStatus` for rendering, the count of tools
+    grafted, and a non-fatal :class:`DeckFault` when the mount itself failed
+    wholesale.
+    """
+
+    # The ledger after enrolling every grafted capability.
+    ledger: BridgeLedger
+    # How many remote tools were enrolled.
+    enrolled: int
+    # The running fleet of endpoints; caller closes it via `detach_bridge`.
+    fleet: ServerFleet | None = None
+    # Aggregate per-server health, when a fleet came up.
+    status: FleetStatus | None = None
+    # A wholesale-mount fault, when connecting the bridge threw.
+    fault: DeckFault | None = None
+
+
+async def attach_bridge_capabilities(
+    ledger: BridgeLedger, config: BridgeConfig
+) -> AttachResult:
+    """Mount external MCP servers and enroll their tools into the bridge
+    ledger.
+
+    Connects every server in ``config`` through the framework's
+    ``mount_protocol_bridge``, adapts the resulting box into capabilities, and
+    folds each one into ``ledger`` as an ``enroll`` event — yielding a *new*
+    ledger (the input is untouched). The live fleet is returned so the caller
+    can read status and later tear it down; a faulted server simply
+    contributes no tools and is reflected in the status.
+
+    A wholesale failure (the mount call itself raising) is caught and reported
+    as a ``bridge`` :class:`DeckFault` on the result rather than raised, so a
+    bad MCP configuration degrades the deck instead of sinking session
+    bootstrap.
+
+    :param ledger: the ledger to enroll into (left untouched)
+    :param config: the set of MCP servers to connect and graft
+    """
+    try:
+        mounted = await _mount_protocol_bridge(config)
+    except Exception as cause:
+        message = (
+            f"bridge mount failed ({cause.kind}): {cause.message}"
+            if is_protocol_fault(cause)
+            else "bridge mount failed"
+        )
+        return AttachResult(
+            ledger=ledger,
+            enrolled=0,
+            fault=deck_fault("bridge", message, cause),
+        )
+
+    capabilities = bridge_box_to_capabilities(mounted.box)
+    next_ledger = ledger
+    for capability in capabilities:
+        next_ledger = enroll_bridge_card(
+            next_ledger,
+            EnrollRequest(
+                capability=capability,
+                server=_server_of_qualified(capability.name),
+            ),
+        )
+
+    return AttachResult(
+        ledger=next_ledger,
+        enrolled=len(capabilities),
+        fleet=mounted.fleet,
+        status=mounted.fleet.status(),
+    )
+
+
+async def detach_bridge(
+    ledger: BridgeLedger,
+    fleet: ServerFleet,
+    servers: Sequence[str] | None = None,
+) -> BridgeLedger:
+    """Detach one or more servers: retire their ledger entries and close the
+    fleet.
+
+    Withdraws every named server's live capabilities from ``ledger`` (or, when
+    no names are given, every server present in the fleet status) and
+    gracefully tears the fleet down (the Python fleet's ``tear_down()``; TS
+    spelled it ``tearDown``). Returns the new ledger; the fleet is no longer
+    usable after this resolves. The teardown is best-effort — a close that
+    throws is swallowed so ledger withdrawal still completes.
+
+    :param ledger: the current ledger (left untouched)
+    :param fleet: the live fleet to close
+    :param servers: optional subset of server ids to detach; defaults to all
+    """
+    ids = list(servers) if servers is not None else list(fleet.status().keys())
+    next_ledger = ledger
+    for server in ids:
+        next_ledger = withdraw_server(next_ledger, server)
+    try:
+        await fleet.tear_down()
+    except Exception:
+        # Best-effort: the ledger already reflects the withdrawal.
+        pass
+    return next_ledger
+
+
+def bridge_config(servers: Sequence[ServerConfig]) -> BridgeConfig:
+    """Convenience: turn a flat list of MCP server descriptions into the
+    :class:`~indusagi.interop.BridgeConfig` that
+    :func:`attach_bridge_capabilities` expects.
+
+    :param servers: the per-server transport configurations, in declaration
+        order
+    """
+    return BridgeConfig(servers=tuple(servers))

induscode/capability_deck/builtin_bridge.py

@@ -0,0 +1,358 @@
+"""Built-in capability bridge — ONE seam to the framework's native tools.
+
+The framework (``indusagi.agent``, the actions surface) already authors its
+file, search, shell, web, process, and checklist tools as fully-formed
+``AgentTool`` objects and ships a ``create_<name>_tool(cwd, options)`` factory
+for each. This module is the single place the deck reaches across that seam:
+it pairs every native factory with a deck :attr:`CapabilityCard.build`-shaped
+closure so the whole framework tool set is re-exposed as :data:`Capability`
+rows in one file rather than in a dozen one-line re-export stubs.
+
+What this buys the rest of the deck:
+
+- :data:`BUILTIN_BRIDGE` — a single mapping keyed by the wire-facing tool
+  name, each value a :data:`BridgeBuilder`-carrying descriptor that mints the
+  live capability for a :class:`DeckContext`. The manifest derives its catalog
+  rows from this mapping; nothing else hand-maintains a parallel list of
+  built-ins.
+- :func:`build_builtin` — resolve-and-build one built-in by id, surfacing a
+  typed :class:`DeckFault` on an unknown id or a builder throw.
+- :data:`BUILTIN_PROFILES` — the per-built-in profile membership the
+  data-driven provisioner intersects with a requested :data:`DeckProfile`, so
+  the survey (observe-only) set falls out of one table instead of a second
+  hand-written tool list.
+
+Design notes (ported from TS ``src/capability-deck/builtin-bridge.ts``):
+
+- The builders thread ``ctx.cwd`` (and, where a factory takes them, the
+  framework option bags) into the native factory. They never reimplement the
+  tool — the framework owns the read/edit/grep/bash/etc. behavior; the bridge
+  only *binds* it to a working context and re-labels it for the catalog.
+- The process and checklist tools are stateful framework singletons exposed
+  through their factories; the bridge keeps them framework-backed while
+  presenting them as plain capabilities to the deck.
+- All model-facing tool ``name`` strings are the framework's own wire contract
+  and are kept verbatim — the model's prompt and the conductor key off them.
+  Only the deck-side titles/summaries are the deck's own prose.
+
+Port note — checklist wire names follow the *Python* framework
+--------------------------------------------------------------
+The TS lineage's framework named the checklist pair ``todoread`` /
+``todowrite``; the rebuilt Python framework's singletons advertise
+``todo_read`` / ``todo_set`` (verified live against ``indusagi.agent``).
+Because the bridge's invariant is "ids are the framework wire contract,
+verbatim", the descriptor ids here are ``todo_read`` / ``todo_set`` — the
+names the model actually invokes — not the TS spellings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from indusagi.agent import (
+    create_bash_tool,
+    create_edit_tool,
+    create_find_tool,
+    create_grep_tool,
+    create_ls_tool,
+    create_process_tool,
+    create_read_tool,
+    create_web_fetch_tool,
+    create_web_search_tool,
+    create_write_tool,
+    todo_read_tool,
+    todo_write_tool,
+)
+
+from .contract import (
+    AnyCapability,
+    Capability,
+    CapabilityId,
+    CardProfiles,
+    DeckContext,
+    DeckProfile,
+    capability_id,
+    deck_fault,
+)
+
+__all__ = [
+    "BUILTIN_BRIDGE",
+    "BUILTIN_IDS",
+    "BUILTIN_PROFILES",
+    "BridgeBuilder",
+    "BuiltinDescriptor",
+    "build_builtin",
+    "build_builtins_for_profile",
+    "builtin_descriptors",
+]
+
+
+# ---------------------------------------------------------------------------
+# Builder seam
+# ---------------------------------------------------------------------------
+
+#: A closure that mints one framework built-in :data:`Capability` for a
+#: working context — the deck's view of a native factory after the bridge has
+#: bound the ``cwd`` (and any option bag) the factory needs.
+#:
+#: Returns :data:`AnyCapability` because the heterogeneous built-ins carry
+#: different parameter schemas; in Python the open and erased forms collapse
+#: to the same structural ``AgentTool`` Protocol.
+BridgeBuilder = Callable[[DeckContext], AnyCapability]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BuiltinDescriptor:
+    """One descriptor in the built-in catalog: the wire-facing id, the
+    deck-side title/summary prose, the profiles the tool participates in, and
+    the :data:`BridgeBuilder` that binds the framework factory to a context.
+
+    The manifest turns each of these into a :class:`CapabilityCard`; consumers
+    that want the raw built-in set read :data:`BUILTIN_BRIDGE` directly.
+    """
+
+    # Wire-facing tool name the model invokes (framework contract, verbatim).
+    id: CapabilityId
+    # Short human-facing title for catalogs and help text.
+    title: str
+    # One-line description in the deck's own voice.
+    summary: str
+    # Which deck profiles this built-in belongs to.
+    profiles: CardProfiles
+    # Bind the framework factory to a working context.
+    build: BridgeBuilder
+
+
+# ---------------------------------------------------------------------------
+# Bridge table
+# ---------------------------------------------------------------------------
+
+#: The two profiles that withhold mutation/shell — the observe-only set. A
+#: built-in tagged with both ``authoring`` and ``survey`` is safe to expose
+#: when the agent must not change the workspace; a built-in tagged
+#: ``authoring`` only is a mutating or stateful tool that the survey profile
+#: drops.
+_READ_ONLY: CardProfiles = ("authoring", "survey")
+
+#: Mutating / stateful tools: full-access (``authoring``) sessions only.
+_MUTATING: CardProfiles = ("authoring",)
+
+#: The single source of truth for the framework built-ins, in catalog order.
+#:
+#: Each row binds a wire name to its framework factory through a
+#: :data:`BridgeBuilder`, declares its profile membership, and carries the
+#: deck-side prose. This list collapses what would otherwise be a stub file
+#: per tool into one table; the manifest's ``CAPABILITY_CARDS`` for built-ins
+#: is a straight projection of it.
+_BUILTIN_DESCRIPTORS: tuple[BuiltinDescriptor, ...] = (
+    BuiltinDescriptor(
+        id=capability_id("read"),
+        title="Read file",
+        summary=(
+            "Return the contents of a file at a path, optionally from an offset and "
+            "capped to a line limit; renders images inline where supported."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_read_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("ls"),
+        title="List directory",
+        summary=(
+            "Enumerate the entries of a directory, with an optional cap on how many "
+            "are returned."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_ls_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("grep"),
+        title="Search file contents",
+        summary=(
+            "Scan files for lines matching a pattern, with optional case-insensitivity, "
+            "literal matching, surrounding context, and a result cap."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_grep_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("find"),
+        title="Find files by name",
+        summary=(
+            "Locate files and directories whose names match a glob-style pattern "
+            "beneath a root, capped to a result limit."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_find_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("websearch"),
+        title="Web search",
+        summary=(
+            "Query the live web for a string and return a ranked set of result "
+            "snippets, capped to a requested count."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_web_search_tool(),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("webfetch"),
+        title="Fetch URL",
+        summary=(
+            "Retrieve a single URL and return its body as text, Markdown, or HTML, "
+            "with an optional request timeout."
+        ),
+        profiles=_READ_ONLY,
+        build=lambda ctx: create_web_fetch_tool(),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("todo_read"),
+        title="Read checklist",
+        summary=(
+            "Read back the session's running task checklist so the agent can review "
+            "what is pending, active, or done."
+        ),
+        profiles=_READ_ONLY,
+        # The framework's default in-memory checklist singleton; a session-aware
+        # persistent store is wired by the separate checklist provisioner, not here.
+        build=lambda ctx: todo_read_tool,
+    ),
+    BuiltinDescriptor(
+        id=capability_id("write"),
+        title="Write file",
+        summary=(
+            "Create or overwrite a file at a path with the given contents, making "
+            "parent directories as needed."
+        ),
+        profiles=_MUTATING,
+        build=lambda ctx: create_write_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("edit"),
+        title="Edit file",
+        summary=(
+            "Apply a find-and-replace edit to a file, swapping an exact span of old "
+            "text for new text and reporting the resulting diff."
+        ),
+        profiles=_MUTATING,
+        build=lambda ctx: create_edit_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("bash"),
+        title="Run shell command",
+        summary=(
+            "Execute a shell command in the working directory, streaming its output "
+            "and honoring an optional timeout."
+        ),
+        profiles=_MUTATING,
+        build=lambda ctx: create_bash_tool(ctx.cwd),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("process"),
+        title="Manage background processes",
+        summary=(
+            "Start, list, inspect, feed input to, and stop long-running background "
+            "commands without blocking the agent on them."
+        ),
+        profiles=_MUTATING,
+        # The TS factory took an option bag ({ cwd }); the Python factory
+        # accepts the same bag and reads `cwd` out of it.
+        build=lambda ctx: create_process_tool(options={"cwd": ctx.cwd}),
+    ),
+    BuiltinDescriptor(
+        id=capability_id("todo_set"),
+        title="Update checklist",
+        summary=(
+            "Replace or amend the session's task checklist, setting each item's "
+            "text, status, and priority."
+        ),
+        profiles=_MUTATING,
+        # Paired with the read singleton above; both share the framework default
+        # in-memory store. The checklist provisioner swaps in a persistent store.
+        build=lambda ctx: todo_write_tool,
+    ),
+)
+
+#: The framework built-ins keyed by their wire-facing :data:`CapabilityId` —
+#: the single mapping the manifest and provisioner read from.
+#:
+#: Derived from the ordered descriptor tuple, so the keyed view and the
+#: ordered list never drift: there is exactly one place a built-in is declared.
+BUILTIN_BRIDGE: Mapping[str, BuiltinDescriptor] = MappingProxyType(
+    {descriptor.id: descriptor for descriptor in _BUILTIN_DESCRIPTORS}
+)
+
+#: The wire-facing ids of every framework built-in, in catalog order.
+#: Convenient for ``--tools`` style selection and for the manifest's
+#: projection.
+BUILTIN_IDS: tuple[CapabilityId, ...] = tuple(
+    descriptor.id for descriptor in _BUILTIN_DESCRIPTORS
+)
+
+#: The profile membership of every built-in, keyed by id — the slice of the
+#: profile table the data-driven provisioner reads to decide which built-ins a
+#: requested :data:`DeckProfile` includes.
+BUILTIN_PROFILES: Mapping[str, CardProfiles] = MappingProxyType(
+    {descriptor.id: descriptor.profiles for descriptor in _BUILTIN_DESCRIPTORS}
+)
+
+
+# ---------------------------------------------------------------------------
+# Build helpers
+# ---------------------------------------------------------------------------
+
+
+def builtin_descriptors() -> tuple[BuiltinDescriptor, ...]:
+    """The ordered tuple of built-in descriptors — the manifest projects its
+    catalog rows from this, preserving order."""
+    return _BUILTIN_DESCRIPTORS
+
+
+def build_builtin(id: CapabilityId, ctx: DeckContext) -> Capability:
+    """Resolve a built-in by id and build its live capability for a context.
+
+    Raises a typed :class:`DeckFault`: ``unknown_capability`` when the id is
+    not a framework built-in, or ``build_failed`` when the framework factory
+    throws. This is the sanctioned entry point so failure shaping stays
+    uniform across the deck.
+
+    :param id: the wire-facing built-in name to build
+    :param ctx: the working context to bind the factory to
+    """
+    descriptor = BUILTIN_BRIDGE.get(id)
+    if descriptor is None:
+        raise deck_fault(
+            "unknown_capability",
+            f'No framework built-in is registered under "{id}".',
+        )
+    try:
+        return descriptor.build(ctx)
+    except Exception as cause:
+        raise deck_fault(
+            "build_failed",
+            f'Framework built-in "{id}" failed to build.',
+            cause,
+        ) from cause
+
+
+def build_builtins_for_profile(
+    profile: DeckProfile, ctx: DeckContext
+) -> list[AnyCapability]:
+    """Build every framework built-in eligible for a profile, bound to a
+    context.
+
+    Walks the bridge table once, keeps each built-in whose profile membership
+    admits the requested profile (``all`` admits everything), and binds it. A
+    single data-driven pass replaces a trio of per-profile build functions.
+
+    :param profile: the requested deck profile
+    :param ctx: the working context to bind each factory to
+    """
+    built: list[AnyCapability] = []
+    for descriptor in _BUILTIN_DESCRIPTORS:
+        if profile != "all" and profile not in descriptor.profiles:
+            continue
+        built.append(build_builtin(descriptor.id, ctx))
+    return built