@xemahq/kernel-contracts 0.1.0

package/src/runner/lib/runner.ts

@@ -0,0 +1,103 @@
+import { RunnerKind } from '../../policy';
+
+/**
+ * Runner-plane contracts (plan §6 Phase F).
+ *
+ * A runner is the executor that picks up a `RunnerJobDispatch` and
+ * actually invokes the capability.
+ *
+ * Note: `RunnerKind` (the policy-routing classifier — Local / Cloud /
+ * CustomerEdge / GPU / Sandbox / CI) is owned by `@xemahq/policy-contracts`
+ * and re-exported from this package via `./runner-kind`. The execution
+ * mode (Embedded / LocalModule / Remote) lives in `./runner-registration`
+ * as `RunnerMode`.
+ */
+
+/**
+ * Trust tier assigned to a runner at attestation time (Phase F.4). The
+ * authorization-api's policy bundle MAY gate sensitive capabilities to
+ * `Trusted` or `System` tiers only.
+ *
+ * Order is intentional: each higher tier is a strict superset of the
+ * authority granted to lower tiers. Do NOT compare via string equality
+ * outside of policy code — compare via the enum.
+ */
+export enum RunnerTrustTier {
+  Untrusted = 'untrusted',
+  Verified = 'verified',
+  Trusted = 'trusted',
+  System = 'system',
+}
+
+/**
+ * Canonical ordinal rank for each {@link RunnerTrustTier}. Higher = more
+ * authority. This is the SINGLE source of trust ordering — the router's
+ * dispatch min-trust gate (Phase F.4) and the runner's per-capability
+ * min-trust gate (Phase F.7) MUST both rank through this map so a runner
+ * the router accepts is ranked identically by the executor. Do not inline a
+ * second ordering.
+ */
+export const RUNNER_TRUST_TIER_RANK: Record<RunnerTrustTier, number> = {
+  [RunnerTrustTier.Untrusted]: 0,
+  [RunnerTrustTier.Verified]: 1,
+  [RunnerTrustTier.Trusted]: 2,
+  [RunnerTrustTier.System]: 3,
+};
+
+/**
+ * True iff `actual` grants at least the authority of `minimum` (i.e. ranks
+ * equal-or-higher). Use this for every trust-tier comparison — never `===`
+ * on the enum, which would reject a strictly-higher tier.
+ */
+export function runnerTrustTierMeets(
+  actual: RunnerTrustTier,
+  minimum: RunnerTrustTier,
+): boolean {
+  return RUNNER_TRUST_TIER_RANK[actual] >= RUNNER_TRUST_TIER_RANK[minimum];
+}
+
+/** Runtime guard: is `value` a member of the closed {@link RunnerTrustTier} set? */
+export function isRunnerTrustTier(value: unknown): value is RunnerTrustTier {
+  return (
+    typeof value === 'string' &&
+    (Object.values(RunnerTrustTier) as string[]).includes(value)
+  );
+}
+
+/**
+ * Nominal string for a runner identifier. The brand is a phantom type
+ * so the value still serializes as a plain string across the wire while
+ * giving editor / TS narrowing protection against passing a random
+ * string where a `RunnerId` is expected.
+ */
+export type RunnerId = string & { readonly __brand: 'RunnerId' };
+
+/**
+ * Self-description a runner publishes at registration time. Mirrors
+ * `ServiceDescriptor` in spirit but carries runner-specific labels
+ * (data locality, region) consumed by `Policy.routeHints` (Phase F.6).
+ *
+ * For the richer Phase F.3 registration shape (mode + biome
+ * provisioning + transport) see `RunnerRegistration`.
+ */
+export interface RunnerDescriptor {
+  id: RunnerId;
+  kind: RunnerKind;
+  trustTier: RunnerTrustTier;
+  version: string;
+  /**
+   * IDs of `ExecutionEnvironment`s this runner is allowed to serve.
+   * The list is signed by the org admin via Phase F.4 attestation; a
+   * runner MUST refuse a dispatch whose `executionContext.environmentId`
+   * is not in this list.
+   */
+  allowedEnvironments: string[];
+  labels: Record<string, string>;
+  /**
+   * Data-locality classifier consumed by policy (e.g. `customer-private`,
+   * `xema-cloud`). Free-form string deliberately — the closed set of
+   * values is defined by org-level policy bundles, not the kernel.
+   */
+  dataLocality?: string;
+  region?: string;
+}

