@xemahq/kernel-contracts

--- package/src/workflow/lib/enums.ts (excerpt) ---
// ═══════════════════════════════════════════════════════════════════════════
// ── Workflow Execution Enums ──
//
// Closed domains for every workflow/job/step state + policy value.
// Every workflow-plane decision point uses one of these enums. Free-form
// strings are forbidden for closed sets (see docs/API_STANDARDS.md §5.3).
// ═══════════════════════════════════════════════════════════════════════════

/** How a workflow run was initiated. */
export enum WorkflowTriggerKind {
  WORKFLOW_DISPATCH = 'workflow_dispatch',
  SCHEDULE = 'schedule',
  WEBHOOK = 'webhook',
  WORKFLOW_CALL = 'workflow_call',
}

/** How concurrent runs that share a concurrency group behave. */
export enum ConcurrencyMode {
  ALLOW = 'allow',
  QUEUE = 'queue',
  CANCEL_IN_PROGRESS = 'cancel_in_progress',
  SKIP = 'skip',
}

/** Permission scopes a workflow may request. Enforced at the activity boundary. */
export enum PermissionScope {
  NONE = 'none',
  READ = 'read',
  LIMITED = 'limited',
  WRITE = 'write',
}

/** Permission resources a workflow may request scoped access to. */
export enum PermissionResource {
  REPOS = 'repos',
  KB = 'kb',
  BACKLOG = 'backlog',
  INTEGRATIONS = 'integrations',
  ARTIFACTS = 'artifacts',
  MEMORY = 'memory',
}

/** How an action is executed under Temporal. */
export enum ActionExecutionKind {
  ACTIVITY = 'activity',
  CHILD_WORKFLOW = 'child_workflow',
}

/**
 * Semantic category of an action — drives consumer presentation (FE
 * canvas shape, badge iconog

--- package/src/search-source/lib/search-replay.ts (excerpt) ---
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.

--- package/src/provisioning/lib/provisioning.ts (excerpt) ---
import { z } from 'zod';

// ─── Closed enums ────────────────────────────────────────────────────────────

/**
 * Kind of provisioning step.
 *
 *  - `SCAFFOLD` — seed an empty target with a project skeleton (e.g.
 *    `create-next-app`). Only runs at workspace boot, guard-gated on the
 *    target being scaffold-safe-empty.
 *  - `EQUIP` — install a reusable unit (a Project Kit) into an already
 *    scaffolded repo. Idempotent: guard-gated on a marker being absent.
 */
export enum ProvisioningStepKind {
  SCAFFOLD = 'scaffold',
  EQUIP = 'equip',
}

/**
 * Pre-condition the executor evaluates against the LIVE filesystem before
 * running a step. A failing guard ⇒ the step is recorded `skipped` — this
 * is what makes the `provision` phase self-idempotent with no mutable
 * ledger.
 *
 *  - `REPO_EMPTY`    — `repos/<repoRef>/` holds only `SCAFFOLD_SAFE_NOISE`.
 *  - `PATH_ABSENT`   — `targetDir` is absent, or holds only safe noise.
 *  - `MARKER_ABSENT` — `guardArgs.markerJsonPointer` resolves to nothing
 *                      (e.g. the kit package is not yet in `package.json`).
 *  - `ALWAYS`        — no pre-condition; the step always runs.
 */
export enum ProvisioningGuard {
  REPO_EMPTY = 'repo_empty',
  PATH_ABSENT = 'path_absent',
  MARKER_ABSENT = 'marker_absent',
  ALWAYS = 'always',
}

/**
 * When a scaffold declaration is allowed to run.
 *
 *  - `WORKSPACE_BOOT`   — during the `provision` phase of session launch.
 *  - `RUNTIME_REQUEST`  — on an explicit later r