@xemahq/kernel-contracts 0.1.0 → 0.2.1

package/src/inquiry/lib/recipient.ts

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+
+import { RecipientKind } from './enums';
+
+/**
+ * Human recipient — a user identified by their identity-system subject.
+ * Resolution happens at the inquiry-creator layer (Decision Gate workflow
+ * or agent-tool-inquiry bridge); the contract carries the resolved string.
+ */
+export const HumanRecipientTargetSchema = z.object({
+  userId: z.string().min(1),
+});
+export type HumanRecipientTarget = z.infer<typeof HumanRecipientTargetSchema>;
+
+/**
+ * Agent recipient — a non-human decider invoked as a peer activity by the
+ * gate workflow or as an in-band call by the inquiry creator. `agentRef`
+ * resolves against the LLM agent registry; the runtime adapter (Platform)
+ * decides which agent runtime executes it.
+ *
+ * `skills` is the canonical extension point for attaching policy bundles
+ * (`@xemahq/kernel-contracts/skill`) to the reviewer agent — the same skill
+ * primitive a workflow agent step uses, mounted into the reviewer's
+ * workspace at `/workspace/.opencode/skills/<slug>/`. Each entry is a
+ * hierarchical skill slug (e.g. `gate-review/requirements-quality`).
+ * Replaces the legacy phase-config `gateReviewers[].perspective` /
+ * `scopeRules` block — the reviewer's per-phase policy now lives in a
+ * first-class Skill bundle that the composer mounts via the standard
+ * skill-resolution path.
+ *
+ * `invocationConfig` is opaque to this contract — passed through to the
+ * adapter unchanged.
+ */
+export const AgentRecipientTargetSchema = z.object({
+  agentRef: z.string().min(1),
+  skills: z.array(z.string().min(1)).optional(),
+  invocationConfig: z.record(z.string(), z.unknown()).optional(),
+});
+export type AgentRecipientTarget = z.infer<typeof AgentRecipientTargetSchema>;
+
+/**
+ * Endpoint recipient — an external HTTP endpoint that produces a verdict.
+ * `verdictMapper` extracts the verdict from the response body (JSONPath
+ * + schema). `authRef` resolves to a service-token credential at runtime.
+ */
+export const EndpointVerdictMapperSchema = z.object({
+  /** JSONPath into the response body (e.g. `$.decision`). */
+  jsonPath: z.string().min(1),
+  /** Map of raw response values → typed verdict. */
+  verdictMap: z.record(z.string(), z.enum(['approve', 'reject', 'abstain'])),
+});
+export type EndpointVerdictMapper = z.infer<typeof EndpointVerdictMapperSchema>;
+
+export const EndpointRecipientTargetSchema = z.object({
+  url: z.string().url(),
+  authRef: z.string().min(1),
+  verdictMapper: EndpointVerdictMapperSchema,
+  timeoutMs: z.number().int().positive().optional(),
+});
+export type EndpointRecipientTarget = z.infer<
+  typeof EndpointRecipientTargetSchema
+>;
+
+/**
+ * Identity-group recipient — an authoring-time alias for "every human
+ * member of this identity-system group, including descendants". The
+ * engine resolves it against the identity API at inquiry-create time and
+ * replaces it with N concrete `HUMAN` rows. It is therefore never seen
+ * on a persisted inquiry — only on the create request and in DSL.
+ *
+ * `allowEmpty` defaults to false: if the resolved member set is empty
+ * the engine fails inquiry creation with `INQUIRY_GROUP_EMPTY`. Set to
+ * true for groups that can legitimately be vacant (e.g. a fallback
+ * notification list).
+ */
+export const IdentityGroupRecipientTargetSchema = z.object({
+  groupId: z.string().min(1),
+  allowEmpty: z.boolean().optional(),
+});
+export type IdentityGroupRecipientTarget = z.infer<
+  typeof IdentityGroupRecipientTargetSchema
+>;
+
+/**
+ * Verdict mapper applied to the child workflow's `outputs` map. Each
+ * outcome (`approve | reject | abstain`) is a JSON-path expression
+ * evaluated against `outputs`; the first matching outcome wins.
+ *
+ * Example:
+ *   { approve: 'outputs.compliant === true',
+ *     reject:  'outputs.compliant === false' }
+ *
+ * Shape kept intentionally narrow — full expression engines belong in
+ * the runtime activity, not in the contract.
+ */
+export const WorkflowVerdictMapperSchema = z.object({
+  approve: z.string().min(1).optional(),
+  reject: z.string().min(1).optional(),
+  abstain: z.string().min(1).optional(),
+});
+export type WorkflowVerdictMapper = z.infer<
+  typeof WorkflowVerdictMapperSchema
+>;
+
+/**
+ * Workflow recipient — dispatch a child workflow as a non-human
+ * responder. The engine starts the workflow with `inputs`, awaits
+ * termination, and maps `outputs` to `{ verdict, payload }` using
+ * `verdictMapper`. From the inquiry's perspective the reply is
+ * indistinguishable from a human submission.
+ *
+ * Recursion is bounded by the engine's responder-chain check: if the
+ * dispatched slug is already on the chain, creation fails with
+ * `INQUIRY_RESPONDER_CYCLE`.
+ */
+export const WorkflowRecipientTargetSchema = z.object({
+  workflowSlug: z.string().min(1),
+  inputs: z.record(z.string(), z.unknown()).optional(),
+  verdictMapper: WorkflowVerdictMapperSchema.optional(),
+});
+export type WorkflowRecipientTarget = z.infer<
+  typeof WorkflowRecipientTargetSchema
+>;
+
+/**
+ * Fields shared by every recipient variant. Authoring-time orthogonal
+ * to `kind` — they describe *how the recipient participates in policy
+ * evaluation*, not who they are.
+ *
+ * `mandatory` (defaults true at the engine boundary): when false the
+ *   recipient's verdict is collected for context but does NOT
+ *   participate in policy evaluation. Existing decision-gate call
+ *   sites omit the field — the engine treats `undefined` as `true` so
+ *   behavior is unchanged. Used by `xema/review@v3` to mark advisory
+ *   reviewers that contribute findings without veto power.
+ *
+ *   Schema-side the field is left `.optional()` (not `.default(true)`)
+ *   so the TypeScript type stays `mandatory?: boolean` for callers,
+ *   while the persistence layer (DB default true) and the engine's
+ *   `expandGroupRecipients` (`r.mandatory ?? true`) materialize the
+ *   default exactly once.
+ *
+ * `agentMaxIterations`: review-loop hint — max number of times this
+ *   AGENT or WORKFLOW responder may reject before the loop demotes it
+ *   to advisory. Ignored outside of `xema/review@v3`; not persisted on
+ *   the recipient row (the review workflow tracks counters in its own
+ *   state).
+ */
+export const RecipientCommonSchema = z.object({
+  mandatory: z.boolean().optional(),
+  agentMaxIterations: z.number().int().positive().optional(),
+});
+export type RecipientCommon = z.infer<typeof RecipientCommonSchema>;
+
+/**
+ * Discriminated recipient. Adding a new kind is a one-line enum extension
+ * + a new schema variant; existing recipients are unaffected.
+ *
+ * The result is the intersection of the discriminated union (kind+target)
+ * and `RecipientCommonSchema` so every variant carries `mandatory` /
+ * `agentMaxIterations` without duplicating those declarations per kind.
+ */
+export const RecipientSchema = z.intersection(
+  z.discriminatedUnion('kind', [
+    z.object({
+      kind: z.literal(RecipientKind.HUMAN),
+      target: HumanRecipientTargetSchema,
+    }),
+    z.object({
+      kind: z.literal(RecipientKind.AGENT),
+      target: AgentRecipientTargetSchema,
+    }),
+    z.object({
+      kind: z.literal(RecipientKind.ENDPOINT),
+      target: EndpointRecipientTargetSchema,
+    }),
+    z.object({
+      kind: z.literal(RecipientKind.IDENTITY_GROUP),
+      target: IdentityGroupRecipientTargetSchema,
+    }),
+    z.object({
+      kind: z.literal(RecipientKind.WORKFLOW),
+      target: WorkflowRecipientTargetSchema,
+    }),
+  ]),
+  RecipientCommonSchema,
+);
+export type Recipient = z.infer<typeof RecipientSchema>;

