@xemahq/kernel-contracts 0.1.0

package/src/workflow/lib/activity-outputs.ts

@@ -0,0 +1,105 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── ActivityOutputs — the unified envelope shape every activity returns ──
+//
+// Under the unified model, every activity's Temporal return value has
+// the same outer shape:
+//
+//   {
+//     outcome: string,             // orchestration flag — fail-fast values
+//     durationMs: number,          // wall-clock execution time
+//     outputs: { name: ArtifactRef | ArtifactRef[] | null },
+//     ...activity-specific orchestration metadata,
+//   }
+//
+// `outputs` is the named, typed bag of artifacts the activity produced.
+// Each entry is either a single `ArtifactRef`, an array (variadic, for
+// activities like `agent` that emit N deliverables), or `null` (the
+// output was conditionally absent).
+//
+// Activity authors do NOT construct ArtifactRefs themselves. They pass
+// content + type to the `finalizeOutputs` helper (in
+// `biomes/workflow-runtime/api/workflow-runtime-worker/src/activities/shared/finalize-outputs.ts`)
+// which promotes content to artifacts via `workflow-artifact-emitter` and
+// replaces the values with refs.
+//
+// Orchestration metadata (worker IDs, allocation status, page IDs, repo
+// SHAs, etc.) stays on the envelope alongside `outputs`. The discipline
+// is: anything reviewable goes in `outputs`; bookkeeping for `if:`
+// clauses and gate logic stays at the top level.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ArtifactRef } from './artifact-ref';
+
+/**
+ * The named-outputs bag. Each value is one of:
+ *   • `ArtifactRef` — a single artifact
+ *   • `readonly ArtifactRef[]` — variadic / array outputs (e.g. harvested
+ *     deliverables, multiple endpoint fetches)
+ *   • `null` — the output was conditionally absent at this run (e.g. the
+ *     agent produced no structured payload). Distinguish from "missing
+ *     key" — declared-but-null is a deliberate signal.
+ *
+ * Generic over the output-key map so per-activity envelopes can have
+ * typed access (`AgentActivityOutput['outputs']['response']` resolves to
+ * `ArtifactRef` precisely).
+ */
+export type ActivityOutputsMap = Readonly<
+  Record<string, ArtifactRef | readonly ArtifactRef[] | null>
+>;
+
+/**
+ * Base shape every activity envelope extends. Activity-specific types
+ * (`AgentActivityOutput`, `PublishKbActivityOutput`, …) declare their
+ * `outputs` field with a precise per-output map and add orchestration
+ * metadata as siblings.
+ *
+ * NOT a strict superset — the `outputs` field is required even when
+ * empty (use `outputs: {}`). The "no outputs" case is an explicit choice,
+ * not an omission, so consumers can trust the shape.
+ */
+export interface ActivityEnvelope {
+  /**
+   * Closed-set orchestration flag. Each activity declares its own enum
+   * of valid outcomes (`'succeeded' | 'empty-response' | 'partial'` for
+   * agent, `'ok' | 'noop' | 'error'` for others). The base type uses
+   * `string` so the enum stays activity-local — the DSL compiler
+   * validates `if:` clauses against the per-activity outcome set.
+   */
+  readonly outcome: string;
+  readonly durationMs: number;
+  readonly outputs: ActivityOutputsMap;
+}
+
+/**
+ * Activity-level declaration of an output's contract. Used by:
+ *   • the DSL compiler to type-check `${{ needs.X.outputs.Y }}` and the
+ *     reach-in accessors (positional, byKey, payload-field);
+ *   • `finalizeOutputs` to pick the producer kind + versioning mode + slug;
+ *   • the FE Run Detail's Job Inspector to label each output row.
+ *
+ * Each activity ships a static `OUTPUT_DECLARATIONS` map of these,
+ * authored alongside the activity code.
+ */
+export interface ActivityOutputDeclaration {
+  /** The output's stable name on the envelope. */
+  readonly name: string;
+  /** Closed `OutputKind` enum value (or biome-extension string). */
+  readonly type: string;
+  /** When `true`, the output is `readonly ArtifactRef[]` (variadic). */
+  readonly array?: boolean;
+}
+
+// NOTE: per-output deliverable-spec bindings live on the action
+// MANIFEST (`spec.outputBindings`, see `ActionManifestSpec` in
+// `@xemahq/workflow-dsl`) — that's the single source of truth the DSL
+// compiler reads at compile time. `OUTPUT_DECLARATIONS` is a worker-
+// internal contract used by the output-promotion wrapper, so binding
+// metadata never has to flow through it.
+
+/**
+ * Static declaration map an activity exports — keyed by output name.
+ * Frozen at module load; the activity's runtime cannot mutate it.
+ */
+export type ActivityOutputDeclarations = Readonly<
+  Record<string, ActivityOutputDeclaration>
+>;

