@aifabrix/builder 2.60.0 → 2.62.0

package/lib/datasource/capability/run-capability-upsert.js

@@ -0,0 +1,202 @@
+/**
+ * File-backed upsert capability authoring with validation and atomic write.
+ *
+ * @fileoverview Run datasource capability upsert CLI operation
+ */
+
+'use strict';
+
+const {
+  readDatasourceConfigFile,
+  writeBackup,
+  atomicWriteJson
+} = require('./run-capability-copy');
+const { validateDatasourceParsed, resolveValidateInputPath } = require('../validate');
+const {
+  resolveVendorOpenApiSpec,
+  inferIntegrationContextFromPath
+} = require('../../validation/openapi-contract-surface-validator');
+const { analyzeUpsertIngredients } = require('./upsert-ingredients');
+const { applyUpsertCapability, existingUpsertMatches } = require('./upsert-operations');
+const { scaffoldUpsertTests } = require('./upsert-test-scaffold');
+
+function parseIdentityFields(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return [];
+  return [...new Set(String(raw).split(',').map((field) => field.trim()).filter(Boolean))];
+}
+
+function applyExplicitIdentity(doc, fields) {
+  if (fields.length === 0) return [];
+  const mapped = new Set(Object.keys(doc.fieldMappings?.attributes || {}));
+  const primary = new Set(Array.isArray(doc.primaryKey) ? doc.primaryKey : []);
+  const invalid = fields.filter((field) => !mapped.has(field) || primary.has(field));
+  if (invalid.length > 0) {
+    throw new Error(
+      `--identity must name mapped non-primary-key fields; invalid: ${invalid.join(', ')}`
+    );
+  }
+  if (!doc.validation) doc.validation = {};
+  if (!Array.isArray(doc.validation.repeatingValues)) {
+    doc.validation.repeatingValues = [];
+  }
+  const added = [];
+  fields.forEach((field) => {
+    const existing = doc.validation.repeatingValues.find((row) => row?.field === field);
+    if (existing && existing.strategy !== 'reject') {
+      throw new Error(`validation.repeatingValues for "${field}" already uses ${existing.strategy}`);
+    }
+    if (!existing) {
+      doc.validation.repeatingValues.push({ field, scope: ['global'], strategy: 'reject' });
+      added.push(field);
+    }
+  });
+  return added;
+}
+
+function resolveVendorSpec(doc, resolvedPath, providedSpec) {
+  if (providedSpec) return { spec: providedSpec, localPath: null };
+  const context = inferIntegrationContextFromPath(resolvedPath);
+  const documentKey = typeof doc.openapi?.documentKey === 'string'
+    ? doc.openapi.documentKey.trim()
+    : '';
+  if (!context || !documentKey) return { spec: null, localPath: null };
+  return resolveVendorOpenApiSpec(context.appPath, context.systemKey, documentKey);
+}
+
+function ineligibleError(analysis, vendor) {
+  const detail = analysis.issues.map((row) => `${row.code}: ${row.message}`).join('\n');
+  const error = new Error(detail || 'Upsert ingredients are not eligible');
+  error.analysis = analysis;
+  error.vendorOpenApiPath = vendor.localPath;
+  return error;
+}
+
+function applyTestScaffold(result, analysis, targetKey) {
+  const scaffold = scaffoldUpsertTests(result.doc, analysis, targetKey);
+  if (scaffold.issue) {
+    throw ineligibleError({
+      eligible: false,
+      status: 'author-fixable',
+      issues: [scaffold.issue]
+    }, { localPath: null });
+  }
+  if (!scaffold.changed) return false;
+  result.doc = scaffold.doc;
+  result.patchOperations.push(...scaffold.patchOperations);
+  result.updatedSections.push(...scaffold.updatedSections);
+  return true;
+}
+
+function buildEnvelope(opts, parsed, analysis, result) {
+  return {
+    changed: true,
+    eligible: true,
+    capabilityKey: result.resolvedAs,
+    identityFields: analysis.identityFields,
+    createKey: analysis.halves.create.logical,
+    updateKey: analysis.halves.update.logical,
+    lookupCandidates: analysis.lookupCandidates,
+    issues: analysis.issues,
+    patchOperations: result.patchOperations,
+    nextActions: [
+      `aifabrix datasource capability validate ${opts.fileOrKey} --capability ${result.resolvedAs}`,
+      `aifabrix validate ${parsed.systemKey || '<system-key>'}`,
+      `aifabrix datasource test-e2e ${parsed.key || '<datasource-key>'} --app ${parsed.systemKey || '<system-key>'} --json`
+    ]
+  };
+}
+
+function prependIdentityPatches(result, doc, added, state) {
+  if (added.length === 0) return;
+  let patches;
+  if (!state.hadValidation) {
+    patches = [{ op: 'add', path: '/validation', value: doc.validation }];
+  } else if (!state.hadRepeatingValues) {
+    patches = [{
+      op: 'add',
+      path: '/validation/repeatingValues',
+      value: doc.validation.repeatingValues
+    }];
+  } else {
+    patches = added.map((field) => ({
+      op: 'add',
+      path: '/validation/repeatingValues/-',
+      value: { field, scope: ['global'], strategy: 'reject' }
+    }));
+  }
+  result.patchOperations.unshift(...patches);
+  added.forEach((field) => result.updatedSections.push(`validation.repeatingValues: ${field}`));
+}
+
+function unchangedUpsertResult(opts, parsed, analysis, resolvedPath) {
+  const result = { resolvedAs: opts.as || 'upsert', patchOperations: [], updatedSections: [] };
+  const validation = validateDatasourceParsed(parsed);
+  const envelope = buildEnvelope(opts, parsed, analysis, result);
+  return {
+    ...envelope,
+    changed: false,
+    dryRun: Boolean(opts.dryRun),
+    resolvedPath,
+    backupPath: null,
+    updatedSections: [],
+    validation
+  };
+}
+
+function validateGeneratedDoc(doc) {
+  const validation = validateDatasourceParsed(doc);
+  if (validation.valid) return validation;
+  const error = new Error(validation.errors.join('\n'));
+  error.validationErrors = validation.errors;
+  throw error;
+}
+
+function finishUpsertRun(opts, resolvedPath, result, envelope, validation) {
+  const common = { resolvedPath, updatedSections: result.updatedSections, validation };
+  if (opts.dryRun) return { ...envelope, ...common, dryRun: true, backupPath: null };
+  const backupPath = writeBackup(resolvedPath, Boolean(opts.noBackup));
+  atomicWriteJson(resolvedPath, result.doc);
+  return { ...envelope, ...common, dryRun: false, backupPath };
+}
+
+async function runCapabilityUpsert(opts) {
+  const resolvedPath = resolveValidateInputPath(String(opts.fileOrKey || '').trim());
+  const parsed = readDatasourceConfigFile(resolvedPath);
+  const identityState = {
+    hadValidation: Boolean(parsed.validation),
+    hadRepeatingValues: Array.isArray(parsed.validation?.repeatingValues)
+  };
+  const identityAdded = applyExplicitIdentity(parsed, parseIdentityFields(opts.identity));
+  const vendor = resolveVendorSpec(parsed, resolvedPath, opts.vendorSpec);
+  const analysis = analyzeUpsertIngredients(parsed, {
+    createKey: opts.create || 'create',
+    updateKey: opts.update || 'update',
+    targetKey: opts.as || 'upsert',
+    vendorSpec: vendor.spec
+  });
+  if (!analysis.eligible) throw ineligibleError(analysis, vendor);
+  const targetKey = opts.as || 'upsert';
+  const targetMatches = !opts.overwrite && existingUpsertMatches(parsed, analysis, targetKey);
+  const result = targetMatches
+    ? { doc: parsed, resolvedAs: targetKey, patchOperations: [], updatedSections: [] }
+    : applyUpsertCapability(parsed, analysis, {
+      targetKey,
+      overwrite: Boolean(opts.overwrite)
+    });
+  prependIdentityPatches(result, parsed, identityAdded, identityState);
+  const testChanged = opts.test ? applyTestScaffold(result, analysis, targetKey) : false;
+  if (targetMatches && identityAdded.length === 0 && !testChanged) {
+    return unchangedUpsertResult(opts, parsed, analysis, resolvedPath);
+  }
+  const validation = validateGeneratedDoc(result.doc);
+  const envelope = buildEnvelope(opts, parsed, analysis, result);
+  return finishUpsertRun(opts, resolvedPath, result, envelope, validation);
+}
+
+module.exports = {
+  runCapabilityUpsert,
+  parseIdentityFields,
+  applyExplicitIdentity,
+  resolveVendorSpec,
+  applyTestScaffold
+};

