forge-workflow 0.1.0-beta.6 → 0.1.0-beta.7

package/node_modules/@forge/memory/src/authority-provider.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const MEMORY_AUTHORITY_METHODS = Object.freeze([
+  'initialize',
+  'runIssueOperation',
+  'runGuardedEvent',
+  'importIssues',
+  'listRecentEvents',
+  'listOpenPrs',
+  'upsertPr',
+  'updatePrVerdict',
+  'retirePr',
+  'listProjectionOutbox',
+  'loadProjectionModel',
+  'markProjectionDelivered',
+  'recordProjectionFailure',
+  'deadLetterProjection',
+]);
+
+// Optional PR lifecycle operations are intentionally separate from the mandatory
+// Memory authority surface. Legacy brokers keep the exact historical provider
+// keys; lifecycle consumers opt into the pair atomically.
+const MEMORY_PR_LIFECYCLE_METHODS = Object.freeze(['recordPrLinkage', 'recordOpenedPrLinkage', 'readTrace']);
+
+function assertMemoryAuthorityProvider(provider, label = 'Memory authority provider') {
+  if (!provider || typeof provider !== 'object' || Array.isArray(provider)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  for (const method of MEMORY_AUTHORITY_METHODS) {
+    if (typeof provider[method] !== 'function') {
+      throw new TypeError(`${label} must implement ${method}()`);
+    }
+  }
+  return provider;
+}
+
+function createMemoryAuthorityProvider({ broker } = {}) {
+  assertMemoryAuthorityProvider(broker, 'Kernel broker');
+  const lifecyclePresence = MEMORY_PR_LIFECYCLE_METHODS.map(method => typeof broker[method] === 'function');
+  if (lifecyclePresence.some(Boolean) && !lifecyclePresence.every(Boolean)) {
+    throw new TypeError('Kernel broker lifecycle surface must implement recordPrLinkage() and readTrace()');
+  }
+  const provider = {};
+  for (const method of MEMORY_AUTHORITY_METHODS) {
+    provider[method] = (...args) => broker[method](...args);
+  }
+  provider.initialize = async (...args) => {
+    const result = await broker.initialize(...args);
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+      throw new TypeError('Kernel broker initialize() must return an object');
+    }
+    return { success: result.success === true };
+  };
+  if (lifecyclePresence.every(Boolean)) {
+    for (const method of MEMORY_PR_LIFECYCLE_METHODS) {
+      provider[method] = (...args) => broker[method](...args);
+    }
+  }
+  return Object.freeze(provider);
+}
+
+module.exports = {
+  MEMORY_AUTHORITY_METHODS,
+  MEMORY_PR_LIFECYCLE_METHODS,
+  assertMemoryAuthorityProvider,
+  createMemoryAuthorityProvider,
+};

