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

package/lib/kernel/taxonomy-validator.js

@@ -29,7 +29,10 @@ const STATUS_TRANSITIONS = Object.freeze({
 	backlog: Object.freeze(['open', 'cancelled']),
 });
 
-const CLAIM_STATES = Object.freeze(['active', 'released', 'expired']);
+// `reclaimable` is the historical row left behind when an expired active lease is
+// superseded. It is distinct from `expired`: both are non-authoritative history,
+// but reclaimable records that the slot was deliberately freed for another owner.
+const CLAIM_STATES = Object.freeze(['active', 'released', 'expired', 'reclaimable']);
 
 const DEFAULT_PRIORITY_RANK = 2;
 const MAX_DISPLAY_PRIORITY_RANK = 4;

package/lib/kernel/windows-private-acl.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/* global ActiveXObject, Enumerator, VBArray, WScript */
+
+// This file is executed by Windows Script Host and loaded by Bun/Node tests.
+// Keep its syntax compatible with the system JScript engine.
+var ADS_PATH_FILE = 1;
+var ADS_SD_FORMAT_IID = 1;
+var ADS_SD_FORMAT_RAW = 2;
+var ADS_SECURITY_INFO_OWNER = 1;
+var ADS_SECURITY_INFO_DACL = 4;
+var PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000;
+var SE_DACL_PRESENT = 0x0004;
+var SE_DACL_PROTECTED = 0x1000;
+var SE_SELF_RELATIVE = 0x8000;
+var FILE_ALL_ACCESS = 0x001f01ff;
+var ACCESS_ALLOWED_ACE_TYPE = 0;
+var OBJECT_INHERIT_ACE = 1;
+var CONTAINER_INHERIT_ACE = 2;
+var MAX_TARGETS = 128;
+
+function invariant(condition, message) {
+	if (!condition) throw new Error(message);
+}
+
+function atStage(code, action) {
+	try {
+		return action();
+	} catch (error) {
+		error.forgeExitCode = code;
+		throw error;
+	}
+}
+
+function bytesFromSafeArray(value) {
+	var values = new VBArray(value).toArray();
+	var bytes = [];
+	for (var i = 0; i < values.length; i++) bytes.push(values[i] & 0xff);
+	return bytes;
+}
+
+function u16(bytes, offset) {
+	invariant(offset >= 0 && offset + 2 <= bytes.length, 'truncated uint16');
+	return bytes[offset] | (bytes[offset + 1] << 8);
+}
+
+function u32(bytes, offset) {
+	invariant(offset >= 0 && offset + 4 <= bytes.length, 'truncated uint32');
+	return (bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)) >>> 0;
+}
+
+function sidAt(bytes, offset) {
+	invariant(offset > 0 && offset + 8 <= bytes.length, 'missing SID');
+	var revision = bytes[offset];
+	var count = bytes[offset + 1];
+	var end = offset + 8 + (count * 4);
+	invariant(revision === 1 && end <= bytes.length, 'malformed SID');
+	var authority = 0;
+	for (var i = 0; i < 6; i++) authority = (authority * 256) + bytes[offset + 2 + i];
+	invariant(authority <= 9007199254740991, 'unsupported SID authority');
+	var parts = ['S', String(revision), String(authority)];
+	for (var j = 0; j < count; j++) parts.push(String(u32(bytes, offset + 8 + (j * 4))));
+	return { end: end, value: parts.join('-') };
+}
+
+function inspectDescriptor(bytes, expectedOwnerSid, expectedAceFlags) {
+	invariant(bytes && typeof bytes.length === 'number' && bytes.length >= 20, 'malformed security descriptor');
+	invariant(/^S-1-[0-9]+(?:-[0-9]+)+$/.test(expectedOwnerSid), 'invalid expected SID');
+	invariant(bytes[0] === 1, 'unsupported security descriptor revision');
+	var control = u16(bytes, 2);
+	invariant((control & SE_SELF_RELATIVE) !== 0, 'security descriptor is not self-relative');
+	invariant((control & SE_DACL_PRESENT) !== 0, 'DACL is absent');
+	invariant((control & SE_DACL_PROTECTED) !== 0, 'DACL is not protected');
+	var owner = sidAt(bytes, u32(bytes, 4));
+	invariant(owner.value === expectedOwnerSid, 'owner changed');
+	var daclOffset = u32(bytes, 16);
+	invariant(daclOffset > 0 && daclOffset + 8 <= bytes.length, 'DACL is malformed');
+	var aclRevision = bytes[daclOffset];
+	var aclSize = u16(bytes, daclOffset + 2);
+	var aceCount = u16(bytes, daclOffset + 4);
+	invariant(aclRevision === 2, 'unsupported ACL revision');
+	invariant(aclSize >= 8 && daclOffset + aclSize <= bytes.length, 'ACL size is malformed');
+	invariant(aceCount === 1, 'DACL must contain one ACE');
+	var aceOffset = daclOffset + 8;
+	invariant(aceOffset + 8 <= daclOffset + aclSize, 'ACE is truncated');
+	var aceType = bytes[aceOffset];
+	var aceFlags = bytes[aceOffset + 1];
+	var aceSize = u16(bytes, aceOffset + 2);
+	invariant(aceType === ACCESS_ALLOWED_ACE_TYPE, 'ACE must allow access');
+	invariant(aceFlags === expectedAceFlags, 'ACE flags are not exact');
+	invariant(aceSize >= 16 && aceOffset + aceSize === daclOffset + aclSize, 'ACE size is not exact');
+	invariant(u32(bytes, aceOffset + 4) === FILE_ALL_ACCESS, 'ACE is not full control');
+	var trustee = sidAt(bytes, aceOffset + 8);
+	invariant(trustee.value === expectedOwnerSid, 'ACE trustee is not the owner');
+	invariant(trustee.end === aceOffset + aceSize, 'ACE contains trailing data');
+	return { aceFlags: aceFlags, ownerSid: owner.value };
+}
+
+function inspectIidDescriptor(descriptor, expectedOwner, expectedAceFlags, enumeratorFactory) {
+	invariant(descriptor && descriptor.Owner, 'IID owner is absent');
+	if (expectedOwner !== null) invariant(String(descriptor.Owner) === expectedOwner, 'IID owner changed');
+	invariant((descriptor.Control & SE_DACL_PRESENT) !== 0, 'IID DACL is absent');
+	invariant((descriptor.Control & SE_DACL_PROTECTED) !== 0, 'IID DACL is not protected');
+	var dacl = descriptor.DiscretionaryAcl;
+	invariant(dacl && dacl.AceCount === 1, 'IID DACL must contain one ACE');
+	var entries = enumeratorFactory ? enumeratorFactory(dacl) : new Enumerator(dacl);
+	invariant(!entries.atEnd(), 'IID ACE is absent');
+	var ace = entries.item();
+	invariant(ace.AceType === ACCESS_ALLOWED_ACE_TYPE, 'IID ACE must allow access');
+	invariant((ace.AccessMask >>> 0) === FILE_ALL_ACCESS, 'IID ACE is not full control');
+	invariant(ace.AceFlags === expectedAceFlags, 'IID ACE flags are not exact');
+	entries.moveNext();
+	invariant(entries.atEnd(), 'IID DACL contains extra ACEs');
+}
+
+function rawDescriptor(utility, targetPath) {
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL;
+	return bytesFromSafeArray(utility.GetSecurityDescriptor(targetPath, ADS_PATH_FILE, ADS_SD_FORMAT_RAW));
+}
+
+function iidDescriptor(utility, targetPath) {
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL;
+	return utility.GetSecurityDescriptor(targetPath, ADS_PATH_FILE, ADS_SD_FORMAT_IID);
+}
+
+function ownerSid(bytes) {
+	invariant(bytes && typeof bytes.length === 'number' && bytes.length >= 20, 'malformed security descriptor');
+	invariant(bytes[0] === 1, 'unsupported security descriptor revision');
+	invariant((u16(bytes, 2) & SE_SELF_RELATIVE) !== 0, 'security descriptor is not self-relative');
+	return sidAt(bytes, u32(bytes, 4)).value;
+}
+
+function readTargets(environment, fso) {
+	var countText = String(environment('FORGE_PRIVATE_ACL_COUNT'));
+	invariant(/^[1-9][0-9]*$/.test(countText), 'invalid target count');
+	var count = Number(countText);
+	invariant(count <= MAX_TARGETS, 'too many ACL targets');
+	var targets = [];
+	for (var i = 0; i < count; i++) {
+		var targetPath = String(environment('FORGE_PRIVATE_ACL_TARGET_' + i));
+		invariant(targetPath.length > 0 && targetPath.indexOf('\0') === -1, 'invalid ACL target');
+		var isDirectory = fso.FolderExists(targetPath);
+		var isFile = fso.FileExists(targetPath);
+		invariant(isDirectory !== isFile, 'ACL target does not exist');
+		targets.push({ isDirectory: isDirectory, path: targetPath });
+	}
+	return targets;
+}
+
+function applyOwnerOnlyDacl(utility, target, currentSid, createObject, descriptor) {
+	var dacl = createObject('AccessControlList');
+	dacl.AclRevision = 2;
+	var ace = createObject('AccessControlEntry');
+	ace.Trustee = currentSid;
+	ace.AccessMask = FILE_ALL_ACCESS;
+	ace.AceType = ACCESS_ALLOWED_ACE_TYPE;
+	ace.AceFlags = target.isDirectory ? (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE) : 0;
+	dacl.AddAce(ace);
+	descriptor.Owner = currentSid;
+	descriptor.DiscretionaryAcl = dacl;
+	descriptor.Control = descriptor.Control | SE_DACL_PRESENT | SE_DACL_PROTECTED;
+	utility.SecurityMask = ADS_SECURITY_INFO_OWNER | ADS_SECURITY_INFO_DACL | PROTECTED_DACL_SECURITY_INFORMATION;
+	utility.SetSecurityDescriptor(target.path, ADS_PATH_FILE, descriptor, ADS_SD_FORMAT_IID);
+}
+
+function runWithDependencies(dependencies) {
+	var environment = dependencies.environment;
+	var fso = dependencies.fso;
+	var utility = dependencies.utility;
+	var createObject = dependencies.createObject;
+	var enumeratorFactory = dependencies.enumeratorFactory;
+	var currentSid = String(environment('FORGE_PRIVATE_ACL_SID'));
+	invariant(/^S-1-[0-9]+(?:-[0-9]+)+$/.test(currentSid), 'invalid current SID');
+	var targets = readTargets(environment, fso);
+	var owners = [];
+	var iidOwners = [];
+	var i;
+
+	// Prove every target and descriptor are readable before the first mutation.
+	for (i = 0; i < targets.length; i++) {
+		var beforeRaw = atStage(20, function () { return rawDescriptor(utility, targets[i].path); });
+		var beforeIid = atStage(21, function () { return iidDescriptor(utility, targets[i].path); });
+		owners.push(atStage(22, function () { return ownerSid(beforeRaw); }));
+		iidOwners.push(atStage(23, function () {
+			invariant(beforeIid && beforeIid.Owner, 'precheck IID owner is absent');
+			return String(beforeIid.Owner);
+		}));
+	}
+
+	for (i = 0; i < targets.length; i++) {
+		// Recheck immediately before changing the owner and DACL together.
+		var currentIid = atStage(30, function () {
+			var isDirectory = fso.FolderExists(targets[i].path);
+			var isFile = fso.FileExists(targets[i].path);
+			invariant(isDirectory === targets[i].isDirectory && isFile !== isDirectory, 'target type changed before mutation');
+			invariant(ownerSid(rawDescriptor(utility, targets[i].path)) === owners[i], 'owner changed before mutation');
+			var descriptor = iidDescriptor(utility, targets[i].path);
+			invariant(descriptor && descriptor.Owner, 'IID owner is absent before mutation');
+			invariant(String(descriptor.Owner) === iidOwners[i], 'IID owner changed before mutation');
+			return descriptor;
+		});
+		atStage(31, function () { applyOwnerOnlyDacl(utility, targets[i], currentSid, createObject, currentIid); });
+		var expectedFlags = targets[i].isDirectory ? (OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE) : 0;
+		atStage(32, function () {
+			inspectDescriptor(rawDescriptor(utility, targets[i].path), currentSid, expectedFlags);
+		});
+		atStage(33, function () {
+			inspectIidDescriptor(iidDescriptor(utility, targets[i].path), null, expectedFlags, enumeratorFactory);
+		});
+	}
+	return true;
+}
+
+function main() {
+	try {
+		var shell = new ActiveXObject('WScript.Shell');
+		runWithDependencies({
+			createObject: function (name) { return new ActiveXObject(name); },
+			environment: shell.Environment('PROCESS'),
+			fso: new ActiveXObject('Scripting.FileSystemObject'),
+			utility: new ActiveXObject('ADsSecurityUtility')
+		});
+		WScript.Quit(0);
+	} catch (_error) {
+		var exitCode = _error && typeof _error.forgeExitCode === 'number' ? _error.forgeExitCode : 1;
+		WScript.Quit(exitCode);
+	}
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+	module.exports = {
+		FILE_ALL_ACCESS: FILE_ALL_ACCESS,
+		inspectDescriptor: inspectDescriptor,
+		inspectIidDescriptor: inspectIidDescriptor,
+		runWithDependencies: runWithDependencies
+	};
+} else {
+	main();
+}