package/lib/datasource/capability/upsert-ingredients.js

@@ -0,0 +1,291 @@
+/**
+ * Static authoring eligibility for manifest-declared upsert capabilities.
+ *
+ * @fileoverview Upsert ingredient analysis without runtime readiness claims
+ */
+
+'use strict';
+
+const { findVendorOperation } = require('../../validation/openapi-contract-vendor-validation');
+const {
+  resolveSourceCapabilityForCopy,
+  resolveOpsKeysForCapability
+} = require('./capability-resolve');
+
+const FUZZY_TOKENS = new Set([
+  'contains', 'like', 'ilike', 'token', 'tokenized', 'prefix', 'suffix',
+  'substring', 'fuzzy', 'partial', 'startswith', 'endswith'
+]);
+
+const ISSUE_GUIDANCE = {
+  'UPSERT-HALF-INVALID': {
+    consequence: 'The upsert would not compose one valid create half and one valid update half.',
+    remediation: ['Repair or select existing create-shaped and update-shaped capabilities.'],
+    prevention: 'Validate each write capability before composing upsert.',
+    residualRisk: 'Authoring remains blocked until both halves are valid.'
+  },
+  'UPSERT-IDENTITY-MISSING': {
+    consequence: 'Record existence cannot be resolved, so a retry may create a duplicate.',
+    remediation: ['Declare mapped business identity fields explicitly with --identity.'],
+    prevention: 'Model business identity before adding write orchestration.',
+    residualRisk: 'Do not publish or claim upsert while identity is absent.'
+  },
+  'UPSERT-IDENTITY-UNMAPPED': {
+    consequence: 'The runtime cannot bind every declared identity field to source data.',
+    remediation: ['Add valid field mappings or select mapped non-primary-key identity fields.'],
+    prevention: 'Keep identity declarations and field mappings in the same review.',
+    residualRisk: 'An incomplete identity can select or update the wrong record.'
+  },
+  'UPSERT-OPENAPI-UNRESOLVED': {
+    consequence: 'Builder cannot establish static authoring eligibility.',
+    remediation: ['Materialize the registered vendor OpenAPI document, then rerun the command.'],
+    prevention: 'Keep the vendor OpenAPI document synchronized before capability authoring.',
+    residualRisk: 'Source support is unknown; no capability was written.'
+  },
+  'UPSERT-EXACT-LOOKUP-MISSING': {
+    consequence: 'A write may create a duplicate or update the wrong business record.',
+    remediation: [
+      'Bind the complete identity to a real equality lookup when the source supports it.',
+      'If the source cannot support exact lookup, keep separate create and update capabilities.'
+    ],
+    prevention: 'Require complete equality binding and a two-write no-duplicate E2E case.',
+    residualRisk: 'AI cannot repair an external API that lacks exact lookup or uniqueness.'
+  }
+};
+
+function uniqueStrings(values) {
+  return [...new Set(values.map((value) => String(value).trim()).filter(Boolean))];
+}
+
+function declaredIdentityFields(doc) {
+  const primary = new Set(uniqueStrings(Array.isArray(doc.primaryKey) ? doc.primaryKey : []));
+  const rows = Array.isArray(doc.validation?.repeatingValues)
+    ? doc.validation.repeatingValues
+    : [];
+  return uniqueStrings(
+    rows
+      .filter((row) => row?.strategy === 'reject' && !primary.has(row.field))
+      .map((row) => row.field)
+  );
+}
+
+function mappedFields(doc) {
+  const attrs = doc.fieldMappings?.attributes;
+  return new Set(attrs && typeof attrs === 'object' ? Object.keys(attrs) : []);
+}
+
+function assertSourceHalf(doc, logicalKey, expectedShape) {
+  const logical = resolveSourceCapabilityForCopy(doc, logicalKey);
+  const keys = resolveOpsKeysForCapability(doc, logical);
+  const operation = doc.execution.cip.operations[keys.cipKey];
+  if (operation?.enabled === false) {
+    throw new Error(`${expectedShape} capability "${logicalKey}" is disabled`);
+  }
+  if (operation?.shape && operation.shape !== expectedShape) {
+    throw new Error(
+      `${expectedShape} capability "${logicalKey}" declares shape "${operation.shape}"`
+    );
+  }
+  return { logical, ...keys };
+}
+
+function collectText(node, out = []) {
+  if (typeof node === 'string') {
+    out.push(node.toLowerCase());
+    return out;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((item) => collectText(item, out));
+    return out;
+  }
+  if (node && typeof node === 'object') {
+    Object.entries(node).forEach(([key, value]) => {
+      out.push(String(key).toLowerCase());
+      collectText(value, out);
+    });
+  }
+  return out;
+}
+
+function resolveLocalSchema(schema, vendorSpec) {
+  const ref = schema?.$ref;
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return schema;
+  return ref.slice(2).split('/').reduce((node, token) => node?.[token], vendorSpec) || schema;
+}
+
+function collectVendorParameterNames(vendorOp, vendorSpec) {
+  const names = [];
+  const parameters = Array.isArray(vendorOp?.parameters) ? vendorOp.parameters : [];
+  parameters
+    .filter((parameter) => !parameter?.in || parameter.in === 'query')
+    .forEach((parameter) => names.push(parameter?.name));
+  const rawSchema = vendorOp?.requestBody?.content?.['application/json']?.schema;
+  const schema = resolveLocalSchema(rawSchema, vendorSpec);
+  if (schema?.properties && typeof schema.properties === 'object') {
+    names.push(...Object.keys(schema.properties));
+  }
+  return uniqueStrings(names).map((name) => name.toLowerCase());
+}
+
+function operationBinding(doc, operationKey) {
+  const cip = doc.execution?.cip?.operations?.[operationKey];
+  const steps = Array.isArray(cip?.steps) ? cip.steps : [];
+  const fetch = steps.map((step) => step?.fetch).find(Boolean);
+  return fetch || {};
+}
+
+function templateReferencesField(value, field) {
+  if (typeof value === 'string') {
+    const templates = [...value.matchAll(/\{\{([^}]+)\}\}/g)];
+    return templates.some((match) =>
+      match[1].toLowerCase().split(/[^a-z0-9_]+/).includes(field.toLowerCase())
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => templateReferencesField(item, field));
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.values(value).some((item) => templateReferencesField(item, field));
+}
+
+function bindingCarriesField(binding, vendorOp, vendorSpec, field) {
+  const accepted = new Set(collectVendorParameterNames(vendorOp, vendorSpec));
+  const containers = [binding.query, binding.bodyTemplate, binding.parameters];
+  return containers.some((container) =>
+    container && typeof container === 'object' && !Array.isArray(container) &&
+    Object.entries(container).some(([key, value]) =>
+      accepted.has(key.toLowerCase()) && templateReferencesField(value, field)
+    )
+  );
+}
+
+function candidateCoverage(doc, opKey, opCfg, vendorOp, identityFields, vendorSpec) {
+  const binding = operationBinding(doc, opKey);
+  const text = collectText({
+    query: binding.query,
+    bodyTemplate: binding.bodyTemplate,
+    parameters: binding.parameters
+  });
+  const coveredFields = identityFields.filter((field) =>
+    bindingCarriesField(binding, vendorOp, vendorSpec, field)
+  );
+  const fuzzy = text.some((item) =>
+    [...FUZZY_TOKENS].some((token) => item === token || item.includes(`"${token}"`))
+  );
+  return {
+    operationKey: opKey,
+    operationId: opCfg.operationId || null,
+    method: String(opCfg.method || 'get').toUpperCase(),
+    coveredFields,
+    missingFields: identityFields.filter((field) => !coveredFields.includes(field)),
+    fuzzy
+  };
+}
+
+function analyzeLookupCandidates(doc, vendorSpec, identityFields, excludedKeys) {
+  const operations = doc.openapi?.operations || {};
+  return Object.entries(operations)
+    .filter(([key]) => !excludedKeys.has(key.toLowerCase()))
+    .map(([key, config]) => {
+      const vendorOp = findVendorOperation(vendorSpec, config);
+      if (!vendorOp) return null;
+      return candidateCoverage(doc, key, config, vendorOp, identityFields, vendorSpec);
+    })
+    .filter(Boolean);
+}
+
+function issue(code, message, ownership, missingFields = []) {
+  return {
+    code,
+    severity: 'blocking',
+    message,
+    observed: message,
+    ownership,
+    aiFixable: ownership === 'manifest',
+    missingFields,
+    ...(ISSUE_GUIDANCE[code] || {})
+  };
+}
+
+function blocked(status, context, finding) {
+  return { eligible: false, status, ...context, issues: [finding] };
+}
+
+function analyzeIdentity(doc, halves) {
+  const identityFields = declaredIdentityFields(doc);
+  const context = { halves, identityFields, lookupCandidates: [] };
+  if (identityFields.length === 0) {
+    return blocked('author-fixable', context, issue(
+      'UPSERT-IDENTITY-MISSING',
+      'No mapped business identity is declared with validation.repeatingValues strategy reject',
+      'manifest'
+    ));
+  }
+  const unmapped = identityFields.filter((field) => !mappedFields(doc).has(field));
+  if (unmapped.length === 0) return context;
+  return blocked('author-fixable', context, issue(
+    'UPSERT-IDENTITY-UNMAPPED',
+    `Business identity fields are not mapped: ${unmapped.join(', ')}`,
+    'manifest',
+    unmapped
+  ));
+}
+
+function noExactLookup(halves, identityFields, lookupCandidates) {
+  const covered = new Set(lookupCandidates.flatMap((candidate) => candidate.coveredFields));
+  const missing = identityFields.filter((field) => !covered.has(field));
+  const suffix = missing.length ? `; uncovered: ${missing.join(', ')}` : '';
+  return blocked(
+    'source-limited',
+    { halves, identityFields, lookupCandidates },
+    issue(
+      'UPSERT-EXACT-LOOKUP-MISSING',
+      `No declared non-fuzzy read covers the full business identity${suffix}`,
+      'manifest-or-source',
+      missing
+    )
+  );
+}
+
+function analyzeUpsertIngredients(doc, options = {}) {
+  const createKey = options.createKey || 'create';
+  const updateKey = options.updateKey || 'update';
+  let halves;
+  try {
+    halves = {
+      create: assertSourceHalf(doc, createKey, 'create'),
+      update: assertSourceHalf(doc, updateKey, 'update')
+    };
+  } catch (error) {
+    return blocked(
+      'author-fixable',
+      { identityFields: [], lookupCandidates: [] },
+      issue('UPSERT-HALF-INVALID', error.message, 'manifest')
+    );
+  }
+  const identity = analyzeIdentity(doc, halves);
+  if (identity.eligible === false) return identity;
+  const { identityFields } = identity;
+  if (!options.vendorSpec) {
+    return blocked('indeterminate', identity, issue(
+      'UPSERT-OPENAPI-UNRESOLVED',
+      'The materialized vendor OpenAPI document could not be resolved',
+      'local-openapi'
+    ));
+  }
+  const excluded = new Set([
+    halves.create.openapiKey.toLowerCase(), halves.update.openapiKey.toLowerCase(),
+    String(options.targetKey || 'upsert').toLowerCase()
+  ]);
+  const lookupCandidates = analyzeLookupCandidates(doc, options.vendorSpec, identityFields, excluded);
+  const exact = lookupCandidates.find((candidate) => !candidate.fuzzy && candidate.missingFields.length === 0);
+  if (!exact) return noExactLookup(halves, identityFields, lookupCandidates);
+  return { eligible: true, status: 'eligible', halves, identityFields, lookupCandidates, selectedLookup: exact, issues: [] };
+}
+
+module.exports = {
+  analyzeUpsertIngredients,
+  declaredIdentityFields,
+  collectVendorParameterNames,
+  candidateCoverage
+};