package/node_modules/@forge/memory/src/backend-registry.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const BACKEND_METHODS = Object.freeze(['add', 'recall', 'search', 'capture', 'digest']);
+const RECEIPT_SCHEMA_ID = 'forge.memory.operation-receipt.v1';
+const RECEIPT_SCHEMA_VERSION = 1;
+const asyncUnsupportedErrors = new WeakSet();
+
+function assertBackendName(name) {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
+    throw new TypeError('memory backend name must use lowercase letters, numbers, and hyphens');
+  }
+}
+
+function assertBackend(adapter, name = 'memory') {
+  if (!adapter || typeof adapter !== 'object' || Array.isArray(adapter)) {
+    throw new TypeError(`${name} memory backend must be an object`);
+  }
+  for (const method of BACKEND_METHODS) {
+    if (typeof adapter[method] !== 'function') {
+      throw new TypeError(`${name} memory backend must implement ${method}()`);
+    }
+  }
+}
+
+function errorRecord(backend, error) {
+  return {
+    backend,
+    code: asyncUnsupportedErrors.has(error)
+      ? 'MEMORY_BACKEND_ASYNC_UNSUPPORTED'
+      : 'MEMORY_BACKEND_FAILED',
+  };
+}
+
+function isThenable(value) {
+  return value && (typeof value === 'object' || typeof value === 'function')
+    && typeof value.then === 'function';
+}
+
+function requireSynchronous(value, backend) {
+  if (!isThenable(value)) return value;
+  value.then(() => {}, () => {});
+  const error = new TypeError(`${backend} memory backend methods must be synchronous`);
+  asyncUnsupportedErrors.add(error);
+  throw error;
+}
+
+function deepFreeze(value, seen = new WeakSet()) {
+  if (!value || typeof value !== 'object' || seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreeze(child, seen);
+  return Object.freeze(value);
+}
+
+function detached(value, { freeze = false } = {}) {
+  const copy = structuredClone(value);
+  return freeze ? deepFreeze(copy) : copy;
+}
+
+function identity(value) {
+  if (value && typeof value === 'object') {
+    if (typeof value.id === 'string') return `id:${value.id}`;
+    if (typeof value.key === 'string') return `key:${value.key}`;
+  }
+  return `value:${JSON.stringify(value)}`;
+}
+
+function enrichLocalValue(localValue, enrichedValue, operation) {
+  if (!['recall', 'search', 'digest'].includes(operation)) return localValue;
+  if (!Array.isArray(localValue) || !Array.isArray(enrichedValue)) return localValue;
+  const seen = new Set(localValue.map(identity));
+  return [...localValue, ...enrichedValue.filter(item => {
+    const key = identity(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  })];
+}
+
+function createMemoryBackendRegistry({ local, selected = 'local' } = {}) {
+  assertBackend(local, 'local');
+  const adapters = new Map([['local', local]]);
+  let selectedBackend = 'local';
+
+  function register(name, adapter) {
+    assertBackendName(name);
+    if (name === 'local') throw new Error('the local memory floor cannot be replaced');
+    if (adapters.has(name)) throw new Error(`memory backend "${name}" is already registered`);
+    assertBackend(adapter, name);
+    adapters.set(name, adapter);
+    return api;
+  }
+
+  function unregister(name) {
+    if (name === 'local') throw new Error('the local memory floor cannot be removed');
+    adapters.delete(name);
+    if (selectedBackend === name) selectedBackend = 'local';
+    return api;
+  }
+
+  function select(name) {
+    assertBackendName(name);
+    if (!adapters.has(name)) throw new Error(`memory backend "${name}" is not registered`);
+    selectedBackend = name;
+    return api;
+  }
+
+  function execute(operation, args) {
+    const localValue = requireSynchronous(adapters.get('local')[operation](...args), 'local');
+    const backends = [{ backend: 'local', status: 'ok' }];
+    const errors = [];
+    let value = localValue;
+
+    if (selectedBackend !== 'local') {
+      try {
+        const localSnapshot = detached(localValue);
+        const enrichedArgs = detached(args, { freeze: true });
+        value = localSnapshot;
+        const enrichedValue = requireSynchronous(
+          adapters.get(selectedBackend)[operation](...enrichedArgs),
+          selectedBackend,
+        );
+        value = enrichLocalValue(localSnapshot, enrichedValue, operation);
+        backends.push({ backend: selectedBackend, status: 'ok' });
+      } catch (error) {
+        backends.push({ backend: selectedBackend, status: 'failed' });
+        errors.push(errorRecord(selectedBackend, error));
+      }
+    }
+
+    return {
+      value,
+      receipt: {
+        schema_id: RECEIPT_SCHEMA_ID,
+        schema_version: RECEIPT_SCHEMA_VERSION,
+        operation,
+        selected_backend: selectedBackend,
+        local_floor: 'local',
+        status: errors.length === 0 ? 'ok' : 'degraded',
+        capabilities: [...BACKEND_METHODS].sort(),
+        backends,
+        errors,
+      },
+    };
+  }
+
+  const api = {
+    register,
+    unregister,
+    select,
+    selected: () => selectedBackend,
+    names: () => [...adapters.keys()].sort((a, b) => (a === 'local' ? -1 : b === 'local' ? 1 : a.localeCompare(b))),
+  };
+  for (const operation of BACKEND_METHODS) {
+    api[operation] = (...args) => execute(operation, args);
+  }
+  select(selected);
+  return Object.freeze(api);
+}
+
+module.exports = {
+  BACKEND_METHODS,
+  RECEIPT_SCHEMA_ID,
+  RECEIPT_SCHEMA_VERSION,
+  assertBackend,
+  createMemoryBackendRegistry,
+};

package/node_modules/@forge/memory/src/feedback-intake.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const { createHash, randomUUID: defaultRandomUUID } = require('node:crypto');
+const {
+  canonicalize,
+  computeContentHash,
+  semanticIdentity,
+  validateContractStructure,
+} = require('@forge/contracts');
+
+const FEEDBACK_SCHEMA_ID = 'forge.memory.feedback-report.v1';
+const ASSIGNED_SECRET = /((?:api[_-]?key|token|secret|password)\s*[:=]\s*)\S{8,}/gi;
+const BARE_SECRET = /(?:gh[pousr]_[A-Za-z0-9]{20,}|sk_(?:live|test)_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16})/gi;
+const USER_PATH = /(?:[A-Za-z]:\\Users\\[^\\\s]+\\|\/(?:Users|home)\/[^/\s]+\/)/gi;
+
+class FeedbackIntakeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'FeedbackIntakeError';
+    this.code = code;
+  }
+}
+
+function requiredString(value, name) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function redactString(value) {
+  return value
+    .replace(USER_PATH, '<user-path>/')
+    .replace(ASSIGNED_SECRET, '[REDACTED]')
+    .replace(BARE_SECRET, '[REDACTED]');
+}
+
+function redactValue(value) {
+  if (typeof value === 'string') return redactString(value);
+  if (Array.isArray(value)) return value.map(redactValue);
+  if (!value || typeof value !== 'object') return value;
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    const safeKey = redactString(key);
+    if (Object.hasOwn(output, safeKey)) {
+      throw new TypeError('redaction produced duplicate returnChannel keys');
+    }
+    output[safeKey] = redactValue(child);
+  }
+  return output;
+}
+
+function sha256(value) {
+  return createHash('sha256').update(canonicalize(value), 'utf8').digest('hex');
+}
+
+function assertFeedbackReport(report) {
+  const validation = validateContractStructure(report);
+  if (report?.schema_id !== FEEDBACK_SCHEMA_ID || !validation.ok) {
+    const codes = validation.errors.map(item => item.code).join(', ') || 'WRONG_SCHEMA';
+    throw new FeedbackIntakeError('FEEDBACK_REPORT_INVALID', `FeedbackReport is invalid: ${codes}`);
+  }
+  return report;
+}
+
+function createFeedbackReport(input = {}, options = {}) {
+  const randomUUID = options.randomUUID || defaultRandomUUID;
+  const now = options.now || (() => new Date().toISOString());
+  const reportId = randomUUID();
+  const reproductionSteps = input.reproductionSteps;
+  if (!Array.isArray(reproductionSteps) || reproductionSteps.length === 0) {
+    throw new TypeError('reproductionSteps must be a non-empty array');
+  }
+  const redactedSteps = reproductionSteps.map((step, index) =>
+    redactString(requiredString(step, `reproductionSteps[${index}]`)));
+  const stableErrorCode = redactString(requiredString(input.stableErrorCode, 'stableErrorCode'));
+  const affectedCapability = redactString(requiredString(input.affectedCapability, 'affectedCapability'));
+  const expectedClassification = redactString(requiredString(input.expectedClassification, 'expectedClassification'));
+  const actualClassification = redactString(requiredString(input.actualClassification, 'actualClassification'));
+  const productVersion = redactString(requiredString(input.productVersion, 'productVersion'));
+  const redactionPolicyRevision = redactString(requiredString(input.redactionPolicyRevision, 'redactionPolicyRevision'));
+  const consentEventId = redactString(requiredString(input.consentEventId, 'consentEventId'));
+  const occurrenceCount = input.occurrenceCount ?? 1;
+  if (!Number.isInteger(occurrenceCount) || occurrenceCount < 1) {
+    throw new TypeError('occurrenceCount must be a positive integer');
+  }
+
+  const payload = {
+    report_id: reportId,
+    product_version: productVersion,
+    contract_version: 1,
+    stable_error_code: stableErrorCode,
+    affected_capability: affectedCapability,
+    redacted_reproduction_steps: redactedSteps,
+    expected_classification: expectedClassification,
+    actual_classification: actualClassification,
+    occurrence_count: occurrenceCount,
+    content_fingerprint: sha256({
+      stable_error_code: stableErrorCode,
+      affected_capability: affectedCapability,
+      redacted_reproduction_steps: redactedSteps,
+      expected_classification: expectedClassification,
+      actual_classification: actualClassification,
+    }),
+    consent_event_id: consentEventId,
+    redaction_policy_revision: redactionPolicyRevision,
+  };
+  if (input.proposedFix !== undefined) {
+    payload.proposed_fix = redactString(requiredString(input.proposedFix, 'proposedFix'));
+  }
+  if (input.returnChannel !== undefined) payload.return_channel = redactValue(input.returnChannel);
+
+  const report = {
+    schema_id: FEEDBACK_SCHEMA_ID,
+    schema_version: 1,
+    object_id: reportId,
+    created_at: now(),
+    producer: {
+      product_id: 'forge-memory',
+      product_version: productVersion,
+      // A per-report nonce prevents anonymous reports from becoming a cross-report tracking key.
+      instance_id: reportId,
+    },
+    capabilities_used: [],
+    provenance: {
+      source_kind: 'feedback',
+      actor_class: 'anonymous-user',
+      actor_id: reportId,
+    },
+    payload,
+    extensions: {},
+  };
+  report.content_hash = computeContentHash(report);
+  return assertFeedbackReport(report);
+}
+
+function assertConsent(report, consent) {
+  if (!consent || consent.approved !== true) return false;
+  if (consent.eventId !== report.payload.consent_event_id
+      || consent.redactionPolicyRevision !== report.payload.redaction_policy_revision
+      || consent.reportId !== report.payload.report_id
+      || consent.contentHash !== report.content_hash) {
+    throw new FeedbackIntakeError(
+      'FEEDBACK_CONSENT_MISMATCH',
+      'Feedback consent must match this report and redaction-policy revision',
+    );
+  }
+  return true;
+}
+
+function createFeedbackIntake({ acceptFeedback, deliverFeedback, deliveryTimeoutMs = 10_000 } = {}) {
+  if (typeof acceptFeedback !== 'function') {
+    throw new TypeError('acceptFeedback must be an atomic durable acceptance function');
+  }
+  if (deliverFeedback !== undefined && typeof deliverFeedback !== 'function') {
+    throw new TypeError('deliverFeedback must be a function when provided');
+  }
+  if (!Number.isInteger(deliveryTimeoutMs) || deliveryTimeoutMs < 1) {
+    throw new TypeError('deliveryTimeoutMs must be a positive integer');
+  }
+
+  function preview(report) {
+    assertFeedbackReport(report);
+    return { status: 'pending-consent', report: structuredClone(report) };
+  }
+
+  async function submit(report, consent) {
+    assertFeedbackReport(report);
+    if (!assertConsent(report, consent)) {
+      return {
+        status: consent?.approved === false ? 'declined' : 'pending-consent',
+        accepted: false,
+        delivered: false,
+      };
+    }
+
+    const identity = semanticIdentity(report);
+    const result = await acceptFeedback({
+      identity,
+      content_hash: report.content_hash,
+      report: structuredClone(report),
+    });
+    if (result?.status === 'identity-conflict') {
+      throw new FeedbackIntakeError(
+        'FEEDBACK_IDENTITY_CONFLICT',
+        'Feedback report identity was already accepted with different content',
+      );
+    }
+    if (result?.status === 'retry-identical') {
+      return { status: 'retry-identical', accepted: false, delivered: false, receipt: result.receipt };
+    }
+    if (result?.status !== 'accepted') {
+      throw new FeedbackIntakeError('FEEDBACK_ACCEPTANCE_INVALID', 'Feedback authority returned an invalid result');
+    }
+    if (!deliverFeedback) {
+      return { status: 'accepted-local', accepted: true, delivered: false, receipt: result.receipt };
+    }
+    const controller = new AbortController();
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        controller.abort();
+        reject(new FeedbackIntakeError('FEEDBACK_DELIVERY_TIMEOUT', 'Feedback delivery timed out'));
+      }, deliveryTimeoutMs);
+    });
+    try {
+      const delivery = await Promise.race([
+        Promise.resolve().then(() => deliverFeedback(structuredClone(report), {
+          receipt: result.receipt,
+          signal: controller.signal,
+        })),
+        timeout,
+      ]);
+      return { status: 'accepted', accepted: true, delivered: true, receipt: result.receipt, delivery };
+    } catch (error) {
+      const code = error?.code === 'FEEDBACK_DELIVERY_TIMEOUT'
+        ? 'FEEDBACK_DELIVERY_TIMEOUT'
+        : 'FEEDBACK_DELIVERY_FAILED';
+      return {
+        status: 'accepted-local',
+        accepted: true,
+        delivered: false,
+        receipt: result.receipt,
+        delivery_error: {
+          code,
+          reason: redactString(String(error?.message || 'unknown delivery failure')).slice(0, 200),
+        },
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  return Object.freeze({ preview, submit });
+}
+
+module.exports = {
+  FEEDBACK_SCHEMA_ID,
+  FeedbackIntakeError,
+  createFeedbackIntake,
+  createFeedbackReport,
+  redactString,
+};