package/lib/memory/hygiene.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+
+const MEMORY_REVIEW_ENTRY_LIMIT = 200;
+const DEFAULT_FINDING_LIMIT = 50;
+const STALE_AFTER_DAYS = 90;
+const STALE_AFTER_MS = STALE_AFTER_DAYS * 24 * 60 * 60 * 1000;
+const VOLATILE_FIELDS = new Set([
+  'id', 'key', 'memory_id', 'created_at', 'updated_at', 'timestamp', 'revision',
+  'createdAt', 'updatedAt',
+]);
+const NEGATION_PREFIXES = Object.freeze(['do not ', "don't ", 'never ']);
+
+function compareCodeUnits(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function normalizeText(value) {
+  return String(value)
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[’']/g, "'")
+    .replace(/[^\p{L}\p{N}'\s]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function canonicalize(value) {
+  if (typeof value === 'string') return normalizeText(value);
+  if (Array.isArray(value)) {
+    return value.map(canonicalize).sort((left, right) =>
+      compareCodeUnits(JSON.stringify(left), JSON.stringify(right)));
+  }
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value)
+    .filter(key => !VOLATILE_FIELDS.has(key))
+    .sort(compareCodeUnits)
+    .map(key => [key, canonicalize(value[key])]));
+}
+
+function payloadFor(entry) {
+  if (entry && Object.hasOwn(entry, 'note')) return entry.note;
+  if (entry && Object.hasOwn(entry, 'value')) return entry.value;
+  return entry;
+}
+
+function fingerprint(value) {
+  return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+}
+
+function reviewId(kind, parts) {
+  const digest = createHash('sha256')
+    .update(`${kind}\0${[...parts].sort(compareCodeUnits).join('\0')}`)
+    .digest('hex')
+    .slice(0, 16);
+  return `memory-${kind}-${digest}`;
+}
+
+function claimFor(entry) {
+  const payload = payloadFor(entry);
+  if (typeof payload !== 'string') return null;
+  let text = normalizeText(payload);
+  let negative = false;
+  const prefix = NEGATION_PREFIXES.find(candidate => text.startsWith(candidate));
+  if (prefix) {
+    negative = true;
+    text = text.slice(prefix.length).trim();
+  }
+  return text ? { basis: text, negative } : null;
+}
+
+function readOwnDataProperty(value, fieldName, subject) {
+  let descriptor;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(value, fieldName);
+  } catch {
+    throw new TypeError(`${subject} ${fieldName} must be an own data property`);
+  }
+  if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+    throw new TypeError(`${subject} ${fieldName} must be an own data property`);
+  }
+  return descriptor.value;
+}
+
+function stalenessForMemory(memory, usageProjection, options = {}) {
+  if (!memory || typeof memory !== 'object') {
+    throw new TypeError('memory must be an object');
+  }
+  const assertCanonicalIso = (value, fieldName) => {
+    if (typeof value !== 'string' || Number.isNaN(Date.parse(value))
+      || new Date(value).toISOString() !== value) {
+      throw new TypeError(`${fieldName} must be a canonical ISO timestamp`);
+    }
+  };
+  const createdAt = readOwnDataProperty(memory, 'created_at', 'memory');
+  assertCanonicalIso(createdAt, 'memory created_at');
+  let useCount = 0;
+  let baselineAt = createdAt;
+  if (usageProjection !== null && usageProjection !== undefined) {
+    if (!usageProjection || typeof usageProjection !== 'object') {
+      throw new TypeError('durable usage projection must be an object');
+    }
+    const lastUsedAt = readOwnDataProperty(usageProjection, 'last_used_at', 'durable usage projection');
+    const projectedUseCount = readOwnDataProperty(usageProjection, 'use_count', 'durable usage projection');
+    assertCanonicalIso(lastUsedAt, 'durable last_used_at');
+    if (!Number.isSafeInteger(projectedUseCount) || projectedUseCount < 0) {
+      throw new TypeError('durable usage projection use_count must be a nonnegative safe integer');
+    }
+    baselineAt = lastUsedAt;
+    useCount = projectedUseCount;
+  }
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('staleness review options must be an object');
+  }
+  const now = readOwnDataProperty(options, 'now', 'staleness review options');
+  assertCanonicalIso(now, 'staleness review now');
+  const ageMs = Date.parse(now) - Date.parse(baselineAt);
+  const stale = ageMs > STALE_AFTER_MS;
+  return {
+    baseline_at: baselineAt,
+    use_count: useCount,
+    stale,
+    demote: stale,
+    age_days: Math.max(0, Math.floor(ageMs / (24 * 60 * 60 * 1000))),
+  };
+}
+
+function reviewMemories(entries, options = {}) {
+  const source = Array.isArray(entries) ? entries : [];
+  const entryLimit = Math.max(1, Math.min(options.entryLimit || MEMORY_REVIEW_ENTRY_LIMIT, MEMORY_REVIEW_ENTRY_LIMIT));
+  const findingLimit = Math.max(1, Math.min(options.findingLimit || DEFAULT_FINDING_LIMIT, DEFAULT_FINDING_LIMIT));
+  const selected = source.slice(0, entryLimit);
+  const findings = [];
+
+  const duplicateGroups = new Map();
+  for (const entry of selected) {
+    const payload = payloadFor(entry);
+    const canonical = JSON.stringify(canonicalize(payload));
+    const group = duplicateGroups.get(canonical) || [];
+    group.push(fingerprint(payload));
+    duplicateGroups.set(canonical, group);
+  }
+  for (const [canonical, members] of duplicateGroups) {
+    if (members.length < 2) continue;
+    findings.push({
+      review_id: reviewId('duplicate', [canonical]),
+      kind: 'duplicate',
+      count: members.length,
+      members: [...new Set(members)].sort(compareCodeUnits),
+    });
+  }
+
+  const claims = new Map();
+  for (const entry of selected) {
+    const claim = claimFor(entry);
+    if (!claim) continue;
+    const sides = claims.get(claim.basis) || { positive: [], negative: [] };
+    sides[claim.negative ? 'negative' : 'positive'].push(fingerprint(payloadFor(entry)));
+    claims.set(claim.basis, sides);
+  }
+  for (const [basis, sides] of claims) {
+    if (!sides.positive.length || !sides.negative.length) continue;
+    findings.push({
+      review_id: reviewId('contradiction', [basis]),
+      kind: 'contradiction',
+      claim: basis,
+      members: [...new Set([...sides.positive, ...sides.negative])].sort(compareCodeUnits),
+    });
+  }
+
+  findings.sort((left, right) => compareCodeUnits(left.review_id, right.review_id));
+  const total = Number.isInteger(options.total) && options.total >= source.length
+    ? options.total
+    : source.length;
+  return {
+    total,
+    scanned: selected.length,
+    truncated: total > selected.length || findings.length > findingLimit,
+    findings: findings.slice(0, findingLimit),
+  };
+}
+
+module.exports = {
+  MEMORY_REVIEW_ENTRY_LIMIT,
+  STALE_AFTER_DAYS,
+  reviewMemories,
+  stalenessForMemory,
+};

