@a5c-ai/krate 5.0.1-staging.00fa5317c

package/src/kubernetes-resource-gateway.js

@@ -0,0 +1,48 @@
+import { createKubernetesResourceClient, repositoryManifest } from './kubernetes-controller.js';
+
+export const KUBERNETES_RESOURCE_GATEWAY_BOUNDARY = {
+  role: 'kubernetes-resource-gateway',
+  scope: 'Application port translating API controller intent into Kubernetes resource-client operations',
+  owns: ['resource definitions', 'list/get/apply/delete/watch delegation', 'Repository manifest application', 'namespace scoping'],
+  delegatesTo: ['kubernetes-resource-client'],
+  mustNotOwn: ['HTTP routes', 'Next.js page flow decisions', 'forge DTO composition', 'Kubernetes reconciliation scheduling']
+};
+
+export function createKubernetesResourceGateway(options = {}) {
+  const resourceClient = options.resourceClient || options.kubernetesClient || createKubernetesResourceClient(options);
+  const namespace = options.namespace || resourceClient.namespace || process.env.KRATE_NAMESPACE || 'krate-system';
+
+  return {
+    ...KUBERNETES_RESOURCE_GATEWAY_BOUNDARY,
+    namespace,
+    resourceDefinitions: resourceClient.resourceDefinitions,
+    async snapshot() {
+      return resourceClient.snapshot();
+    },
+    async list(kindOrPlural) {
+      return resourceClient.listResource(kindOrPlural);
+    },
+    async get(kindOrPlural, name) {
+      return resourceClient.getResource(kindOrPlural, name);
+    },
+    async apply(resource) {
+      return resourceClient.applyResource(resource);
+    },
+    async delete(kindOrPlural, name) {
+      return resourceClient.deleteResource(kindOrPlural, name);
+    },
+    async createRepository(input) {
+      return resourceClient.applyResource(repositoryManifest(input, namespace));
+    },
+    async createOrganization(input) {
+      return resourceClient.createOrganization(input);
+    },
+    watch(resourcePath, handlers = {}) {
+      return resourceClient.watchResource(resourcePath, handlers);
+    }
+  };
+}
+
+
+
+

package/src/notification-controller.js

@@ -0,0 +1,178 @@
+import { randomUUID } from 'node:crypto';
+
+export const NOTIFICATION_CONTROLLER_BOUNDARY = {
+  role: 'notification-controller',
+  scope: 'User notification lifecycle: creation from events, querying, read state, and preferences',
+  owns: ['notification creation', 'notification listing', 'read state', 'user preferences'],
+  delegatesTo: [],
+  mustNotOwn: ['event dispatch', 'UI rendering', 'push delivery']
+};
+
+const NOTIFICATION_TYPES = {
+  'run-complete': { severity: 'info' },
+  'approval-needed': { severity: 'warning' },
+  'conflict-detected': { severity: 'warning' },
+  'workspace-ready': { severity: 'info' },
+  'system': { severity: 'info' },
+};
+
+const DEFAULT_PREFERENCES = {
+  runs: true,
+  approvals: true,
+  conflicts: true,
+  workspaces: true,
+  sound: false,
+  desktop: false,
+};
+
+export function createNotificationController() {
+  // Map of org -> notifications[]
+  const store = new Map();
+  // Map of userId -> preferences
+  const prefsStore = new Map();
+
+  function getOrgNotifications(org) {
+    if (!store.has(org)) store.set(org, []);
+    return store.get(org);
+  }
+
+  function mapEventToNotification(event) {
+    const { type, status, name, action, resourceRef, org = 'default' } = event || {};
+
+    let notifType = 'system';
+    let title = 'System event';
+    let message = '';
+    let severity = 'info';
+
+    if (type === 'AgentDispatchRun') {
+      notifType = 'run-complete';
+      const runName = name || event?.metadata?.name || 'Unknown';
+      if (status === 'completed') {
+        title = `Run ${runName} completed`;
+        message = `Agent dispatch run "${runName}" completed successfully.`;
+        severity = 'info';
+      } else if (status === 'failed') {
+        title = `Run ${runName} failed`;
+        message = `Agent dispatch run "${runName}" failed.`;
+        severity = 'error';
+      } else {
+        title = `Run ${runName} updated`;
+        message = `Agent dispatch run "${runName}" status: ${status || 'unknown'}.`;
+        severity = 'info';
+      }
+    } else if (type === 'AgentApproval' && status === 'pending') {
+      notifType = 'approval-needed';
+      const actionLabel = action || event?.spec?.action || 'unknown action';
+      title = `Approval needed for ${actionLabel}`;
+      message = `An agent is requesting approval for: ${actionLabel}.`;
+      severity = 'warning';
+    } else if (type === 'ExternalSyncConflict') {
+      notifType = 'conflict-detected';
+      const resource = resourceRef || event?.spec?.resourceRef || name || 'unknown resource';
+      title = `Conflict in ${resource}`;
+      message = `A sync conflict was detected in resource: ${resource}.`;
+      severity = 'warning';
+    } else if (type === 'KrateWorkspace' && event?.claimed) {
+      notifType = 'workspace-ready';
+      const wsName = name || event?.metadata?.name || 'Unknown';
+      const runRef = event?.claimedBy || event?.spec?.claimedBy || 'a run';
+      title = `Workspace ${wsName} claimed by ${runRef}`;
+      message = `Workspace "${wsName}" has been claimed by "${runRef}".`;
+      severity = 'info';
+    }
+
+    return { notifType, title, message, severity, org };
+  }
+
+  return {
+    role: 'notification-controller',
+
+    createNotification(event) {
+      const { notifType, title, message, severity, org } = mapEventToNotification(event);
+
+      const notification = {
+        id: randomUUID(),
+        type: notifType,
+        title,
+        message,
+        severity,
+        resourceRef: event?.resourceRef || null,
+        createdAt: new Date().toISOString(),
+        read: false,
+        org,
+      };
+
+      const notifications = getOrgNotifications(org);
+      notifications.push(notification);
+
+      return notification;
+    },
+
+    listNotifications(org, opts = {}) {
+      const { unreadOnly = false, limit = 20, since = null } = opts;
+      let notifications = [...getOrgNotifications(org)];
+
+      // Filter by read state
+      if (unreadOnly) {
+        notifications = notifications.filter((n) => !n.read);
+      }
+
+      // Filter by since timestamp
+      if (since) {
+        const sinceDate = new Date(since).getTime();
+        notifications = notifications.filter((n) => new Date(n.createdAt).getTime() > sinceDate);
+      }
+
+      // Newest first
+      notifications.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+
+      // Cap to limit
+      if (limit > 0) {
+        notifications = notifications.slice(0, limit);
+      }
+
+      return notifications;
+    },
+
+    markAsRead(notificationId) {
+      for (const notifications of store.values()) {
+        const notification = notifications.find((n) => n.id === notificationId);
+        if (notification) {
+          notification.read = true;
+          return true;
+        }
+      }
+      return false;
+    },
+
+    markAllAsRead(org) {
+      const notifications = getOrgNotifications(org);
+      let count = 0;
+      for (const notification of notifications) {
+        if (!notification.read) {
+          notification.read = true;
+          count++;
+        }
+      }
+      return count;
+    },
+
+    getUnreadCount(org) {
+      return getOrgNotifications(org).filter((n) => !n.read).length;
+    },
+
+    getPreferences(userId) {
+      if (!prefsStore.has(userId)) {
+        return { ...DEFAULT_PREFERENCES };
+      }
+      return { ...DEFAULT_PREFERENCES, ...prefsStore.get(userId) };
+    },
+
+    updatePreferences(userId, prefs) {
+      const existing = prefsStore.get(userId) || {};
+      const merged = { ...DEFAULT_PREFERENCES, ...existing, ...prefs };
+      prefsStore.set(userId, merged);
+      return merged;
+    },
+  };
+}