package/src/workflow/lib/agent-role.ts

@@ -0,0 +1,136 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Canonical AgentRunRole ──
+//
+// Single source of truth for the role an agent invocation takes. Every
+// downstream consumer — kernel composer, agent-session-runtime, worker
+// activity, agent-session-api, llm-registry-api API DTO,
+// workspace-manifest-dsl Zod schema, AGENTS.md template registry, and
+// the opencode-xema-plugin context reader — imports from here.
+//
+// `workflow-contracts` is intentionally runtime-dep-free, so this module
+// exports a `const` array + derived type. Validators that need a Zod
+// enum (manifest schema) or a class-validator allow-list (NestJS DTO)
+// wrap `AGENT_RUN_ROLES` themselves; the values stay canonical.
+//
+// Adding a role:
+//   1. Append to `AGENT_RUN_ROLES`.
+//   2. If the role is interactive-only or pipeline-only, register it in
+//      either `AGENT_RUN_ROLES_INTERACTIVE` or `AGENT_RUN_ROLES_PIPELINE`
+//      below — the surface guard in `agent-run-context.service.ts` reads
+//      these to reject mismatched manifests.
+//   3. The role-specific mission prose comes from the agent's own
+//      `<slug>.md` body (resolved via `ResolveFullService`); no
+//      handlebars template registry exists. AGENTS.md is composed
+//      programmatically by `composeAgentsMd` from the resolved body +
+//      declared mounts + deliverable spec.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Canonical role values. Closed list. New roles MUST be added here
+ * first; downstream consumers extend their case-handling from this
+ * array.
+ *
+ * Naming convention: kebab-case strings that read as "what kind of
+ * worker is running". Pipeline workers have role names matching their
+ * domain (`engineer`, `auditor`, `coordinator`, …). Interactive
+ * surfaces have role names matching their context (`agent-session`,
+ * `design-system-builder`).
+ */
+export const AGENT_RUN_ROLES = [
+  /** Pipeline executor producing deliverables under a builder template. */
+  'unit-worker',
+  /** Pipeline coordinator merging unit outputs / authoring system-wide pages. */
+  'coordinator',
+  /** Pipeline gate-reviewer producing pass/fail verdicts; read-only authority. */
+  'gate-reviewer',
+  /** Pre-pipeline clarification phase that turns raw requests into typed handoff packages. */
+  'clarification-coordinator',
+  /** Validates whether an upstream output stays inside an envelope; read-only. */
+  'scope-validator',
+  /** Free-chat session bound to a primary agent (default `session` profile). */
+  'agent-session',
+  /** Design System Builder session — design canvas, no pipeline retry/manifest concepts. */
+  'design-system-builder',
+  /** User-defined pipeline agent that doesn't fit the closed catalogue. */
+  'generic-agent',
+  /** Repo audit role — read-only scanner. */
+  'auditor',
+  /** Engineer producing code + PRs (auto-remediation pipelines). */
+  'engineer',
+  /**
+   * Studio chat-author. Read-only authoring co-pilot bound to the
+   * `studio-{workflow|manifest|spec}-author` workspace manifests
+   * shipped by `biomes/kernel/studio-author`. The agent emits typed
+   * proposals only — apply goes through the standard write APIs on
+   * user confirmation. Interactive surface; never runs in a pipeline.
+   */
+  'studio-author',
+  /**
+   * Webapp Studio session — live-coded Next.js / Vite SPA inside the
+   * project's attached repo. Planner-only `webapp-coordinator` agent
+   * orchestrates scaffolder + page-builder + data-builder sub-agents.
+   * Interactive surface; never runs in a pipeline. Bound to the
+   * `webapp-studio-default` workspace manifest shipped by
+   * `biomes/platform/webapp-studio`.
+   */
+  'webapp-studio',
+  /**
+   * Document Buddy session — agent authors a single knowledge-base
+   * document page (MARKDOWN_DOCUMENT or RICH_DOCUMENT) by editing a
+   * real working file at `/workspace/document/<slug>.<ext>` natively;
+   * workspace-proxy's document-sync component derives the reviewable
+   * diff and persists it to knowledge-base-api. Interactive surface;
+   * never runs in a pipeline. Bound to the `document-md-default` /
+   * `document-rich-default` workspace manifests shipped by
+   * `biomes/platform/document-buddy`.
+   */
+  'document',
+] as const;
+
+/**
+ * Discriminated string literal type derived from {@link AGENT_RUN_ROLES}.
+ * Adding a value to that array automatically extends this type;
+ * removing a value forces every consumer to handle the deletion at
+ * compile time.
+ */
+export type AgentRunRole = (typeof AGENT_RUN_ROLES)[number];
+
+/**
+ * Subset of {@link AGENT_RUN_ROLES} that may run on an interactive
+ * (chat-driven) surface. The renderer's surface guard rejects any
+ * role outside this set when the surface is `agent-session` /
+ * `design-system-builder`. Mirrored on the pipeline side by
+ * {@link AGENT_RUN_ROLES_PIPELINE}.
+ */
+export const AGENT_RUN_ROLES_INTERACTIVE = [
+  'agent-session',
+  'design-system-builder',
+  'studio-author',
+  'webapp-studio',
+  'document',
+] as const satisfies ReadonlyArray<AgentRunRole>;
+
+/**
+ * Subset of {@link AGENT_RUN_ROLES} valid on the pipeline (workflow
+ * run / activity-driven) surface.
+ */
+export const AGENT_RUN_ROLES_PIPELINE = [
+  'unit-worker',
+  'coordinator',
+  'gate-reviewer',
+  'clarification-coordinator',
+  'scope-validator',
+  'generic-agent',
+  'auditor',
+  'engineer',
+] as const satisfies ReadonlyArray<AgentRunRole>;
+
+/**
+ * Runtime guard: is `value` one of the canonical roles?
+ */
+export function isAgentRunRole(value: unknown): value is AgentRunRole {
+  return (
+    typeof value === 'string' &&
+    (AGENT_RUN_ROLES as ReadonlyArray<string>).includes(value)
+  );
+}

