@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/identity/infrastructure/owned-resource-store.ts

@@ -0,0 +1,259 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, readdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import {
+  ownedResourceLocator,
+  type OwnedResource,
+  type OwnedResourceKind,
+  type OwnedResourceLocator,
+  type RecordOwnedResourceInput,
+} from '../domain/owned-resource';
+import { ensureForgeInstanceIdentity } from './identity-store';
+
+function resourcesDir(controllerHome: string): string {
+  const dir = resolve(controllerHome, 'owned-resources');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function resourcePath(controllerHome: string, resourceId: string): string {
+  const sanitized = resourceId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  return join(resourcesDir(controllerHome), `${sanitized}.json`);
+}
+
+function validateOwnedResource(value: unknown): OwnedResource {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('record must be an object');
+  const resource = value as OwnedResource;
+  if (resource.schemaVersion !== 1 || !resource.resourceId || !resource.kind || !resource.targetRef) {
+    throw new Error('required resource identity is missing');
+  }
+  if (!resource.provenance?.creator || !resource.provenance.createdAt || !resource.retention?.intent || !resource.status || !resource.updatedAt) {
+    throw new Error('required ownership metadata is missing');
+  }
+  if (resource.cleanupCapable === true
+    && (!resource.ownerForgeInstanceId || !resource.locator?.kind || !resource.locator.value || !resource.identityFingerprint)) {
+    throw new Error('cleanup-capable resource lacks owner/locator/fingerprint');
+  }
+  return resource;
+}
+
+function readResourceFile(filePath: string): OwnedResource | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    return validateOwnedResource(JSON.parse(readFileSync(filePath, 'utf8')));
+  } catch (error) {
+    throw new Error(`OWNED_RESOURCE_STORE_CORRUPT: ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function writeResourceFile(controllerHome: string, resource: OwnedResource): void {
+  const filePath = resourcePath(controllerHome, resource.resourceId);
+  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(resource, null, 2), 'utf8');
+  renameSync(tmpPath, filePath);
+}
+
+export function ownedResourceLocatorFingerprint(ownerForgeInstanceId: string, locator: OwnedResourceLocator): string {
+  const owner = ownerForgeInstanceId.trim();
+  if (!owner || !locator.kind || !locator.value.trim()) throw new Error('OWNED_RESOURCE_FINGERPRINT_IDENTITY_REQUIRED');
+  return createHash('sha256').update(`${owner}\0${locator.kind}\0${locator.value.trim()}`).digest('hex');
+}
+
+export function ownedFilesystemIdentityFingerprint(ownerForgeInstanceId: string, pathInput: string): string {
+  const path = resolve(pathInput);
+  if (!existsSync(path)) throw new Error(`OWNED_RESOURCE_FILESYSTEM_TARGET_MISSING: ${path}`);
+  const canonicalPath = realpathSync(path);
+  const stat = lstatSync(canonicalPath);
+  const kind = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : stat.isSymbolicLink() ? 'symlink' : 'other';
+  return createHash('sha256').update([
+    ownerForgeInstanceId.trim(),
+    'filesystem_path',
+    canonicalPath,
+    String(stat.dev),
+    String(stat.ino),
+    kind,
+  ].join('\0')).digest('hex');
+}
+
+function resolvedIdentityFingerprint(
+  ownerForgeInstanceId: string,
+  locator: OwnedResourceLocator,
+  explicitFingerprint?: string,
+): string {
+  const explicit = explicitFingerprint?.trim();
+  if (explicit) return explicit;
+  if (locator.kind === 'filesystem_path') return ownedFilesystemIdentityFingerprint(ownerForgeInstanceId, locator.value);
+  return ownedResourceLocatorFingerprint(ownerForgeInstanceId, locator);
+}
+
+export interface OwnedResourceCleanupTargetInput {
+  resourceId: string;
+  kind: OwnedResourceKind;
+  targetRef?: string;
+  locator?: OwnedResourceLocator;
+  identityFingerprint?: string;
+}
+
+/**
+ * Cleanup authorization is an exact OwnedResource fact, never path shape or caller possession.
+ * Filesystem targets are re-fingerprinted immediately before mutation so a recycled path cannot
+ * inherit an older Forge ownership record.
+ */
+export function assertOwnedResourceCleanupTarget(
+  controllerHome: string,
+  input: OwnedResourceCleanupTargetInput,
+): OwnedResource {
+  const resource = getOwnedResource(controllerHome, input.resourceId);
+  if (!resource) throw new Error(`OWNED_RESOURCE_CLEANUP_AUTHORITY_MISSING: ${input.resourceId}`);
+  const currentInstance = ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+  if (resource.ownerForgeInstanceId !== currentInstance) {
+    throw new Error(`OWNED_RESOURCE_OWNER_INSTANCE_MISMATCH: ${input.resourceId}`);
+  }
+  if (resource.cleanupCapable !== true) throw new Error(`OWNED_RESOURCE_NOT_CLEANUP_CAPABLE: ${input.resourceId}`);
+  if (resource.status === 'released') throw new Error(`OWNED_RESOURCE_ALREADY_RELEASED: ${input.resourceId}`);
+  if (resource.kind !== input.kind) throw new Error(`OWNED_RESOURCE_KIND_MISMATCH: ${input.resourceId}`);
+  if (input.targetRef?.trim() && resource.targetRef !== input.targetRef.trim()) {
+    throw new Error(`OWNED_RESOURCE_TARGET_MISMATCH: ${input.resourceId}`);
+  }
+  if (!resource.locator || !resource.identityFingerprint) throw new Error(`OWNED_RESOURCE_CLEANUP_IDENTITY_MISSING: ${input.resourceId}`);
+  const expectedLocator = input.locator ?? resource.locator;
+  if (expectedLocator.kind !== resource.locator.kind || expectedLocator.value.trim() !== resource.locator.value) {
+    throw new Error(`OWNED_RESOURCE_LOCATOR_MISMATCH: ${input.resourceId}`);
+  }
+  const observedFingerprint = input.identityFingerprint?.trim()
+    || (resource.locator.kind === 'filesystem_path'
+      ? ownedFilesystemIdentityFingerprint(currentInstance, resource.locator.value)
+      : ownedResourceLocatorFingerprint(currentInstance, expectedLocator));
+  if (observedFingerprint !== resource.identityFingerprint) {
+    throw new Error(`OWNED_RESOURCE_IDENTITY_FINGERPRINT_MISMATCH: ${input.resourceId}`);
+  }
+  return resource;
+}
+
+export function recordOwnedResource(controllerHome: string, input: RecordOwnedResourceInput): OwnedResource {
+  const now = new Date().toISOString();
+  const resourceId = input.resourceId || `res-${randomUUID()}`;
+  // Cleanup authority is target-safe: ownership is pinned to the ForgeInstance
+  // that created/adopted the resource, and the locator fingerprint follows the
+  // resource kind so a recycled path/id cannot be reclaimed as the same resource.
+  const ownerForgeInstanceId = input.ownerForgeInstanceId?.trim()
+    || ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+  const locator = input.locator ?? ownedResourceLocator(input.kind, input.targetRef);
+  const identityFingerprint = resolvedIdentityFingerprint(ownerForgeInstanceId, locator, input.identityFingerprint);
+  const cleanupCapable = input.cleanupCapable ?? true;
+  const existing = readResourceFile(resourcePath(controllerHome, resourceId));
+  if (existing) {
+    const sameLocator = existing.kind === input.kind
+      && existing.ownerForgeInstanceId === ownerForgeInstanceId
+      && existing.locator?.kind === locator.kind
+      && existing.locator?.value === locator.value;
+    const sameIdentity = sameLocator && existing.identityFingerprint === identityFingerprint;
+    const legacyWeakFilesystemFingerprint = sameLocator
+      && locator.kind === 'filesystem_path'
+      && existing.identityFingerprint === ownedResourceLocatorFingerprint(ownerForgeInstanceId, locator)
+      && existing.identityFingerprint !== identityFingerprint;
+    if (legacyWeakFilesystemFingerprint) {
+      // Never bless a pre-upgrade path-only fingerprint as the identity of the
+      // currently observed inode. Preserve the historical record but retire its
+      // destructive authority; a newly created resource gets a new strong witness.
+      const downgraded: OwnedResource = { ...existing, cleanupCapable: false, updatedAt: now };
+      writeResourceFile(controllerHome, downgraded);
+      return downgraded;
+    }
+    if (!sameIdentity) throw new Error(`OWNED_RESOURCE_IDENTITY_CONFLICT: ${resourceId}`);
+    if (existing.cleanupCapable !== true && cleanupCapable === true) {
+      throw new Error(`OWNED_RESOURCE_CLEANUP_AUTHORITY_ESCALATION_FORBIDDEN: ${resourceId}`);
+    }
+    if (existing.status === 'released') throw new Error(`OWNED_RESOURCE_REUSE_REQUIRES_NEW_ID: ${resourceId}`);
+  }
+  const resource: OwnedResource = {
+    schemaVersion: 1,
+    resourceId,
+    kind: input.kind,
+    targetRef: input.targetRef,
+    ownerForgeInstanceId,
+    locator,
+    identityFingerprint,
+    cleanupCapable,
+    provenance: {
+      creator: input.creator,
+      createdAt: now,
+      associatedWorkId: input.associatedWorkId,
+      associatedRequirementId: input.associatedRequirementId,
+      repoId: input.repoId,
+    },
+    retention: {
+      intent: input.retentionIntent ?? 'temporary',
+      expiresAt: input.expiresAt,
+    },
+    status: 'active',
+    updatedAt: now,
+  };
+
+  writeResourceFile(controllerHome, resource);
+  return resource;
+}
+
+export function getOwnedResource(controllerHome: string, resourceId: string): OwnedResource | undefined {
+  return readResourceFile(resourcePath(controllerHome, resourceId));
+}
+
+export function listOwnedResources(controllerHome: string, filter?: { kind?: string; status?: string; repoId?: string }): OwnedResource[] {
+  const dir = resourcesDir(controllerHome);
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const results: OwnedResource[] = [];
+
+  for (const file of files) {
+    const resource = readResourceFile(join(dir, file));
+    if (!resource) continue;
+    if (filter?.kind && resource.kind !== filter.kind) continue;
+    if (filter?.status && resource.status !== filter.status) continue;
+    if (filter?.repoId && resource.provenance.repoId !== filter.repoId) continue;
+    results.push(resource);
+  }
+
+  return results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** Mark an owned resource as intentionally retained without changing cleanup authority. */
+export function markOwnedResourceRetained(
+  controllerHome: string,
+  resourceId: string,
+): OwnedResource | undefined {
+  const existing = getOwnedResource(controllerHome, resourceId);
+  if (!existing) return undefined;
+  const updated: OwnedResource = {
+    ...existing,
+    status: 'retained',
+    updatedAt: new Date().toISOString(),
+  };
+  writeResourceFile(controllerHome, updated);
+  return updated;
+}
+
+export function markOwnedResourceCleaned(
+  controllerHome: string,
+  resourceId: string,
+  cleanedBy: string,
+  receiptRef?: string,
+): OwnedResource | undefined {
+  const existing = getOwnedResource(controllerHome, resourceId);
+  if (!existing) return undefined;
+
+  const now = new Date().toISOString();
+  const updated: OwnedResource = {
+    ...existing,
+    status: 'released',
+    updatedAt: now,
+    cleanupProof: {
+      cleanedAt: now,
+      cleanedBy,
+      receiptRef,
+    },
+  };
+
+  writeResourceFile(controllerHome, updated);
+  return updated;
+}

package/packages/kernel/identity/infrastructure/user-request-store.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type {
+  CreateUserRequestInput,
+  ResolveUserRequestInput,
+  UserRequest,
+} from '../domain/user-request';
+
+interface UserRequestStoreData {
+  schemaVersion: 1;
+  requests: UserRequest[];
+}
+
+export function userRequestStorePath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'system', 'user-requests', 'requests.json');
+}
+
+function loadStore(controllerHome: string): UserRequestStoreData {
+  const path = userRequestStorePath(controllerHome);
+  if (!existsSync(path)) return { schemaVersion: 1, requests: [] };
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('store must be an object');
+    const record = raw as Record<string, unknown>;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.requests)) throw new Error('schemaVersion/requests are invalid');
+    return { schemaVersion: 1, requests: record.requests as UserRequest[] };
+  } catch (error) {
+    throw new Error(`USER_REQUEST_STORE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function saveStore(controllerHome: string, store: UserRequestStoreData): void {
+  const path = userRequestStorePath(controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+  renameSync(temporary, path);
+}
+
+function canonicalRequestIndex(requests: readonly UserRequest[], requestId: string): number {
+  let selected = -1;
+  let selectedAt = Number.NEGATIVE_INFINITY;
+  for (let index = 0; index < requests.length; index += 1) {
+    const request = requests[index]!;
+    if (request.requestId !== requestId) continue;
+    const updatedAt = Date.parse(request.updatedAt);
+    const comparableAt = Number.isFinite(updatedAt) ? updatedAt : Number.NEGATIVE_INFINITY;
+    if (selected < 0 || comparableAt >= selectedAt) {
+      selected = index;
+      selectedAt = comparableAt;
+    }
+  }
+  return selected;
+}
+
+function canonicalUserRequests(requests: readonly UserRequest[]): UserRequest[] {
+  const requestIds = [...new Set(requests.map((request) => request.requestId))];
+  return requestIds.map((requestId) => requests[canonicalRequestIndex(requests, requestId)]!);
+}
+
+/**
+ * Creates or coalesces a UserActionRequest / UserDecisionRequest.
+ * If an active (pending) request exists with the exact same rootCauseKey,
+ * return the existing record to guarantee deduplication across retries.
+ */
+export function recordUserRequest(controllerHome: string, input: CreateUserRequestInput): UserRequest {
+  const rootCauseKey = input.rootCauseKey.trim();
+  if (!rootCauseKey) throw new Error('USER_REQUEST_ROOT_CAUSE_KEY_REQUIRED');
+
+  const store = loadStore(controllerHome);
+  const explicitRequestId = input.requestId?.trim();
+  if (explicitRequestId) {
+    const identityMatches = store.requests.filter((request) => request.requestId === explicitRequestId);
+    if (identityMatches.some((request) => request.rootCauseKey !== rootCauseKey)) {
+      throw new Error(`USER_REQUEST_ID_CONFLICT: ${explicitRequestId}`);
+    }
+    if (identityMatches.length) {
+      const existingIndex = canonicalRequestIndex(store.requests, explicitRequestId);
+      const existing = store.requests[existingIndex]!;
+      if (existing.status !== 'pending' || !input.presentation) return structuredClone(existing);
+      const merged = {
+        ...existing,
+        presentation: { ...(existing.presentation ?? {}), ...input.presentation },
+      };
+      if (JSON.stringify(merged.presentation) !== JSON.stringify(existing.presentation ?? {})) {
+        merged.updatedAt = (input.now ?? new Date()).toISOString();
+        store.requests[existingIndex] = merged;
+        saveStore(controllerHome, store);
+        return structuredClone(merged);
+      }
+      return structuredClone(existing);
+    }
+  }
+
+  // Coalescing: return matching pending request for the same semantic root cause.
+  const existingIndex = store.requests.findIndex(
+    (r) => r.status === 'pending' && r.rootCauseKey === rootCauseKey,
+  );
+  if (existingIndex >= 0) {
+    const existing = store.requests[existingIndex]!;
+    if (input.presentation) {
+      const merged = {
+        ...existing,
+        presentation: { ...(existing.presentation ?? {}), ...input.presentation },
+      };
+      if (JSON.stringify(merged.presentation) !== JSON.stringify(existing.presentation ?? {})) {
+        merged.updatedAt = (input.now ?? new Date()).toISOString();
+        store.requests[existingIndex] = merged;
+        saveStore(controllerHome, store);
+        return structuredClone(merged);
+      }
+    }
+    return structuredClone(existing);
+  }
+
+  const now = (input.now ?? new Date()).toISOString();
+  const requestId = explicitRequestId || `usrreq_${randomUUID().replaceAll('-', '')}`;
+  const record: UserRequest = {
+    schemaVersion: 1,
+    requestId,
+    kind: input.kind,
+    rootCauseKey,
+    title: input.title.trim(),
+    summary: input.summary.trim(),
+    actionRequired: input.actionRequired,
+    ...(input.targetScope ? { targetScope: input.targetScope } : {}),
+    ...(input.options ? { options: input.options } : {}),
+    ...(input.presentation ? { presentation: input.presentation } : {}),
+    status: 'pending',
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  store.requests.push(record);
+  saveStore(controllerHome, store);
+  return record;
+}
+
+export function resolveUserRequest(controllerHome: string, input: ResolveUserRequestInput): UserRequest {
+  const requestId = input.requestId.trim();
+  const decision = input.decision.trim();
+  const resolvedBy = input.resolvedBy.trim();
+  if (!requestId || !decision || !resolvedBy) throw new Error('RESOLVE_USER_REQUEST_ARGS_REQUIRED');
+
+  const store = loadStore(controllerHome);
+  const matchingIndexes = store.requests.flatMap((request, index) => request.requestId === requestId ? [index] : []);
+  if (!matchingIndexes.length) throw new Error(`USER_REQUEST_NOT_FOUND: ${requestId}`);
+  const canonicalIndex = canonicalRequestIndex(store.requests, requestId);
+  const now = (input.now ?? new Date()).toISOString();
+  let changed = false;
+  for (const index of matchingIndexes) {
+    const current = store.requests[index]!;
+    if (current.status !== 'pending') continue;
+    store.requests[index] = {
+      ...current,
+      status: 'resolved',
+      resolution: { decision, resolvedBy, resolvedAt: now },
+      updatedAt: now,
+    };
+    changed = true;
+  }
+  if (changed) saveStore(controllerHome, store);
+  const resolvedCanonicalIndex = canonicalRequestIndex(store.requests, requestId);
+  return structuredClone(store.requests[resolvedCanonicalIndex >= 0 ? resolvedCanonicalIndex : canonicalIndex]!);
+}
+
+export function getUserRequest(controllerHome: string, requestId: string): UserRequest | undefined {
+  const normalized = requestId.trim();
+  if (!normalized) return undefined;
+  const store = loadStore(controllerHome);
+  const index = canonicalRequestIndex(store.requests, normalized);
+  return index >= 0 ? structuredClone(store.requests[index]!) : undefined;
+}
+
+export function listUserRequests(controllerHome: string, status?: 'pending' | 'resolved' | 'cancelled' | 'all'): UserRequest[] {
+  const store = loadStore(controllerHome);
+  return canonicalUserRequests(store.requests)
+    .filter((r) => !status || status === 'all' || r.status === status)
+    .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt))
+    .map((r) => structuredClone(r));
+}

package/packages/kernel/memory/api/index.ts

@@ -0,0 +1,5 @@
+/** Stable in-process API for closed operational-prior contracts and reducers. */
+export * from '../domain/operational-prior';
+export * from '../domain/experience';
+export * from '../application/experience-service';
+export * from '../application/outcome-service';

package/packages/kernel/memory/application/experience-service.ts

@@ -0,0 +1,118 @@
+import { matchesExperienceApplicability, validateExperience, type ExperienceApplicability, type ExperienceDraft, type ExperienceRecord } from '../domain/experience';
+import type { ScopeRef } from '../../identity/api/index';
+
+/** Ports are supplied by trusted composition, never deserialized from a tool call. */
+export interface ExperienceStorePort {
+  transaction<T>(operation: () => T): T;
+  assertWriteAuthority(scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void;
+  evidenceAvailable(ref: string, scope: ScopeRef, sourceWorkId: string): boolean;
+  read(scope: ScopeRef, id: string): ExperienceRecord | undefined;
+  list(scope: ScopeRef, limit: number): ExperienceRecord[];
+  write(record: ExperienceRecord, expectedRevision: number | null): void;
+  assertSafePayload(record: ExperienceRecord): void;
+}
+
+const DAY = 86_400_000;
+export const MAX_EXPERIENCES_PER_SCOPE = 1000;
+
+function normalized(draft: ExperienceDraft): ExperienceRecord {
+  const expiresAt = draft.expiresAt ?? (draft.kind === 'lesson' ? undefined : new Date(Date.parse(draft.recordedAt) + (draft.kind === 'observation' ? 30 : 90) * DAY).toISOString());
+  return validateExperience({ ...structuredClone(draft), schemaVersion: 1, revision: 1, expiresAt });
+}
+
+function contentIdentity(record: ExperienceRecord): string {
+  const { revision: _revision, retractedAt: _at, retractionReason: _reason, retractionSourceWorkId: _work, retractionSourceRoundId: _round, ...content } = record;
+  // Stable property order comes from the validated draft shape supplied by callers.
+  const canonical = (v: unknown): unknown => Array.isArray(v) ? v.map(canonical) : v && typeof v === 'object'
+    ? Object.fromEntries(Object.entries(v).filter(([, value]) => value !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, canonical(value)])) : v;
+  return JSON.stringify(canonical(content));
+}
+
+export function recordExperience(store: ExperienceStorePort, draft: ExperienceDraft, now = new Date().toISOString()): ExperienceRecord {
+  return store.transaction(() => {
+    const record = normalized(draft);
+    if (!Number.isFinite(Date.parse(now)) || Date.parse(record.recordedAt) > Date.parse(now)) throw new Error('EXPERIENCE_FUTURE_OBSERVATION');
+    if (record.supersedesId) throw new Error('EXPERIENCE_USE_SUPERSEDE');
+    store.assertWriteAuthority(record.scope, record.sourceWorkId, record.sourceRoundId);
+    store.assertSafePayload(record);
+    const current = store.read(record.scope, record.id);
+    if (current) {
+      if (current.retractedAt || contentIdentity(current) !== contentIdentity(record)) throw new Error('EXPERIENCE_IDENTITY_CONFLICT');
+      return current;
+    }
+    for (const ref of [...record.evidenceRefs, ...record.counterEvidenceRefs]) {
+      if (!store.evidenceAvailable(ref, record.scope, record.sourceWorkId)) throw new Error('EXPERIENCE_EVIDENCE_UNAVAILABLE');
+    }
+    if (store.list(record.scope, MAX_EXPERIENCES_PER_SCOPE).length >= MAX_EXPERIENCES_PER_SCOPE) throw new Error('EXPERIENCE_CAPACITY_REACHED');
+    store.write(record, null);
+    return record;
+  });
+}
+
+export function queryExperiences(store: Pick<ExperienceStorePort, 'list' | 'evidenceAvailable'>, input: {
+  scopes: readonly ScopeRef[]; applicability: ExperienceApplicability; now: string; limit?: number;
+}): { records: ExperienceRecord[]; gaps: string[] } {
+  if (!Number.isFinite(Date.parse(input.now))) throw new Error('EXPERIENCE_QUERY_TIME_INVALID');
+  const records: ExperienceRecord[] = [], gaps: string[] = [];
+  for (const scope of input.scopes.slice(0, 8)) {
+    const candidates = store.list(scope, MAX_EXPERIENCES_PER_SCOPE);
+    if (candidates.length >= MAX_EXPERIENCES_PER_SCOPE) gaps.push('experience_candidate_limit');
+    for (const candidate of candidates) {
+      try { validateExperience(candidate); } catch { gaps.push('experience_record_invalid'); continue; }
+      if (candidate.scope.kind !== scope.kind || candidate.scope.id !== scope.id || candidate.retractedAt
+        || candidate.expiresAt && Date.parse(candidate.expiresAt) <= Date.parse(input.now)
+        || !matchesExperienceApplicability(candidate.applicability, input.applicability)) continue;
+      if ([...candidate.evidenceRefs, ...candidate.counterEvidenceRefs].some(ref => !store.evidenceAvailable(ref, scope, candidate.sourceWorkId))) { gaps.push(`experience_evidence_unavailable:${candidate.id}`); continue; }
+      records.push(candidate);
+    }
+  }
+  const limit = Math.max(1, Math.min(input.limit ?? 32, 32));
+  records.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt) || a.id.localeCompare(b.id));
+  if (records.length > limit) gaps.push('experience_result_limit');
+  return { records: records.slice(0, limit), gaps: [...new Set(gaps)] };
+}
+
+export function retractExperience(store: ExperienceStorePort, input: {
+  scope: ScopeRef; id: string; expectedRevision: number; sourceWorkId: string; sourceRoundId: string; reason: string; now: string;
+}): ExperienceRecord {
+  return store.transaction(() => {
+    store.assertWriteAuthority(input.scope, input.sourceWorkId, input.sourceRoundId);
+    const current = store.read(input.scope, input.id);
+    if (current?.retractedAt === input.now && current.retractionReason === input.reason
+      && current.revision === input.expectedRevision + 1 && current.retractionSourceWorkId === input.sourceWorkId
+      && current.retractionSourceRoundId === input.sourceRoundId) return current;
+    if (!current || current.revision !== input.expectedRevision) throw new Error('EXPERIENCE_REVISION_CONFLICT');
+    if (current.retractedAt) throw new Error('EXPERIENCE_REVISION_CONFLICT');
+    const next = validateExperience({ ...current, revision: current.revision + 1, retractedAt: input.now, retractionReason: input.reason,
+      retractionSourceWorkId: input.sourceWorkId, retractionSourceRoundId: input.sourceRoundId });
+    store.assertSafePayload(next); store.write(next, current.revision);
+    return next;
+  });
+}
+
+export function supersedeExperience(store: ExperienceStorePort, input: {
+  previousId: string; expectedRevision: number; draft: ExperienceDraft; now: string;
+}): ExperienceRecord {
+  return store.transaction(() => {
+    if (input.previousId === input.draft.id) throw new Error('EXPERIENCE_SUPERSEDE_SELF');
+    const proposed = normalized({ ...input.draft, supersedesId: undefined });
+    store.assertWriteAuthority(proposed.scope, proposed.sourceWorkId, proposed.sourceRoundId);
+    store.assertSafePayload(proposed);
+    const previous = store.read(input.draft.scope, input.previousId);
+    const replacement = store.read(input.draft.scope, input.draft.id);
+    if (previous?.revision === input.expectedRevision + 1 && previous.retractedAt === input.now
+      && previous.retractionReason === `superseded:${input.draft.id}`
+      && previous.retractionSourceWorkId === proposed.sourceWorkId && previous.retractionSourceRoundId === proposed.sourceRoundId
+      && replacement?.supersedesId === previous.id && !replacement.retractedAt
+      && contentIdentity({ ...replacement, supersedesId: undefined }) === contentIdentity(proposed)) return replacement;
+    if (replacement) throw new Error('EXPERIENCE_IDENTITY_CONFLICT');
+    if (!previous || previous.revision !== input.expectedRevision || previous.retractedAt) throw new Error('EXPERIENCE_REVISION_CONFLICT');
+    // Admission is shared with ordinary recording; both writes commit atomically.
+    const created = recordExperience(store, { ...input.draft, supersedesId: undefined }, input.now);
+    const next = validateExperience({ ...created, supersedesId: previous.id, revision: created.revision + 1 });
+    store.write(next, created.revision);
+    retractExperience(store, { scope: previous.scope, id: previous.id, expectedRevision: previous.revision,
+      sourceWorkId: input.draft.sourceWorkId, sourceRoundId: input.draft.sourceRoundId, reason: `superseded:${next.id}`, now: input.now });
+    return next;
+  });
+}