package/src/operations.js

@@ -0,0 +1,112 @@
+import { ControlPlane } from './control-plane.js';
+import { GiteaGitService, GiteaRepositoryStore } from './data-plane.js';
+import { WebhookBus } from './hooks-events.js';
+import { RunnerScheduler } from './runners-ci.js';
+import { createAdmissionPolicy, mapOidcIdentity, toResourceYaml } from './identity-policy.js';
+import { createResource } from './resource-model.js';
+import { createDashboard, createPullRequestReviewModel, createRunnerPoolEditor, createTriageView, createWebhookInspector } from './web-ui.js';
+import { createKrateComponentCatalog, createKrateLifecycleSnapshot } from './component-catalog.js';
+
+export function chartPackageSurface() {
+  return {
+    chart: 'charts/krate',
+    values: 'charts/krate/values.yaml',
+    crds: ['Repository', 'BranchProtection', 'RefPolicy', 'RunnerPool', 'WebhookSubscription', 'View', 'Selector'],
+    templates: ['CRDs', 'optional APIService', 'ServiceAccount', 'ClusterRole', 'ClusterRoleBinding', 'Deployment', 'Service', 'NetworkPolicy', 'Gitea backend', 'Argo CD Application'],
+    examples: ['examples/minikube-demo.yaml', 'examples/policy-kyverno-pr-title.yaml'],
+    validation: ['npm run e2e', 'npm run package:check', 'npm run setup:minikube -- --dry-run']
+  };
+}
+
+export function localSetupPlan() {
+  return {
+    script: 'scripts/setup-minikube.mjs',
+    defaultMode: 'dry-run',
+    applyMode: 'npm run setup:minikube -- --apply',
+    requiredTools: ['minikube', 'kubectl', 'helm', 'node', 'npm'],
+    defaultProfile: 'krate',
+    namespace: 'krate-system'
+  };
+}
+
+export function generateInstallManifests({ namespace = 'krate-system' } = {}) {
+  const manifests = [
+    { apiVersion: 'apiregistration.k8s.io/v1', kind: 'APIService', metadata: { name: 'v1alpha1.krate.a5c.ai' }, spec: { group: 'krate.a5c.ai', version: 'v1alpha1', service: { namespace, name: 'krate-api' } } },
+    { apiVersion: 'apps/v1', kind: 'Deployment', metadata: { name: 'krate-api', namespace }, spec: { replicas: 2, template: { spec: { containers: [{ name: 'api', image: 'krate/api:dev' }] } } } },
+    { apiVersion: 'apps/v1', kind: 'Deployment', metadata: { name: 'krate-gitea', namespace, labels: { 'app.kubernetes.io/component': 'gitea-backend' } }, spec: { replicas: 1, template: { spec: { containers: [{ name: 'gitea', image: 'gitea/gitea:1.22-rootless' }] } } } },
+    { apiVersion: 'argoproj.io/v1alpha1', kind: 'Application', metadata: { name: 'krate', namespace: 'argocd' }, spec: { source: { repoURL: 'https://gitea-http.krate-system.svc.cluster.local/krate/platform-config.git', path: 'charts/krate', targetRevision: 'main' }, destination: { namespace, server: 'https://kubernetes.default.svc' }, syncPolicy: { automated: { prune: true, selfHeal: true } } } },
+    { apiVersion: 'apps/v1', kind: 'Deployment', metadata: { name: 'krate-web', namespace }, spec: { replicas: 1 } }
+  ];
+  return manifests.map((manifest) => `---\n${toResourceYaml(manifest)}`).join('\n');
+}
+
+export function backupPlan() {
+  return { resources: ['CRDs and low-cardinality config', 'Postgres aggregated records', 'repository storage', 'object storage'], restoreOrder: ['API/config', 'Postgres', 'repository data', 'objects', 'controllers'], validation: ['list resources', 'read Gitea repository refs', 'open PR', 'replay webhook delivery'] };
+}
+
+export function observabilityModel() {
+  return {
+    metrics: ['api_request_latency', 'postgres_aggregate_lag', 'gitea_receive_pack_latency', 'runner_queue_depth', 'webhook_delivery_phase', 'admission_denials'],
+    logs: ['control-plane audit', 'gitea access', 'runner job', 'webhook dispatcher', 'controller reconcile'],
+    alerts: ['APIService unavailable', 'Postgres unavailable', 'repository service unavailable', 'runner saturation', 'webhook failure burst', 'backup validation failed']
+  };
+}
+
+export function releaseGates() {
+  return ['build', 'docs and ontology coverage', 'unit acceptance tests', 'e2e package lifecycle tests', 'package validation', 'minikube dry-run setup', 'smoke flow', 'backup restore validation', 'known limitations reviewed'];
+}
+
+export function createKrateMvpDemo() {
+  const platformEngineer = mapOidcIdentity({ subject: 'user:platform', email: 'platform@example.com', groups: ['krate:platform-engineers'] });
+  const developer = mapOidcIdentity({ subject: 'user:dev', email: 'dev@example.com', groups: ['krate:developers'] });
+  const repoAdmin = mapOidcIdentity({ subject: 'user:admin', email: 'admin@example.com', groups: ['krate:repo-admins'] });
+  const organizationRef = 'default';
+  const namespace = 'krate-org-default';
+  const controlPlane = new ControlPlane();
+  controlPlane.addAdmissionPolicy(createAdmissionPolicy({ name: 'pr-title-required', mode: 'enforce', match: ({ resource }) => resource.kind === 'PullRequest', validate: ({ resource }) => Boolean(resource.spec.title && resource.spec.title.length >= 8), message: 'PullRequest spec.title must be descriptive' }));
+  const git = new GiteaGitService({ controlPlane, stores: [new GiteaRepositoryStore({ name: 'gitea-primary', receivePackReady: true })] });
+  const runners = new RunnerScheduler({ controlPlane });
+  const webhooks = new WebhookBus({ controlPlane });
+  const repository = git.createRepository({ name: 'krate-demo', namespace, organizationRef }, repoAdmin);
+  const branchProtection = controlPlane.create(createResource('BranchProtection', { name: 'main-protection', namespace }, { organizationRef, refs: ['refs/heads/main'], requirePullRequest: true }), repoAdmin);
+  const refPolicy = controlPlane.create(createResource('RefPolicy', { name: 'deny-internal-refs', namespace }, { organizationRef, deny: ['refs/internal/'] }), repoAdmin);
+  const runnerPool = runners.createRunnerPool({ name: 'trusted-linux', namespace, organizationRef, warmReplicas: 1, maxReplicas: 4 }, platformEngineer);
+  const subscription = webhooks.subscribe({ name: 'chatops', namespace, organizationRef, url: 'https://hooks.example.test/krate', events: ['pullrequest.created'] }, repoAdmin);
+  const pullRequest = controlPlane.create(createResource('PullRequest', { name: 'pr-1', namespace, labels: { repository: 'krate-demo' } }, { organizationRef, repository: 'krate-demo', sourceRef: 'refs/heads/feature', targetRef: 'refs/heads/main', title: 'Add Kubernetes-native forge smoke path' }, { phase: 'Open' }), developer);
+  const pipelineRun = runners.startPipeline({ name: 'pipeline-pr-1', namespace, organizationRef, repository: 'krate-demo', ref: 'refs/pull/1/head', actor: developer, fork: false }, developer);
+  const delivery = webhooks.deliver({ subscriptionName: 'chatops', namespace, organizationRef, eventType: 'pullrequest.created', payload: { pullRequest: pullRequest.metadata.name, repository: 'krate-demo' } }, repoAdmin);
+  const replay = webhooks.replay(delivery, repoAdmin);
+  const triageView = controlPlane.create(createTriageView({ name: 'priority-triage', namespace, organizationRef, selector: { labels: { priority: 'high' } } }), repoAdmin);
+  const demo = {
+    users: { platformEngineer, developer, repoAdmin }, controlPlane, git, runners, webhooks,
+    resources: { repository, branchProtection, refPolicy, runnerPool, subscription, pullRequest, pipelineRun, delivery, replay, triageView },
+    ui: { dashboard: createDashboard({ repositories: [repository], pullRequests: [pullRequest], pipelines: [pipelineRun.pipeline], runnerPools: [runnerPool], webhookDeliveries: [delivery, replay] }), review: createPullRequestReviewModel({ pullRequest, changedFiles: ['src/index.js'], pipelineRuns: [pipelineRun.pipeline] }), runnerPoolEditor: createRunnerPoolEditor(runnerPool), webhookInspector: createWebhookInspector({ subscription, deliveries: [delivery, replay] }) },
+    operations: { installManifests: generateInstallManifests(), chartPackage: chartPackageSurface(), localSetup: localSetupPlan(), backupPlan: backupPlan(), observability: observabilityModel(), releaseGates: releaseGates() }
+  };
+  demo.components = createKrateComponentCatalog(demo);
+  demo.lifecycle = createKrateLifecycleSnapshot(demo);
+  return demo;
+}
+
+export function runSmokeAssertions(demo = createKrateMvpDemo()) {
+  const storage = demo.controlPlane.storageReport();
+  const assertions = [
+    ['Repository stored as CRD/etcd config', storage.etcd.includes('Repository')],
+    ['PullRequest stored as aggregated/Postgres record', storage.postgres.includes('PullRequest')],
+    ['RunnerPool stored as CRD/etcd configuration', storage.etcd.includes('RunnerPool')],
+    ['WebhookDelivery stored as aggregated/Postgres record', storage.postgres.includes('WebhookDelivery')],
+    ['Gitea receive path is ready', demo.git.route('krate-demo').backend === 'gitea' && demo.git.route('krate-demo').receivePackReady],
+    ['Repository exposes Gitea integration plan', demo.resources.repository.spec.gitHosting.backend === 'gitea' && demo.resources.repository.spec.gitHosting.integrationPlan.backend === 'gitea'],
+    ['UI exposes YAML for PR review', demo.ui.review.yaml.includes('kind: PullRequest')],
+    ['Install manifests expose Kubernetes API discovery', demo.operations.installManifests.includes('kind: APIService') || demo.operations.chartPackage.crds.includes('Repository')],
+    ['Chart package exposes CRDs', demo.operations.chartPackage.crds.includes('Repository')],
+    ['Local setup defaults to dry-run minikube flow', demo.operations.localSetup.defaultMode === 'dry-run'],
+    ['Release gates include docs and ontology coverage', demo.operations.releaseGates.includes('docs and ontology coverage')],
+    ['Release gates include e2e package lifecycle tests', demo.operations.releaseGates.includes('e2e package lifecycle tests')],
+    ['Observability tracks webhook delivery phase', demo.operations.observability.metrics.includes('webhook_delivery_phase')],
+    ['Component catalog covers every implementation area', demo.components.every((component) => component.implemented)],
+    ['Lifecycle snapshot is ready for local development', demo.lifecycle.status === 'ready-for-local-development']
+  ];
+  return { ok: assertions.every(([, passed]) => passed), assertions };
+}
+