package/src/workflow/lib/artifact-ref.ts

@@ -0,0 +1,93 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── ArtifactRef — the universal cross-step reference to an artifact ──
+//
+// Under the unified outputs/deliverables/artifacts model, every named
+// output of every activity is an `ArtifactRef`. Activities never carry
+// reviewable bytes inline; the bytes live in artifact-store, the envelope
+// carries refs. Downstream activities consume refs (and fetch bytes when
+// they need them), the FE renders refs uniformly via OutputCard, the DSL
+// supports typed reach-in and `fromJSON` against refs.
+//
+// Shape is intentionally minimal — everything else (size, content-type,
+// pointer, payload) is fetched from artifact-store on demand and cached
+// per `versionId`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+/**
+ * Stable cross-step pointer to a single artifact version. The fields are
+ * sufficient to:
+ *   • render the artifact via OutputCard (no extra metadata required for
+ *     the chrome — `type` drives the renderer pick, `title` is the label,
+ *     `version` is shown in the version selector);
+ *   • pin a review (`{artifactId, versionId, version, hash}` is the
+ *     existing `PinnedSubjectArtifact` shape — ArtifactRef is the
+ *     producer-side superset);
+ *   • fetch bytes on demand from artifact-store via `versionId`.
+ *
+ * `type` is the OutputKind string (or a biome-shipped extension). It is
+ * the routing key for renderer dispatch on the FE. Keep it as a string
+ * here so biome-defined kinds don't require kernel changes — the closed
+ * enum on the consumer side (`OutputKind`) gates the built-in renderers.
+ */
+export interface ArtifactRef {
+  readonly artifactId: string;
+  readonly versionId: string;
+  readonly version: number;
+  readonly hash: string;
+  readonly type: string;
+  readonly title?: string;
+}
+
+export const ArtifactRefSchema = z.object({
+  artifactId: z.string().min(1),
+  versionId: z.string().min(1),
+  version: z.number().int().nonnegative(),
+  hash: z.string().min(1),
+  type: z.string().min(1),
+  title: z.string().optional(),
+});
+
+/**
+ * Structural narrower used by the review-subject taxonomy and DSL runtime.
+ * Returns `true` when a value matches the ArtifactRef shape. Deliberately
+ * a runtime check (not just a type guard) — the wire receives `unknown`,
+ * and the kernel is the single boundary where we decide what's a ref.
+ */
+export function isArtifactRef(value: unknown): value is ArtifactRef {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const rec = value as Record<string, unknown>;
+  return (
+    typeof rec.artifactId === 'string' &&
+    typeof rec.versionId === 'string' &&
+    typeof rec.version === 'number' &&
+    Number.isInteger(rec.version) &&
+    typeof rec.hash === 'string' &&
+    typeof rec.type === 'string'
+  );
+}
+
+/**
+ * Closed set of `ArtifactRef` member names — i.e. the fields a DSL
+ * expression `outputs.<name>.<field>` can read directly off the
+ * envelope without fetching artifact bytes. Anything else is treated
+ * as a payload-reach-in by the DSL compiler (§C.1).
+ *
+ * Kept here so the DSL compiler, the worker evaluator, and any future
+ * static-analysis tools share one source of truth.
+ */
+export const ARTIFACT_REF_ENVELOPE_FIELDS = Object.freeze([
+  'artifactId',
+  'versionId',
+  'version',
+  'hash',
+  'type',
+  'title',
+]) as readonly (keyof ArtifactRef)[];
+
+export function isArtifactRefEnvelopeField(name: string): boolean {
+  return (ARTIFACT_REF_ENVELOPE_FIELDS as readonly string[]).includes(name);
+}

