@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/session-kit/approvals/approval-model.ts

@@ -1,204 +0,0 @@
-/**
- * Approval primitive — generic frame model + scoped-body payloads.
- *
- * The approval is the runtime face of a kernel policy decision: a
- * capability call returns `allow | deny | needs_approval`
- * (`PolicyDecisionKind`); on `needs_approval` the gateway suspends the
- * call and renders a TYPED approval. The frame is identical platform-wide
- * (risk pill + capability ref + obligations + quorum + actions); each
- * biome supplies a typed `scope` body for rich detail — the same
- * generic-frame + biome-body pattern as the in-chat widget registry
- * and the preview-tab kinds.
- *
- * This module REUSES the kernel contracts rather than redefining them:
- *   • `CapabilityRiskTier` (low/medium/high/critical) — risk pill + accent
- *   • `PolicyObligationKind` (the closed 9-kind taxonomy) — obligation chips
- *   • `CapabilityRef` (`domain.biome/action@v` mono ref)
- * It only ADDS the two things the kernel has no opinion on: the closed
- * `ApprovalScopeKind` set + its discriminated scope-payload union (the
- * biome-supplied detail), and the binary `ApprovalDecision` the surfaces
- * emit. Both are presentation contracts, not policy contracts.
- */
-import type { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
-import type { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
-
-/**
- * Closed set of biome-supplied scoped-body kinds. This is the
- * approval analogue of `ChatWidgetKind` — a typed, versioned catalogue of
- * rich bodies that render UNDER the generic frame. The renderer
- * (`ScopedBody`) switches on `kind`; an unknown kind fails SAFE to a
- * visible "unknown scope" rendering rather than a silent drop.
- *
- * First-party kinds ship here; a biome registers a custom kind the same
- * way it registers a chat widget (backend-defined, versioned). Extend the
- * enum + add a body component + a `union` member in lockstep — never match
- * on a free-form string.
- */
-export enum ApprovalScopeKind {
-  Payment = 'payment',
-  Sql = 'sql',
-  Slack = 'slack',
-  Deploy = 'deploy',
-  Files = 'files',
-}
-
-/** Disbursement / payment scope (finance biomes). */
-export interface PaymentScope {
-  readonly kind: ApprovalScopeKind.Payment;
-  /** Pre-formatted display amount (e.g. `$18,400.00`). */
-  readonly amount: string;
-  readonly payee: string;
-  /** Payment rail, e.g. `ACH wire`. */
-  readonly method: string;
-  /** Masked account, e.g. `•••• 7741`. */
-  readonly account: string;
-  readonly memo?: string;
-}
-
-/** Write-query scope (data-warehouse biomes). */
-export interface SqlScope {
-  readonly kind: ApprovalScopeKind.Sql;
-  readonly dialect: string;
-  readonly table: string;
-  /** Pre-formatted affected-row estimate (e.g. `≈ 1,240`). */
-  readonly rowsAffected: string;
-  readonly query: string;
-}
-
-/** Outbound message scope (chat / outreach biomes). */
-export interface SlackScope {
-  readonly kind: ApprovalScopeKind.Slack;
-  readonly channel: string;
-  readonly workspace: string;
-  /** The identity the message is posted as (e.g. `@sales-bot`). */
-  readonly as: string;
-  readonly message: string;
-}
-
-/** Production-deploy scope (release biomes). */
-export interface DeployScope {
-  readonly kind: ApprovalScopeKind.Deploy;
-  readonly version: string;
-  readonly cluster: string;
-  readonly services: number;
-  readonly migrations: number;
-  readonly changelog: readonly string[];
-}
-
-/** A single changed file with line deltas. */
-export interface ApprovalFileChange {
-  readonly path: string;
-  readonly add: number;
-  readonly del: number;
-}
-
-/** Working-tree write scope (software-dev biomes). */
-export interface FilesScope {
-  readonly kind: ApprovalScopeKind.Files;
-  readonly files: readonly ApprovalFileChange[];
-}
-
-/**
- * Discriminated union of every first-party scope payload. The `kind`
- * discriminant maps 1:1 onto `ApprovalScopeKind`; `ScopedBody` is an
- * exhaustive switch over it with a safe fallback for unknown kinds (so a
- * biome that ships a not-yet-known scope renders a visible placeholder
- * instead of crashing or silently dropping the body).
- */
-export type ApprovalScope =
-  | PaymentScope
-  | SqlScope
-  | SlackScope
-  | DeployScope
-  | FilesScope;
-
-/**
- * A rendered obligation — the `PolicyObligationKind` discriminant plus a
- * pre-formatted display value the producer derived from the typed kernel
- * `PolicyObligation` payload (e.g. `max-cost-usd` → `$25,000`,
- * `max-duration-seconds` → `30s`). The kit deliberately takes a formatted
- * `value` string rather than the raw typed payload so the chip stays
- * presentation-only; the host's `obligationDisplay` helper does the
- * typed→display mapping from the wire `PolicyObligation`.
- */
-export interface ApprovalObligation {
-  readonly kind: PolicyObligationKind;
-  /** Pre-formatted display value for the chip's trailing mono span. */
-  readonly value?: string;
-}
-
-/**
- * The generic approval request — the envelope every surface (inline card,
- * sticky bar, Center row) renders. Field names mirror the kernel/wire
- * shape so the backend approval envelope (capability ref, riskTier,
- * obligations[], requireRole, requireApproverCount, approvalsIn, scope)
- * maps onto it 1:1.
- */
-export interface ApprovalRequest {
-  /** Stable id of the suspended invocation awaiting approval. */
-  readonly id: string;
-  /** Capability ref (`domain.biome/action@v`) rendered mono in the frame. */
-  readonly capability: string;
-  /** Owning biome id + display name (the scoped body's provenance). */
-  readonly biomeId: string;
-  readonly biomeName: string;
-  /** Serif title + one-line summary (the generic frame's headline). */
-  readonly title: string;
-  readonly summary: string;
-  /** Kernel risk tier — drives the pill + accent + low/critical action set. */
-  readonly riskTier: CapabilityRiskTier;
-  /** Obligations rendered as chips (closed `PolicyObligationKind` taxonomy). */
-  readonly obligations?: readonly ApprovalObligation[];
-  /** Approver role required by the matched `ApprovalRule`, if any. */
-  readonly requireRole?: string;
-  /** Quorum size; `1` (or absent) = single-approver. */
-  readonly requireApproverCount?: number;
-  /** Approvals already collected toward the quorum. */
-  readonly approvalsIn?: number;
-  /** Biome-supplied typed scope body. */
-  readonly scope: ApprovalScope;
-}
-
-/**
- * Binary surface decision. Closed set — never a free-form string. The
- * "allow once" vs "approve & remember" distinction is a UI affordance on
- * top of the same `Approved` decision (the remember flag is carried
- * separately when the backend supports it); both resolve the suspended
- * call. The denied/override-rationale path is not yet implemented.
- */
-export enum ApprovalDecision {
-  Approved = 'approved',
-  Denied = 'denied',
-}
-
-/**
- * A pending approval as it appears in the cross-portal Approvals Center —
- * the request plus the portal/session context it was raised in. The
- * portal fields are first-class so the Portals surface can batch and group
- * approvals across portals without reshaping this model.
- */
-export interface ApprovalCenterItem {
-  /** Mirrors `request.id`; kept distinct so a Center may track its own row id. */
-  readonly id: string;
-  readonly request: ApprovalRequest;
-  /** Portal the approval was raised in (cross-portal context). */
-  readonly portalId?: string;
-  readonly portalName?: string;
-  /** Portal accent token (`var(--p-*)`) for the row glyph; optional. */
-  readonly portalAccentVar?: `var(--${string})`;
-  /** Session the suspended capability belongs to ("Open session"). */
-  readonly sessionId?: string;
-  readonly sessionTitle?: string;
-}
-
-/** True when the tier always demands an explicit Approve (no allow-once). */
-export function isExplicitApprovalTier(tier: CapabilityRiskTier): boolean {
-  // `critical` and `high` are explicit-only (critical always
-  // explicit; high uses the warning accent and skips allow-once-remember).
-  return tier === 'critical' || tier === 'high';
-}
-
-/** True when the request carries a multi-approver quorum. */
-export function isQuorum(req: ApprovalRequest): boolean {
-  return (req.requireApproverCount ?? 1) > 1;
-}

package/src/session-kit/approvals/index.ts

@@ -1,22 +0,0 @@
-/**
- * `@xemahq/ui-kernel/session-kit` approvals — the generic approval
- * primitive.
- *
- * Generic frame + scoped bodies + sticky bar + Approvals Center. Models on
- * the kernel contracts (`CapabilityRiskTier`, `PolicyObligationKind`) and
- * adds only the presentation contracts the kernel has no opinion on
- * (`ApprovalScopeKind` + scope union, `ApprovalDecision`). Every component
- * is icon-agnostic and prop-driven — the host supplies the icon bundle and
- * the data.
- */
-export * from './approval-model';
-export * from './obligation-display';
-export * from './scope-icons';
-export * from './risk-accent';
-export * from './approval-icons';
-export * from './ApprovalButton';
-export * from './Obligation';
-export * from './ScopedBody';
-export * from './ApprovalCard';
-export * from './CapabilityApprovalStickyBar';
-export * from './ApprovalsCenter';

package/src/session-kit/approvals/obligation-display.ts

@@ -1,100 +0,0 @@
-/**
- * Obligation → display metadata map.
- *
- * Covers ALL NINE obligation kinds in the kernel closed taxonomy —
- * `audit`, `redact-secrets`, `require-runner-kind`,
- * `require-human-approval`, `max-duration-seconds`, `max-cost-usd`,
- * `restrict-output-classification`, `data-residency`, `egress-allowlist`.
- *
- * The map is typed `Record<PolicyObligationKind, …>` so it is EXHAUSTIVE
- * over the installed kernel enum: adding a new `PolicyObligationKind`
- * member is a COMPILE ERROR here until it gets a label + icon key. The
- * published `@xemahq/kernel-contracts` enum now ships all nine members
- * (incl. `egress-allowlist`), so every kind is keyed directly by its enum
- * value — no literal-wire fallback is needed.
- *
- * The kit is icon-agnostic: this module names a stable `iconKey`
- * (`ObligationIcon`) and the host translates it into a concrete icon node
- * via the `Obligation`/`renderIcon` prop. No icon dependency leaks into
- * the kernel package.
- */
-import { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
-
-/**
- * Stable, icon-set-agnostic glyph keys for obligation chips. The host
- * maps each onto a concrete icon (lucide, etc.); the kit never imports an
- * icon set. Closed set — one key per obligation family.
- */
-export enum ObligationIcon {
-  Dollar = 'dollar',
-  ShieldCheck = 'shield-check',
-  Scroll = 'scroll',
-  Eye = 'eye',
-  Clock = 'clock',
-  Layers = 'layers',
-  Globe = 'globe',
-  Lock = 'lock',
-  Network = 'network',
-}
-
-export interface ObligationDisplayMeta {
-  readonly iconKey: ObligationIcon;
-  readonly label: string;
-}
-
-/**
- * Chip metadata for every member of the kernel `PolicyObligationKind`
- * enum. Typed as `Record<PolicyObligationKind, …>` so adding a new kernel
- * enum member is a COMPILE ERROR here until it gets a label + icon key —
- * the exhaustiveness guarantee.
- */
-const ENUM_OBLIGATION_DISPLAY: Record<
-  PolicyObligationKind,
-  ObligationDisplayMeta
-> = {
-  [PolicyObligationKind.MaxCostUsd]: {
-    iconKey: ObligationIcon.Dollar,
-    label: 'Spend cap',
-  },
-  [PolicyObligationKind.RequireHumanApproval]: {
-    iconKey: ObligationIcon.ShieldCheck,
-    label: 'Human approval',
-  },
-  [PolicyObligationKind.Audit]: {
-    iconKey: ObligationIcon.Scroll,
-    label: 'Audited',
-  },
-  [PolicyObligationKind.RestrictOutputClassification]: {
-    iconKey: ObligationIcon.Eye,
-    label: 'Output limited',
-  },
-  [PolicyObligationKind.MaxDurationSeconds]: {
-    iconKey: ObligationIcon.Clock,
-    label: 'Time cap',
-  },
-  [PolicyObligationKind.RequireRunnerKind]: {
-    iconKey: ObligationIcon.Layers,
-    label: 'Runner',
-  },
-  [PolicyObligationKind.DataResidency]: {
-    iconKey: ObligationIcon.Globe,
-    label: 'Residency',
-  },
-  [PolicyObligationKind.RedactSecrets]: {
-    iconKey: ObligationIcon.Lock,
-    label: 'Redacted',
-  },
-  [PolicyObligationKind.EgressAllowlist]: {
-    iconKey: ObligationIcon.Network,
-    label: 'Egress',
-  },
-};
-
-/**
- * The authoritative obligation-kind → chip metadata map, keyed by the
- * obligation wire-string. Exhaustive over the installed kernel enum via
- * `ENUM_OBLIGATION_DISPLAY` (compile-checked).
- */
-export const OBLIGATION_DISPLAY: Record<string, ObligationDisplayMeta> = {
-  ...ENUM_OBLIGATION_DISPLAY,
-};

package/src/session-kit/approvals/risk-accent.ts

@@ -1,47 +0,0 @@
-/**
- * Risk-tier → colour expressions for the approval frame's accent rail and
- * the sticky bar. RiskPill owns the PILL styling; this map is
- * the matching surface accent (foreground / soft background / border) the
- * frame and bar paint with. Both read the SAME kernel `CapabilityRiskTier`
- * enum so the pill and the rail can never disagree on a tier's colour.
- *
- *   low      → ink / muted   (quiet)
- *   medium   → --info
- *   high     → --warning
- *   critical → --destructive / --danger
- */
-import { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
-
-export interface RiskAccent {
-  /** Solid accent (rail, icon, critical button). */
-  readonly fg: string;
-  /** Soft tinted background (sticky bar surface). */
-  readonly bg: string;
-  /** Border (sticky bar, critical card outline). */
-  readonly bd: string;
-}
-
-const DANGER = 'var(--destructive, var(--danger))';
-
-export const RISK_ACCENT: Record<CapabilityRiskTier, RiskAccent> = {
-  [CapabilityRiskTier.Low]: {
-    fg: 'hsl(var(--ink-3))',
-    bg: 'hsl(var(--muted))',
-    bd: 'hsl(var(--rule))',
-  },
-  [CapabilityRiskTier.Medium]: {
-    fg: 'hsl(var(--info))',
-    bg: 'hsl(var(--info) / 0.07)',
-    bd: 'hsl(var(--info) / 0.28)',
-  },
-  [CapabilityRiskTier.High]: {
-    fg: 'hsl(var(--warning))',
-    bg: 'hsl(var(--warning) / 0.08)',
-    bd: 'hsl(var(--warning) / 0.3)',
-  },
-  [CapabilityRiskTier.Critical]: {
-    fg: `hsl(${DANGER})`,
-    bg: `hsl(${DANGER} / 0.07)`,
-    bd: `hsl(${DANGER} / 0.32)`,
-  },
-};

package/src/session-kit/approvals/scope-icons.ts

@@ -1,19 +0,0 @@
-/**
- * Stable, icon-set-agnostic glyph keys used by the scoped approval bodies
- * (`ScopedBody`). Kept in its own module (not alongside the body
- * components) so the icon bundle and the bodies can both import it without
- * a component file also exporting a non-component value.
- */
-import type { ReactNode } from 'react';
-
-export enum ScopeIcon {
-  Database = 'database',
-  Layers = 'layers',
-  Alert = 'alert',
-  Send = 'send',
-  Globe = 'globe',
-  ArrowRight = 'arrow-right',
-  FileEdit = 'file-edit',
-}
-
-export type ScopeIconRenderer = (key: ScopeIcon, size: number) => ReactNode;