@xemahq/kernel-contracts 0.50.0 → 0.57.0

package/src/capability-projection/lib/projected-capability.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+import {
+  CapabilityContributionManifestSchema,
+  type CapabilityContributionManifest,
+} from '../../capability';
+import {
+  CapabilityInvocationBindingSchema,
+  type CapabilityInvocationBinding,
+} from './capability-invocation-binding';
+
+/**
+ * Where a projected capability came from.
+ *
+ * `sourceKey` scopes the projector's PRUNE set: a projector may only ever
+ * delete refs it previously projected, and a ref is attributed to exactly one
+ * source per reconcile. `biomeId` / `biomeVersion` are the same provenance the
+ * contribution path stamps — authors never declare them inline.
+ */
+export interface ProjectedCapabilityProvenance {
+  readonly sourceKey: string;
+  readonly biomeId: string;
+  readonly biomeVersion: string;
+}
+
+export const ProjectedCapabilityProvenanceSchema: z.ZodType<ProjectedCapabilityProvenance> =
+  z.object({
+    sourceKey: z.string().min(1).max(200),
+    biomeId: z.string().min(1).max(200),
+    biomeVersion: z.string().min(1).max(200),
+  }) as unknown as z.ZodType<ProjectedCapabilityProvenance>;
+
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * `ProjectedCapability` — one capability DERIVED by a producer, rather than
+ * hand-authored as a contribution file.
+ *
+ * It deliberately EXTENDS {@link CapabilityContributionManifest} instead of
+ * restating its fields: the hand-authored path, the decorator path and the
+ * projection path must all end up on the SAME `POST /capabilities/register`
+ * wire shape, so there is exactly one place that shape is described. A
+ * projection adds only the two things a hand-authored descriptor does not
+ * carry:
+ *
+ *  - {@link CapabilityInvocationBinding} — HOW to invoke it, as data, so the
+ *    router resolves a target by lookup instead of a hardcoded switch;
+ *  - {@link ProjectedCapabilityProvenance} — WHICH source owns it, which is
+ *    what scopes the reconcile engine's prune set.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+export interface ProjectedCapability extends CapabilityContributionManifest {
+  readonly invocation: CapabilityInvocationBinding;
+  readonly provenance: ProjectedCapabilityProvenance;
+}
+
+export const ProjectedCapabilitySchema: z.ZodType<ProjectedCapability> = z
+  .intersection(
+    CapabilityContributionManifestSchema,
+    z.object({
+      invocation: CapabilityInvocationBindingSchema,
+      provenance: ProjectedCapabilityProvenanceSchema,
+    }),
+  ) as unknown as z.ZodType<ProjectedCapability>;

package/src/connector/lib/onboarding-manifest.ts