package/lib/memory/router.js

@@ -29,11 +29,16 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const projectMemory = require('../project-memory');
+const {
+  assertBackend,
+  createMemoryBackendRegistry,
+} = require('@forge/memory');
 
 /** Supported PUBLIC backends, default first. */
 const MEMORY_BACKENDS = ['local', 'graphiti'];
 const DEFAULT_MEMORY_BACKEND = 'local';
 const ENV_VAR = 'FORGE_MEMORY_BACKEND';
+const registeredMemoryBackends = new Map();
 
 /** Default recall cap — newest-N, so `recall` with no query never dumps the whole store. */
 const DEFAULT_RECALL_LIMIT = 20;
@@ -126,7 +131,7 @@ function resolveMemoryBackend({
   if (!value) return DEFAULT_MEMORY_BACKEND;
 
   const normalized = value.toLowerCase();
-  if (MEMORY_BACKENDS.includes(normalized)) return normalized;
+  if (MEMORY_BACKENDS.includes(normalized) || registeredMemoryBackends.has(normalized)) return normalized;
 
   warn(
     `Unknown memory backend "${value}" from ${source}; `
@@ -135,6 +140,22 @@ function resolveMemoryBackend({
   return DEFAULT_MEMORY_BACKEND;
 }
 
+function registerMemoryBackend(name, adapter) {
+  const normalized = typeof name === 'string' ? name.trim().toLowerCase() : '';
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(normalized) || MEMORY_BACKENDS.includes(normalized)) {
+    throw new TypeError('custom memory backend must have a unique lowercase name');
+  }
+  if (registeredMemoryBackends.has(normalized)) {
+    throw new Error(`custom memory backend "${normalized}" is already registered`);
+  }
+  assertBackend(adapter, normalized);
+  registeredMemoryBackends.set(normalized, adapter);
+}
+
+function unregisterMemoryBackend(name) {
+  registeredMemoryBackends.delete(String(name || '').trim().toLowerCase());
+}
+
 /**
  * Strict validation for the resolved backend. Unlike `resolveMemoryBackend`
  * (which soft-falls-back), this THROWS a clear, actionable error when the
@@ -145,6 +166,17 @@ function resolveMemoryBackend({
  */
 function assertMemoryConfigValid({ deps = {}, env = process.env, projectRoot, config } = {}) {
   const memory = config || readMemoryConfig(projectRoot);
+  const signal = collectBackendSignal({ deps, env, projectRoot, config: memory });
+  const requested = signal.value?.toLowerCase();
+  if (requested && !MEMORY_BACKENDS.includes(requested) && !registeredMemoryBackends.has(requested)) {
+    const error = new Error(
+      `memory backend "${signal.value}" from ${signal.source} is not registered. `
+      + `Available backends: ${[...MEMORY_BACKENDS, ...registeredMemoryBackends.keys()]
+        .sort((left, right) => left.localeCompare(right)).join(', ')}.`,
+    );
+    error.backend = signal.value;
+    throw error;
+  }
   const backend = resolveMemoryBackend({ deps, env, projectRoot, config: memory, warn: () => {} });
 
   if (backend !== 'graphiti') {
@@ -182,19 +214,32 @@ function assertMemoryConfigValid({ deps = {}, env = process.env, projectRoot, co
  * never-hang guarantee — the emitter, not this seam, owns preventing that.
  *
  * @param {object} [emitter] - optional `{ emit(entry) }` injected by callers.
- * @param {object} entry - the persisted local entry.
+ * @param {Function} entryProvider - returns the persisted local entry.
  */
-function fireAndForgetGraphitiEmit(emitter, entry) {
-  if (!emitter || typeof emitter.emit !== 'function') return;
-  try {
-    // Do not await: fire-and-forget. If it returns a promise, swallow rejection.
-    const maybePromise = emitter.emit(entry);
-    if (maybePromise && typeof maybePromise.then === 'function') {
-      maybePromise.then(() => {}, () => {});
-    }
-  } catch {
-    // Hard fallback: the local write already succeeded. Never surface emit errors.
-  }
+// The implementation now lives in the adapter below so synchronous failures can
+// be represented in the operation receipt while rejected promises stay consumed.
+
+function graphitiAdapter(emitter, entryProvider) {
+  const unavailable = () => [];
+  const freeze = (value, seen = new WeakSet()) => {
+    if (!value || typeof value !== 'object' || seen.has(value)) return value;
+    seen.add(value);
+    for (const child of Object.values(value)) freeze(child, seen);
+    return Object.freeze(value);
+  };
+  return {
+    add() {
+      if (!emitter || typeof emitter.emit !== 'function') return;
+      const maybePromise = emitter.emit(freeze(structuredClone(entryProvider())));
+      if (maybePromise && typeof maybePromise.then === 'function') {
+        maybePromise.then(() => {}, () => {});
+      }
+    },
+    recall: unavailable,
+    search: unavailable,
+    capture: unavailable,
+    digest: unavailable,
+  };
 }
 
 /**
@@ -336,20 +381,38 @@ function migrateJsonlNotesOnce(projectRoot, options = {}) {
  * @param {object} [options] - { tags, deps, env, config, graphitiEmitter, store }
  * @returns {{ id: string, note: string, timestamp: string, tags: string[] }}
  */
-function append(projectRoot, note, options = {}) {
+function appendWithReceipt(projectRoot, note, options = {}) {
   migrateJsonlNotesOnce(projectRoot, options);
   const backend = resolveMemoryBackend({ ...options, projectRoot });
-  const written = projectMemory.write(projectRoot, {
-    key: crypto.randomUUID(),
-    value: note,
-    sourceAgent: REMEMBER_SOURCE_AGENT,
-    tags: Array.isArray(options.tags) ? options.tags : [],
-  }, options);
-  const entry = toNote(written);
+  let entry;
+  const local = {
+    add() {
+      const written = projectMemory.write(projectRoot, {
+        key: crypto.randomUUID(),
+        value: note,
+        sourceAgent: REMEMBER_SOURCE_AGENT,
+        tags: Array.isArray(options.tags) ? options.tags : [],
+      }, options);
+      entry = toNote(written);
+      return entry;
+    },
+    recall: () => [],
+    search: () => [],
+    capture: () => null,
+    digest: () => null,
+  };
+  const registry = createMemoryBackendRegistry({ local });
   if (backend === 'graphiti') {
-    fireAndForgetGraphitiEmit(options.graphitiEmitter, entry);
+    registry.register('graphiti', graphitiAdapter(options.graphitiEmitter, () => entry));
+  } else if (backend !== 'local') {
+    registry.register(backend, registeredMemoryBackends.get(backend));
   }
-  return entry;
+  registry.select(backend);
+  return registry.add(note);
+}
+
+function append(projectRoot, note, options = {}) {
+  return appendWithReceipt(projectRoot, note, options).value;
 }
 
 /**
@@ -363,7 +426,7 @@ function append(projectRoot, note, options = {}) {
  * widens it to every stored memory.
  *
  * @param {string} projectRoot
- * @param {object} [selection] - { query, limit, all }
+ * @param {object} [selection] - { query, limit, all, kind }
  * @param {object} [options] - forwarded to the project-memory read paths (e.g. a store).
  * @returns {{ notes: object[], total: number, capped: boolean, query: string, limit: number, scope: string }}
  */
@@ -373,15 +436,16 @@ function recall(projectRoot, selection = {}, options = {}) {
   const limit = Number.isInteger(requested) && requested > 0 ? requested : DEFAULT_RECALL_LIMIT;
   const query = String(selection.query || '').trim();
   const includeAll = Boolean(selection.all);
+  const kind = typeof selection.kind === 'string' ? selection.kind.trim() : '';
+  const agents = includeAll ? undefined : HUMAN_MEMORY_AGENTS;
+  const readOptions = { ...options, agents, kind };
 
   if (query) {
-    const notes = projectMemory.searchRanked(projectRoot, query, limit, options).map(toNote);
+    const notes = projectMemory.searchRanked(projectRoot, query, limit, readOptions).map(toNote);
     // BM25 returns at most `limit`; a full result set signals there may be more.
     return { notes, total: notes.length, capped: notes.length >= limit, query, limit, scope: 'all' };
   }
 
-  const agents = includeAll ? undefined : HUMAN_MEMORY_AGENTS;
-  const readOptions = { ...options, agents };
   const notes = projectMemory.recent(projectRoot, limit, readOptions).map(toNote);
   const total = projectMemory.count(projectRoot, readOptions);
   return { notes, total, capped: total > notes.length, query: '', limit, scope: includeAll ? 'all' : 'remembered' };
@@ -395,8 +459,11 @@ module.exports = {
   readMemoryConfig,
   resolveMemoryBackend,
   assertMemoryConfigValid,
+  registerMemoryBackend,
+  unregisterMemoryBackend,
   migrateJsonlNotesOnce,
   toNote,
   append,
+  appendWithReceipt,
   recall,
 };

package/lib/memory/usage-evidence.js

@@ -0,0 +1,4 @@
+'use strict';
+
+// Compatibility shim: the durable usage contract belongs to @forge/memory.
+module.exports = require('@forge/memory');