package/src/runner/lib/runtime-isolation.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+/**
+ * Coarse isolation boundary a biome runtime provides for the workloads it
+ * runs. A biome manifest declares the isolation levels it ACCEPTS (via
+ * `runtimeRequirements.isolation.allowed`); a runtime/runner advertises the
+ * isolation level it PROVIDES. The scheduler matches the two — a runtime
+ * whose isolation is not in the biome's allowed set is ineligible.
+ *
+ * This is the *runtime placement* concern (where/how strongly a biome's
+ * workload is isolated), DISTINCT from `RunnerMode` (embedded vs local
+ * sidecar vs remote — how the biome is provisioned onto a runner). A
+ * `local-module` biome may run at `process` isolation today and `container`
+ * isolation on a hardened runner tomorrow without changing its mode.
+ *
+ * Closed set on purpose — adding a level is a coordinated kernel change so
+ * producer (manifest) and consumer (runtime descriptor) stay in lockstep.
+ * Ordered weakest → strongest for callers that gate on a minimum.
+ */
+export enum RuntimeIsolationLevel {
+  /** No dedicated boundary — shares the host process (in-process module). */
+  None = 'none',
+  /** A separate OS process on a shared host. */
+  Process = 'process',
+  /** A container (namespaced filesystem/network/cgroups). */
+  Container = 'container',
+  /** A virtual machine / micro-VM (hardware-virtualized boundary). */
+  Vm = 'vm',
+}
+
+export const RuntimeIsolationLevelSchema = z.nativeEnum(RuntimeIsolationLevel);
+
+/**
+ * Weakest → strongest ordering used by `runtimeIsolationMeets`. Index is
+ * the rank; a higher rank is a stronger boundary.
+ */
+const ISOLATION_RANK: readonly RuntimeIsolationLevel[] = [
+  RuntimeIsolationLevel.None,
+  RuntimeIsolationLevel.Process,
+  RuntimeIsolationLevel.Container,
+  RuntimeIsolationLevel.Vm,
+];
+
+/**
+ * True when `actual` provides at least as strong a boundary as `minimum`.
+ * Mirrors `runnerTrustTierMeets` so a single ranking governs every gate.
+ */
+export function runtimeIsolationMeets(
+  actual: RuntimeIsolationLevel,
+  minimum: RuntimeIsolationLevel,
+): boolean {
+  return ISOLATION_RANK.indexOf(actual) >= ISOLATION_RANK.indexOf(minimum);
+}

package/src/search-source/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/indexable-document';
+export * from './lib/search-index-event';
+export * from './lib/search-source-descriptor';
+export * from './lib/search-replay';