@@ -99,6 +99,21 @@ export interface CredentialFieldSpec {
   readonly type: CredentialFieldType;
   /** When true, the wizard refuses submission unless the field is filled. */
   readonly required: boolean;
+  /**
+   * DECLARED secrecy of the field's value. `true` ⇒ the value is a secret and
+   * MUST travel to credential custody (the broker's opaque `secretValue`
+   * bundle); `false` ⇒ the value is non-secret configuration and is stored in
+   * the provision's plain JSON config.
+   *
+   * This is a DECLARATION, never an inference. Secrecy was previously derived
+   * from `type === CredentialFieldType.PASSWORD`, which made a *rendering*
+   * affordance load-bearing for a *custody* decision: a secret rendered as
+   * `TEXT` (an API key an author wanted visible) silently landed in
+   * non-secret storage, and a non-secret masked for ergonomics silently landed
+   * in custody. `type` now means "how to render it" and `isSecret` means
+   * "where it may be stored" — the two are independent and both required.
+   */
+  readonly isSecret: boolean;
   /** Optional placeholder copy. */
   readonly placeholder?: string;
   /** Optional secondary hint shown beneath the input. */
@@ -119,6 +134,7 @@ export const CredentialFieldSpecSchema = z.strictObject({
   label: z.string().min(1),
   type: z.nativeEnum(CredentialFieldType),
   required: z.boolean(),
+  isSecret: z.boolean(),
   placeholder: z.string().optional(),
   hint: z.string().optional(),
   transform: z.nativeEnum(CredentialFieldTransform),

package/src/contribution/lib/contribution-kind.ts

@@ -28,12 +28,23 @@ import { z } from 'zod';
  *          adapter projecting the `MountSourceKindRegistry`; NO biome-host
  *          parser.
  *   3. RESERVED — declared for protocol/catalog completeness but with NO
- *      contribution-protocol ingestion path today. Where the underlying feature
- *      exists it ships via the convention CONTENT-DIRECTORY seeder (on-disk
- *      presence — see the manifest reference), NOT the enum-dispatched
- *      contribution protocol; a few members have no delivery path at all yet.
- *      Do NOT assume a biome-host parser exists for a RESERVED member, and do
- *      not ship a biome contribution of that kind expecting it to be ingested.
+ *      contribution-protocol ingestion path today. Every remaining RESERVED
+ *      member has a REAL, verified delivery path that is deliberately NOT the
+ *      contribution protocol — either a biome-host-api HTTP content endpoint
+ *      that reads the biome's convention directory off disk ON DEMAND
+ *      (`Icon`, `BiomeInstallSchema`, `ProvisioningScaffold`), or a build-time
+ *      bake into the agent-runtime image (`OpenCodeTool`, `OpenCodePlugin`).
+ *      None of them is "seeded": nothing walks those directories at boot.
+ *      A member with NO delivery path at all is DELETED rather than left as
+ *      decoration — `GateAction`, `ChartRuntime`, `WorkspaceSpecOverlay` and
+ *      `SystemOverlayContribution` in the first cleanup; `McpTool` and
+ *      `WorkspaceManifestTemplate` in the second (each had zero readers, zero
+ *      on-disk instances anywhere in the tree, no manifest schema, and a live
+ *      superseding kind — `McpCatalog` and `AgentSkill` respectively). Do NOT
+ *      assume a biome-host parser exists for a RESERVED member, and do not
+ *      ship a biome contribution of that kind expecting it to be ingested —
+ *      biome-host's `assertContributionKindsAreIngestable` coverage guard
+ *      rejects it fail-fast, naming the file.
  *
  * This doc-comment is kept HONEST by review: a member with no biome-host parser
  * MUST be annotated with its true category (2 or 3). An earlier revision falsely
@@ -46,7 +57,16 @@ import { z } from 'zod';
  * Enum string values match the slug spoken by the rest of the protocol
  * (Capability References, manifest declarations) so that round-tripping
  * between the enum and the wire is lossless. The values themselves are a WIRE
- * CONTRACT — never rename or delete a member without a migration plan.
+ * CONTRACT — never rename or delete a member without a migration plan. The
+ * migration plan for the two deletions above is EMPTY BY CONSTRUCTION, and that
+ * is the bar any future deletion must clear: neither value had a producer (no
+ * biome ships the directory, no parser emits the envelope), a consumer (no
+ * routing-table row, no sync handler), or a persisted row (the contribution-sync
+ * store's `kind` column is an open `string`, and biome-host's coverage guard has
+ * been rejecting envelopes of both kinds fail-fast). The only downstream churn is
+ * mechanical regeneration: biome-host-api's `openapi.public.json`, the generated
+ * `@xemahq/biome-host-api-client` `contributionKind` model, and the frontend
+ * mirror of both (via `pnpm sync:frontend`).
  */
 export enum ContributionKind {
   // -- v1 seed ---------------------------------------------------------------
@@ -58,27 +78,16 @@ export enum ContributionKind {
    * stays the authoritative owner and read path; there is NO biome-host parser.
    */
   MountSource = 'mount-source',
-  /**
-   * RESERVED (category 3). No contribution-protocol parser. MCP tool
-   * descriptors ship today via the convention `mcpTools/` content directory
-   * (on-disk presence seeder). The enum-dispatched contribution path for MCP is
-   * `McpCatalog`, which HAS a parser — do not expect one here.
-   */
-  McpTool = 'mcp-tool',
+  // `McpTool = 'mcp-tool'` was DELETED here. It claimed delivery through a
+  // `mcp-tools/` convention directory that NO biome ships and NO code reads:
+  // the only references were the `CONTENT_KIND_DIR` / `CONTENT_KIND_EXTENSIONS`
+  // table rows and biome-host's generic presence loop. There was no manifest
+  // schema (kernel or SDK), no owning registry, and no sync handler. The live
+  // MCP contribution path is `McpCatalog` (parser + routes to BOTH
+  // llm-registry-api and mcp-gateway-api); the live per-biome code-tool
+  // declaration is the manifest block `xema.mcpTools[]`, which is unrelated to
+  // this enum despite the shared name.
   WorkflowStep = 'workflow-step',
-  /**
-   * RESERVED (category 3). No ingestion path today — no parser, no
-   * content-directory seeder, no domain-service handler. The only in-tree use
-   * is a deliberate PLACEHOLDER reuse of this value in the kernel
-   * `inquiry-kind-adapter` (its own comment flags it as a placeholder, not an
-   * equivalence). A biome contribution of this kind is NOT ingested.
-   */
-  GateAction = 'gate-action',
-  /**
-   * RESERVED (category 3). No ingestion path today; referenced only as a worked
-   * "a third party adds a new kind" example in the contribution test-suite.
-   */
-  ChartRuntime = 'chart-runtime',
   AgentSkill = 'agent-skill',
   AgentKernel = 'agent-kernel',
   /**
@@ -91,6 +100,28 @@ export enum ContributionKind {
    */
   ModelResolutionDimension = 'model-resolution-dimension',
   WidgetKind = 'widget-kind',
+  /**
+   * Category 1 (biome-host `KindParser` — parser pending). A VISTA SURFACE
+   * KIND contributed by a biome: the render kind a Vista preview tab can hold,
+   * declared as a bare biome-local slug plus a version, display name, summary,
+   * and an opaque JSON `payloadSchema`. The catalogue namespaces the slug to
+   * `<biomeId>:<kind>` at ingest so a biome can never shadow a first-party
+   * `SurfaceKind`.
+   *
+   * The kernel owns this member AND the manifest schema
+   * (`SurfaceContributionManifestSchema`, exported from
+   * `@xemahq/kernel-contracts/surface`) — the 2-file rule. The per-kind
+   * ingestion parser belongs to the consuming service (`biome-host-api`), not
+   * the kernel, and is NOT shipped yet: a later Vista unit adds
+   * `surface-kind.parser.ts` alongside the catalogue endpoint. Until then this
+   * member is declared but not ingested — do not ship a biome contribution of
+   * this kind expecting it to be picked up.
+   *
+   * Structurally identical to {@link ContributionKind.WidgetKind} on purpose:
+   * the in-chat widget plane and the Vista render plane share ONE contribution
+   * shape, one frontend registry core, and one three-layer renderer fallback.
+   */
+  SurfaceKind = 'surface-kind',
 
   // -- Registry gaps closed --------------------------------------------------
   /**
@@ -117,34 +148,48 @@ export enum ContributionKind {
   /** A role capability bundle contributed by a biome. */
   RoleCapability = 'role-capability',
   /**
-   * RESERVED (category 3). No contribution-protocol parser. The install-wizard
-   * resource-selection schema ships via the convention `biomeInstallSchema/`
-   * content directory (on-disk presence seeder), not the enum-dispatched path.
+   * RESERVED (category 3). No parser, and none is wanted: the install-wizard
+   * resource-selection schema is an OPAQUE, browser-facing JSON Schema that
+   * biome-host-api serves on demand from the biome's convention
+   * `install-schema/` directory (`install.json` plus an optional
+   * `ui-schema.json`) via `GET /platform/biomes/server/:id/install-schema`. It
+   * is not seeded at boot and never crosses a service boundary as a
+   * contribution — the only consumer is the frontend install wizard, which
+   * pulls it over HTTP and renders it with rjsf. There is nothing for a kernel
+   * manifest schema to validate: the body is an arbitrary draft-2020-12 JSON
+   * Schema, and a parser could only pass it through verbatim to a registry
+   * that does not exist.
    */
   BiomeInstallSchema = 'biome-install-schema',
   /**
-   * RESERVED (category 3). No parser. Icon assets ship via the convention
-   * `icons/` content directory (on-disk presence seeder).
+   * RESERVED (category 3). No parser, and none is wanted: icons are BYTE
+   * ASSETS, not manifests — biome-host-api serves each one straight off disk
+   * from the biome's convention `icons/` directory via the public CDN-asset
+   * route `GET /platform/biomes/server/:id/icons/:slug.svg`, discovered by
+   * on-disk presence and never indexed. Nothing queries "which icons exist":
+   * the caller already knows the slug (it is the workflow activity kind) and
+   * builds the URL deterministically, so a third-party biome overrides an icon
+   * simply by shipping the file. Routing SVG bytes through the contribution
+   * outbox would mean base64-in-JSON into a database row only to re-serve it.
    */
   Icon = 'icon',
   /** A project-kit bundle contributed by a biome. */
   ProjectKit = 'project-kit',
   /**
-   * RESERVED (category 3). No parser. Provisioning scaffolds ship via the
-   * convention `provisioning/` content directory (declared in
-   * `xema.provisioning[]`, parity-checked at boot), not the contribution path.
+   * RESERVED (category 3). No parser: a provisioning scaffold is declared in
+   * the manifest's `xema.provisioning[]` and authored as
+   * `provisioning/<id>.yaml` plus an optional `provisioning/<id>/` template
+   * tree, and agent-session-api's `provisioning-plan-resolver` PULLS it over
+   * HTTP per session bootstrap from biome-host-api's
+   * `GET /platform/biomes/server/:id/provisioning-scaffolds`. The render
+   * depends on that session's runtime `customConfig`, so there is no static
+   * descriptor to upsert into a registry, and agent-session-api has no
+   * contribution-sync seam. NOTE the declaration-vs-disk parity check is LAZY,
+   * not boot-time: it runs inside `loadProvisioningScaffolds` when the
+   * scaffolds are fetched, so a biome whose `provisioning[]` disagrees with its
+   * `provisioning/` directory boots green and fails at first provision.
    */
   ProvisioningScaffold = 'provisioning-scaffold',
-  /**
-   * RESERVED (category 3). No ingestion path today — no parser, no
-   * content-directory seeder, no domain-service handler.
-   */
-  WorkspaceSpecOverlay = 'workspace-spec-overlay',
-  /**
-   * RESERVED (category 3). No ingestion path today — no parser, no
-   * content-directory seeder, no domain-service handler.
-   */
-  SystemOverlayContribution = 'system-overlay-contribution',
   /** A concrete connector provider contributed by a biome inside an
    * adapter kind. */
   ConnectorAdapter = 'connector-adapter',
@@ -156,29 +201,88 @@ export enum ContributionKind {
   DeliverableSpec = 'deliverable-spec',
   /** A workspace manifest contributed by a biome. */
   WorkspaceManifest = 'workspace-manifest',
-  /**
-   * RESERVED (category 3). No parser (distinct from `WorkspaceManifest`, which
-   * HAS one). Reusable workspace-manifest templates ship via the convention
-   * `workspaceManifestTemplates/` content directory (on-disk presence seeder).
-   */
-  WorkspaceManifestTemplate = 'workspace-manifest-template',
+  // `WorkspaceManifestTemplate = 'workspace-manifest-template'` was DELETED
+  // here. It claimed delivery through a `workspace-manifest-templates/`
+  // convention directory that NOTHING reads — no seeder, no endpoint, and no
+  // `walkContent` call for that kind exists anywhere. The manifest templates a
+  // workspace actually renders (`spec.seedFiles[].template`) are resolved at
+  // compose time by `buildSkillBundleTemplateResolver` from SKILL BUNDLE
+  // resources at `assets/templates/<name>.hbs`, fetched from
+  // skill-registry-api — i.e. they ship as `AgentSkill`, which HAS a parser and
+  // a route. Re-adding a second delivery path for the same artifact would fork
+  // ownership away from skill-registry (bundle fetch, 5-tier scope ladder,
+  // shared Handlebars compile) for no gain.
   /** A tool-profile contributed by a biome. */
   ToolProfile = 'tool-profile',
-  /** An MCP catalog entry contributed by a biome. Distinct from `McpTool`,
-   * which is a single tool descriptor; an `McpCatalog` entry is a catalog
-   * manifest. */
+  /** An MCP catalog entry contributed by a biome — a catalog manifest naming a
+   * connectable MCP service and the tools it exposes. This is the ONLY
+   * enum-dispatched MCP contribution path. */
   McpCatalog = 'mcp-catalog',
   /**
-   * RESERVED (category 3). No contribution-protocol parser. Agent-runtime
-   * custom tools ship via the convention `openCodeTools/` content directory,
-   * baked into the opencode-worker image at build time — not the
-   * enum-dispatched contribution path.
+   * RESERVED (category 3). No parser, and one CANNOT be shipped without first
+   * closing the build-time gap tracked as H10 in
+   * `.claude/plans/canopy-universal-agent.md` §11.1, which carries the full,
+   * component-by-component write-down of what a runtime path would require;
+   * this note is the summary. Agent-runtime custom tools are EXECUTABLE
+   * `.ts`/`.js` files that reach an agent ONLY by being copied into the
+   * agent-runtime worker image at build time — every kernel biome that ships a
+   * tools directory has its own explicit `COPY` line in that image's
+   * Dockerfile, landing the files in the runtime's tool slot, which the runtime
+   * auto-discovers when its process starts. So a third-party biome tool costs a
+   * Dockerfile edit plus an image rebuild. The one runtime seam that exists is
+   * a WHOLE-DIRECTORY swap, not a merge: when the templates read-only volume is
+   * mounted, workspace-proxy deletes the image-baked tool directory and
+   * symlinks that volume's copy in its place — and the volume is populated
+   * entirely out of band.
+   *
+   * Do NOT ship a parser that fakes the missing half. A real runtime path needs
+   * FOUR things, none of which exists:
+   *   1. An owning registry that stores tool SOURCE and can be reconciled by
+   *      the contribution outbox. It cannot be a plain descriptor table: the
+   *      payload is code, so the store has to carry the bytes AND the trust
+   *      decision (signature verification + static analysis — the pipeline
+   *      `biome-fetcher-api` already runs for biome bundles), not just a row.
+   *   2. Materialization in the workspace composer, which starts with a new
+   *      `WorkspaceMount` slot: that enum is CLOSED and has no tools entry, and
+   *      workspace-proxy rejects a mount whose slot is not in it. The composer
+   *      (`@xemahq/agent-session-runtime`) already writes the skill-bundle and
+   *      slash-command slots the same way; a tools slot additionally needs
+   *      biome-NAMESPACED filenames (two biomes must not collide on a tool
+   *      name) that stay FLAT — the runtime's discovery glob is one level deep,
+   *      so a nested directory is invisible — and it must compose with, not be
+   *      clobbered by, the templates-volume symlink above.
+   *   3. A per-session tool allow/deny decision. Filtering is static today,
+   *      baked into the image's runtime config, so a dynamically mounted tool
+   *      has no visibility story.
+   *   4. Sandboxing/permission review, because a contributed tool executes in
+   *      the agent's workspace with the agent's credentials.
+   *
+   * Timing is the one part already solved: discovery runs once per runtime
+   * PROCESS, and workspace-proxy already restarts that process after every
+   * session-bundle apply.
    */
   OpenCodeTool = 'opencode-tool',
   /**
-   * RESERVED (category 3). No parser — the contribution-registrar explicitly
-   * does NOT route this kind. Agent-runtime plugins ship via the convention
-   * `openCodePlugins/` content directory, baked into the opencode-worker image.
+   * RESERVED (category 3). No parser, and the contribution-registrar
+   * deliberately does NOT route this kind — its own unit test uses this member
+   * as the canonical "not routed" fixture. Plugins are baked harder than tools:
+   * a kernel biome's plugin directory is installed under a read-only `/opt`
+   * prefix during the image build, with its dependency tree resolved there, and
+   * the generated runtime config references it by ABSOLUTE IMAGE PATH. That
+   * `/opt` location is load-bearing — plugins once lived under the workspace
+   * root, where the per-session volume mount SHADOWED them and both shipped
+   * plugins silently failed to load.
+   *
+   * On top of the four prerequisites listed on
+   * {@link ContributionKind.OpenCodeTool}, a runtime plugin path additionally
+   * needs (a) the plugin list in the generated runtime config to become
+   * per-session paths instead of image constants, (b) a dependency story, since
+   * a plugin's dependencies are installed at image-build time and the runtime
+   * workspace has neither an install step nor network egress for one, and (c) a
+   * process restart, because the runtime resolves plugins once at process
+   * start. Until all of that lands, treat plugins as an image concern — tools
+   * are the cheaper half to make runtime-loadable first. See
+   * `.claude/plans/canopy-universal-agent.md` §11.1.
    */
   OpenCodePlugin = 'opencode-plugin',
   // -- Capability self-registration ------------------------------------------

package/src/distribution/index.ts

@@ -3,3 +3,4 @@ export * from './lib/distribution-selector';
 export * from './lib/distribution';
 export * from './lib/distribution-lock';
 export * from './lib/image-lock';
+export * from './lib/first-party-capability-domains';

package/src/distribution/lib/distribution-lock.ts

@@ -9,6 +9,7 @@ import {
   type BiomeOrigin,
   type BiomeAudience,
 } from '../../biome';
+import { CapabilityDomainSchema } from '../../capability';
 import {
   PlatformServiceTierSchema,
   type PlatformServiceTier,
@@ -164,10 +165,44 @@ export const LockedPlatformServiceSchema = z.object({
  * kernel (kernel contracts hold no clock); both optional so the type is usable
  * mid-resolution.
  */
+/**
+ * One platform-reserved capability domain and the biome that owns it.
+ *
+ * Resolved from the FULL biome index the release pipeline discovered — NOT
+ * from `DistributionLock.biomes`. A reservation is a statement about who
+ * AUTHORED the domain, so it holds in every edition whether or not that
+ * edition preloads the owning biome. See `first-party-capability-domains.ts`
+ * for why per-edition ownership would be a fail-open hole.
+ */
+export interface CapabilityDomainOwner {
+  /** The `<domain>` segment of a `CapabilityRef`. */
+  domain: string;
+  /** `xema.id` of the biome whose manifest claims it. */
+  biomeId: string;
+}
+
+export const CapabilityDomainOwnerSchema = z
+  .object({
+    domain: CapabilityDomainSchema,
+    biomeId: z.string().min(1),
+  })
+  .strict() as z.ZodType<CapabilityDomainOwner>;
+
 export interface DistributionLock {
   schemaVersion: 1;
   distributionId: string;
   biomes: readonly LockedBiome[];
+  /**
+   * Platform-reserved capability domains — the input `capability-registry-api`
+   * derives its org-provider-binding shadow refusal from, and the router its
+   * third-party authority-effect rule.
+   *
+   * REQUIRED, deliberately. An absent or empty table means "no domain is
+   * first-party", which is fail-OPEN: every platform ref would become
+   * org-bindable. A lock that predates this field must therefore fail to parse
+   * rather than silently disarm the guard.
+   */
+  capabilityDomainOwners: readonly CapabilityDomainOwner[];
   /** Non-biome substrate services that ship with this distribution (the deploy "init system"). */
   platformServices: readonly LockedPlatformService[];
   /** ISO-8601 timestamp the resolver stamped (tooling-supplied). */
@@ -180,6 +215,7 @@ export const DistributionLockSchema = z.object({
   schemaVersion: z.literal(1),
   distributionId: z.string().min(1),
   biomes: z.array(LockedBiomeSchema).readonly(),
+  capabilityDomainOwners: z.array(CapabilityDomainOwnerSchema).readonly(),
   platformServices: z.array(LockedPlatformServiceSchema).readonly(),
   resolvedAt: z.string().min(1).optional(),
   inputHash: z.string().min(1).optional(),

package/src/distribution/lib/first-party-capability-domains.ts

@@ -0,0 +1,166 @@
+import {
+  capabilityDomainOf,
+  isCapabilityDomain,
+  type CapabilityDomain,
+} from '../../capability';
+import type { DistributionLock } from './distribution-lock';
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * First-party capability domains — DERIVED from the distribution lock
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * A capability ref is `<domain>:<resource>.<verb>@<major>`. A DOMAIN is
+ * "first-party" when an in-the-box platform biome owns every ref under it.
+ *
+ * WHY THIS MATTERS (the security job):
+ *
+ *   `capability-registry-api` REFUSES an org `CapabilityProviderBinding` whose
+ *   ref domain is first-party. Without that refusal an org admin could bind
+ *   `kb:page.read@1` — or `web:page.fetch@1` — to a URL they control and
+ *   silently shadow the platform data plane for every user, agent and app in
+ *   the org. The router is data-driven off the invocation binding, so a
+ *   shadowing binding is a live redirect, not a theoretical one.
+ *
+ * WHY THE DISTRIBUTION LOCK IS THE RIGHT SOURCE, AND THE OTHER TWO WERE NOT:
+ *
+ *   • NOT `exposesCapabilities` on a live manifest — that is SELF-DECLARED at
+ *     install time, so a third-party biome an org admin installs could mint
+ *     itself first-party and then bind the domain it just claimed. Circular.
+ *   • NOT capability-record provenance in the registry DB — that is written by
+ *     an eventually-consistent contribution-sync retry, so a derivation from it
+ *     would report "not first-party" for a genuinely first-party domain during
+ *     the exact window (boot, resync) the refusal exists to cover. FAIL-OPEN.
+ *   • The distribution lock is neither. It is RESOLVED by the release pipeline
+ *     from a pinned checkout, COMMITTED, drift-checked in CI (`dist-check`),
+ *     vendored into the deployment as an immutable ConfigMap, and read once at
+ *     boot. Nothing an org admin can do at runtime — installing a biome from
+ *     npm/OCI/git, editing a manifest, publishing a contribution — changes it.
+ *     Membership is a PLATFORM-AUTHOR decision, exactly as it should be.
+ *
+ * ── OWNERSHIP IS RESERVATION-WIDE, NOT PER-EDITION ─────────────────────────
+ *
+ * `DistributionLock.capabilityDomainOwners` is resolved from the FULL biome
+ * index — every first-party biome the release pipeline discovered in its own
+ * checkout — NOT from the subset of biomes this edition happens to ship.
+ *
+ * That distinction is load-bearing. If ownership were per-edition, a trimmed
+ * edition that does not ship `knowledge-base` would leave `kb` unowned, so an
+ * org admin could install `knowledge-base` from the store and THEN bind
+ * `kb:page.read@1` to a URL they control — shadowing it for the whole org.
+ * Being authored by the platform is what makes a domain un-shadowable;
+ * whether a given edition preloads the owning biome is a packaging choice and
+ * must not change the security answer. The domains are RESERVED by the
+ * platform in every edition, shipped or not.
+ *
+ * This is also why the field is on the LOCK and not on `LockedBiome`: a
+ * reservation exists whether or not the owning biome appears in `biomes[]`.
+ *
+ * COLLISIONS FAIL FAST. Two biomes claiming the same domain is a packaging
+ * error that would make ownership ambiguous, so this class throws rather than
+ * picking a winner. The distribution resolver runs the same check before it
+ * writes, so the failure surfaces at build time; the boot-time throw is the
+ * backstop.
+ *
+ * UNDECIDABLE INPUT IS FIRST-PARTY, NOT THIRD-PARTY. `has()` on a string that
+ * is not a syntactically valid domain returns `true` (⇒ refuse the binding).
+ * A guard must never treat "I could not parse this" as "safe to shadow".
+ */
+export class FirstPartyCapabilityDomains {
+  private constructor(
+    private readonly owners: ReadonlyMap<CapabilityDomain, string>,
+  ) {}
+
+  /**
+   * Build the ownership index from a parsed distribution lock's
+   * `capabilityDomainOwners` reservation table.
+   *
+   * @throws when two biomes claim the same domain, or when a claimed value is
+   * not a syntactically valid capability domain. Both are packaging errors;
+   * neither may be tolerated silently in a security guard's input.
+   */
+  static fromDistributionLock(
+    lock: DistributionLock,
+  ): FirstPartyCapabilityDomains {
+    return FirstPartyCapabilityDomains.fromOwnerEntries(
+      lock.capabilityDomainOwners.map(
+        (owner) => [owner.domain, owner.biomeId] as const,
+      ),
+      `Distribution "${lock.distributionId}"`,
+    );
+  }
+
+  /**
+   * Build the ownership index directly from `(domain → owning biome id)` pairs.
+   * For consumers that receive the ownership projection over the wire instead
+   * of reading the lock file themselves. Same validation, same collision rule.
+   */
+  static fromOwnerEntries(
+    entries: Iterable<readonly [string, string]>,
+    sourceLabel: string,
+  ): FirstPartyCapabilityDomains {
+    const owners = new Map<CapabilityDomain, string>();
+    for (const [claimed, biomeId] of entries) {
+      if (!isCapabilityDomain(claimed)) {
+        throw new Error(
+          `${sourceLabel}: "${claimed}" is not a valid capability domain (^[a-z][a-z0-9-]*$).`,
+        );
+      }
+      const incumbent = owners.get(claimed);
+      if (incumbent !== undefined && incumbent !== biomeId) {
+        throw new Error(
+          `${sourceLabel}: capability domain "${claimed}" is claimed by BOTH "${incumbent}" and "${biomeId}". ` +
+            'A domain has exactly one owner — ownership decides whether an org may bind refs in it, ' +
+            'so an ambiguous claim is refused rather than resolved to a winner.',
+        );
+      }
+      owners.set(claimed, biomeId);
+    }
+    return new FirstPartyCapabilityDomains(owners);
+  }
+
+  /**
+   * `true` iff `domain` is owned by a biome in the active distribution — or if
+   * `domain` is not a parseable domain at all (undecidable ⇒ protected).
+   */
+  has(domain: string): boolean {
+    return !isCapabilityDomain(domain) || this.owners.has(domain);
+  }
+
+  /**
+   * `true` iff the DOMAIN OF `ref` is first-party. A ref whose domain cannot be
+   * extracted is undecidable and therefore protected.
+   */
+  hasRefDomain(ref: string): boolean {
+    const domain = capabilityDomainOf(ref);
+    return domain === null || this.owners.has(domain);
+  }
+
+  /** The biome that owns `domain`, or `undefined` when nobody claims it. */
+  ownerOf(domain: string): string | undefined {
+    return this.owners.get(domain);
+  }
+
+  /** Claimed domains, sorted — for boot logs and diagnostics. */
+  get domains(): readonly CapabilityDomain[] {
+    return [...this.owners.keys()].sort();
+  }
+
+  get size(): number {
+    return this.owners.size;
+  }
+}
+
+/**
+ * Convenience wrapper — `(domain → owning biome id)` for the whole lock, with
+ * the collision + grammar checks applied. The distribution resolver calls this
+ * at build time so a bad claim fails the release, not the deployment.
+ */
+export function resolveFirstPartyCapabilityDomains(
+  lock: DistributionLock,
+): ReadonlyMap<CapabilityDomain, string> {
+  const resolved = FirstPartyCapabilityDomains.fromDistributionLock(lock);
+  return new Map(
+    resolved.domains.map((domain) => [domain, resolved.ownerOf(domain)!]),
+  );
+}