@a5c-ai/krate 5.0.1-staging.660d2b90f → 5.0.1-staging.69cb593ea

package/src/agent-writeback-controller.js

@@ -0,0 +1,302 @@
+import { createResource, clone } from './resource-model.js';
+
+export const AGENT_WRITEBACK_CONTROLLER_BOUNDARY = {
+  role: 'agent-writeback-controller',
+  scope: 'KrateArtifact write pipeline, branch push approval flow, and PR merge with status check enforcement',
+  owns: ['artifact creation', 'artifact listing', 'branch push requests', 'push approval/denial', 'PR merge requests', 'write intent validation', 'write intent status'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['git operations', 'secret values', 'agent execution', 'CI orchestration']
+};
+
+const VALID_WRITE_TYPES = new Set(['artifact', 'branch-push', 'pr-merge']);
+
+/**
+ * In-memory store of AgentWriteIntent records (plain objects, not K8s CRDs,
+ * because AgentWriteIntent is not in the canonical resource taxonomy).
+ * Controllers operate statelessly against caller-supplied resources maps;
+ * the write intent shape mirrors what would live in an aggregated store.
+ */
+
+export function createAgentWritebackController() {
+  return {
+    role: 'agent-writeback-controller',
+
+    // -----------------------------------------------------------------------
+    // Artifacts
+    // -----------------------------------------------------------------------
+
+    createArtifact({ name, runRef, contentRef, kind = 'output', namespace = 'default', organizationRef = 'default' }) {
+      if (!runRef) {
+        return { error: true, reason: 'missing-run-ref', message: 'runRef is required to link an artifact to a dispatch run' };
+      }
+      if (!contentRef) {
+        return { error: true, reason: 'missing-content-ref', message: 'contentRef is required to identify the artifact content' };
+      }
+
+      const now = new Date().toISOString();
+      const artifactName = name || `artifact-${runRef}-${Date.now()}`;
+
+      const artifact = createResource('KrateArtifact', { name: artifactName, namespace }, {
+        organizationRef,
+        dispatchRun: runRef,
+        kind,
+        digest: contentRef
+      });
+      artifact.status = { phase: 'Available', createdAt: now };
+
+      return { error: false, artifact };
+    },
+
+    validateArtifact({ artifact }) {
+      if (!artifact || typeof artifact !== 'object') {
+        return { valid: false, error: true, reason: 'invalid-artifact', message: 'artifact must be an object' };
+      }
+      if (artifact.kind !== 'KrateArtifact') {
+        return { valid: false, error: true, reason: 'wrong-kind', message: `Expected KrateArtifact, got: ${artifact.kind}` };
+      }
+      if (!artifact.spec?.dispatchRun) {
+        return { valid: false, error: true, reason: 'missing-run-ref', message: 'artifact spec.dispatchRun is required' };
+      }
+      if (!artifact.spec?.digest) {
+        return { valid: false, error: true, reason: 'missing-digest', message: 'artifact spec.digest is required' };
+      }
+      return { valid: true, error: false };
+    },
+
+    listArtifactsForRun({ runRef, resources = {} }) {
+      const artifacts = resources.KrateArtifact || [];
+      return artifacts.filter((a) => a.spec?.dispatchRun === runRef).map(clone);
+    },
+
+    // -----------------------------------------------------------------------
+    // Branch push approval flow
+    // -----------------------------------------------------------------------
+
+    requestBranchPush({ runRef, branch, targetRepo, requestedBy, namespace = 'default', organizationRef = 'default' }) {
+      if (!runRef) {
+        return { error: true, reason: 'missing-run-ref', message: 'runRef is required' };
+      }
+      if (!branch) {
+        return { error: true, reason: 'missing-branch', message: 'branch is required' };
+      }
+      if (!targetRepo) {
+        return { error: true, reason: 'missing-target-repo', message: 'targetRepo is required' };
+      }
+
+      const now = new Date().toISOString();
+      const intentName = `push-${runRef}-${Date.now()}`;
+
+      const pushRequest = {
+        kind: 'AgentWriteIntent',
+        metadata: { name: intentName, namespace, labels: {}, annotations: {} },
+        spec: { organizationRef, runRef, branch, targetRepo, writeType: 'branch-push', requestedBy: requestedBy || 'unknown', requestedAt: now },
+        status: { approvalStatus: 'pending', phase: 'Pending', createdAt: now }
+      };
+
+      return { error: false, pushRequest };
+    },
+
+    approveBranchPush({ intentName, approvedBy, reason, resources = {} }) {
+      if (!intentName) {
+        return { error: true, reason: 'missing-intent-name', message: 'intentName is required' };
+      }
+      if (!approvedBy) {
+        return { error: true, reason: 'missing-approved-by', message: 'approvedBy is required' };
+      }
+
+      const intents = resources.AgentWriteIntent || [];
+      const intent = intents.find((i) => i.metadata?.name === intentName);
+      if (!intent) {
+        return { error: true, reason: 'not-found', message: `AgentWriteIntent not found: ${intentName}` };
+      }
+      if (intent.status?.approvalStatus !== 'pending') {
+        return { error: true, reason: 'already-decided', message: `AgentWriteIntent ${intentName} has already been decided: ${intent.status?.approvalStatus}` };
+      }
+
+      const now = new Date().toISOString();
+      const pushRequest = clone(intent);
+      pushRequest.status = {
+        ...pushRequest.status,
+        approvalStatus: 'approved',
+        phase: 'Approved',
+        approvedBy,
+        approvedAt: now,
+        reason: reason || undefined
+      };
+
+      return { error: false, pushRequest };
+    },
+
+    denyBranchPush({ intentName, deniedBy, reason, resources = {} }) {
+      if (!intentName) {
+        return { error: true, reason: 'missing-intent-name', message: 'intentName is required' };
+      }
+      if (!deniedBy) {
+        return { error: true, reason: 'missing-denied-by', message: 'deniedBy is required' };
+      }
+
+      const intents = resources.AgentWriteIntent || [];
+      const intent = intents.find((i) => i.metadata?.name === intentName);
+      if (!intent) {
+        return { error: true, reason: 'not-found', message: `AgentWriteIntent not found: ${intentName}` };
+      }
+      if (intent.status?.approvalStatus !== 'pending') {
+        return { error: true, reason: 'already-decided', message: `AgentWriteIntent ${intentName} has already been decided: ${intent.status?.approvalStatus}` };
+      }
+
+      const now = new Date().toISOString();
+      const pushRequest = clone(intent);
+      pushRequest.status = {
+        ...pushRequest.status,
+        approvalStatus: 'denied',
+        phase: 'Denied',
+        deniedBy,
+        deniedAt: now,
+        reason: reason || undefined
+      };
+
+      return { error: false, pushRequest };
+    },
+
+    // -----------------------------------------------------------------------
+    // PR merge with status check enforcement
+    // -----------------------------------------------------------------------
+
+    requestPrMerge({ runRef, prRef, statusChecks = [], requestedBy, namespace = 'default', organizationRef = 'default' }) {
+      if (!runRef) {
+        return { error: true, reason: 'missing-run-ref', message: 'runRef is required' };
+      }
+      if (!prRef) {
+        return { error: true, reason: 'missing-pr-ref', message: 'prRef is required' };
+      }
+
+      // Enforce status check gate — reject if any check is not 'success'
+      const failing = statusChecks.filter((c) => c.state !== 'success');
+      if (failing.length > 0) {
+        const names = failing.map((c) => c.name).join(', ');
+        return { error: true, reason: 'status-checks-failing', message: `The following status checks are not passing: ${names}` };
+      }
+
+      const now = new Date().toISOString();
+      const intentName = `merge-${runRef}-${Date.now()}`;
+
+      const mergeRequest = {
+        kind: 'AgentWriteIntent',
+        metadata: { name: intentName, namespace, labels: {}, annotations: {} },
+        spec: { organizationRef, runRef, prRef, writeType: 'pr-merge', statusChecks: clone(statusChecks), requestedBy: requestedBy || 'unknown', requestedAt: now },
+        status: { approvalStatus: 'pending', phase: 'Pending', createdAt: now }
+      };
+
+      return { error: false, mergeRequest };
+    },
+
+    // -----------------------------------------------------------------------
+    // Write intent validation & status
+    // -----------------------------------------------------------------------
+
+    validateWriteIntent({ intent }) {
+      if (!intent || typeof intent !== 'object') {
+        return { valid: false, error: true, reason: 'invalid-intent', message: 'intent must be an object' };
+      }
+      const writeType = intent.spec?.writeType;
+      if (!writeType || !VALID_WRITE_TYPES.has(writeType)) {
+        return { valid: false, error: true, reason: 'invalid-write-type', message: `Unknown write type: ${writeType}. Must be one of: ${[...VALID_WRITE_TYPES].join(', ')}` };
+      }
+      if (!intent.spec?.runRef) {
+        return { valid: false, error: true, reason: 'missing-run-ref', message: 'intent spec.runRef is required' };
+      }
+      return { valid: true, error: false };
+    },
+
+    getWriteIntentStatus({ intentName, resources = {} }) {
+      if (!intentName) {
+        return { error: true, reason: 'missing-intent-name', message: 'intentName is required' };
+      }
+
+      const intents = resources.AgentWriteIntent || [];
+      const intent = intents.find((i) => i.metadata?.name === intentName);
+      if (!intent) {
+        return { error: true, reason: 'not-found', message: `AgentWriteIntent not found: ${intentName}` };
+      }
+
+      return {
+        error: false,
+        intent: clone(intent),
+        approvalStatus: intent.status?.approvalStatus || 'pending',
+        phase: intent.status?.phase || 'Pending',
+        approvedBy: intent.status?.approvedBy || null,
+        deniedBy: intent.status?.deniedBy || null,
+        approvedAt: intent.status?.approvedAt || null,
+        deniedAt: intent.status?.deniedAt || null,
+        reason: intent.status?.reason || null
+      };
+    },
+
+    // -----------------------------------------------------------------------
+    // B2: Persistence
+    // -----------------------------------------------------------------------
+
+    async persistWriteIntent({ intent, applyResource }) {
+      if (!intent) {
+        return { error: true, reason: 'missing-intent', message: 'intent is required' };
+      }
+      if (typeof applyResource !== 'function') {
+        return { error: true, reason: 'missing-apply-resource', message: 'applyResource function is required' };
+      }
+      try {
+        const applyResult = await applyResource(intent);
+        return { error: false, intent, applyResult };
+      } catch (err) {
+        return { error: true, reason: 'persist-failed', message: err?.message || 'applyResource failed' };
+      }
+    },
+
+    // -----------------------------------------------------------------------
+    // B2: Execution pipeline
+    // -----------------------------------------------------------------------
+
+    async executeWriteIntent({ intent, gateway }) {
+      if (!intent) {
+        return { error: true, reason: 'missing-intent', message: 'intent is required' };
+      }
+
+      const approvalStatus = intent.status?.approvalStatus;
+      if (approvalStatus !== 'approved') {
+        return { error: true, reason: 'not-approved', message: `WriteIntent is not approved (current status: ${approvalStatus})` };
+      }
+
+      const writeType = intent.spec?.writeType;
+
+      try {
+        if (writeType === 'branch-push') {
+          const executionResult = await gateway.pushBranch({
+            branch: intent.spec.branch,
+            targetRepo: intent.spec.targetRepo,
+            runRef: intent.spec.runRef
+          });
+          return { error: false, executionResult };
+        }
+
+        if (writeType === 'pr-merge') {
+          // Validate status checks before merging
+          const statusChecks = intent.spec?.statusChecks || [];
+          const failing = statusChecks.filter((c) => c.state !== 'success');
+          if (failing.length > 0) {
+            const names = failing.map((c) => c.name).join(', ');
+            return { error: true, reason: 'status-checks-failing', message: `The following status checks are not passing: ${names}` };
+          }
+
+          const executionResult = await gateway.mergePr({
+            prRef: intent.spec.prRef,
+            runRef: intent.spec.runRef
+          });
+          return { error: false, executionResult };
+        }
+
+        return { error: true, reason: 'unsupported-write-type', message: `Execution not supported for writeType: ${writeType}` };
+      } catch (err) {
+        return { error: true, reason: 'execution-failed', message: err?.message || 'Gateway execution failed' };
+      }
+    }
+  };
+}

package/src/api-controller.js

@@ -1,8 +1,17 @@
 import { createKubernetesResourceGateway } from './kubernetes-resource-gateway.js';
+import { clearSnapshotCache } from './snapshot-cache.js';
 import { createPermissionReviewer } from './agent-permission-review.js';
 import { createAgentDispatchController } from './agent-dispatch-controller.js';
 import { createAgentApprovalController } from './agent-approval-controller.js';
 import { createAgentTriggerController } from './agent-trigger-controller.js';
+import { createAgentWorkspaceController } from './agent-workspace-controller.js';
+import { createAgentMemoryController } from './agent-memory-controller.js';
+import { orgNamespaceName, normalizeOrgSlug } from './org-scoping.js';
+import { globalEventBus } from './event-bus.js';
+import { createSyncController } from './external/sync-controller.js';
+import { createWebhookController } from './external/webhook-controller.js';
+import { createWriteController } from './external/write-controller.js';
+import { createConflictController } from './external/conflict-controller.js';
 
 export const KRATE_API_CONTROLLER_BOUNDARY = {
   role: 'krate-api-controller',
@@ -15,6 +24,24 @@ export const KRATE_API_CONTROLLER_BOUNDARY = {
 export function createKrateApiController(options = {}) {
   const resourceGateway = options.resourceGateway || createKubernetesResourceGateway(options);
   const namespace = options.namespace || resourceGateway.namespace || process.env.KRATE_NAMESPACE || 'krate-system';
+  const onAuditEvent = typeof options.onAuditEvent === 'function' ? options.onAuditEvent : null;
+
+  function emitAuditEvent(resource, operation) {
+    if (!onAuditEvent) return;
+    try {
+      const org = resource.spec?.organizationRef || resource.metadata?.labels?.['krate.a5c.ai/org'] || '';
+      onAuditEvent({
+        operation,
+        org,
+        namespace: org ? orgNamespaceName(org) : (resource.metadata?.namespace || namespace),
+        kind: resource.kind,
+        name: resource.metadata?.name,
+        timestamp: new Date().toISOString()
+      });
+    } catch {
+      // Audit failures must not crash apply operations
+    }
+  }
 
   return {
     role: 'krate-api-controller',
@@ -36,18 +63,133 @@ export function createKrateApiController(options = {}) {
     async listResource(kindOrPlural) {
       return resourceGateway.list(kindOrPlural);
     },
+    async listResourceForOrg(org, kindOrPlural) {
+      const orgNs = orgNamespaceName(normalizeOrgSlug(org));
+      // Client-side filtering is used because the resource gateway's list()
+      // method does not currently support namespace-scoped listing.  The
+      // gateway aggregates resources across namespaces at snapshot time, so
+      // filtering here is both correct and consistent with the gateway API.
+      const result = await resourceGateway.list(kindOrPlural);
+      const items = normalizeResourceList(result).filter(
+        (item) => item.metadata?.namespace === orgNs
+      );
+      return { ...result, items };
+    },
     async getResource(kindOrPlural, name) {
       return resourceGateway.get(kindOrPlural, name);
     },
     async applyResource(resource) {
-      return resourceGateway.apply(resource);
+      // Cross-org admission check: if the resource has an organizationRef,
+      // ensure the namespace matches the org's derived namespace.
+      const resourceOrg = resource.spec?.organizationRef;
+      const resourceNs = resource.metadata?.namespace;
+      if (resourceOrg) {
+        const expectedNs = orgNamespaceName(resourceOrg);
+        if (resourceNs && resourceNs !== expectedNs) {
+          // Explicit namespace does not match the org — reject
+          throw new Error(
+            `Cross-org namespace mismatch: resource organizationRef "${resourceOrg}" expects namespace "${expectedNs}" but got "${resourceNs}"`
+          );
+        }
+        if (!resourceNs) {
+          // organizationRef present but no namespace — auto-assign
+          resource = {
+            ...resource,
+            metadata: { ...resource.metadata, namespace: expectedNs }
+          };
+        }
+      }
+      const result = await resourceGateway.apply(resource);
+      clearSnapshotCache();
+      const appliedResource = result.resource || resource;
+      emitAuditEvent(appliedResource, result.operation || 'apply');
+      globalEventBus.emitResourceChange(
+        appliedResource.kind || resource.kind || 'Unknown',
+        appliedResource.metadata?.name || resource.metadata?.name || 'unknown',
+        result.operation || 'apply'
+      );
+      return result;
+    },
+    async applyResourceForOrg(orgSlug, resource) {
+      const slug = normalizeOrgSlug(orgSlug);
+      const orgNs = orgNamespaceName(slug);
+      const resourceOrg = resource.spec?.organizationRef;
+      if (resourceOrg && normalizeOrgSlug(resourceOrg) !== slug) {
+        throw new Error(
+          `Org mismatch: resource organizationRef "${resourceOrg}" does not match target org "${slug}"`
+        );
+      }
+      const scopedResource = {
+        ...resource,
+        metadata: { ...resource.metadata, namespace: orgNs },
+        spec: { ...resource.spec, organizationRef: slug }
+      };
+      const result = await resourceGateway.apply(scopedResource);
+      clearSnapshotCache();
+      const appliedResource = result.resource || scopedResource;
+      emitAuditEvent(appliedResource, result.operation || 'apply');
+      globalEventBus.emitResourceChange(
+        appliedResource.kind || scopedResource.kind || 'Unknown',
+        appliedResource.metadata?.name || scopedResource.metadata?.name || 'unknown',
+        result.operation || 'apply'
+      );
+      return { ...result, resource: appliedResource };
     },
     async deleteResource(kindOrPlural, name) {
-      return resourceGateway.delete(kindOrPlural, name);
+      const result = await resourceGateway.delete(kindOrPlural, name);
+      clearSnapshotCache();
+      emitAuditEvent(
+        { kind: kindOrPlural, metadata: { name, namespace }, spec: {} },
+        'delete'
+      );
+      globalEventBus.emitResourceChange(kindOrPlural, name, 'delete');
+      return result;
+    },
+    async deleteResourceForOrg(orgSlug, kindOrPlural, name) {
+      const slug = normalizeOrgSlug(orgSlug);
+      const orgNs = orgNamespaceName(slug);
+      // Verify the resource exists and belongs to the org before deleting
+      const existing = await resourceGateway.get(kindOrPlural, name);
+      const resource = existing?.resource || existing;
+      if (resource) {
+        const resourceNs = resource.metadata?.namespace;
+        if (!resourceNs || resourceNs !== orgNs) {
+          throw new Error(
+            `Cross-org denial: resource "${name}" is in namespace "${resourceNs || '(none)'}" which does not match org "${slug}" namespace "${orgNs}"`
+          );
+        }
+      }
+      const result = await resourceGateway.delete(kindOrPlural, name);
+      clearSnapshotCache();
+      emitAuditEvent(
+        { kind: kindOrPlural, metadata: { name, namespace: orgNs }, spec: { organizationRef: slug } },
+        'delete'
+      );
+      globalEventBus.emitResourceChange(kindOrPlural, name, 'delete');
+      return result;
+    },
+    async getResourceForOrg(orgSlug, kindOrPlural, name) {
+      const slug = normalizeOrgSlug(orgSlug);
+      const orgNs = orgNamespaceName(slug);
+      const existing = await resourceGateway.get(kindOrPlural, name);
+      const resource = existing?.resource || existing;
+      if (resource) {
+        const resourceNs = resource.metadata?.namespace;
+        if (!resourceNs || resourceNs !== orgNs) {
+          throw new Error(
+            `Cross-org denial: resource "${name}" is in namespace "${resourceNs || '(none)'}" which does not match org "${slug}" namespace "${orgNs}"`
+          );
+        }
+      }
+      return existing;
     },
     async createRepository(input) {
       const created = await resourceGateway.createRepository(input);
       const repository = created?.resource || created;
+      emitAuditEvent(
+        repository?.kind ? repository : { kind: 'Repository', metadata: repository?.metadata || { name: input.name || input.metadata?.name }, spec: repository?.spec || input.spec || input },
+        'create-repository'
+      );
       return {
         operation: created?.operation || 'create-repository',
         command: created?.command || 'kubectl apply -f -',
@@ -56,7 +198,13 @@ export function createKrateApiController(options = {}) {
       };
     },
     async createOrganization(input) {
-      return resourceGateway.createOrganization(input);
+      const result = await resourceGateway.createOrganization(input);
+      const orgResource = result?.organization || result?.resource || result;
+      emitAuditEvent(
+        orgResource?.kind ? orgResource : { kind: 'Organization', metadata: orgResource?.metadata || { name: input.slug || input.name || input.metadata?.name }, spec: orgResource?.spec || input.spec || input },
+        'create-organization'
+      );
+      return result;
     },
     watchResource(resourcePath, handlers = {}) {
       return resourceGateway.watch(resourcePath, handlers);
@@ -105,6 +253,193 @@ export function createKrateApiController(options = {}) {
         namespace: input.namespace || namespace,
         organizationRef: input.organizationRef || 'default',
       });
+    },
+    async provisionAgentWorkspace(input) {
+      const workspaceController = createAgentWorkspaceController();
+      return workspaceController.provisionWorkspace({
+        ...input,
+        namespace: input.namespace || namespace,
+        organizationRef: input.organizationRef || 'default'
+      });
+    },
+    async archiveAgentWorkspace(input) {
+      const snapshot = await this.snapshot();
+      const workspaceController = createAgentWorkspaceController();
+      return workspaceController.archiveWorkspace({
+        ...input,
+        resources: snapshot.resources
+      });
+    },
+    async linkWorkItem(input) {
+      const workspaceController = createAgentWorkspaceController();
+      return workspaceController.linkWorkItem({
+        ...input,
+        namespace: input.namespace || namespace,
+        organizationRef: input.organizationRef || 'default'
+      });
+    },
+    async queryAgentMemory(input) {
+      const memoryController = createAgentMemoryController();
+      return memoryController.queryMemory({
+        ...input,
+        namespace: input.namespace || namespace,
+        organizationRef: input.organizationRef || 'default'
+      });
+    },
+    async createMemoryImport(input) {
+      const memoryController = createAgentMemoryController();
+      return memoryController.createImport({
+        ...input,
+        namespace: input.namespace || namespace,
+        organizationRef: input.organizationRef || 'default'
+      });
+    },
+
+    // ---------------------------------------------------------------------------
+    // External controller integration
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Sync an external resource into the Krate resource store.
+     * Creates a SyncController with a persistFn that calls applyResource, then
+     * upserts the resource and optionally advances the watermark.
+     *
+     * @param {string} bindingName
+     * @param {{ kind, localName, namespace?, spec, externalEnvelope, watermark? }} options
+     */
+    async syncExternalBinding(bindingName, options = {}) {
+      const self = this;
+      const syncController = createSyncController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+
+      const {
+        kind,
+        localName,
+        namespace: resourceNamespace = 'default',
+        spec = {},
+        externalEnvelope,
+        watermark
+      } = options;
+
+      const resource = syncController.upsertResource({
+        kind,
+        localName,
+        namespace: resourceNamespace,
+        spec,
+        externalEnvelope
+      });
+
+      if (watermark) {
+        syncController.updateWatermark(bindingName, watermark);
+      }
+
+      // Keep a reference to the sync controller so getExternalSyncStatus can read it
+      if (!self._syncControllers) self._syncControllers = new Map();
+      self._syncControllers.set(bindingName, syncController);
+
+      return { resource, bindingName };
+    },
+
+    /**
+     * Create a write intent for an external operation.
+     *
+     * @param {{ interfaceKey, operation, payload?, resourceRef, requiresApproval?,
+     *           maxRetries?, namespace?, organizationRef? }} input
+     */
+    async createExternalWriteIntent(input) {
+      const writeController = createWriteController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+      return writeController.createWriteIntent(input);
+    },
+
+    /**
+     * Approve a PendingApproval ExternalWriteIntent.
+     *
+     * @param {{ intentName, approvedBy, resources? }} opts
+     */
+    async approveExternalWriteIntent(opts) {
+      const writeController = createWriteController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+      return writeController.approveWriteIntent(opts);
+    },
+
+    /**
+     * Cancel (reject) an ExternalWriteIntent.
+     *
+     * @param {{ intentName, cancelledBy, resources? }} opts
+     */
+    async cancelExternalWriteIntent({ intentName, cancelledBy, resources } = {}) {
+      const writeController = createWriteController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+      return writeController.rejectWriteIntent({
+        intentName,
+        rejectedBy: cancelledBy,
+        reason: 'cancelled',
+        resources
+      });
+    },
+
+    /**
+     * Detect a conflict between local and external field values.
+     *
+     * @param {{ resourceRef, fieldPath, localValue, externalValue, namespace?, organizationRef? }} input
+     */
+    async detectExternalConflict(input) {
+      const conflictController = createConflictController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+      return conflictController.detectConflict(input);
+    },
+
+    /**
+     * Resolve an Open ExternalSyncConflict using the specified strategy.
+     *
+     * @param {{ conflictName, strategy, resolvedValue?, resources? }} opts
+     */
+    async resolveExternalConflict(opts) {
+      const conflictController = createConflictController({
+        persistFn: async (resource) => {
+          await resourceGateway.apply(resource);
+        }
+      });
+      return conflictController.resolveConflict(opts);
+    },
+
+    /**
+     * Return the current sync state for a binding (watermark, etc.).
+     *
+     * @param {string} bindingName
+     * @returns {{ bindingName: string, watermark: string|null }}
+     */
+    async getExternalSyncStatus(bindingName) {
+      const syncController = this._syncControllers?.get(bindingName);
+      const watermark = syncController ? syncController.getWatermark(bindingName) : null;
+      return { bindingName, watermark };
+    },
+
+    /**
+     * Process an inbound external webhook payload.
+     * Creates a WebhookController, processes the delivery, and emits events.
+     *
+     * @param {{ deliveryId, eventType, payload, rawBody, providerType?, secret? }} params
+     */
+    async processExternalWebhook({ deliveryId, eventType, payload, rawBody, providerType, secret } = {}) {
+      const webhookController = createWebhookController({ secret: secret || '' });
+      return webhookController.processDelivery({ deliveryId, eventType, payload, rawBody });
     }
   };
 }