package/src/workflow/lib/briefcase.ts

@@ -0,0 +1,194 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Briefcase — run-scoped ephemeral context object ──
+//
+// Every workflow run carries exactly one Briefcase. It is synthesized at
+// dispatch time from the dispatch request body and propagated to every
+// activity / child-workflow via `ActionBaseInput.briefcase`. Discarded
+// when the run terminates.
+//
+// Purpose:
+//   - Replace ad-hoc `inputs.uploads[]` / `inputs.references[]` shapes
+//     that today's workflows declare-by-convention. Workflows authored
+//     against the Briefcase don't need to plumb those fields through.
+//   - Give non-agent activities (endpoint-fetch, validate-deliverables,
+//     publish-kb, custom transforms) a uniform way to read run-scoped
+//     context without each rolling its own input schema.
+//   - Give the agent-activity workspace composer a single source for
+//     uploads + references to merge into AWP-aligned mount entries.
+//
+// Distinct from workspace manifests:
+//   A workspace manifest declares the SHAPE of an agent's workspace
+//   (AWP slots, tools available, permissions) — static, agent-bound.
+//   A Briefcase carries the CONTENTS for one specific run (the actual
+//   uploads, references, vars) — dynamic, run-bound.
+//
+// Lifecycle (intentional non-features):
+//   - NOT persisted as a standalone entity (no briefcase-api service).
+//   - NOT versioned (briefcases are run-scoped; the run is the version).
+//   - NOT a library (no reuse across runs; pre-curated context would
+//     live as a biome-shipped seed of dispatch inputs, not here).
+//   - NOT biome-contributed.
+//
+// Every slot is OPTIONAL — activities that don't need a slot simply
+// don't read it. An entirely empty Briefcase (`{}`) is a valid value.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { ArtifactRefSchema, type ArtifactRef } from './artifact-ref';
+
+/**
+ * A file uploaded at dispatch (or promoted from design-system-builder). By the
+ * time the engine carries it on the Briefcase the bytes are already in
+ * artifact-store-api and the upload is just a typed reference.
+ *
+ * `filename` is the user-supplied display name (preserved end-to-end so
+ * agents see meaningful paths under `inputs/uploads/<filename>`).
+ * `contentType` is captured for downstream activities that need to
+ * route on MIME type (e.g. a transform that only operates on images).
+ */
+export interface BriefcaseUpload {
+  readonly artifact: ArtifactRef;
+  readonly filename: string;
+  readonly contentType: string | null;
+  readonly sizeBytes: number;
+}
+
+export const BriefcaseUploadSchema = z.object({
+  artifact: ArtifactRefSchema,
+  filename: z.string().min(1).max(512),
+  contentType: z.string().min(1).max(256).nullable(),
+  sizeBytes: z.number().int().nonnegative(),
+});
+
+/**
+ * Tagged pointer to platform content the run should consider
+ * authoritative. The kind narrows the resolution path:
+ *   - `kb_page`        → knowledge-base-api page
+ *   - `kb_space`       → knowledge-base-api space slug
+ *   - `artifact`       → existing artifact in artifact-store-api
+ *   - `scm_repo`       → repo at a specific ref (commit-pinned)
+ *   - `external_url`   → external link (fetched only if an activity
+ *                        explicitly asks; agents see the URL string).
+ *
+ * The discriminator is open-ended-but-typed: new reference kinds can
+ * be added without changing every consumer (they fall back to ignoring
+ * unknown kinds; the agent activity will skip them silently). New
+ * kinds MUST land in this enum and the validating schema below.
+ */
+export const BriefcaseReferenceKind = {
+  KB_PAGE: 'kb_page',
+  KB_SPACE: 'kb_space',
+  ARTIFACT: 'artifact',
+  SCM_REPO: 'scm_repo',
+  EXTERNAL_URL: 'external_url',
+} as const;
+export type BriefcaseReferenceKind =
+  (typeof BriefcaseReferenceKind)[keyof typeof BriefcaseReferenceKind];
+
+export interface BriefcaseReference {
+  readonly kind: BriefcaseReferenceKind;
+  /**
+   * Opaque reference target. For `kb_page` this is the page slug; for
+   * `kb_space` the space slug; for `artifact` the artifact id; for
+   * `scm_repo` it's a `repoSlug@ref` string; for `external_url` it's
+   * the URL. Closed-set on the kind, open-string for the value.
+   */
+  readonly ref: string;
+  /** Optional human-facing label (mostly for run-detail rendering). */
+  readonly title: string | null;
+}
+
+export const BriefcaseReferenceSchema = z.object({
+  kind: z.enum([
+    BriefcaseReferenceKind.KB_PAGE,
+    BriefcaseReferenceKind.KB_SPACE,
+    BriefcaseReferenceKind.ARTIFACT,
+    BriefcaseReferenceKind.SCM_REPO,
+    BriefcaseReferenceKind.EXTERNAL_URL,
+  ]),
+  ref: z.string().min(1).max(2048),
+  title: z.string().min(1).max(512).nullable(),
+});
+
+/**
+ * Per-run MCP tool selections that augment whatever the agent's
+ * workspace manifest already declares for this run. Union with the
+ * job's own `with.tools[]` — never narrows. Activities that talk to
+ * the MCP gateway see these via the shared helper's `getMcpTools`.
+ *
+ * Shape mirrors `ToolSelectionEntry` from `@xemahq/mcp-tool-contracts`
+ * but is duplicated here to avoid a new cross-package dep on the
+ * workflow-contracts side. The platform-common helper validates with
+ * the canonical schema at consumption time.
+ */
+export interface BriefcaseMcpTool {
+  readonly kind: 'provider' | 'tool';
+  readonly providerKind: string;
+  readonly resourceId: string;
+  readonly toolName?: string;
+}
+
+export const BriefcaseMcpToolSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('provider'),
+    providerKind: z.string().min(1).max(64),
+    resourceId: z.string().min(1).max(256),
+  }),
+  z.object({
+    kind: z.literal('tool'),
+    providerKind: z.string().min(1).max(64),
+    resourceId: z.string().min(1).max(256),
+    toolName: z.string().min(1).max(256),
+  }),
+]);
+
+/**
+ * The Briefcase itself. Every field is optional / may be empty; an
+ * empty Briefcase is a valid value and means "the dispatcher had
+ * nothing extra to attach". The activity decides what it needs.
+ *
+ * `vars` carries free-form string KV — useful for run-scoped facts
+ * like `designSystemVersion`, `kbSpaceSlug`, `targetEnvironment`.
+ * NOT a substitute for workflow-level `vars:` (which is the right
+ * home for fixed config the YAML author owns) or for run-wide
+ * identifiers (orgId / projectId / runId — those live on the run
+ * record + `ActionContext`, never duplicated here).
+ */
+export interface Briefcase {
+  readonly vars: Readonly<Record<string, string>>;
+  readonly uploads: readonly BriefcaseUpload[];
+  readonly references: readonly BriefcaseReference[];
+  readonly mcpTools: readonly BriefcaseMcpTool[];
+}
+
+export const BriefcaseSchema = z.object({
+  vars: z.record(z.string(), z.string().max(8_192)),
+  uploads: z.array(BriefcaseUploadSchema).max(256),
+  references: z.array(BriefcaseReferenceSchema).max(256),
+  mcpTools: z.array(BriefcaseMcpToolSchema).max(64),
+});
+
+/**
+ * Helper to construct an empty Briefcase. Use it instead of `{}` so the
+ * field structure stays consistent and future Briefcase fields default
+ * to their empty form without every consumer chasing the change.
+ */
+export function emptyBriefcase(): Briefcase {
+  return { vars: {}, uploads: [], references: [], mcpTools: [] };
+}
+
+/**
+ * Structural check — `true` when every Briefcase field is empty. Used
+ * by the engine to skip carrying a no-op briefcase through Temporal
+ * history (small but meaningful payload-size optimization).
+ */
+export function isEmptyBriefcase(briefcase: Briefcase | undefined): boolean {
+  if (!briefcase) return true;
+  return (
+    Object.keys(briefcase.vars).length === 0 &&
+    briefcase.uploads.length === 0 &&
+    briefcase.references.length === 0 &&
+    briefcase.mcpTools.length === 0
+  );
+}