package/src/org-scoping.js

@@ -0,0 +1,5 @@
+// Dedicated org-scoping module — re-exports the org namespace derivation
+// function so callers can depend on it without pulling in the full
+// kubernetes-controller surface.
+
+export { orgNamespaceName, normalizeOrgSlug, resolveResourceOrg, withOrgScope } from './kubernetes-controller.js';

package/src/resource-model.js

@@ -0,0 +1,221 @@
+export const CONFIG_KINDS = new Set(['Organization', 'OrgNamespaceBinding', 'User', 'Team', 'Invite', 'IdentityMapping', 'AuthProvider', 'Repository', 'SSHKey', 'RepositoryPermission', 'WebhookSubscription', 'RefPolicy', 'BranchProtection', 'PolicyProfile', 'PolicyTemplate', 'PolicyBinding', 'PolicyExceptionRequest', 'RunnerPool', 'View', 'Selector', 'AgentStack', 'AgentSubagent', 'AgentToolProfile', 'AgentMcpServer', 'AgentSkill', 'AgentTriggerRule', 'AgentContextLabel', 'KrateWorkspacePolicy', 'AgentServiceAccount', 'AgentRoleBinding', 'AgentSecretGrant', 'AgentConfigGrant', 'AgentAdapter', 'AgentTransportBinding', 'AgentProviderConfig', 'KrateProject', 'AgentGatewayConfig', 'AgentMemoryRepository', 'AgentMemorySource', 'AgentMemoryOntology', 'AgentMemoryAssociation', 'KrateWorkspace', 'ExternalBackendProvider', 'ExternalBackendBinding', 'ExternalBackendSyncPolicy', 'ExternalProviderCapabilityManifest']);
+export const AGGREGATED_KINDS = new Set(['PullRequest', 'Issue', 'Review', 'Pipeline', 'Job', 'WebhookDelivery', 'AgentDispatchRun', 'AgentDispatchAttempt', 'AgentSession', 'AgentContextBundle', 'KrateArtifact', 'AgentApproval', 'AgentTriggerExecution', 'AgentCapabilityRequirement', 'WorkItemSessionLink', 'WorkItemWorkspaceLink', 'AgentSessionTranscript', 'AgentSessionAttachment', 'KrateWorkspaceRuntime', 'AgentMemorySnapshot', 'AgentMemoryQuery', 'AgentMemoryUpdate', 'AgentRunMemoryImport', 'ExternalWebhookDelivery', 'ExternalSyncEvent', 'ExternalSyncState', 'ExternalWriteIntent', 'ExternalSyncConflict', 'ExternalObjectLink']);
+export const ALL_KINDS = new Set([...CONFIG_KINDS, ...AGGREGATED_KINDS]);
+
+export const RESOURCE_DEFINITIONS = Object.freeze({
+  Organization: { storage: 'etcd', context: 'identity', plural: 'organizations', purpose: 'Krate organization identity in the platform namespace with a bound tenant namespace', requiredSpec: ['displayName', 'namespaceName'] },
+  OrgNamespaceBinding: { storage: 'etcd', context: 'identity', plural: 'orgnamespacebindings', purpose: 'Binding from one organization to exactly one tenant namespace for resources and side effects', requiredSpec: ['organizationRef', 'namespace'] },
+  User: { storage: 'etcd', context: 'identity', plural: 'users', purpose: 'Human account profile, sign-in state, admin flag, and linked identities', requiredSpec: ['organizationRef', 'displayName', 'email'] },
+  Team: { storage: 'etcd', context: 'identity', plural: 'teams', purpose: 'Team membership, maintainers, and repository permission grants', requiredSpec: ['organizationRef', 'displayName'] },
+  Invite: { storage: 'etcd', context: 'identity', plural: 'invites', purpose: 'Pending user invitation with requested teams and expiry', requiredSpec: ['organizationRef', 'email', 'role'] },
+  IdentityMapping: { storage: 'etcd', context: 'identity', plural: 'identitymappings', purpose: 'Mapping between Krate users, sign-in subjects, workspace identities, and repository accounts', requiredSpec: ['organizationRef', 'user', 'provider', 'subject'] },
+  AuthProvider: { storage: 'etcd', context: 'identity', plural: 'authproviders', purpose: 'Installation sign-in provider visibility and delegated identity settings', requiredSpec: ['organizationRef', 'type'] },
+  Repository: { storage: 'etcd', context: 'data-plane', plural: 'repositories', purpose: 'Repository identity, visibility, repository hosting integration, object storage, and search settings', requiredSpec: ['organizationRef', 'visibility'] },
+  SSHKey: { storage: 'etcd', context: 'data-plane', plural: 'sshkeys', purpose: 'User, deploy, and automation SSH keys reconciled into repository key APIs', requiredSpec: ['organizationRef', 'scope', 'key'] },
+  RepositoryPermission: { storage: 'etcd', context: 'data-plane', plural: 'repositorypermissions', purpose: 'Repository collaborators and teams synced with repository permissions', requiredSpec: ['organizationRef', 'repository', 'subject', 'permission'] },
+  WebhookSubscription: { storage: 'etcd', context: 'hooks-events', plural: 'webhooksubscriptions', purpose: 'Endpoint, event filters, signing reference, delivery mode, and retry policy', requiredSpec: ['organizationRef', 'url', 'events'] },
+  RefPolicy: { storage: 'etcd', context: 'data-plane', plural: 'refpolicies', purpose: 'Reference deny rules, force-push policy, signing policy, and future custom hook gates', requiredSpec: ['organizationRef'] },
+  BranchProtection: { storage: 'etcd', context: 'control-plane', plural: 'branchprotections', purpose: 'Protected ref rules such as pull-request requirements', requiredSpec: ['organizationRef', 'refs'] },
+  PolicyProfile: { storage: 'etcd', context: 'policy', plural: 'policyprofiles', purpose: 'Organization policy posture, default templates, rollout mode, and exception approval rules', requiredSpec: ['organizationRef', 'displayName', 'mode'] },
+  PolicyTemplate: { storage: 'etcd', context: 'policy', plural: 'policytemplates', purpose: 'Curated Kyverno policy template metadata, parameters, rollout defaults, and remediation guidance', requiredSpec: ['displayName', 'targetKinds', 'kyverno'] },
+  PolicyBinding: { storage: 'etcd', context: 'policy', plural: 'policybindings', purpose: 'Binding from a policy template to org, repository, environment, or resource selectors with audit/enforce rollout state', requiredSpec: ['organizationRef', 'templateRef', 'mode'] },
+  PolicyExceptionRequest: { storage: 'etcd', context: 'policy', plural: 'policyexceptionrequests', purpose: 'Auditable request and approval workflow for temporary Kyverno PolicyException resources', requiredSpec: ['organizationRef', 'policyRef', 'justification', 'expiresAt'] },
+  View: { storage: 'etcd', context: 'web-ui', plural: 'views', purpose: 'Saved triage and dashboard view backed by resource selectors', requiredSpec: ['organizationRef', 'selector'] },
+  Selector: { storage: 'etcd', context: 'web-ui', plural: 'selectors', purpose: 'Reusable label/query selector for workflows and views', requiredSpec: ['organizationRef'] },
+  PullRequest: { storage: 'postgres', context: 'control-plane', plural: 'pullrequests', purpose: 'Review unit with source/target refs, title, checks, and merge lifecycle', requiredSpec: ['organizationRef', 'repository', 'title'] },
+  Issue: { storage: 'postgres', context: 'control-plane', plural: 'issues', purpose: 'Project-scoped work item with labels, comments, backend sync metadata, and zero-or-more repository associations', requiredSpec: ['organizationRef', 'title'] },
+  Review: { storage: 'postgres', context: 'control-plane', plural: 'reviews', purpose: 'Approval, comment, or change-request record for a pull request', requiredSpec: ['organizationRef', 'pullRequest'] },
+  Pipeline: { storage: 'postgres', context: 'runners-ci', plural: 'pipelines', purpose: 'CI pipeline run state, trust tier, steps, and resume point', requiredSpec: ['organizationRef', 'repository', 'ref'] },
+  Job: { storage: 'postgres', context: 'runners-ci', plural: 'jobs', purpose: 'Executable CI step with service-account scope and isolation metadata', requiredSpec: ['organizationRef', 'pipeline', 'step'] },
+  RunnerPool: { storage: 'etcd', context: 'runners-ci', plural: 'runnerpools', purpose: 'Runner capacity, warm/max replicas, cache policy, and trust boundary', requiredSpec: ['organizationRef', 'warmReplicas', 'maxReplicas'] },
+  WebhookDelivery: { storage: 'postgres', context: 'hooks-events', plural: 'webhookdeliveries', purpose: 'Durable outbound webhook delivery attempt with signature, phase, response, and replay metadata', requiredSpec: ['organizationRef', 'subscription', 'eventType', 'signature'] },
+  AgentStack: { storage: 'etcd', context: 'agents', plural: 'agentstacks', purpose: 'Reusable agent definition with model, prompt, tools, MCP servers, skills, subagents, approval mode, and runner policy', requiredSpec: ['organizationRef', 'baseAgent', 'adapter', 'runtimeIdentity'] },
+  AgentSubagent: { storage: 'etcd', context: 'agents', plural: 'agentsubagents', purpose: 'Named child-agent definition with role, task kinds, tool subset, and workspace scope', requiredSpec: ['organizationRef', 'rolePrompt', 'taskKinds'] },
+  AgentToolProfile: { storage: 'etcd', context: 'agents', plural: 'agenttoolprofiles', purpose: 'Native tool policy for filesystem, network, shell, and approval gates', requiredSpec: ['organizationRef', 'filesystemPolicy', 'approvalPolicyByTool'] },
+  AgentMcpServer: { storage: 'etcd', context: 'agents', plural: 'agentmcpservers', purpose: 'Managed MCP endpoint with transport, discovery, health, and secret/config refs', requiredSpec: ['organizationRef', 'transport', 'scope'] },
+  AgentSkill: { storage: 'etcd', context: 'agents', plural: 'agentskills', purpose: 'Reusable runbook/procedure bundle with prompt fragments, tool deps, and output contracts', requiredSpec: ['organizationRef', 'format', 'sourceRef'] },
+  AgentTriggerRule: { storage: 'etcd', context: 'agents', plural: 'agenttriggerrules', purpose: 'Event-to-stack routing for CI failures, webhooks, comments, labels, schedules, and manual dispatch', requiredSpec: ['organizationRef', 'sources', 'agentStack', 'taskKind'] },
+  AgentContextLabel: { storage: 'etcd', context: 'agents', plural: 'agentcontextlabels', purpose: 'Reviewed prompt fragment with provenance and allowlisted sources', requiredSpec: ['organizationRef', 'promptFragment', 'allowedSources'] },
+  KrateWorkspacePolicy: { storage: 'etcd', context: 'agents', plural: 'krateworkspacepolicies', purpose: 'Git worktree provisioning, cleanup, retention, and trust tier policies', requiredSpec: ['organizationRef', 'mode', 'retentionPolicy'] },
+  AgentServiceAccount: { storage: 'etcd', context: 'identity', plural: 'agentserviceaccounts', purpose: 'Kubernetes ServiceAccount wrapper for agent/runner identity binding', requiredSpec: ['organizationRef', 'namespace', 'serviceAccountName'] },
+  AgentRoleBinding: { storage: 'etcd', context: 'identity', plural: 'agentrolebindings', purpose: 'Managed projection to native Kubernetes RBAC for agent identity', requiredSpec: ['organizationRef', 'subject', 'roleRef', 'scope'] },
+  AgentSecretGrant: { storage: 'etcd', context: 'identity', plural: 'agentsecretgrants', purpose: 'Explicit permission for subject to access Secret keys with purpose scope', requiredSpec: ['organizationRef', 'subject', 'secretRef', 'purpose'] },
+  AgentConfigGrant: { storage: 'etcd', context: 'identity', plural: 'agentconfiggrants', purpose: 'Explicit permission for subject to access ConfigMap keys with purpose scope', requiredSpec: ['organizationRef', 'subject', 'configMapRef', 'purpose'] },
+  AgentDispatchRun: { storage: 'postgres', context: 'agents', plural: 'agentdispatchruns', purpose: 'Logical CI-like run visible beside Pipeline/Job records with queue, status, workspace, and cost', requiredSpec: ['organizationRef', 'repository', 'sourceRefs', 'agentStack', 'taskKind'] },
+  AgentDispatchAttempt: { storage: 'postgres', context: 'agents', plural: 'agentdispatchattempts', purpose: 'Concrete execution attempt with reason, stack snapshot, and runtime state', requiredSpec: ['organizationRef', 'agentDispatchRun', 'attemptReason', 'agentStackSnapshot'] },
+  AgentSession: { storage: 'postgres', context: 'agents', plural: 'agentsessions', purpose: 'Krate projection of Agent Mux chat/session with lifecycle state', requiredSpec: ['organizationRef', 'agentMuxSessionId', 'dispatchRun'] },
+  AgentContextBundle: { storage: 'postgres', context: 'agents', plural: 'agentcontextbundles', purpose: 'Immutable prompt/context snapshot with digest, provenance, and redaction manifest', requiredSpec: ['organizationRef', 'dispatchRun', 'digest', 'sources'] },
+  KrateArtifact: { storage: 'postgres', context: 'agents', plural: 'krateartifacts', purpose: 'Durable agent output with kind, digest, and retention policy', requiredSpec: ['organizationRef', 'dispatchRun', 'kind', 'digest'] },
+  AgentApproval: { storage: 'postgres', context: 'agents', plural: 'agentapprovals', purpose: 'Human gate for tools, secrets, write-back, and release actions', requiredSpec: ['organizationRef', 'dispatchRun', 'action', 'requestedBy'] },
+  KrateWorkspace: { storage: 'etcd', context: 'workspaces', plural: 'krateworkspaces', purpose: 'Volume-backed git workspace with PVC lifecycle, repo binding, and runner mount spec', requiredSpec: ['organizationRef', 'repository', 'volumeSpec'] },
+  AgentTriggerExecution: { storage: 'postgres', context: 'agents', plural: 'agenttriggerexecutions', purpose: 'Durable trigger evaluation record with dedupe, coalescing, and rejection reason', requiredSpec: ['organizationRef', 'triggerRule', 'sourceEvent', 'decision'] },
+  AgentCapabilityRequirement: { storage: 'postgres', context: 'agents', plural: 'agentcapabilityrequirements', purpose: 'Computed dependency record from tools, MCP, skills, models, and subagents', requiredSpec: ['organizationRef', 'ownerRef', 'requiredRoles'] },
+  WorkItemSessionLink: { storage: 'postgres', context: 'agents', plural: 'workitemsessionlinks', purpose: 'Association between issues/PRs and agent sessions', requiredSpec: ['organizationRef', 'workItemRef', 'agentSession'] },
+  WorkItemWorkspaceLink: { storage: 'postgres', context: 'agents', plural: 'workitemworkspacelinks', purpose: 'Association between issues/PRs and agent workspaces', requiredSpec: ['organizationRef', 'workItemRef', 'workspace'] },
+  AgentAdapter: { storage: 'etcd', context: 'agents', plural: 'agentadapters', purpose: 'Agent adapter definition with transport type, capabilities matrix, auth requirements, and installation method', requiredSpec: ['organizationRef', 'adapterType', 'transport'] },
+  AgentTransportBinding: { storage: 'etcd', context: 'agents', plural: 'agenttransportbindings', purpose: 'Connection configuration for an adapter instance with endpoint, protocol, auth, health check, and reconnect policy', requiredSpec: ['organizationRef', 'adapterRef', 'endpoint', 'protocol'] },
+  AgentProviderConfig: { storage: 'etcd', context: 'agents', plural: 'agentproviderconfigs', purpose: 'Model provider configuration with API base, auth type, default model, model translations, and rate limits', requiredSpec: ['organizationRef', 'provider', 'authType'] },
+  KrateProject: { storage: 'etcd', context: 'agents', plural: 'krateprojects', purpose: 'Org project grouping issues, linked repositories, kanban board config, default workflow, and backend sync refs', requiredSpec: ['organizationRef', 'displayName'] },
+  AgentGatewayConfig: { storage: 'etcd', context: 'agents', plural: 'agentgatewayconfigs', purpose: 'Runtime Agent Mux gateway connection settings with URL, auth, reconnect policy, and feature flags', requiredSpec: ['organizationRef', 'gatewayUrl'] },
+  AgentSessionTranscript: { storage: 'postgres', context: 'agents', plural: 'agentsessiontranscripts', purpose: 'Durable chat transcript with message nodes, pagination support, and cost per turn', requiredSpec: ['organizationRef', 'sessionRef', 'messages'] },
+  AgentSessionAttachment: { storage: 'postgres', context: 'agents', plural: 'agentsessionattachments', purpose: 'File attached to a session message with source type, MIME type, digest, and redaction status', requiredSpec: ['organizationRef', 'sessionRef', 'sourceType', 'digest'] },
+  KrateWorkspaceRuntime: { storage: 'postgres', context: 'agents', plural: 'krateworkspaceruntimes', purpose: 'Workspace runtime surface state with cwd, environment variables, process status, and preview URL', requiredSpec: ['organizationRef', 'workspaceRef', 'status'] },
+  AgentMemoryRepository: { storage: 'etcd', context: 'agents', plural: 'agentmemoryrepositories', purpose: 'Org-level Git repository pointer for shared agent memory with layout profile and index policy', requiredSpec: ['organizationRef', 'repositoryRef', 'defaultBranch', 'layoutProfile'] },
+  AgentMemorySource: { storage: 'etcd', context: 'agents', plural: 'agentmemorysources', purpose: 'Read policy for memory paths and kinds per repository, team, stack, or trigger', requiredSpec: ['organizationRef', 'repositoryRef', 'appliesTo', 'include'] },
+  AgentMemoryOntology: { storage: 'etcd', context: 'agents', plural: 'agentmemoryontologies', purpose: 'Ontology policy pointer with required fields, edge kinds, and controlled vocabulary', requiredSpec: ['organizationRef', 'memoryRepository', 'ontologyPath'] },
+  AgentMemoryAssociation: { storage: 'etcd', context: 'agents', plural: 'agentmemoryassociations', purpose: 'Bridge record linking memory content to Krate resources by relationship type', requiredSpec: ['organizationRef', 'memoryRef', 'targetRef', 'relationship'] },
+  AgentMemorySnapshot: { storage: 'postgres', context: 'agents', plural: 'agentmemorysnapshots', purpose: 'Immutable dispatch-time memory pin with resolved commit, query manifest digest, and selected records digest', requiredSpec: ['organizationRef', 'memoryRepository', 'requestedRef', 'resolvedCommit'] },
+  AgentMemoryQuery: { storage: 'postgres', context: 'agents', plural: 'agentmemoryqueries', purpose: 'Graph and grep retrieval record with query parameters, result digests, and ranking metadata', requiredSpec: ['organizationRef', 'snapshotRef', 'requester', 'query'] },
+  AgentMemoryUpdate: { storage: 'postgres', context: 'agents', plural: 'agentmemoryupdates', purpose: 'Reviewable proposed memory mutation with branch, changes, and validation status', requiredSpec: ['organizationRef', 'memoryRepository', 'sourceRun', 'changes'] },
+  AgentRunMemoryImport: { storage: 'postgres', context: 'agents', plural: 'agentrunmemoryimports', purpose: 'Import curated babysitter run metadata into org company brain with redaction and review', requiredSpec: ['organizationRef', 'memoryRepository', 'source', 'include'] },
+  ExternalBackendProvider: { storage: 'etcd', context: 'external-backends', plural: 'externalbackendproviders', purpose: 'External backend provider registration with type, endpoint, auth configuration, and capability discovery settings', requiredSpec: ['organizationRef', 'providerType', 'endpoint'] },
+  ExternalBackendBinding: { storage: 'etcd', context: 'external-backends', plural: 'externalbackendbindings', purpose: 'Binding of an external backend provider to an organization with credential reference and sync scope', requiredSpec: ['organizationRef', 'providerRef', 'credentialRef'] },
+  ExternalBackendSyncPolicy: { storage: 'etcd', context: 'external-backends', plural: 'externalbackendsyncpolicies', purpose: 'Sync interval, conflict resolution mode, field mapping overrides, and retry policy for an external backend provider', requiredSpec: ['organizationRef', 'providerRef', 'syncInterval'] },
+  ExternalProviderCapabilityManifest: { storage: 'etcd', context: 'external-backends', plural: 'externalprovidercapabilitymanifests', purpose: 'Discovered capability surface of an external backend provider including supported resource kinds and API features', requiredSpec: ['organizationRef', 'providerRef', 'capabilities'] },
+  ExternalWebhookDelivery: { storage: 'postgres', context: 'external-backends', plural: 'externalwebhookdeliveries', purpose: 'Inbound webhook delivery from an external backend provider with event type, payload, and processing state', requiredSpec: ['organizationRef', 'providerRef', 'eventType', 'payload'] },
+  ExternalSyncEvent: { storage: 'postgres', context: 'external-backends', plural: 'externalsyncevents', purpose: 'Discrete sync event record from an external backend for a specific resource kind with dedupe and ordering metadata', requiredSpec: ['organizationRef', 'providerRef', 'eventKind', 'resourceRef'] },
+  ExternalSyncState: { storage: 'postgres', context: 'external-backends', plural: 'externalsyncstates', purpose: 'Current sync phase, last successful sync timestamp, and error details for an external resource binding', requiredSpec: ['organizationRef', 'providerRef', 'resourceRef', 'phase'] },
+  ExternalWriteIntent: { storage: 'postgres', context: 'external-backends', plural: 'externalwriteintents', purpose: 'Queued write-back intent to an external backend with operation, payload snapshot, and approval state', requiredSpec: ['organizationRef', 'providerRef', 'resourceRef', 'operation'] },
+  ExternalSyncConflict: { storage: 'postgres', context: 'external-backends', plural: 'externalsyncconflicts', purpose: 'Detected conflict between local and external state with conflict kind, diff, and resolution outcome', requiredSpec: ['organizationRef', 'providerRef', 'resourceRef', 'conflictKind'] },
+  ExternalObjectLink: { storage: 'postgres', context: 'external-backends', plural: 'externalobjectlinks', purpose: 'Stable mapping between a Krate local resource and its external backend counterpart by external ID', requiredSpec: ['organizationRef', 'providerRef', 'externalId', 'localRef'] }
+});
+
+export function listResourceDefinitions() {
+  return Object.entries(RESOURCE_DEFINITIONS).map(([kind, definition]) => ({ kind, ...clone(definition) }));
+}
+
+export function resourceDefinitionForKind(kind) {
+  const definition = RESOURCE_DEFINITIONS[kind];
+  if (!definition) throw new Error(`Unknown Krate resource kind: ${kind}`);
+  return { kind, ...clone(definition) };
+}
+
+export function resourceSchemaForKind(kind) {
+  const definition = resourceDefinitionForKind(kind);
+  return {
+    apiVersion: 'krate.a5c.ai/v1alpha1',
+    kind: definition.kind,
+    plural: definition.plural,
+    storage: definition.storage,
+    context: definition.context,
+    required: {
+      metadata: ['name'],
+      spec: [...definition.requiredSpec]
+    },
+    status: ['storage', 'phase', 'conditions']
+  };
+}
+
+export function storageClassForKind(kind) {
+  return resourceDefinitionForKind(kind).storage;
+}
+
+export function resourceKey(resource) {
+  const namespace = resource.metadata?.namespace || 'default';
+  const name = resource.metadata?.name;
+  if (!name) throw new Error('resource metadata.name is required');
+  return `${resource.kind}/${namespace}/${name}`;
+}
+
+export function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+export function createResource(kind, metadata, spec = {}, status = {}) {
+  if (!ALL_KINDS.has(kind)) throw new Error(`Unknown Krate resource kind: ${kind}`);
+  if (!metadata?.name) throw new Error(`${kind} requires metadata.name`);
+  return {
+    apiVersion: 'krate.a5c.ai/v1alpha1',
+    kind,
+    metadata: { namespace: metadata.namespace || 'default', labels: {}, annotations: {}, ...metadata },
+    spec: clone(spec),
+    status: clone(status)
+  };
+}
+
+export function validateResource(resource) {
+  if (!resource || typeof resource !== 'object') throw new Error('resource must be an object');
+  const definition = resourceDefinitionForKind(resource.kind);
+  if (!resource.metadata?.name) throw new Error(`${resource.kind} metadata.name is required`);
+  if (!resource.spec || typeof resource.spec !== 'object') resource.spec = {};
+  if (!resource.status || typeof resource.status !== 'object') resource.status = {};
+  resource.metadata.namespace ||= 'default';
+  resource.metadata.labels ||= {};
+  resource.metadata.annotations ||= {};
+  for (const field of definition.requiredSpec) {
+    if (resource.spec[field] === undefined || resource.spec[field] === null || resource.spec[field] === '') {
+      throw new Error(`${resource.kind} spec.${field} is required`);
+    }
+  }
+  return resource;
+}
+
+export function toKubernetesList(kind, items) {
+  return { apiVersion: 'krate.a5c.ai/v1alpha1', kind: `${kind}List`, items: items.map(clone) };
+}
+
+export function matchLabels(resource, selector = {}) {
+  const labels = resource.metadata?.labels || {};
+  return Object.entries(selector).every(([key, value]) => labels[key] === value);
+}
+
+export function createSelector({ name, namespace = 'krate-org-default', organizationRef = 'default', labels = {}, query = '' }) {
+  return createResource('Selector', { name, namespace }, { organizationRef, labels, query });
+}
+
+export function createView({ name, namespace = 'krate-org-default', organizationRef = 'default', selector, columns = [], sort = [] }) {
+  return createResource('View', { name, namespace }, { organizationRef, selector, columns, sort });
+}
+
+export function resourceToYaml(resource) {
+  const lines = [];
+  const scalar = (value) => {
+    if (value === null) return 'null';
+    if (value === undefined) return 'null';
+    if (typeof value === 'string') return value.includes(': ') || value.startsWith('{') || value.startsWith('[') ? JSON.stringify(value) : value;
+    return String(value);
+  };
+  const writeValue = (key, value, indent = 0) => {
+    const pad = ' '.repeat(indent);
+    if (Array.isArray(value)) {
+      lines.push(`${pad}${key}:`);
+      writeArray(value, indent + 2);
+    } else if (value && typeof value === 'object') {
+      lines.push(`${pad}${key}:`);
+      writeObject(value, indent + 2);
+    } else {
+      lines.push(`${pad}${key}: ${scalar(value)}`);
+    }
+  };
+  const writeObject = (value, indent) => {
+    for (const [childKey, childValue] of Object.entries(value)) writeValue(childKey, childValue, indent);
+  };
+  const writeArray = (value, indent) => {
+    const pad = ' '.repeat(indent);
+    for (const item of value) {
+      if (Array.isArray(item)) {
+        lines.push(`${pad}-`);
+        writeArray(item, indent + 2);
+      } else if (item && typeof item === 'object') {
+        const entries = Object.entries(item);
+        if (entries.length === 0) {
+          lines.push(`${pad}- {}`);
+        } else {
+          const [[firstKey, firstValue], ...rest] = entries;
+          if (firstValue && typeof firstValue === 'object') {
+            lines.push(`${pad}- ${firstKey}:`);
+            if (Array.isArray(firstValue)) writeArray(firstValue, indent + 4);
+            else writeObject(firstValue, indent + 4);
+          } else {
+            lines.push(`${pad}- ${firstKey}: ${scalar(firstValue)}`);
+          }
+          for (const [childKey, childValue] of rest) writeValue(childKey, childValue, indent + 2);
+        }
+      } else {
+        lines.push(`${pad}- ${scalar(item)}`);
+      }
+    }
+  };
+  writeObject(resource, 0);
+  return lines.join('\n') + '\n';
+}