package/lib/datasource/capability/upsert-operations.js

@@ -0,0 +1,138 @@
+/**
+ * Create the canonical manifest-declared upsert slice after eligibility passes.
+ *
+ * @fileoverview Pure upsert manifest mutation
+ */
+
+'use strict';
+
+const { jsonPointerPath } = require('./json-pointer');
+const { storageOpsKey } = require('./capability-storage-keys');
+const {
+  deepClone,
+  removeCapability,
+  resolveTargetKey
+} = require('./copy-operations');
+const { resolveProfileKeyForLogical, capabilityLogicalExists } = require('./capability-resolve');
+const { buildCapabilityObject } = require('./capability-manifest');
+
+function profileFields(profile) {
+  if (Array.isArray(profile)) return profile;
+  if (profile && Array.isArray(profile.attributes)) return profile.attributes;
+  return [];
+}
+
+function buildUpsertProfile(doc, createLogical, updateLogical, identityFields) {
+  const createKey = resolveProfileKeyForLogical(doc, createLogical);
+  const updateKey = resolveProfileKeyForLogical(doc, updateLogical);
+  const createFields = profileFields(createKey ? doc.exposed.profiles[createKey] : null);
+  const updateSet = new Set(profileFields(updateKey ? doc.exposed.profiles[updateKey] : null));
+  const common = createFields.filter((field) => updateSet.has(field));
+  const fields = [...new Set([...common, ...identityFields])];
+  if (fields.length === 0) {
+    throw new Error('Create and update profiles have no shared input fields');
+  }
+  return fields;
+}
+
+function buildOpenApiOperation(createOperation, targetKey) {
+  const operation = deepClone(createOperation);
+  operation.operationId = targetKey;
+  operation.method = 'POST';
+  operation.restRuntime = {
+    pathKind: 'collectionSubresource',
+    subpathSegments: [targetKey]
+  };
+  return operation;
+}
+
+function buildCipOperation(doc, targetKey, createKey, updateKey, identityFields) {
+  return {
+    enabled: true,
+    description: `Create or update ${doc.displayName || doc.key || 'record'} by ${identityFields.join(', ')}`,
+    shape: 'upsert',
+    steps: [
+      { fetch: { source: 'datasource', datasource: doc.key, operation: createKey } },
+      { fetch: { source: 'datasource', datasource: doc.key, operation: updateKey } },
+      { output: { mode: 'records' } }
+    ]
+  };
+}
+
+function addCapability(doc, targetKey) {
+  if (!Array.isArray(doc.capabilities)) doc.capabilities = [];
+  const usesObjects = doc.capabilities.some((row) => row && typeof row === 'object');
+  const value = usesObjects
+    ? { ...buildCapabilityObject(targetKey, doc.displayName || doc.key), description: `Create or update ${doc.displayName || doc.key || 'record'}` }
+    : targetKey;
+  doc.capabilities.push(value);
+  return value;
+}
+
+function applyUpsertCapability(originalDoc, analysis, options = {}) {
+  if (!analysis?.eligible) throw new Error('Upsert ingredients are not eligible');
+  const doc = deepClone(originalDoc);
+  const targetKey = resolveTargetKey(doc, options.targetKey || 'upsert', Boolean(options.overwrite));
+  if (options.overwrite && capabilityLogicalExists(doc, targetKey)) removeCapability(doc, targetKey);
+  const storageKey = storageOpsKey(targetKey);
+  const createOperation = doc.openapi.operations[analysis.halves.create.openapiKey];
+  const openapiOperation = buildOpenApiOperation(createOperation, targetKey);
+  const cipOperation = buildCipOperation(
+    doc, targetKey, analysis.halves.create.logical, analysis.halves.update.logical,
+    analysis.identityFields
+  );
+  const profile = buildUpsertProfile(
+    doc, analysis.halves.create.logical, analysis.halves.update.logical,
+    analysis.identityFields
+  );
+  doc.openapi.operations[storageKey] = openapiOperation;
+  doc.execution.cip.operations[storageKey] = cipOperation;
+  if (!doc.exposed) doc.exposed = {};
+  if (!doc.exposed.profiles) doc.exposed.profiles = {};
+  doc.exposed.profiles[targetKey] = profile;
+  const capability = addCapability(doc, targetKey);
+  const patchOperations = [
+    { op: 'add', path: jsonPointerPath('openapi', 'operations', storageKey), value: openapiOperation },
+    { op: 'add', path: jsonPointerPath('execution', 'cip', 'operations', storageKey), value: cipOperation },
+    { op: 'add', path: jsonPointerPath('exposed', 'profiles', targetKey), value: profile },
+    { op: 'add', path: '/capabilities/-', value: capability }
+  ];
+  return {
+    doc,
+    resolvedAs: targetKey,
+    patchOperations,
+    updatedSections: [
+      `capabilities[]: ${targetKey}`,
+      `openapi.operations.${storageKey}`,
+      `execution.cip.operations.${storageKey}`,
+      `exposed.profiles.${targetKey}`
+    ]
+  };
+}
+
+function existingUpsertMatches(originalDoc, analysis, targetKey = 'upsert') {
+  if (!capabilityLogicalExists(originalDoc, targetKey)) return false;
+  const expected = applyUpsertCapability(originalDoc, analysis, {
+    targetKey,
+    overwrite: true
+  }).doc;
+  const storageKey = storageOpsKey(targetKey);
+  const actualSlices = {
+    openapi: originalDoc.openapi?.operations?.[storageKey],
+    cip: originalDoc.execution?.cip?.operations?.[storageKey],
+    profile: originalDoc.exposed?.profiles?.[targetKey]
+  };
+  const expectedSlices = {
+    openapi: expected.openapi?.operations?.[storageKey],
+    cip: expected.execution?.cip?.operations?.[storageKey],
+    profile: expected.exposed?.profiles?.[targetKey]
+  };
+  return JSON.stringify(actualSlices) === JSON.stringify(expectedSlices);
+}
+
+module.exports = {
+  applyUpsertCapability,
+  existingUpsertMatches,
+  buildUpsertProfile,
+  buildCipOperation
+};