package/src/workflow/lib/canonical-concepts/canonical-concept-registry.ts

@@ -0,0 +1,99 @@
+/**
+ * CanonicalConceptRegistry — machine-owned semantic normalization layer.
+ *
+ * Maps raw project context (tech stack items, change descriptions, concerns)
+ * to canonical concept keys used by the skill selection algorithm.
+ *
+ * Skills stay clean (OpenCode-style markdown). This registry handles the
+ * messy alias resolution so skills don't need to encode every variant.
+ *
+ * Concept data lives in per-kind files under ./concepts/ for scalability.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Enums & Types ──
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum ConceptKind {
+  Technology = 'technology',
+  Concern = 'concern',
+  ChangeIntent = 'change_intent',
+  Domain = 'domain',
+}
+
+export interface CanonicalConcept {
+  key: string;
+  aliases: string[];
+  parents?: string[];
+  related?: string[];
+  kind: ConceptKind;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Registry Data (loaded from per-kind concept files) ──
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { ALL_CONCEPTS } from './concepts';
+
+const CONCEPTS: CanonicalConcept[] = ALL_CONCEPTS;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Lookup Index ──
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Alias → canonical concept key lookup. Built once at module init. */
+const ALIAS_INDEX: Map<string, CanonicalConcept> = new Map();
+
+for (const concept of CONCEPTS) {
+  // Index the canonical key itself
+  ALIAS_INDEX.set(concept.key, concept);
+  // Index all aliases
+  for (const alias of concept.aliases) {
+    ALIAS_INDEX.set(alias.toLowerCase(), concept);
+  }
+  // Index parent concepts as aliases pointing to themselves if not already registered
+  if (concept.parents) {
+    for (const parent of concept.parents) {
+      if (!ALIAS_INDEX.has(parent)) {
+        // Parent concept exists but may not have its own entry — skip (no silent creation)
+      }
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Public API ──
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolve a raw term to its canonical concept, or null if not recognized.
+ */
+export function resolveCanonicalConcept(raw: string): CanonicalConcept | null {
+  const normalized = raw.toLowerCase().trim().replace(/\s+/g, '-');
+  return ALIAS_INDEX.get(normalized) ?? null;
+}
+
+/**
+ * Resolve a raw term to its canonical key, or return the normalized form if not recognized.
+ * Unrecognized terms pass through as-is (lowercase, hyphenated) — they won't match any skill
+ * index entry, but they're preserved for LLM fallback context.
+ */
+export function resolveCanonicalKey(raw: string): string {
+  const concept = resolveCanonicalConcept(raw);
+  return concept?.key ?? raw.toLowerCase().trim().replace(/\s+/g, '-');
+}
+
+/**
+ * Get the kind of a canonical concept, or null if not in registry.
+ */
+export function getConceptKind(key: string): ConceptKind | null {
+  const concept = ALIAS_INDEX.get(key.toLowerCase());
+  return concept?.kind ?? null;
+}
+
+/**
+ * Get all registered concepts.
+ */
+export function getAllConcepts(): readonly CanonicalConcept[] {
+  return CONCEPTS;
+}