@xemahq/kernel-contracts 0.49.3 → 0.56.0

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

@@ -28,12 +28,14 @@ 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 delivery path through the convention CONTENT-DIRECTORY
+ *      seeder (on-disk presence — see the manifest reference); the four members
+ *      that had NO delivery path at all (`GateAction`, `ChartRuntime`,
+ *      `WorkspaceSpecOverlay`, `SystemOverlayContribution`) were DELETED rather
+ *      than left as decoration. 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.
  *
  * 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
@@ -66,19 +68,6 @@ export enum ContributionKind {
    */
   McpTool = 'mcp-tool',
   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 +80,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 --------------------------------------------------
   /**
@@ -135,16 +146,6 @@ export enum ContributionKind {
    * `xema.provisioning[]`, parity-checked at boot), not the contribution path.
    */
   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',

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)!]),
+  );
+}

package/src/object/lib/xema-object-ref.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
-import { SpaceRef, SpaceKind, spaceRefToPath } from '../../space';
+import {
+  parseSpaceRefScopeSegments,
+  SpaceRef,
+  SpaceRefParseError,
+  spaceRefToPath,
+} from '../../space';
 import { XemaObjectKind, XemaObjectKindSchema } from './xema-object-kind';
 
 /**
@@ -69,9 +74,26 @@ const SLUG_SEGMENT = '[a-zA-Z0-9][a-zA-Z0-9_.-]*';
 const SLUG_PATTERN = new RegExp(`^${SLUG_SEGMENT}(?:/${SLUG_SEGMENT})*$`);
 const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.+-]*$/;
 
-export interface ScopeParse {
-  scope: SpaceRef;
-  consumed: number;
+/**
+ * Consume the leading scope segments of a `xema://` object ref, re-raising any
+ * scope-grammar failure as a {@link XemaObjectRefParseError} so an object-ref
+ * caller only ever has to catch ONE error type. The scope grammar itself lives
+ * in `@xemahq/kernel-contracts/space` (`parseSpaceRefScopeSegments`) — it is a
+ * SPACE grammar, and object refs, search refs and Space refs all read it from
+ * there rather than restating it.
+ */
+function parseScope(
+  segments: string[],
+  ref: string,
+): { scope: SpaceRef; consumed: number } {
+  try {
+    return parseSpaceRefScopeSegments(segments, ref);
+  } catch (err) {
+    if (err instanceof SpaceRefParseError) {
+      throw new XemaObjectRefParseError(ref, err.message);
+    }
+    throw err;
+  }
 }
 
 function requireSegment(
@@ -87,83 +109,6 @@ function requireSegment(
   return value;
 }
 
-/**
- * Parse the leading scope segments of a `xema://` ref path into a
- * {@link SpaceRef} plus the number of segments consumed. Shared by
- * {@link parseXemaObjectRef} and the search-source `parseSearchRef` helper so
- * the `xema://<scope-path>/...` scope grammar (plural `orgs`/`projects`, the
- * same one {@link spaceRefToPath} formats) lives in exactly ONE place. The
- * caller owns whatever follows the scope (a `<kind>/<slug>` for objects, a
- * `<docType>/<sourceId>` for search refs).
- */
-export function parseObjectRefScopeSegments(
-  segments: string[],
-  ref: string,
-): ScopeParse {
-  const head = requireSegment(segments, 0, ref, 'scope');
-  switch (head) {
-    case 'system':
-      return { scope: { tier: SpaceKind.System }, consumed: 1 };
-    case 'biomes': {
-      const biomeId = requireSegment(segments, 1, ref, 'biomeId');
-      return {
-        scope: { tier: SpaceKind.Biome, biomeId },
-        consumed: 2,
-      };
-    }
-    case 'users': {
-      const userId = requireSegment(segments, 1, ref, 'userId');
-      return {
-        scope: { tier: SpaceKind.User, userId },
-        consumed: 2,
-      };
-    }
-    case 'sessions': {
-      const sessionId = requireSegment(segments, 1, ref, 'sessionId');
-      return {
-        scope: { tier: SpaceKind.Session, sessionId },
-        consumed: 2,
-      };
-    }
-    case 'orgs': {
-      const orgId = requireSegment(segments, 1, ref, 'orgId');
-      if (segments.length >= 4 && segments[2] === 'projects') {
-        const projectId = requireSegment(segments, 3, ref, 'projectId');
-        // …/projects/<p>/apps/<a> — the App tier (most specific under a project).
-        if (segments.length >= 6 && segments[4] === 'apps') {
-          const appId = requireSegment(segments, 5, ref, 'appId');
-          return {
-            scope: {
-              tier: SpaceKind.App,
-              orgId,
-              projectId,
-              appId,
-            },
-            consumed: 6,
-          };
-        }
-        return {
-          scope: {
-            tier: SpaceKind.Project,
-            orgId,
-            projectId,
-          },
-          consumed: 4,
-        };
-      }
-      return {
-        scope: { tier: SpaceKind.Org, orgId },
-        consumed: 2,
-      };
-    }
-    default:
-      throw new XemaObjectRefParseError(
-        ref,
-        `unknown scope head "${head}" (expected one of: system, biomes, orgs, users, sessions)`,
-      );
-  }
-}
-
 /**
  * Parse a `XemaObjectRef` into structured parts. Fail-fast on every
  * malformed input (no silent coercion). When the `@<version>` suffix
@@ -210,7 +155,7 @@ export function parseXemaObjectRef(ref: string): XemaObjectRefParts {
     );
   }
 
-  const { scope, consumed } = parseObjectRefScopeSegments(segments, ref);
+  const { scope, consumed } = parseScope(segments, ref);
   const remaining = segments.slice(consumed);
   if (remaining.length < 2) {
     throw new XemaObjectRefParseError(

package/src/output-surface-inspect/index.ts

@@ -1,4 +1,6 @@
 // Pure, zod-free contract — safe to bundle into the browser-side bridge.
 export * from './lib/output-surface-inspect';
+// Shared bounded console/network ring buffers (also zod-free).
+export * from './lib/buffers';
 // Runtime zod validator — pulled in by agent-session-api's broker only.
 export * from './lib/step-schema';