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

package/src/runner-controller.js

@@ -0,0 +1,272 @@
+import { createResource, clone } from './resource-model.js';
+import { serviceAccountForJob } from './identity-policy.js';
+
+export const RUNNER_CONTROLLER_BOUNDARY = {
+  role: 'runner-controller',
+  scope: 'RunnerPool lifecycle, runner scheduling, pod spec generation, job assignment',
+  owns: ['pool validation', 'runner lifecycle', 'job scheduling', 'pod spec generation', 'capacity tracking'],
+  delegatesTo: ['resource-model', 'identity-policy'],
+  mustNotOwn: ['Kubernetes API calls', 'actual pod creation', 'network I/O']
+};
+
+const RUNNER_STATUSES = new Set(['Idle', 'Running', 'Terminating']);
+const DEFAULT_IMAGE = 'ubuntu:24.04';
+const DEFAULT_SERVICE_ACCOUNT = 'krate-runner';
+const DEFAULT_NAMESPACE = 'krate-org-default';
+
+export function createRunnerController() {
+  // In-memory runner registry (runner id → runner record)
+  const runners = new Map();
+  // job ref → runner id
+  const jobAssignments = new Map();
+
+  return {
+    role: 'runner-controller',
+
+    // -------------------------------------------------------------------------
+    // Pool management
+    // -------------------------------------------------------------------------
+
+    validateRunnerPool(resource) {
+      if (!resource || typeof resource !== 'object') {
+        return { valid: false, reason: 'missing-resource', message: 'resource is required' };
+      }
+      const name = resource.metadata?.name;
+      if (!name) return { valid: false, reason: 'missing-name', message: 'metadata.name is required' };
+
+      const spec = resource.spec || {};
+      if (spec.organizationRef === undefined || spec.organizationRef === null || String(spec.organizationRef).trim() === '') return { valid: false, reason: 'missing-org', message: 'spec.organizationRef is required' };
+
+      const min = Number(spec.warmReplicas ?? 0);
+      const max = Number(spec.maxReplicas ?? 0);
+      if (!Number.isInteger(min) || min < 0) return { valid: false, reason: 'invalid-min-replicas', message: 'spec.warmReplicas must be a non-negative integer' };
+      if (!Number.isInteger(max) || max < 1) return { valid: false, reason: 'invalid-max-replicas', message: 'spec.maxReplicas must be a positive integer' };
+      if (min > max) return { valid: false, reason: 'replicas-conflict', message: 'spec.warmReplicas must not exceed spec.maxReplicas' };
+
+      return {
+        valid: true,
+        name,
+        organizationRef: spec.organizationRef,
+        warmReplicas: min,
+        maxReplicas: max,
+        image: spec.image || DEFAULT_IMAGE,
+        labels: resource.metadata?.labels || {}
+      };
+    },
+
+    getPoolStatus(pool) {
+      const poolName = pool?.metadata?.name;
+      const poolRunners = [...runners.values()].filter((r) => r.poolName === poolName);
+      const idle = poolRunners.filter((r) => r.status === 'Idle').length;
+      const active = poolRunners.filter((r) => r.status === 'Running').length;
+      const terminating = poolRunners.filter((r) => r.status === 'Terminating').length;
+      const total = poolRunners.length;
+      const desired = Number(pool?.spec?.warmReplicas ?? 0);
+      const maxReplicas = Number(pool?.spec?.maxReplicas ?? 0);
+
+      return {
+        poolName,
+        idle,
+        active,
+        terminating,
+        total,
+        desired,
+        maxReplicas,
+        phase: total === 0 ? 'Empty' : active > 0 ? 'Active' : 'Idle',
+        scaling: total < desired ? 'ScalingUp' : total > maxReplicas ? 'ScalingDown' : 'Stable'
+      };
+    },
+
+    getCapacity(pool) {
+      const poolName = pool?.metadata?.name;
+      const poolRunners = [...runners.values()].filter((r) => r.poolName === poolName);
+      const maxReplicas = Number(pool?.spec?.maxReplicas ?? 0);
+      const used = poolRunners.filter((r) => r.status === 'Running').length;
+      const available = Math.max(0, maxReplicas - used);
+
+      return {
+        poolName,
+        maxReplicas,
+        used,
+        available,
+        utilizationPct: maxReplicas > 0 ? Math.round((used / maxReplicas) * 100) : 0
+      };
+    },
+
+    // -------------------------------------------------------------------------
+    // Runner lifecycle
+    // -------------------------------------------------------------------------
+
+    createRunner(pool, runRef = null) {
+      const poolName = pool?.metadata?.name;
+      if (!poolName) return { error: true, reason: 'missing-pool', message: 'pool.metadata.name is required' };
+
+      const namespace = pool?.metadata?.namespace || DEFAULT_NAMESPACE;
+      const spec = pool?.spec || {};
+      const runnerId = `runner-${poolName}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+      const workspace = runRef ? { runRef, mountPath: '/workspace' } : null;
+      const podSpec = this.generatePodSpec({ runnerId, pool }, workspace);
+
+      const runner = {
+        id: runnerId,
+        poolName,
+        namespace,
+        status: runRef ? 'Running' : 'Idle',
+        runRef: runRef || null,
+        createdAt: new Date().toISOString(),
+        image: spec.image || DEFAULT_IMAGE,
+        podSpec
+      };
+
+      runners.set(runnerId, runner);
+      if (runRef) jobAssignments.set(runRef, runnerId);
+
+      return { error: false, runnerId, runner: clone(runner) };
+    },
+
+    terminateRunner(runnerId) {
+      const runner = runners.get(runnerId);
+      if (!runner) return { error: true, reason: 'not-found', message: `Runner not found: ${runnerId}` };
+
+      // Remove job assignment if any
+      if (runner.runRef) jobAssignments.delete(runner.runRef);
+
+      runner.status = 'Terminating';
+      runner.terminatedAt = new Date().toISOString();
+      runners.delete(runnerId);
+
+      return { error: false, runnerId, terminatedAt: runner.terminatedAt };
+    },
+
+    // -------------------------------------------------------------------------
+    // Job scheduling
+    // -------------------------------------------------------------------------
+
+    scheduleJob(pool, job) {
+      const jobRef = job?.metadata?.name || job?.ref;
+      if (!jobRef) return { error: true, reason: 'missing-job-ref', message: 'job.metadata.name or job.ref is required' };
+
+      const poolName = pool?.metadata?.name;
+      if (!poolName) return { error: true, reason: 'missing-pool', message: 'pool.metadata.name is required' };
+
+      // Check if already assigned
+      if (jobAssignments.has(jobRef)) {
+        const existingRunnerId = jobAssignments.get(jobRef);
+        return { error: false, runnerId: existingRunnerId, reused: true };
+      }
+
+      // Find an idle runner in this pool
+      const idleRunner = [...runners.values()].find(
+        (r) => r.poolName === poolName && r.status === 'Idle'
+      );
+
+      if (idleRunner) {
+        idleRunner.status = 'Running';
+        idleRunner.runRef = jobRef;
+        idleRunner.assignedAt = new Date().toISOString();
+        jobAssignments.set(jobRef, idleRunner.id);
+        return { error: false, runnerId: idleRunner.id, reused: false, runner: clone(idleRunner) };
+      }
+
+      // Check capacity for a new runner
+      const capacity = this.getCapacity(pool);
+      if (capacity.available <= 0) {
+        return { error: true, reason: 'no-capacity', message: `Pool ${poolName} has no available capacity (${capacity.used}/${capacity.maxReplicas})` };
+      }
+
+      // Create a new runner
+      const result = this.createRunner(pool, jobRef);
+      if (result.error) return result;
+      return { error: false, runnerId: result.runnerId, reused: false, runner: result.runner };
+    },
+
+    getRunnerForJob(jobRef) {
+      const runnerId = jobAssignments.get(jobRef);
+      if (!runnerId) return null;
+      const runner = runners.get(runnerId);
+      return runner ? clone(runner) : null;
+    },
+
+    // -------------------------------------------------------------------------
+    // Pod spec generation
+    // -------------------------------------------------------------------------
+
+    generatePodSpec({ runnerId, pool }, workspace = null) {
+      const spec = pool?.spec || {};
+      const namespace = pool?.metadata?.namespace || DEFAULT_NAMESPACE;
+      const image = spec.image || DEFAULT_IMAGE;
+      const organizationRef = spec.organizationRef || 'default';
+      const serviceAccountName = spec.serviceAccount || DEFAULT_SERVICE_ACCOUNT;
+      const runId = workspace?.runRef || runnerId;
+
+      const resourceLimits = spec.resourceLimits || {};
+      const resourceRequests = spec.resourceRequests || {};
+
+      const envVars = [
+        { name: 'KRATE_ORG', value: organizationRef },
+        { name: 'KRATE_RUN_ID', value: runId },
+        { name: 'KRATE_WORKSPACE_PATH', value: workspace?.mountPath || '/workspace' }
+      ];
+
+      const volumes = [];
+      const volumeMounts = [];
+
+      if (workspace) {
+        const pvcName = workspace.pvcName || `krate-ws-${runId}`;
+        volumes.push({
+          name: 'workspace',
+          persistentVolumeClaim: { claimName: pvcName }
+        });
+        volumeMounts.push({
+          name: 'workspace',
+          mountPath: workspace.mountPath || '/workspace'
+        });
+      }
+
+      return {
+        apiVersion: 'v1',
+        kind: 'Pod',
+        metadata: {
+          name: `runner-${runnerId}`,
+          namespace,
+          labels: {
+            'krate.a5c.ai/runner': runnerId,
+            'krate.a5c.ai/pool': pool?.metadata?.name || 'unknown',
+            'krate.a5c.ai/org': organizationRef
+          }
+        },
+        spec: {
+          serviceAccountName,
+          restartPolicy: 'Never',
+          containers: [{
+            name: 'runner',
+            image,
+            env: envVars,
+            volumeMounts,
+            resources: {
+              limits: Object.keys(resourceLimits).length ? resourceLimits : { cpu: '2', memory: '4Gi' },
+              requests: Object.keys(resourceRequests).length ? resourceRequests : { cpu: '500m', memory: '1Gi' }
+            }
+          }],
+          volumes
+        }
+      };
+    },
+
+    // -------------------------------------------------------------------------
+    // Introspection helpers
+    // -------------------------------------------------------------------------
+
+    listRunners(poolName = null) {
+      const all = [...runners.values()];
+      if (poolName) return all.filter((r) => r.poolName === poolName).map(clone);
+      return all.map(clone);
+    },
+
+    getRunner(runnerId) {
+      const r = runners.get(runnerId);
+      return r ? clone(r) : null;
+    }
+  };
+}

package/src/runners-ci.js

@@ -0,0 +1,48 @@
+import { createResource } from './resource-model.js';
+import { serviceAccountForJob } from './identity-policy.js';
+
+export class RunnerScheduler {
+  constructor({ controlPlane }) { this.controlPlane = controlPlane; }
+
+  createRunnerPool({ name, namespace = 'krate-org-default', organizationRef = 'default', image = 'ubuntu:24.04', warmReplicas = 1, maxReplicas = 10, trustTier = 'trusted', cache = { type: 'object-storage' } }, user) {
+    return this.controlPlane.create(createResource('RunnerPool', { name, namespace, labels: { trustTier } }, {
+      organizationRef, image, warmReplicas, maxReplicas, trustTier, cache, scalingMetric: 'queueDepth'
+    }, { readyReplicas: warmReplicas, queueDepth: 0 }), user);
+  }
+
+  planReplicas(pool, queueDepth) {
+    return Math.min(pool.spec.maxReplicas || 0, Math.max(pool.spec.warmReplicas || 0, queueDepth));
+  }
+
+  startPipeline({ name, namespace = 'krate-org-default', organizationRef = 'default', repository, ref, actor, steps = ['checkout', 'test'], fork = false, resumeFrom = null }, user) {
+    const trustTier = fork ? 'untrusted' : 'trusted';
+    const pipeline = this.controlPlane.create(createResource('Pipeline', { name, namespace, labels: { repository, ref, trustTier } }, {
+      organizationRef, repository, ref, actor: actor.name, resumeFrom, trustTier, steps
+    }, { phase: 'Running', currentStep: resumeFrom || steps[0] }), user);
+    const jobs = steps.map((step, index) => this.controlPlane.create(createResource('Job', {
+      name: `${name}-${index + 1}-${step}`,
+      namespace,
+      labels: { pipeline: name, repository, trustTier }
+    }, {
+      organizationRef: pipeline.spec?.organizationRef || organizationRef,
+      pipeline: name,
+      step,
+      serviceAccount: serviceAccountForJob({ namespace, repository, pipeline: name, trustTier })
+    }, { phase: step === (resumeFrom || steps[0]) ? 'Running' : 'Pending' }), user));
+    return { pipeline, jobs };
+  }
+
+  rerunFromStep(pipeline, step, user) {
+    return this.startPipeline({
+      name: `${pipeline.metadata.name}-rerun-${step}`,
+      namespace: pipeline.metadata.namespace,
+      organizationRef: pipeline.spec.organizationRef,
+      repository: pipeline.spec.repository,
+      ref: pipeline.spec.ref,
+      actor: { name: pipeline.spec.actor },
+      steps: pipeline.spec.steps,
+      resumeFrom: step,
+      fork: pipeline.spec.trustTier === 'untrusted'
+    }, user);
+  }
+}

package/src/runtime.js

@@ -0,0 +1,196 @@
+import { ControlPlane } from './control-plane.js';
+import { GiteaGitService, GiteaRepositoryStore } from './data-plane.js';
+import { WebhookBus } from './hooks-events.js';
+import { createAdmissionPolicy, mapOidcIdentity } from './identity-policy.js';
+import { createInviteResource, createTeamResource, createAuthProviderResources, mapLoginProfileToKrateIdentity } from './auth.js';
+import { createResource, clone } from './resource-model.js';
+import { RunnerScheduler } from './runners-ci.js';
+
+const DEFAULT_ORG = 'default';
+const DEFAULT_NAMESPACE = 'krate-org-default';
+
+export function createDefaultKrateUsers() {
+  return {
+    platformEngineer: mapOidcIdentity({ subject: 'user:platform', email: 'platform@example.com', groups: ['krate:platform-engineers'] }),
+    developer: mapOidcIdentity({ subject: 'user:dev', email: 'dev@example.com', groups: ['krate:developers'] }),
+    repoAdmin: mapOidcIdentity({ subject: 'user:admin', email: 'admin@example.com', groups: ['krate:repo-admins'] })
+  };
+}
+
+export class KrateRuntime {
+  constructor({ organizationRef = DEFAULT_ORG, namespace = DEFAULT_NAMESPACE, users = createDefaultKrateUsers(), controlPlane, git, runners, webhooks } = {}) {
+    this.organizationRef = organizationRef;
+    this.namespace = namespace;
+    this.users = users;
+    this.controlPlane = controlPlane || new ControlPlane();
+    this.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'
+    }));
+    this.git = git || new GiteaGitService({ controlPlane: this.controlPlane, stores: [new GiteaRepositoryStore({ name: 'gitea-primary', receivePackReady: true })] });
+    this.runners = runners || new RunnerScheduler({ controlPlane: this.controlPlane });
+    this.webhooks = webhooks || new WebhookBus({ controlPlane: this.controlPlane });
+    this.seeded = false;
+  }
+
+  static fromSnapshot(snapshot, options = {}) {
+    const runtime = new KrateRuntime(options);
+    runtime.importSnapshot(snapshot);
+    return runtime;
+  }
+
+  bootstrap({ repository = 'krate-demo', webhookUrl = 'https://hooks.example.test/krate' } = {}) {
+    if (this.seeded) return this.snapshot();
+    const { platformEngineer, repoAdmin } = this.users;
+    this.git.createRepository({ name: repository, namespace: this.namespace, organizationRef: this.organizationRef }, repoAdmin);
+    this.controlPlane.create(createResource('BranchProtection', { name: 'main-protection', namespace: this.namespace }, { organizationRef: this.organizationRef, refs: ['refs/heads/main'], requirePullRequest: true, requiredChecks: ['test'], requiredApprovals: 1 }), repoAdmin);
+    this.controlPlane.create(createResource('RefPolicy', { name: 'deny-internal-refs', namespace: this.namespace }, { organizationRef: this.organizationRef, deny: ['refs/internal/'] }), repoAdmin);
+    this.runners.createRunnerPool({ name: 'trusted-linux', namespace: this.namespace, organizationRef: this.organizationRef, warmReplicas: 1, maxReplicas: 4 }, platformEngineer);
+    this.webhooks.subscribe({ name: 'chatops', namespace: this.namespace, organizationRef: this.organizationRef, url: webhookUrl, events: ['pullrequest.created', 'pullrequest.merged'] }, repoAdmin);
+    this.controlPlane.create(createTeamResource({ name: 'maintainers', organizationRef: this.organizationRef, displayName: 'Maintainers', members: ['admin'], maintainers: ['admin'], repositoryGrants: [{ repository, permission: 'admin' }], namespace: this.namespace }), platformEngineer);
+    const identity = mapLoginProfileToKrateIdentity({ provider: 'sso', subject: 'user:admin', email: 'admin@example.com', displayName: 'Admin', username: 'admin', teams: ['maintainers'], admin: true, namespace: this.namespace, organizationRef: this.organizationRef });
+    this.controlPlane.create(identity.user, platformEngineer);
+    this.controlPlane.create(identity.mapping, platformEngineer);
+    this.controlPlane.create(createInviteResource({ email: 'new-user@example.com', role: 'member', teams: ['maintainers'], invitedBy: 'admin', namespace: this.namespace, organizationRef: this.organizationRef }), repoAdmin);
+    for (const provider of createAuthProviderResources(undefined, this.namespace, this.organizationRef)) this.controlPlane.create(provider, platformEngineer);
+    this.seeded = true;
+    return this.snapshot();
+  }
+
+  exportSnapshot() {
+    return {
+      apiVersion: 'krate.a5c.ai/v1alpha1',
+      kind: 'KrateRuntimeSnapshot',
+      namespace: this.namespace,
+      organizationRef: this.organizationRef,
+      seeded: this.seeded,
+      controlPlane: this.controlPlane.exportSnapshot(),
+      git: this.git.snapshot?.() || null
+    };
+  }
+
+  importSnapshot(snapshot) {
+    const controlPlaneSnapshot = snapshot?.controlPlane || snapshot;
+    this.controlPlane.importSnapshot(controlPlaneSnapshot);
+    if (snapshot?.git) this.git.importSnapshot(snapshot.git);
+    this.seeded = Boolean(snapshot?.seeded || this.controlPlane.list('Repository', { namespace: this.namespace }).items.length);
+    return this.snapshot();
+  }
+
+  createRepository({ name, visibility = 'private' }, user = this.users.repoAdmin) {
+    return this.git.createRepository({ name, namespace: this.namespace, organizationRef: this.organizationRef, visibility }, user);
+  }
+
+  createPullRequest({ repository, sourceRef = 'refs/heads/feature', targetRef = 'refs/heads/main', title, actor = this.users.developer, fork = false }) {
+    this.#requireRepository(repository);
+    const index = this.controlPlane.list('PullRequest', { namespace: this.namespace }).items.length + 1;
+    const name = `pr-${index}`;
+    const pullRequest = this.controlPlane.create(createResource('PullRequest', { name, namespace: this.namespace, labels: { repository } }, {
+      organizationRef: this.organizationRef,
+      repository,
+      sourceRef,
+      targetRef,
+      title,
+      author: actor.name,
+      checks: [],
+      requiredApprovals: this.#requiredApprovals(targetRef)
+    }, { phase: 'Open', approvals: 0, mergeable: false }), actor);
+    const pipelineRun = this.runners.startPipeline({ name: `pipeline-${name}`, namespace: this.namespace, organizationRef: this.organizationRef, repository, ref: `refs/pull/${index}/head`, actor, fork, steps: ['checkout', 'test'] }, actor);
+    this.webhooks.deliver({ subscriptionName: 'chatops', namespace: this.namespace, organizationRef: this.organizationRef, eventType: 'pullrequest.created', payload: { pullRequest: name, repository, title } }, this.users.repoAdmin);
+    return { pullRequest, pipeline: pipelineRun.pipeline, jobs: pipelineRun.jobs };
+  }
+
+  completePipeline({ pipeline, phase = 'Succeeded', failedStep = null }, user = this.users.developer) {
+    const existing = this.controlPlane.get('Pipeline', this.namespace, pipeline);
+    if (!existing) throw new Error(`Pipeline ${pipeline} not found`);
+    const jobs = this.controlPlane.list('Job', { namespace: this.namespace, labels: { pipeline } }).items.map((job) => {
+      const jobPhase = failedStep && job.spec.step === failedStep ? 'Failed' : phase;
+      return this.controlPlane.patchStatus('Job', this.namespace, job.metadata.name, { phase: jobPhase, finishedAt: new Date().toISOString() }, user);
+    });
+    const pipelinePhase = jobs.some((job) => job.status.phase === 'Failed') ? 'Failed' : phase;
+    const updatedPipeline = this.controlPlane.patchStatus('Pipeline', this.namespace, pipeline, { phase: pipelinePhase, currentStep: null, finishedAt: new Date().toISOString() }, user);
+    this.#refreshPullRequestMergeability(existing.spec.repository);
+    return { pipeline: updatedPipeline, jobs };
+  }
+
+  addReview({ pullRequest, decision = 'approved', body = 'Looks good', reviewer = this.users.repoAdmin }) {
+    const pr = this.#requirePullRequest(pullRequest);
+    const reviewCount = this.controlPlane.list('Review', { namespace: this.namespace, labels: { pullRequest } }).items.length + 1;
+    const review = this.controlPlane.create(createResource('Review', { name: `${pullRequest}-review-${reviewCount}`, namespace: this.namespace, labels: { pullRequest, decision } }, {
+      organizationRef: this.organizationRef,
+      pullRequest,
+      repository: pr.spec.repository,
+      reviewer: reviewer.name,
+      decision,
+      body
+    }, { phase: decision === 'approved' ? 'Approved' : 'ChangesRequested' }), reviewer);
+    this.#refreshPullRequestMergeability(pr.spec.repository);
+    return review;
+  }
+
+  mergePullRequest({ pullRequest, actor = this.users.repoAdmin }) {
+    const pr = this.#requirePullRequest(pullRequest);
+    const refreshed = this.#refreshPullRequestMergeability(pr.spec.repository).find((candidate) => candidate.metadata.name === pullRequest) || pr;
+    if (!refreshed.status.mergeable) throw new Error(`PullRequest ${pullRequest} is not mergeable`);
+    const gitEvent = this.git.receivePack({ repository: refreshed.spec.repository, namespace: this.namespace, ref: refreshed.spec.targetRef, newRev: this.#syntheticRevision(pullRequest), actor });
+    const merged = this.controlPlane.patchStatus('PullRequest', this.namespace, pullRequest, { phase: 'Merged', mergeable: false, mergedAt: new Date().toISOString(), mergeCommit: gitEvent.newRev }, actor);
+    const delivery = this.webhooks.deliver({ subscriptionName: 'chatops', namespace: this.namespace, organizationRef: this.organizationRef, eventType: 'pullrequest.merged', payload: { pullRequest, repository: refreshed.spec.repository, mergeCommit: gitEvent.newRev } }, this.users.repoAdmin);
+    return { pullRequest: merged, gitEvent, delivery };
+  }
+
+  snapshot() {
+    const kinds = ['Organization', 'User', 'Team', 'Invite', 'IdentityMapping', 'AuthProvider', 'Repository', 'SSHKey', 'RepositoryPermission', 'BranchProtection', 'RefPolicy', 'RunnerPool', 'PullRequest', 'Issue', 'Review', 'Pipeline', 'Job', 'WebhookSubscription', 'WebhookDelivery'];
+    const resources = Object.fromEntries(kinds.map((kind) => [kind, this.controlPlane.list(kind, { namespace: this.namespace }).items]));
+    return {
+      namespace: this.namespace,
+      export: this.exportSnapshot(),
+      storage: this.controlPlane.storageReport(),
+      resources,
+      events: clone(this.controlPlane.events),
+      auditLog: clone(this.controlPlane.auditLog)
+    };
+  }
+
+  #requireRepository(repository) {
+    const existing = this.controlPlane.get('Repository', this.namespace, repository);
+    if (!existing) throw new Error(`Repository ${repository} not found`);
+    return existing;
+  }
+
+  #requirePullRequest(pullRequest) {
+    const existing = this.controlPlane.get('PullRequest', this.namespace, pullRequest);
+    if (!existing) throw new Error(`PullRequest ${pullRequest} not found`);
+    return existing;
+  }
+
+  #requiredApprovals(targetRef) {
+    const branchProtection = this.controlPlane.list('BranchProtection', { namespace: this.namespace }).items.find((policy) => (policy.spec.refs || []).includes(targetRef));
+    return branchProtection?.spec.requiredApprovals || 0;
+  }
+
+  #refreshPullRequestMergeability(repository) {
+    const pullRequests = this.controlPlane.list('PullRequest', { namespace: this.namespace, labels: { repository } }).items;
+    return pullRequests.map((pr) => {
+      if (pr.status.phase !== 'Open') return pr;
+      const reviews = this.controlPlane.list('Review', { namespace: this.namespace, labels: { pullRequest: pr.metadata.name } }).items;
+      const approvals = reviews.filter((review) => review.spec.decision === 'approved').length;
+      const pipelines = this.controlPlane.list('Pipeline', { namespace: this.namespace, labels: { repository } }).items.filter((pipeline) => pipeline.metadata.name === `pipeline-${pr.metadata.name}`);
+      const checksPassed = pipelines.length > 0 && pipelines.every((pipeline) => pipeline.status.phase === 'Succeeded');
+      return this.controlPlane.patchStatus('PullRequest', this.namespace, pr.metadata.name, { approvals, checksPassed, mergeable: approvals >= (pr.spec.requiredApprovals || 0) && checksPassed }, this.users.repoAdmin);
+    });
+  }
+
+  #syntheticRevision(seed) {
+    const source = Buffer.from(`${seed}:${Date.now()}`).toString('hex');
+    return source.padEnd(40, '0').slice(0, 40);
+  }
+}
+
+export function createKrateRuntime(options = {}) {
+  const runtime = new KrateRuntime(options);
+  if (options.bootstrap !== false) runtime.bootstrap(options.bootstrapOptions);
+  return runtime;
+}

package/src/snapshot-cache.js

@@ -0,0 +1,157 @@
+/**
+ * Snapshot cache with:
+ *  - Per-org storage (multiple orgs cached simultaneously)
+ *  - stale-while-revalidate: return stale data immediately, refresh in background
+ *  - Configurable TTL via KRATE_SNAPSHOT_CACHE_TTL_MS
+ */
+
+export const CACHE_TTL_MS = Number(process.env.KRATE_SNAPSHOT_CACHE_TTL_MS || 30_000);
+
+/**
+ * Per-org cache map.  Key = org string (or '' for no-org).
+ * Value = { data, timestamp, revalidating: boolean }
+ */
+const orgCacheMap = new Map();
+
+// Legacy single-org cache kept for backward compatibility with controller-client.js
+let snapshotCache = { data: null, timestamp: 0, org: null };
+
+export function getSnapshotCache() {
+  return snapshotCache;
+}
+
+export function setSnapshotCache(data, org) {
+  snapshotCache = { data, timestamp: Date.now(), org };
+  // Also update per-org map
+  const key = org ?? '';
+  const entry = orgCacheMap.get(key) || {};
+  orgCacheMap.set(key, { ...entry, data, timestamp: Date.now(), revalidating: false });
+}
+
+export function clearSnapshotCache() {
+  snapshotCache = { data: null, timestamp: 0, org: null };
+  orgCacheMap.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Per-org cache API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the cached snapshot for a specific org.
+ * Returns null when nothing is cached or when the TTL has expired.
+ *
+ * @param {string|null} org
+ * @returns {{ data: object, timestamp: number, revalidating: boolean } | null}
+ */
+export function getOrgCache(org) {
+  const key = org ?? '';
+  const entry = orgCacheMap.get(key);
+  if (!entry || !entry.data) return null;
+  return entry;
+}
+
+/**
+ * Store a snapshot for a specific org.
+ *
+ * @param {object} data
+ * @param {string|null} org
+ */
+export function setOrgCache(data, org) {
+  const key = org ?? '';
+  orgCacheMap.set(key, { data, timestamp: Date.now(), revalidating: false });
+  // Keep legacy cache in sync for the most recently written org
+  snapshotCache = { data, timestamp: Date.now(), org };
+}
+
+/**
+ * Clear the cache entry for a specific org only.
+ *
+ * @param {string|null} org
+ */
+export function clearOrgCache(org) {
+  orgCacheMap.delete(org ?? '');
+  if (snapshotCache.org === org) {
+    snapshotCache = { data: null, timestamp: 0, org: null };
+  }
+}
+
+/**
+ * Return all orgs currently in the cache (for introspection / debugging).
+ *
+ * @returns {string[]}
+ */
+export function cachedOrgs() {
+  return [...orgCacheMap.keys()];
+}
+
+// ---------------------------------------------------------------------------
+// stale-while-revalidate helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the cache entry for the given org is fresh.
+ *
+ * @param {string|null} org
+ * @param {number} [ttlMs] - defaults to CACHE_TTL_MS
+ * @returns {boolean}
+ */
+export function isCacheFresh(org, ttlMs = CACHE_TTL_MS) {
+  const entry = getOrgCache(org);
+  if (!entry) return false;
+  return (Date.now() - entry.timestamp) < ttlMs;
+}
+
+/**
+ * stale-while-revalidate: return stale data immediately if available, then
+ * trigger revalidateFn() in the background to refresh the cache entry.
+ *
+ * @param {string|null} org - Organization key for the cache
+ * @param {Function} revalidateFn - Async function that returns fresh data
+ * @param {object} [swrOptions]
+ * @param {number} [swrOptions.ttlMs] - Fresh TTL in ms (default: CACHE_TTL_MS)
+ * @param {number} [swrOptions.staleMs] - Max staleness before we block on revalidate (default: 5 × ttlMs)
+ * @returns {Promise<object>} Either the stale cached value or the freshly fetched one
+ */
+export async function staleWhileRevalidate(org, revalidateFn, swrOptions = {}) {
+  const ttlMs = swrOptions.ttlMs ?? CACHE_TTL_MS;
+  const staleMs = swrOptions.staleMs ?? ttlMs * 5;
+  const key = org ?? '';
+  const entry = orgCacheMap.get(key);
+  const now = Date.now();
+
+  const isFresh = entry && entry.data && (now - entry.timestamp) < ttlMs;
+  const isStale = entry && entry.data && (now - entry.timestamp) < staleMs;
+
+  if (isFresh) {
+    // Cache is fresh: return immediately
+    return entry.data;
+  }
+
+  if (isStale && !entry.revalidating) {
+    // Stale but still usable: return immediately and revalidate in background
+    orgCacheMap.set(key, { ...entry, revalidating: true });
+    Promise.resolve().then(async () => {
+      try {
+        const fresh = await revalidateFn();
+        setOrgCache(fresh, org);
+      } catch {
+        // On background refresh error, clear the revalidating flag so a future
+        // request can try again
+        const current = orgCacheMap.get(key);
+        if (current) orgCacheMap.set(key, { ...current, revalidating: false });
+      }
+    });
+    return entry.data;
+  }
+
+  if (isStale && entry.revalidating) {
+    // Another caller is already refreshing: return stale data now
+    return entry.data;
+  }
+
+  // No usable cache: block on the revalidation
+  const fresh = await revalidateFn();
+  setOrgCache(fresh, org);
+  return fresh;
+}