package/src/inquiry/lib/workflow-verdict-evaluator.ts

@@ -0,0 +1,220 @@
+import type { WorkflowVerdictMapper } from './recipient';
+
+/**
+ * Bounded grammar for `WorkflowVerdictMapper` expressions. The runtime
+ * dispatcher (worker-side) and the engine validator (inquiry-create
+ * boundary) share this implementation so authors hit identical errors at
+ * both ends.
+ *
+ * Supported forms:
+ *   `outputs`                     → truthy when value is non-null / non-undefined / non-false / non-empty-string
+ *   `outputs.<key>(.<key>)*`      → same truthy check on a nested field
+ *   `outputs.<path> === <literal>` → strict equality
+ *   `outputs.<path> !== <literal>` → strict inequality
+ *
+ * Literals: `true`, `false`, `null`, `"<string>"`, `<number>`. Strings
+ * support escaped backslash + double-quote (`\\` and `\"`); other escape
+ * sequences are passed through verbatim. Floats use a leading digit
+ * (`0.5`, not `.5`).
+ *
+ * Anything outside this grammar fails parsing. Callers convert parse
+ * failure into a typed error (engine: 400 INQUIRY_VERDICT_MAPPER_INVALID;
+ * worker: ABSTAIN with `verdictmapper_unparseable:<expression>`).
+ *
+ * Why so narrow: a permissive grammar (full JS, JSONPath filters) would
+ * push expression evaluation into a runtime that can throw on arbitrary
+ * inputs and complicate sandboxing. The supported set covers the
+ * documented examples (`outputs.compliant === true`) and forces authors
+ * to do any structural reshaping inside the responder workflow's
+ * `outputs:` block — where it belongs.
+ */
+
+const PATH_SEGMENT = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export type CompiledWorkflowVerdictExpression = (
+  outputs: Readonly<Record<string, unknown>>,
+) => boolean;
+
+export interface CompiledWorkflowVerdictMapper {
+  readonly approve?: CompiledWorkflowVerdictExpression;
+  readonly reject?: CompiledWorkflowVerdictExpression;
+  readonly abstain?: CompiledWorkflowVerdictExpression;
+}
+
+export class WorkflowVerdictMapperParseError extends Error {
+  constructor(
+    public readonly outcome: 'approve' | 'reject' | 'abstain',
+    public readonly expression: string,
+    detail: string,
+  ) {
+    super(
+      `WorkflowVerdictMapper.${outcome} expression '${expression}' is invalid: ${detail}`,
+    );
+    this.name = 'WorkflowVerdictMapperParseError';
+  }
+}
+
+/**
+ * Parse + compile every defined branch in the mapper. Throws
+ * `WorkflowVerdictMapperParseError` on the first invalid expression so
+ * authors fix one issue at a time with a clear diagnostic.
+ */
+export function compileWorkflowVerdictMapper(
+  mapper: WorkflowVerdictMapper,
+): CompiledWorkflowVerdictMapper {
+  return {
+    ...(mapper.approve !== undefined && {
+      approve: compileExpression('approve', mapper.approve),
+    }),
+    ...(mapper.reject !== undefined && {
+      reject: compileExpression('reject', mapper.reject),
+    }),
+    ...(mapper.abstain !== undefined && {
+      abstain: compileExpression('abstain', mapper.abstain),
+    }),
+  };
+}
+
+/**
+ * Apply a compiled mapper against the responder workflow's flattened
+ * outputs. Returns the first matching outcome (in `approve → reject →
+ * abstain` order) or `null` when no branch matched.
+ */
+export function evaluateCompiledWorkflowVerdictMapper(
+  mapper: CompiledWorkflowVerdictMapper,
+  outputs: Readonly<Record<string, unknown>>,
+): 'approve' | 'reject' | 'abstain' | null {
+  if (mapper.approve && mapper.approve(outputs)) {return 'approve';}
+  if (mapper.reject && mapper.reject(outputs)) {return 'reject';}
+  if (mapper.abstain && mapper.abstain(outputs)) {return 'abstain';}
+  return null;
+}
+
+function compileExpression(
+  outcome: 'approve' | 'reject' | 'abstain',
+  raw: string,
+): CompiledWorkflowVerdictExpression {
+  const expression = raw.trim();
+  if (expression.length === 0) {
+    throw new WorkflowVerdictMapperParseError(outcome, raw, 'expression is empty');
+  }
+  const equality = expression.match(/^(.+?)\s+(===|!==)\s+(.+)$/);
+  if (equality) {
+    const [, lhsRaw, op, rhsRaw] = equality;
+    const path = parseOutputsPath(outcome, raw, lhsRaw!);
+    const literal = parseLiteral(outcome, raw, rhsRaw!);
+    return (outputs) => {
+      const value = readPath(outputs, path);
+      return op === '===' ? value === literal : value !== literal;
+    };
+  }
+  const path = parseOutputsPath(outcome, raw, expression);
+  return (outputs) => isTruthy(readPath(outputs, path));
+}
+
+function parseOutputsPath(
+  outcome: 'approve' | 'reject' | 'abstain',
+  raw: string,
+  cursor: string,
+): readonly string[] {
+  const trimmed = cursor.trim();
+  if (trimmed === 'outputs') {return [];}
+  if (!trimmed.startsWith('outputs.')) {
+    throw new WorkflowVerdictMapperParseError(
+      outcome,
+      raw,
+      `expected 'outputs' or 'outputs.<path>' (got '${trimmed}')`,
+    );
+  }
+  const segments = trimmed.slice('outputs.'.length).split('.');
+  for (const seg of segments) {
+    if (!PATH_SEGMENT.test(seg)) {
+      throw new WorkflowVerdictMapperParseError(
+        outcome,
+        raw,
+        `'${seg}' is not a valid identifier (segments must match ${PATH_SEGMENT.source})`,
+      );
+    }
+  }
+  return segments;
+}
+
+function parseLiteral(
+  outcome: 'approve' | 'reject' | 'abstain',
+  raw: string,
+  cursor: string,
+): string | number | boolean | null {
+  const trimmed = cursor.trim();
+  if (trimmed === 'true') {return true;}
+  if (trimmed === 'false') {return false;}
+  if (trimmed === 'null') {return null;}
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+    return parseStringLiteral(outcome, raw, trimmed);
+  }
+  // Numbers: integers + simple floats. No leading dot, no exponent (yet);
+  // expand the grammar in a follow-up if real authors need it.
+  if (/^-?[0-9]+(\.[0-9]+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+  throw new WorkflowVerdictMapperParseError(
+    outcome,
+    raw,
+    `right-hand side '${trimmed}' is not a supported literal (true | false | null | "string" | number)`,
+  );
+}
+
+function parseStringLiteral(
+  outcome: 'approve' | 'reject' | 'abstain',
+  raw: string,
+  literal: string,
+): string {
+  const inner = literal.slice(1, -1);
+  let out = '';
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (ch === '\\') {
+      const next = inner[i + 1];
+      if (next === '\\' || next === '"') {
+        out += next;
+        i++;
+        continue;
+      }
+      throw new WorkflowVerdictMapperParseError(
+        outcome,
+        raw,
+        `unsupported escape in string literal — only \\\\ and \\" are allowed`,
+      );
+    }
+    if (ch === '"') {
+      throw new WorkflowVerdictMapperParseError(
+        outcome,
+        raw,
+        `unescaped double-quote inside string literal`,
+      );
+    }
+    out += ch;
+  }
+  return out;
+}
+
+function readPath(
+  source: Readonly<Record<string, unknown>>,
+  path: readonly string[],
+): unknown {
+  let cursor: unknown = source;
+  for (const segment of path) {
+    if (cursor === null || cursor === undefined) {return undefined;}
+    if (typeof cursor !== 'object') {return undefined;}
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return cursor;
+}
+
+function isTruthy(value: unknown): boolean {
+  if (value === null || value === undefined) {return false;}
+  if (typeof value === 'boolean') {return value;}
+  if (typeof value === 'string') {return value.length > 0;}
+  if (typeof value === 'number') {return value !== 0 && !Number.isNaN(value);}
+  // Objects (including arrays) are truthy.
+  return true;
+}

package/src/org-database/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/enums';
+export * from './lib/driver';
+export * from './lib/migration-runner';
+export * from './lib/db-result-event';

package/src/org-database/lib/db-result-event.ts

@@ -0,0 +1,59 @@
+import type { DbMutationKind } from './enums';
+
+/**
+ * Column metadata for a result set row returned by the database explorer.
+ *
+ * Field semantics:
+ * - `name`        — column alias as it appears in the result set
+ * - `typeOid`     — Postgres pg_type OID (closed across a given server version)
+ * - `typeName`    — human-readable Postgres type name (e.g. `int4`, `text`,
+ *                   `timestamptz`). Sourced from `information_schema` /
+ *                   `pg_type.typname`; used for UI type chips.
+ * - `nullable`    — `true` when the column is nullable. For ad-hoc query
+ *                   columns where nullability cannot be determined from the
+ *                   statement alone, the producer SHOULD set `true`
+ *                   (conservative default).
+ * - `isPrimaryKey`     — `true` only for table-column listings, undefined
+ *                        for ad-hoc SELECT projections.
+ * - `foreignKeyTarget` — `"<schema>.<table>.<column>"` reference for FK
+ *                        columns; undefined when no FK exists or the column
+ *                        is an ad-hoc projection.
+ */
+export interface DbColumnMeta {
+  readonly name: string;
+  readonly typeOid: number;
+  readonly typeName: string;
+  readonly nullable: boolean;
+  readonly isPrimaryKey?: boolean;
+  readonly foreignKeyTarget?: string;
+}
+
+/**
+ * Surface event payload emitted when the database explorer executes a SQL
+ * statement on behalf of an agent tool call. Mirrors plan §12.4 verbatim.
+ *
+ * `rows` carries the actual row data — it MUST go to the frontend only and
+ * MUST never be passed back into LLM context. Producers route it through
+ * the agent-session SSE channel (in H5+) or return it inline to the
+ * caller (in H1, when no SSE bridge exists yet).
+ *
+ * `statement` is the SQL string the agent supplied. It is shown in the UI
+ * as a reference for the user; it is NOT a secret. Audit logs hash the
+ * statement separately — never log it verbatim.
+ */
+export interface DbResultSurfaceEvent {
+  readonly type: 'db.result';
+  /** Stable per tool call so the frontend can update the same widget on retry. */
+  readonly surfaceId: string;
+  readonly databaseId: string;
+  readonly schemaName: string;
+  readonly statement: string;
+  readonly columns: readonly DbColumnMeta[];
+  readonly rows: readonly unknown[][];
+  readonly rowCount: number;
+  readonly truncated: boolean;
+  readonly durationMs: number;
+  /** Present only on mutate results — discriminates the wire shape. */
+  readonly mutationKind?: DbMutationKind;
+  readonly affectedRows?: number;
+}

package/src/org-database/lib/driver.ts

@@ -0,0 +1,47 @@
+import type { DbDriverKind } from './enums';
+
+export interface ProvisionInput {
+  orgId: string;
+  databaseName: string;
+}
+
+export interface EnsureSchemaInput {
+  databaseName: string;
+  schemaName: string;
+  rwRoleName: string;
+  roRoleName: string;
+}
+
+export interface DropSchemaInput {
+  databaseName: string;
+  schemaName: string;
+  rwRoleName: string;
+  roRoleName: string;
+}
+
+export interface MintConnectionInput {
+  databaseName: string;
+  schemaName: string;
+  roleName: string;
+  ttlSeconds: number;
+}
+
+export interface ConnectionGrant {
+  host: string;
+  port: number;
+  database: string;
+  schema: string;
+  user: string;
+  password: string;
+  expiresAt: Date;
+}
+
+export interface DatabaseDriver {
+  readonly kind: DbDriverKind;
+
+  provisionOrgDatabase(input: ProvisionInput): Promise<{ databaseName: string }>;
+  ensureSchema(input: EnsureSchemaInput): Promise<void>;
+  dropSchema(input: DropSchemaInput): Promise<void>;
+  dropOrgDatabase(databaseName: string): Promise<void>;
+  mintConnection(input: MintConnectionInput): Promise<ConnectionGrant>;
+}

package/src/org-database/lib/enums.ts

@@ -0,0 +1,51 @@
+export enum DbDriverKind {
+  Postgres = 'postgres',
+  Mongo = 'mongo',
+  Weaviate = 'weaviate',
+}
+
+export enum DbPoolStatus {
+  Active = 'active',
+  Draining = 'draining',
+  Decommissioned = 'decommissioned',
+}
+
+export enum OrgDatabaseStatus {
+  Provisioning = 'provisioning',
+  Active = 'active',
+  Migrating = 'migrating',
+  Failed = 'failed',
+  Archived = 'archived',
+}
+
+export enum OrgDatabasePurpose {
+  Biome = 'biome',
+  AppDev = 'app_dev',
+  AppProd = 'app_prod',
+  System = 'system',
+}
+
+export enum MigrationRunnerKind {
+  Prisma = 'prisma',
+  Drizzle = 'drizzle',
+  Flyway = 'flyway',
+  RawSql = 'raw_sql',
+}
+
+export enum MigrationStatus {
+  Pending = 'pending',
+  Running = 'running',
+  Succeeded = 'succeeded',
+  Failed = 'failed',
+}
+
+/**
+ * The kind of single-statement DML executed via the explorer `/mutate`
+ * endpoint. Closed domain — the SQL validator rejects everything else
+ * (DDL, multi-statement, transactional control) at parse time.
+ */
+export enum DbMutationKind {
+  Insert = 'insert',
+  Update = 'update',
+  Delete = 'delete',
+}

package/src/org-database/lib/migration-runner.ts

@@ -0,0 +1,17 @@
+import type { MigrationRunnerKind } from './enums';
+
+export interface MigrationRunInput {
+  connectionUrl: string;
+  workspaceDir: string;
+  env: Record<string, string>;
+}
+
+export interface MigrationRunResult {
+  exitCode: number;
+  output: string;
+}
+
+export interface MigrationRunner {
+  readonly kind: MigrationRunnerKind;
+  run(input: MigrationRunInput): Promise<MigrationRunResult>;
+}

package/src/project-kit/index.ts

@@ -0,0 +1,17 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/project-kit-contracts — Project Kit wire contracts.
+//
+// Pure types + enums for the "Project Kit" concept (reusable units installed
+// into a project repo at session start). Zero runtime deps.
+//
+// A FOCUSED package on purpose: the catalog DTOs in `llm-registry-api` and
+// `webapp-studio-api` expose these enums via `@ApiProperty({ enum })`, and the
+// @nestjs/swagger CLI plugin bakes a `require()` to each enum's declaration
+// into the OpenAPI metadata factory. That require only resolves cleanly when
+// the package is NOT physically nested under another (`platform-common` is, so
+// enums living there produced an unresolvable nested specifier). Keeping these
+// contracts in their own leaf package — depended on only by the consuming
+// services, never transitively — guarantees a clean top-level resolution.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/project-kit';