package/packages/kernel/memory/application/outcome-service.ts

@@ -0,0 +1,77 @@
+import type { ScopeRef } from '../../identity/api/index';
+import { validateOutcomeObservation, type OutcomeObservation } from '../domain/experience';
+
+export interface OutcomeObservationStorePort {
+  transaction<T>(operation: () => T): T;
+  assertWriteAuthority(scope: ScopeRef, sourceWorkId: string, sourceRoundId: string): void;
+  evidenceAvailable(ref: string, scope: ScopeRef, sourceWorkId: string): boolean;
+  read(scope: ScopeRef, id: string): OutcomeObservation | undefined;
+  list(scope: ScopeRef, limit: number): OutcomeObservation[];
+  write(observation: OutcomeObservation): void;
+  assertSafePayload(observation: OutcomeObservation): void;
+}
+
+export const MAX_OUTCOME_OBSERVATIONS_PER_SCOPE = 1000;
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+    .filter(([, entry]) => entry !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => [key, canonical(entry)]));
+}
+
+function sameObservation(left: OutcomeObservation, right: OutcomeObservation): boolean {
+  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}
+
+export function recordOutcomeObservation(
+  store: OutcomeObservationStorePort,
+  observation: OutcomeObservation,
+  now = new Date().toISOString(),
+): OutcomeObservation {
+  return store.transaction(() => {
+    const value = validateOutcomeObservation(structuredClone(observation));
+    const currentTime = Date.parse(now);
+    if (!Number.isFinite(currentTime) || Date.parse(value.observedAt) > currentTime) throw new Error('OUTCOME_FUTURE_OBSERVATION');
+    store.assertWriteAuthority(value.scope, value.sourceWorkId, value.sourceRoundId);
+    store.assertSafePayload(value);
+    const existing = store.read(value.scope, value.id);
+    if (existing) {
+      if (!sameObservation(existing, value)) throw new Error('OUTCOME_IDENTITY_CONFLICT');
+      return existing;
+    }
+    if (!store.evidenceAvailable(value.evidenceRef, value.scope, value.sourceWorkId)) throw new Error('OUTCOME_EVIDENCE_UNAVAILABLE');
+    if (store.list(value.scope, MAX_OUTCOME_OBSERVATIONS_PER_SCOPE).length >= MAX_OUTCOME_OBSERVATIONS_PER_SCOPE) throw new Error('OUTCOME_CAPACITY_REACHED');
+    store.write(value);
+    return value;
+  });
+}
+
+export function queryOutcomeObservations(
+  store: Pick<OutcomeObservationStorePort, 'list' | 'evidenceAvailable'>,
+  input: { scopes: readonly ScopeRef[]; channel?: string; account?: string; since?: string; limit?: number },
+): { observations: OutcomeObservation[]; gaps: string[] } {
+  const since = input.since ? Date.parse(input.since) : undefined;
+  if (input.since && !Number.isFinite(since)) throw new Error('OUTCOME_QUERY_TIME_INVALID');
+  const observations: OutcomeObservation[] = [];
+  const gaps: string[] = [];
+  for (const scope of input.scopes.slice(0, 8)) {
+    const rows = store.list(scope, MAX_OUTCOME_OBSERVATIONS_PER_SCOPE);
+    if (rows.length >= MAX_OUTCOME_OBSERVATIONS_PER_SCOPE) gaps.push('outcome_candidate_limit');
+    for (const row of rows) {
+      try { validateOutcomeObservation(row); } catch { gaps.push('outcome_record_invalid'); continue; }
+      if (row.scope.kind !== scope.kind || row.scope.id !== scope.id) continue;
+      if (input.channel && row.remoteObject.channel !== input.channel) continue;
+      if (input.account && row.remoteObject.account !== input.account) continue;
+      if (since !== undefined && Date.parse(row.observedAt) < since) continue;
+      if (!store.evidenceAvailable(row.evidenceRef, scope, row.sourceWorkId)) { gaps.push(`outcome_evidence_unavailable:${row.id}`); continue; }
+      observations.push(row);
+    }
+  }
+  const limit = Math.max(1, Math.min(input.limit ?? 32, 32));
+  observations.sort((a, b) => b.observedAt.localeCompare(a.observedAt) || a.id.localeCompare(b.id));
+  if (observations.length > limit) gaps.push('outcome_result_limit');
+  return { observations: observations.slice(0, limit), gaps: [...new Set(gaps)] };
+}