package/src/search-source/lib/indexable-document.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+
+/**
+ * The canonical, source-AGNOSTIC indexable document. A searchable biome
+ * projects its own domain entity into this shape (producer-side) so that
+ * search-api can index it WITHOUT importing the biome's client or knowing its
+ * entity schema.
+ *
+ * Server-owned fields (vector embedding, chunk index, parent-doc linkage) are
+ * NOT part of this contract — search computes them from `content`. The producer
+ * supplies identity, scope, and the human/searchable text only.
+ *
+ * `sourceKey` + `docType` + `sourceId` is the stable natural key: re-emitting
+ * the same triple is an idempotent upsert.
+ */
+export interface IndexableDocument {
+  /** Registered source that produced this document (e.g. `knowledge-base`). */
+  readonly sourceKey: string;
+  /** Entity kind within the source (e.g. `kb_page`, `backlog_item`). Open taxonomy owned by search. */
+  readonly docType: string;
+  /** The source's stable primary key for this entity. */
+  readonly sourceId: string;
+  /** Tenant scope. Search re-derives/validates this from the event envelope — the producer copy is advisory. */
+  readonly orgId: string;
+  /** Project scope, when applicable. */
+  readonly projectId?: string;
+  readonly title?: string;
+  readonly summary?: string;
+  /** Full searchable text. */
+  readonly content?: string;
+  /** Code text (separate analyzer), when applicable. */
+  readonly code?: string;
+  readonly tags?: readonly string[];
+  readonly status?: string;
+  readonly phase?: string;
+  readonly priority?: string;
+  readonly createdBy?: string;
+  /** ISO-8601 timestamp. */
+  readonly createdAt?: string;
+  /** ISO-8601 timestamp. */
+  readonly updatedAt?: string;
+  /** Free-form per-source metadata carried verbatim onto the index document. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Wire schema for {@link IndexableDocument}. search-api validates every consumed
+ * upsert against this and dead-letters on failure — no silent thin-index.
+ */
+export const IndexableDocumentSchema = z
+  .object({
+    sourceKey: z.string().min(1),
+    docType: z.string().min(1),
+    sourceId: z.string().min(1),
+    orgId: z.string().min(1),
+    projectId: z.string().min(1).optional(),
+    title: z.string().optional(),
+    summary: z.string().optional(),
+    content: z.string().optional(),
+    code: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    status: z.string().optional(),
+    phase: z.string().optional(),
+    priority: z.string().optional(),
+    createdBy: z.string().optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();

package/src/search-source/lib/search-index-event.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+import { IndexableDocumentSchema, type IndexableDocument } from './indexable-document';
+
+/**
+ * Canonical search-index change operation. Closed set.
+ */
+export enum SearchIndexOp {
+  Upsert = 'upsert',
+  Delete = 'delete',
+}
+
+/**
+ * The TWO canonical event types search-api subscribes to. EVERY searchable
+ * biome projects its domain events into one of these (producer-side) and emits
+ * it on the generic event bus. search-api subscribes to exactly these two and
+ * nothing else — so a NEW searchable biome requires ZERO search-api changes.
+ */
+export const SEARCH_INDEX_UPSERT_EVENT_TYPE = 'search.index.upsert' as const;
+export const SEARCH_INDEX_DELETE_EVENT_TYPE = 'search.index.delete' as const;
+
+/** Upsert: the full canonical document to (re)index. */
+export interface SearchIndexUpsert {
+  readonly op: SearchIndexOp.Upsert;
+  readonly document: IndexableDocument;
+}
+
+/** Delete: drop the identified document (or whole source scope) from the index. */
+export interface SearchIndexDelete {
+  readonly op: SearchIndexOp.Delete;
+  readonly sourceKey: string;
+  readonly docType: string;
+  readonly sourceId: string;
+  readonly orgId: string;
+  readonly projectId?: string;
+}
+
+export type SearchIndexChange = SearchIndexUpsert | SearchIndexDelete;
+
+export const SearchIndexUpsertSchema = z
+  .object({
+    op: z.literal(SearchIndexOp.Upsert),
+    document: IndexableDocumentSchema,
+  })
+  .strict();
+
+export const SearchIndexDeleteSchema = z
+  .object({
+    op: z.literal(SearchIndexOp.Delete),
+    sourceKey: z.string().min(1),
+    docType: z.string().min(1),
+    sourceId: z.string().min(1),
+    orgId: z.string().min(1),
+    projectId: z.string().min(1).optional(),
+  })
+  .strict();

package/src/search-source/lib/search-replay.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+
+import { IndexableDocumentSchema, type IndexableDocument } from './indexable-document';
+
+/**
+ * The `<resource>.<verb>` segment every source-replay capability ref carries.
+ * search-api discovers backfill-capable sources by listing capability-registry
+ * and matching refs of shape `<sourceKey>:search.replay@<major>` — so it never
+ * imports a source client and a new source becomes reindexable simply by
+ * registering its capability.
+ */
+export const SEARCH_REPLAY_CAPABILITY_KIND = 'search.replay' as const;
+
+/**
+ * Major version of the replay capability contract. Bumped only on a breaking
+ * change to the {@link SearchReplayRequest} / {@link SearchReplayResponse}
+ * wire shape.
+ */
+export const SEARCH_REPLAY_CAPABILITY_MAJOR = 1 as const;
+
+/**
+ * Canonical capability ref for a source's replay endpoint. Convention:
+ * `<sourceKey>:search.replay@<major>`. This is a FULL kernel CapabilityRef
+ * (`<domain>:<resource>.<verb>@<major>`) — the source key is the domain — so
+ * it registers in capability-registry, resolves in the capability-router, and
+ * invokes through the gateway like any other capability. Deterministic +
+ * auditable: derivable from the sourceKey alone, so the registry and the
+ * descriptor never drift.
+ */
+export function searchReplayCapabilityRef(sourceKey: string): string {
+  return `${sourceKey}:${SEARCH_REPLAY_CAPABILITY_KIND}@${SEARCH_REPLAY_CAPABILITY_MAJOR}`;
+}
+
+/**
+ * Matches any source's replay capability ref (`<sourceKey>:search.replay@<n>`).
+ * The `<sourceKey>` capture is the domain segment of the kernel CapabilityRef
+ * grammar (kebab, must start with a letter).
+ */
+const SEARCH_REPLAY_REF_REGEX = /^([a-z][a-z0-9-]*):search\.replay@(\d+)$/;
+
+/**
+ * True when `ref` is a source-replay capability ref. search-api uses this to
+ * pick backfill-capable capabilities out of the full registry listing without
+ * knowing any specific source.
+ */
+export function isSearchReplayCapabilityRef(ref: string): boolean {
+  return SEARCH_REPLAY_REF_REGEX.test(ref);
+}
+
+/**
+ * Extract the `sourceKey` (domain segment) from a replay capability ref, or
+ * `null` when `ref` is not a replay ref. Used by the capability-router to map
+ * a replay ref to the owning source's HTTP endpoint.
+ */
+export function searchSourceKeyFromReplayRef(ref: string): string | null {
+  const match = SEARCH_REPLAY_REF_REGEX.exec(ref);
+  return match?.[1] ?? null;
+}
+
+/**
+ * Backfill request search sends to a source's replay capability (via
+ * capability-router — NOT a direct client call). Paginated so a large source
+ * drains in bounded batches.
+ */
+export interface SearchReplayRequest {
+  readonly orgId?: string;
+  readonly projectId?: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+/**
+ * Backfill response: a page of canonical documents plus an opaque cursor for
+ * the next page (absent = drained). The source re-projects its current rows
+ * through the SAME projection used on the hot path.
+ */
+export interface SearchReplayResponse {
+  readonly documents: readonly IndexableDocument[];
+  readonly nextCursor?: string;
+}
+
+export const SearchReplayRequestSchema = z
+  .object({
+    orgId: z.string().min(1).optional(),
+    projectId: z.string().min(1).optional(),
+    cursor: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(1000).optional(),
+  })
+  .strict();
+
+export const SearchReplayResponseSchema = z
+  .object({
+    documents: z.array(IndexableDocumentSchema),
+    nextCursor: z.string().min(1).optional(),
+  })
+  .strict();

package/src/search-source/lib/search-source-descriptor.ts

@@ -0,0 +1,50 @@
+import type { SearchIndexChange } from './search-index-event';
+
+/**
+ * Producer-side declaration that makes a biome SEARCHABLE. The biome owns this
+ * descriptor; search-api NEVER imports it. It is used in two places, both on
+ * the SOURCE side:
+ *
+ *   1. At emit time — a shared producer helper runs `project()` on each of the
+ *      source's own domain events and emits the resulting canonical
+ *      `search.index.upsert` / `search.index.delete` event on the bus.
+ *   2. At backfill time — the source's `replay` capability (if declared)
+ *      re-projects its current rows into the same canonical events.
+ *
+ * Because the projection runs on the producer (which already owns the entity
+ * schema), search-api consumes only the canonical change events and imports no
+ * source client. A new searchable biome adds a descriptor + emits the canonical
+ * events; search-api is untouched.
+ *
+ * @typeParam TEvent the union of the source's own domain event payloads
+ */
+export interface SearchSourceDescriptor<TEvent = unknown> {
+  /** Stable identifier of this source (e.g. `knowledge-base`, `design-system-builder`). */
+  readonly sourceKey: string;
+  /** Human label for ops/registry surfaces. */
+  readonly displayName: string;
+  /** The `docType`(s) this source emits — the open taxonomy entries search will see. */
+  readonly docTypes: readonly string[];
+  /** Source domain event types that drive (re)indexing vs deletion. */
+  readonly events: {
+    readonly indexed: readonly string[];
+    readonly deleted?: readonly string[];
+  };
+  /**
+   * Project ONE of the source's domain events into a canonical change, or
+   * `null` to skip (e.g. an event the source listed but that carries nothing
+   * indexable yet). Runs PRODUCER-side. MUST be deterministic and free of
+   * silent fallbacks — return `null` only for a genuine, intended skip.
+   */
+  project(eventType: string, data: TEvent): SearchIndexChange | null;
+  /**
+   * Optional backfill/reindex support. When present, the source exposes a
+   * capability (ref = {@link searchReplayCapabilityRef}) that re-emits the
+   * canonical events for its current rows. ABSENT means this source does not
+   * support full reindex — search treats that as an explicit, declared
+   * limitation (no silent fallback to a stale or partial index).
+   */
+  readonly replay?: {
+    readonly capabilityRef: string;
+  };
+}

package/src/service-registry/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/service-descriptor';
+export * from './lib/service-registry-client';
+export * from './lib/inject-service';

package/src/service-registry/lib/inject-service.ts

@@ -0,0 +1,25 @@
+/**
+ * Declarative contract referenced by the `@xemahq/service-registry-nest`
+ * SDK's `@InjectService(name)` decorator. Lives in the kernel-leaf so
+ * any package can describe an injection point without importing NestJS.
+ *
+ * The runtime decorator itself (which reads / attaches this metadata via
+ * `reflect-metadata`) belongs in the SDK package — kernel leaves never
+ * carry NestJS or `reflect-metadata` runtime deps.
+ *
+ * The literal string in `kind` doubles as the metadata key used by the
+ * SDK's `Reflector.get(...)`; bumping it is a breaking change.
+ */
+export interface InjectServiceMetadata<T extends string = string> {
+  kind: 'xema/inject-service';
+  service: T;
+}
+
+/**
+ * Metadata key under which `InjectServiceMetadata` is stamped on a
+ * parameter / property by the SDK decorator. Exposed as a `const`
+ * (not just a TS type) so tooling that scans `reflect-metadata` (e.g.
+ * boundary-check scripts) can reference it without hard-coding the
+ * string.
+ */
+export const INJECT_SERVICE_METADATA_KEY = 'xema/inject-service' as const;

package/src/service-registry/lib/service-descriptor.ts

@@ -0,0 +1,75 @@
+/**
+ * Service Registry contracts (plan §6 Phase B.1).
+ *
+ * The Service Registry is the kernel primitive that replaces the
+ * `*_API_URL` env-var hellscape. Every NestJS app at boot registers a
+ * `ServiceDescriptor` keyed under `/xema/services/<name>/<instanceId>/`
+ * in KernelState; consumers `resolve()` or `watch()` instead of reading
+ * env vars. The Kernel state grammar enum lives in
+ * `@xemahq/kernel-state-contracts`.
+ *
+ * These contracts are pure TS — no runtime deps, no NestJS imports.
+ */
+
+/**
+ * Transport protocols a Xema service may expose. Closed set: adding a new
+ * transport is an explicit enum change so consumers cannot silently match
+ * an unknown one.
+ */
+export enum ServiceEndpointProtocol {
+  Http = 'http',
+  Grpc = 'grpc',
+  EventHub = 'event-hub',
+  Mcp = 'mcp',
+}
+
+/**
+ * Authentication mode a caller must use against a given endpoint. Closed
+ * set; an endpoint that has no auth requirement MUST set `auth: 'none'`
+ * explicitly — `undefined` is reserved for "auth metadata not declared"
+ * and downstream resolvers MUST refuse to call such an endpoint.
+ */
+export enum ServiceEndpointAuth {
+  ServiceToken = 'service-token',
+  Mtls = 'mtls',
+  None = 'none',
+}
+
+/**
+ * Single network endpoint declared by a service. A service MAY expose
+ * multiple endpoints (e.g. HTTP for control-plane + MCP for tool calls).
+ */
+export interface ServiceEndpoint {
+  protocol: ServiceEndpointProtocol;
+  url: string;
+  auth?: ServiceEndpointAuth;
+}
+
+/**
+ * Self-description a service writes to the registry at boot. The shape is
+ * deliberately flat so it round-trips losslessly through KernelState
+ * (SQLite or etcd) as a JSON blob.
+ *
+ * Invariants (consumers MUST fail-fast on violation):
+ * - `name` is the canonical service slug (matches `package.json#name`
+ *   stripped of scope, e.g. `llm-registry-api`).
+ * - `semver` matches the published service version, not the kernel
+ *   schema version.
+ * - `instanceId` is the per-replica identifier; the same `name` MAY have
+ *   N concurrent `instanceId`s under horizontal scaling.
+ * - `endpoints` is non-empty; a service with no endpoints cannot be
+ *   resolved and must not register.
+ * - `exposesCapabilities` / `requiresServices` carry only canonical
+ *   refs / service names — no env-var URLs.
+ */
+export interface ServiceDescriptor {
+  name: string;
+  semver: string;
+  instanceId: string;
+  endpoints: ServiceEndpoint[];
+  exposesCapabilities: string[];
+  requiresServices: string[];
+  healthEndpoint?: string;
+  region?: string;
+  labels?: Record<string, string>;
+}

package/src/service-registry/lib/service-registry-client.ts

@@ -0,0 +1,107 @@
+import type { ServiceDescriptor, ServiceEndpoint } from './service-descriptor';
+
+/**
+ * Lease granted by the registry on `register` / `renew`. The lease is the
+ * sole proof-of-liveness — if a service stops renewing, its descriptor is
+ * GC'd and `resolve()` will stop returning it. There is NO secondary
+ * heartbeat channel.
+ */
+export interface ServiceLease {
+  leaseId: string;
+  instanceId: string;
+  name: string;
+  /**
+   * Absolute UTC timestamp (ISO-8601) at which the lease expires unless
+   * renewed. Consumers MUST renew before this instant.
+   */
+  expiresAt: string;
+  /**
+   * Time-to-live in seconds as granted by the registry. May be shorter
+   * than the value the caller requested; the registry has authority to
+   * cap.
+   */
+  ttlSeconds: number;
+}
+
+/**
+ * Descriptor plus resolved endpoint(s) returned by `resolve` / `watch`.
+ * Selection between multiple endpoints (e.g. HTTP vs MCP) is the
+ * consumer's responsibility — the registry returns the full set.
+ */
+export interface ResolvedService {
+  name: string;
+  instanceId: string;
+  semver: string;
+  endpoints: ServiceEndpoint[];
+  /**
+   * The full original descriptor. Carried so callers performing
+   * capability-aware routing don't need a second lookup.
+   */
+  descriptor: ServiceDescriptor;
+  /**
+   * Absolute UTC timestamp at which the underlying lease expires. A
+   * consumer cache SHOULD evict on or before this instant.
+   */
+  leaseExpiresAt: string;
+}
+
+/**
+ * Optional filters applied at resolution time. Filters AND together;
+ * a service must match every populated filter to be returned.
+ */
+export interface ResolveOptions {
+  region?: string;
+  /**
+   * Subset of labels that the resolved service's `descriptor.labels`
+   * MUST contain (string equality on each key).
+   */
+  labels?: Record<string, string>;
+  /**
+   * If set, only return services whose `exposesCapabilities` contains
+   * every entry. Empty array is treated as "no constraint".
+   */
+  requiredCapabilities?: string[];
+  /**
+   * Semver range the resolved service's `semver` must satisfy. The
+   * registry implementation is responsible for parsing the range —
+   * this contract carries it through opaquely as a string.
+   */
+  semverRange?: string;
+}
+
+/**
+ * Kernel-leaf interface every Service Registry adapter implements
+ * (SQLite-backed in dev / single-instance, etcd-backed in cluster).
+ *
+ * Implementations MUST:
+ * - throw on register if `descriptor.endpoints` is empty.
+ * - throw on renew if the lease is unknown / already expired (fail-fast,
+ *   no silent re-register).
+ * - return an empty array (not throw) from `resolve` when no instance
+ *   matches — "no providers" is a valid state callers must handle.
+ * - call the `watch` callback synchronously on subscribe with the
+ *   current set, then again on every change. The returned function
+ *   detaches the subscription.
+ */
+export interface ServiceRegistry {
+  register(descriptor: ServiceDescriptor): Promise<ServiceLease>;
+  renew(leaseId: string): Promise<ServiceLease>;
+  resolve(name: string, opts?: ResolveOptions): Promise<ResolvedService>;
+  watch(
+    name: string,
+    cb: (services: ResolvedService[]) => void,
+  ): () => void;
+  /**
+   * Enumerate EVERY current registration across all service names — one
+   * {@link ResolvedService} entry per live instance. Unlike {@link resolve}
+   * (single name, fail-fast on miss), this is the full-mesh read used by
+   * operator/topology surfaces.
+   *
+   * Implementations MUST reflect the registry the process is connected to
+   * — the shared cluster registry (etcd) for the KernelState adapter, the
+   * in-process map for the dev adapter — NOT merely the caller's own
+   * registration. An empty registry returns an empty array (it does NOT
+   * throw); a registry-unavailable condition propagates (fail-fast).
+   */
+  list(): Promise<ResolvedService[]>;
+}

package/src/skill/index.ts

@@ -0,0 +1,15 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for the Skill primitive. Pure types + closed
+// enums — zero runtime deps, no NestJS, no Prisma. Shared between
+// skill-registry-api, the workspace composer, deliverable-specs-api (for
+// the deliverable-skill projection) and the frontend Agent Studio.
+//
+// A Skill is a folder bundle whose only strict part is SKILL.md.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/skill-enums';
+export * from './lib/skill-governance';
+export * from './lib/skill-source';
+export * from './lib/skill';