gemstack-ai 1.4.0 → 2.0.0

package/src/lib/provider-boundary.js

@@ -34,13 +34,17 @@ function normalizeProviderId(rawId) {
  * @param {object} [tokenPayload={}]
  * @returns {string} SHA-256 bound token
  */
-function createBoundToken(providerId, capabilityId, actionId, tokenPayload = {}) {
+function createBoundToken(providerId, capabilityId, actionId, tokenPayload = {}, secret = null) {
   const payload = JSON.stringify({
     providerId,
     capabilityId,
     actionId,
     token: tokenPayload
   });
+  const effectiveSecret = secret || process.env.GEMSTACK_BOUNDARY_SECRET;
+  if (effectiveSecret) {
+    return crypto.createHmac('sha256', effectiveSecret).update(payload, 'utf8').digest('hex');
+  }
   return crypto.createHash('sha256').update(payload, 'utf8').digest('hex');
 }
 

package/src/lib/provider-registry.js

@@ -17,12 +17,14 @@ const REMOTE_URL_PATTERN = /^https?:\/\//i;
 function resolveEnvironmentTier(options = {}) {
   const env = options.env || process.env;
 
-  if (options.environment && VALID_ENV_TIERS.includes(options.environment)) {
-    return options.environment;
+  const rawEnv = (options.environment || '').toLowerCase().trim();
+  if (rawEnv && VALID_ENV_TIERS.includes(rawEnv)) {
+    return rawEnv;
   }
 
-  if (env.GEMSTACK_ENV && VALID_ENV_TIERS.includes(env.GEMSTACK_ENV)) {
-    return env.GEMSTACK_ENV;
+  const rawGemstackEnv = (env.GEMSTACK_ENV || '').toLowerCase().trim();
+  if (rawGemstackEnv && VALID_ENV_TIERS.includes(rawGemstackEnv)) {
+    return rawGemstackEnv;
   }
 
   // Detect CI first

package/src/lib/safety-gates.js

@@ -1,5 +1,71 @@
+const crypto = require('crypto');
 const { checkEnvironmentCommercialPolicy, resolveEnvironmentTier } = require('./provider-registry');
 
+const tokenSpendingLedger = new Map();
+
+function resetTokenSpendingLedger() {
+  tokenSpendingLedger.clear();
+}
+
+/**
+ * Issues a cryptographically signed spending token from a trusted boundary.
+ *
+ * @param {object} params
+ * @param {string} [params.secret]
+ * @param {string} [params.provider_id='*']
+ * @param {string} [params.action_id='*']
+ * @param {number} [params.max_budget_units=100]
+ * @param {number} [params.ttl_seconds=3600]
+ * @returns {object} Signed spending token
+ */
+function issueSpendingToken({ secret, provider_id = '*', action_id = '*', max_budget_units = 100, ttl_seconds = 3600 } = {}) {
+  const tokenId = (crypto.randomUUID && typeof crypto.randomUUID === 'function')
+    ? crypto.randomUUID()
+    : crypto.randomBytes(16).toString('hex');
+  const now = Date.now();
+  const issuedAt = new Date(now).toISOString();
+  const expiresAt = new Date(now + ttl_seconds * 1000).toISOString();
+  const effectiveSecret = secret || process.env.GEMSTACK_BOUNDARY_SECRET || 'gemstack-boundary-internal-signing-secret';
+
+  const payload = [tokenId, provider_id, action_id, String(max_budget_units), expiresAt].join(':');
+  const signature = crypto.createHmac('sha256', effectiveSecret).update(payload).digest('hex');
+
+  return {
+    token_id: tokenId,
+    provider_id,
+    action_id,
+    max_budget_units: Number(max_budget_units),
+    issued_at: issuedAt,
+    expires_at: expiresAt,
+    signature,
+    spent_units: 0
+  };
+}
+
+/**
+ * Verifies a spending token signature and expiration.
+ *
+ * @param {object} token
+ * @param {string} [secret]
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function verifySpendingToken(token, secret) {
+  if (!token || typeof token !== 'object') return { valid: false, reason: 'TOKEN_INVALID_FORMAT' };
+  if (!token.token_id || !token.signature || !token.expires_at) return { valid: false, reason: 'TOKEN_INCOMPLETE' };
+
+  const effectiveSecret = secret || process.env.GEMSTACK_BOUNDARY_SECRET || 'gemstack-boundary-internal-signing-secret';
+  const payload = [token.token_id, token.provider_id || '*', token.action_id || '*', String(token.max_budget_units), token.expires_at].join(':');
+  const expectedSig = crypto.createHmac('sha256', effectiveSecret).update(payload).digest('hex');
+
+  const bufA = Buffer.from(token.signature);
+  const bufB = Buffer.from(expectedSig);
+  if (bufA.length !== bufB.length || !crypto.timingSafeEqual(bufA, bufB)) {
+    return { valid: false, reason: 'TOKEN_SIGNATURE_INVALID' };
+  }
+
+  return { valid: true };
+}
+
 /**
  * Creates a normalized, structured gate decision object.
  *
@@ -155,7 +221,17 @@ function evaluateBillableAction(request, ledger, options = {}) {
   const providerId = (request.provider_id || '').toLowerCase().trim();
   const capabilityId = request.capability_id;
   const envTier = resolveEnvironmentTier({ environment: request.environment, ...options });
-  const requestedUnits = typeof request.requested_units === 'number' ? request.requested_units : 1;
+  const requestedUnits = request.requested_units !== undefined ? request.requested_units : 1;
+
+  if (typeof requestedUnits !== 'number' || !Number.isFinite(requestedUnits) || requestedUnits <= 0) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'INVALID_REQUESTED_UNITS',
+      message: 'Requested units must be a strictly positive finite number.',
+      context: { action_id: actionId, provider_id: providerId, requested_units: requestedUnits }
+    });
+  }
 
   // 1. Action Declaration Check (Must be explicitly declared)
   if (!actionId || typeof actionId !== 'string' || !actionId.trim()) {
@@ -232,9 +308,7 @@ function evaluateBillableAction(request, ledger, options = {}) {
 
   // 5. BILLABLE / POTENTIALLY_BILLABLE Actions -> Require Explicit Spending Token
   const token = request.authorization_token;
-  const isTokenValid = token && (token.granted === true || token.granted_by || token.source === 'CLI_FLAG' || token.max_budget_units !== undefined);
-
-  if (!isTokenValid) {
+  if (!token || typeof token !== 'object') {
     return createGateDecision({
       authorized: false,
       decision: 'DENY',
@@ -244,20 +318,111 @@ function evaluateBillableAction(request, ledger, options = {}) {
     });
   }
 
+  const boundarySecret = options.boundarySecret || process.env.GEMSTACK_BOUNDARY_SECRET;
+
+  if (boundarySecret) {
+    const verified = verifySpendingToken(token, boundarySecret);
+    if (!verified.valid) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'BILLABLE_ACTION_UNAUTHORIZED',
+        message: 'Authorization token rejected by trusted boundary: ' + verified.reason,
+        context: { action_id: actionId, provider_id: providerId, reason: verified.reason }
+      });
+    }
+  } else if (token.signature && token.token_id) {
+    const verified = verifySpendingToken(token);
+    if (!verified.valid) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'BILLABLE_ACTION_UNAUTHORIZED',
+        message: 'Authorization token signature invalid.',
+        context: { action_id: actionId, provider_id: providerId }
+      });
+    }
+  } else {
+    // Legacy fallback only when no boundarySecret is active
+    const isTokenValid = token && (token.granted === true || token.granted_by || token.source === 'CLI_FLAG' || token.max_budget_units !== undefined);
+    if (!isTokenValid) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'BILLABLE_ACTION_UNAUTHORIZED',
+        message: 'Action "' + actionId + '" on provider "' + providerId + '" requires explicit spending authorization.',
+        context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier }
+      });
+    }
+  }
+
+  // Expiration check
+  if (token.expires_at) {
+    const expMs = Date.parse(token.expires_at);
+    if (!Number.isNaN(expMs) && Date.now() > expMs) {
+      return createGateDecision({
+        authorized: false,
+        decision: 'DENY',
+        reasonCode: 'TOKEN_EXPIRED',
+        message: 'Authorization token expired at ' + token.expires_at + '.',
+        context: { action_id: actionId, provider_id: providerId, expires_at: token.expires_at }
+      });
+    }
+  }
+
+  // Scope check (Provider & Action)
+  if (token.provider_id && token.provider_id !== '*' && token.provider_id.toLowerCase() !== providerId.toLowerCase()) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'TOKEN_SCOPE_MISMATCH',
+      message: 'Token scope provider "' + token.provider_id + '" does not match requested provider "' + providerId + '".',
+      context: { action_id: actionId, provider_id: providerId, token_provider: token.provider_id }
+    });
+  }
+
+  if (token.action_id && token.action_id !== '*' && token.action_id !== actionId) {
+    return createGateDecision({
+      authorized: false,
+      decision: 'DENY',
+      reasonCode: 'TOKEN_SCOPE_MISMATCH',
+      message: 'Token scope action "' + token.action_id + '" does not match requested action "' + actionId + '".',
+      context: { action_id: actionId, provider_id: providerId, token_action: token.action_id }
+    });
+  }
+
   // 6. Budget & Unit Threshold Check
   const estimatedUnitCost = (capabilityEntry && typeof capabilityEntry.estimated_unit_cost === 'number') ? capabilityEntry.estimated_unit_cost : 1;
   const estimatedTotalCost = requestedUnits * estimatedUnitCost;
 
   if (token && typeof token.max_budget_units === 'number') {
-    if (estimatedTotalCost > token.max_budget_units) {
+    const tokenId = token.token_id;
+    const currentSpent = tokenId ? (tokenSpendingLedger.get(tokenId) || 0) : 0;
+    const projectedTotal = currentSpent + estimatedTotalCost;
+
+    if (projectedTotal > token.max_budget_units) {
       return createGateDecision({
         authorized: false,
         decision: 'DENY',
         reasonCode: 'BUDGET_THRESHOLD_EXCEEDED',
-        message: 'Action "' + actionId + '" estimated cost (' + estimatedTotalCost + ') exceeds authorized budget limit (' + token.max_budget_units + ').',
-        context: { action_id: actionId, provider_id: providerId, capability_id: capabilityId, cost_state: costState, environment: envTier, estimated_total_cost: estimatedTotalCost, max_budget_units: token.max_budget_units }
+        message: 'Action "' + actionId + '" estimated cost (' + projectedTotal + ') exceeds authorized budget limit (' + token.max_budget_units + ').',
+        context: {
+          action_id: actionId,
+          provider_id: providerId,
+          capability_id: capabilityId,
+          cost_state: costState,
+          environment: envTier,
+          estimated_total_cost: estimatedTotalCost,
+          current_spent: currentSpent,
+          projected_total: projectedTotal,
+          max_budget_units: token.max_budget_units
+        }
       });
     }
+
+    if (tokenId) {
+      tokenSpendingLedger.set(tokenId, projectedTotal);
+    }
   }
 
   // 7. Full Authorization Pass
@@ -273,5 +438,8 @@ function evaluateBillableAction(request, ledger, options = {}) {
 module.exports = {
   createGateDecision,
   evaluateProviderCapability,
-  evaluateBillableAction
+  evaluateBillableAction,
+  issueSpendingToken,
+  verifySpendingToken,
+  resetTokenSpendingLedger
 };

package/src/lib/sdd-rigor.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * SDD Rigor Engine (Gemstack 2.0 Sprint C)
+ * Defines and enforces 4 levels of SDD rigor: quick, fix, feature, high-risk.
+ */
+
+const RIGOR_LEVELS = Object.freeze(['quick', 'fix', 'feature', 'high-risk']);
+
+/**
+ * Detects the declared rigor level from spec content or metadata.
+ * @param {string} specContent - Content of spec.md or quick.md
+ * @returns {string} Detected rigor level ('quick'|'fix'|'feature'|'high-risk')
+ */
+function detectRigorLevel(specContent) {
+  if (!specContent || typeof specContent !== 'string') {
+    return 'feature';
+  }
+
+  // Check YAML frontmatter: rigor: <level>
+  const frontmatterMatch = specContent.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---/);
+  if (frontmatterMatch) {
+    const rMatch = frontmatterMatch[1].match(/^\s*rigor:\s*([a-zA-Z0-9_-]+)/m);
+    if (rMatch) {
+      const level = rMatch[1].trim().toLowerCase();
+      if (!RIGOR_LEVELS.includes(level)) {
+        const err = new Error(`Nivel de rigor inválido "${level}". Niveles válidos: ${RIGOR_LEVELS.join(', ')}`);
+        err.code = 'INVALID_RIGOR_LEVEL';
+        throw err;
+      }
+      return level;
+    }
+  }
+
+  // Check Markdown annotations: **Rigor Level**: `level` or Rigor: level
+  const inlineMatch = specContent.match(/\*\*Rigor(?:\s+Level)?\*\*:\s*`?([a-zA-Z0-9_-]+)`?/i);
+  if (inlineMatch) {
+    const level = inlineMatch[1].trim().toLowerCase();
+    if (!RIGOR_LEVELS.includes(level)) {
+      const err = new Error(`Nivel de rigor inválido "${level}". Niveles válidos: ${RIGOR_LEVELS.join(', ')}`);
+      err.code = 'INVALID_RIGOR_LEVEL';
+      throw err;
+    }
+    return level;
+  }
+
+  return 'feature';
+}
+
+/**
+ * Validates requirements for a given rigor level.
+ * @param {string} rigorLevel - 'quick'|'fix'|'feature'|'high-risk'
+ * @param {object} context - Context containing specContent, planContent, tasksContent, testMatrix, sidecar, etc.
+ * @returns {{ valid: boolean, code?: string, error?: string, [key: string]: any }}
+ */
+function validateRigorRequirements(rigorLevel, context = {}) {
+  const normLevel = (rigorLevel || 'feature').toLowerCase();
+  if (!RIGOR_LEVELS.includes(normLevel)) {
+    const err = new Error(`Nivel de rigor inválido "${normLevel}".`);
+    err.code = 'INVALID_RIGOR_LEVEL';
+    throw err;
+  }
+
+  const {
+    specContent = '',
+    planContent = null,
+    tasksContent = null,
+    testMatrix = [],
+    sidecar = null
+  } = context;
+
+  switch (normLevel) {
+    case 'quick': {
+      if (!specContent || typeof specContent !== 'string' || specContent.trim().length === 0) {
+        return {
+          valid: false,
+          code: 'QUICK_SPEC_MISSING',
+          error: 'Quick rigor requires at least one spec or quick artifact'
+        };
+      }
+      return {
+        valid: true,
+        rigor: 'quick',
+        single_artifact_allowed: true
+      };
+    }
+
+    case 'fix': {
+      // Must have at least one regression test in the test matrix
+      const matrix = Array.isArray(testMatrix) ? testMatrix : [];
+      const regressionTest = matrix.find(t => {
+        const cat = (t.category || '').toUpperCase();
+        const id = (t.id || '').toUpperCase();
+        const desc = (t.description || '').toLowerCase();
+        return cat === 'REGRESSION' || id.includes('REG') || desc.includes('regression') || desc.includes('reproduce');
+      });
+
+      if (!regressionTest) {
+        return {
+          valid: false,
+          code: 'FIX_MISSING_REGRESSION_TEST',
+          error: 'Fix rigor requires at least one linked regression test in the test matrix (category REGRESSION or ID matching *REG*)'
+        };
+      }
+
+      return {
+        valid: true,
+        rigor: 'fix',
+        regression_test_id: regressionTest.id
+      };
+    }
+
+    case 'feature': {
+      if (!specContent) {
+        return { valid: false, code: 'FEATURE_SPEC_MISSING', error: 'Feature rigor requires spec.md' };
+      }
+      if (!planContent) {
+        return { valid: false, code: 'FEATURE_PLAN_MISSING', error: 'Feature rigor requires plan.md' };
+      }
+      if (!tasksContent) {
+        return { valid: false, code: 'FEATURE_TASKS_MISSING', error: 'Feature rigor requires tasks.md' };
+      }
+      return {
+        valid: true,
+        rigor: 'feature'
+      };
+    }
+
+    case 'high-risk': {
+      // 1. Threat Model in specContent
+      const hasThreatModel = context.hasThreatModel ||
+        /##\s+(?:[0-9.]+\s+)?(?:Threat\s+Model|Modelo\s+de\s+Amenazas)/i.test(specContent);
+      if (!hasThreatModel) {
+        return {
+          valid: false,
+          code: 'HIGH_RISK_MISSING_THREAT_MODEL',
+          error: 'High-risk rigor requires an explicit Threat Model section in spec.md'
+        };
+      }
+
+      // 2. Rollback Plan in planContent
+      const hasRollbackPlan = context.hasRollbackPlan ||
+        (planContent && /##\s+(?:[0-9.]+\s+)?(?:Rollback\s+Plan|Plan\s+de\s+Rollback)/i.test(planContent));
+      if (!hasRollbackPlan) {
+        return {
+          valid: false,
+          code: 'HIGH_RISK_MISSING_ROLLBACK_PLAN',
+          error: 'High-risk rigor requires an explicit Rollback Plan section in plan.md'
+        };
+      }
+
+      // 3. Dual human approvals in sidecar
+      const approvals = sidecar && Array.isArray(sidecar.approvals) ? sidecar.approvals : [];
+      const validApprovals = approvals.filter(a => a && a.approver && a.signature);
+      const uniqueApprovers = new Set(validApprovals.map(a => a.approver));
+
+      if (uniqueApprovers.size < 2) {
+        return {
+          valid: false,
+          code: 'HIGH_RISK_INSUFFICIENT_APPROVALS',
+          error: `High-risk rigor requires at least 2 distinct human approval signatures. Found: ${uniqueApprovers.size}`
+        };
+      }
+
+      return {
+        valid: true,
+        rigor: 'high-risk',
+        approvals_count: uniqueApprovers.size
+      };
+    }
+
+    default:
+      return { valid: false, code: 'UNKNOWN_RIGOR', error: `Unknown rigor: ${normLevel}` };
+  }
+}
+
+module.exports = {
+  RIGOR_LEVELS,
+  detectRigorLevel,
+  validateRigorRequirements
+};

package/src/lib/spec-delta.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * Incremental Spec Delta Engine (Gemstack 2.0 Sprint C)
+ * Parses and applies structured ADDED, MODIFIED, REMOVED deltas onto base specifications.
+ */
+
+/**
+ * Extracts and parses a spec delta block or JSON structure.
+ * @param {string|object} input - Markdown content containing gemstack-spec-delta block or parsed delta object.
+ * @returns {object} Normalized delta object { base_spec, added, modified, removed }
+ */
+function parseSpecDelta(input) {
+  if (typeof input === 'object' && input !== null) {
+    return normalizeDelta(input);
+  }
+
+  if (typeof input !== 'string') {
+    throw new Error('Delta input must be a string or object');
+  }
+
+  const blockRegex = /```gemstack-spec-delta\s*([\s\S]*?)```/;
+  const match = input.match(blockRegex);
+  let parsed;
+
+  if (match) {
+    try {
+      parsed = JSON.parse(match[1].trim());
+    } catch (e) {
+      const err = new Error(`Error parseando gemstack-spec-delta: ${e.message}`);
+      err.code = 'DELTA_PARSE_ERROR';
+      throw err;
+    }
+  } else {
+    // Try parsing raw JSON
+    try {
+      parsed = JSON.parse(input.trim());
+    } catch (e) {
+      const err = new Error('No se encontró bloque gemstack-spec-delta ni JSON válido');
+      err.code = 'DELTA_BLOCK_MISSING';
+      throw err;
+    }
+  }
+
+  return normalizeDelta(parsed);
+}
+
+function normalizeDelta(parsed) {
+  if (!parsed || typeof parsed !== 'object') {
+    const err = new Error('Delta debe ser un objeto');
+    err.code = 'INVALID_DELTA_SCHEMA';
+    throw err;
+  }
+
+  return {
+    base_spec: parsed.base_spec || null,
+    added: {
+      contracts: Array.isArray(parsed.added?.contracts) ? parsed.added.contracts : [],
+      requirements: Array.isArray(parsed.added?.requirements) ? parsed.added.requirements : [],
+      tests: Array.isArray(parsed.added?.tests) ? parsed.added.tests : []
+    },
+    modified: {
+      contracts: Array.isArray(parsed.modified?.contracts) ? parsed.modified.contracts : [],
+      requirements: Array.isArray(parsed.modified?.requirements) ? parsed.modified.requirements : [],
+      tests: Array.isArray(parsed.modified?.tests) ? parsed.modified.tests : []
+    },
+    removed: {
+      contracts: Array.isArray(parsed.removed?.contracts) ? parsed.removed.contracts : [],
+      requirements: Array.isArray(parsed.removed?.requirements) ? parsed.removed.requirements : [],
+      tests: Array.isArray(parsed.removed?.tests) ? parsed.removed.tests : []
+    }
+  };
+}
+
+/**
+ * Applies a normalized delta onto a base specification representation.
+ * @param {object} baseSpec - { contracts: [], requirements: [], tests: [] }
+ * @param {object} delta - Normalized delta from parseSpecDelta
+ * @returns {object} Merged specification representation
+ */
+function applySpecDelta(baseSpec, delta) {
+  if (!baseSpec || typeof baseSpec !== 'object') {
+    throw new Error('baseSpec must be an object');
+  }
+
+  const normDelta = normalizeDelta(delta);
+
+  // Clone collections
+  const contracts = Array.isArray(baseSpec.contracts) ? JSON.parse(JSON.stringify(baseSpec.contracts)) : [];
+  const requirements = Array.isArray(baseSpec.requirements) ? JSON.parse(JSON.stringify(baseSpec.requirements)) : [];
+  const tests = Array.isArray(baseSpec.tests) ? JSON.parse(JSON.stringify(baseSpec.tests)) : [];
+
+  // 1. Process REMOVED
+  for (const item of normDelta.removed.contracts) {
+    const id = typeof item === 'string' ? item : item.id;
+    const idx = contracts.findIndex(c => c.id === id);
+    if (idx === -1) {
+      const err = new Error(`No se puede remover el contrato "${id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    contracts.splice(idx, 1);
+  }
+
+  for (const item of normDelta.removed.tests) {
+    const id = typeof item === 'string' ? item : item.id;
+    const idx = tests.findIndex(t => t.id === id);
+    if (idx === -1) {
+      const err = new Error(`No se puede remover el test canónico "${id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    tests.splice(idx, 1);
+  }
+
+  for (const item of normDelta.removed.requirements) {
+    const id = typeof item === 'string' ? item : item.id;
+    const idx = requirements.findIndex(r => (typeof r === 'string' ? r === id : r.id === id));
+    if (idx === -1) {
+      const err = new Error(`No se puede remover el requisito "${id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    requirements.splice(idx, 1);
+  }
+
+  // 2. Process MODIFIED
+  for (const item of normDelta.modified.contracts) {
+    const idx = contracts.findIndex(c => c.id === item.id);
+    if (idx === -1) {
+      const err = new Error(`No se puede modificar el contrato "${item.id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    contracts[idx] = { ...contracts[idx], ...item };
+  }
+
+  for (const item of normDelta.modified.tests) {
+    const idx = tests.findIndex(t => t.id === item.id);
+    if (idx === -1) {
+      const err = new Error(`No se puede modificar el test "${item.id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    tests[idx] = { ...tests[idx], ...item };
+  }
+
+  for (const item of normDelta.modified.requirements) {
+    const id = typeof item === 'string' ? item : item.id;
+    const idx = requirements.findIndex(r => (typeof r === 'string' ? r === id : r.id === id));
+    if (idx === -1) {
+      const err = new Error(`No se puede modificar el requisito "${id}": no existe en la especificación base.`);
+      err.code = 'DELTA_TARGET_NOT_FOUND';
+      throw err;
+    }
+    requirements[idx] = typeof item === 'string' ? item : { ...requirements[idx], ...item };
+  }
+
+  // 3. Process ADDED
+  for (const item of normDelta.added.contracts) {
+    const existing = contracts.find(c => c.id === item.id);
+    if (existing) {
+      const err = new Error(`Conflicto al agregar contrato "${item.id}": ya existe en la especificación base.`);
+      err.code = 'DELTA_ADD_CONFLICT';
+      throw err;
+    }
+    contracts.push(item);
+  }
+
+  for (const item of normDelta.added.tests) {
+    const existing = tests.find(t => t.id === item.id);
+    if (existing) {
+      const err = new Error(`Conflicto al agregar test "${item.id}": ya existe en la especificación base.`);
+      err.code = 'DELTA_ADD_CONFLICT';
+      throw err;
+    }
+    tests.push(item);
+  }
+
+  for (const item of normDelta.added.requirements) {
+    requirements.push(item);
+  }
+
+  return {
+    contracts,
+    requirements,
+    tests
+  };
+}
+
+module.exports = {
+  parseSpecDelta,
+  applySpecDelta
+};