@moretea-labs/forge 1.7.2 → 1.8.0

package/packages/kernel/identity/application/identity-service.ts

@@ -0,0 +1,67 @@
+import { createHash } from 'crypto';
+import type {
+  CapabilityGrant,
+  ConnectionIdentity,
+  CredentialReference,
+  ForgeInstanceIdentity,
+  Principal,
+  PrincipalKind,
+} from '../domain/types';
+export { ensureForgeInstanceIdentity, forgeInstanceIdentityPath, readForgeInstanceIdentity } from '../infrastructure/identity-store';
+export type { ForgeIdentityStoreOptions } from '../infrastructure/identity-store';
+
+export function normalizeConfiguredForgeInstanceId(value: string | undefined, label = 'Forge instance id'): string | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (!/^[a-z][a-z0-9-]{1,62}$/.test(normalized)) {
+    throw new Error(`${label} must match ^[a-z][a-z0-9-]{1,62}$`);
+  }
+  return normalized;
+}
+
+export function principal(principalId: string, kind: PrincipalKind, issuer?: string): Principal {
+  const normalized = principalId.trim();
+  if (!normalized) throw new Error('PRINCIPAL_ID_REQUIRED');
+  return { principalId: normalized.slice(0, 512), kind, ...(issuer?.trim() ? { issuer: issuer.trim().slice(0, 160) } : {}) };
+}
+
+export function credentialReference(reference: string, provider?: string): CredentialReference {
+  const normalized = reference.trim();
+  const match = /^(env|file|store|keychain|secret-ref):(.+)$/.exec(normalized);
+  if (!match) throw new Error('CREDENTIAL_REFERENCE_REQUIRED: raw credentials are not accepted by Kernel identity');
+  const kind = match[1] === 'secret-ref' ? 'secret_ref' : match[1] as CredentialReference['kind'];
+  return { reference: normalized, kind, ...(provider?.trim() ? { provider: provider.trim().slice(0, 160) } : {}) };
+}
+
+export function capabilityGrant(input: Omit<CapabilityGrant, 'capabilities'> & { capabilities: readonly string[] }): CapabilityGrant {
+  if (!input.grantId.trim() || !input.principalId.trim()) throw new Error('CAPABILITY_GRANT_IDENTITY_REQUIRED');
+  const capabilities = [...new Set(input.capabilities.map((value) => value.trim()).filter(Boolean))].sort();
+  return { ...input, grantId: input.grantId.trim(), principalId: input.principalId.trim(), capabilities };
+}
+
+export function connectionIdentity(input: {
+  instance: ForgeInstanceIdentity;
+  adapterId: string;
+  principal: Principal;
+  credentialReference?: CredentialReference;
+  now?: () => string;
+}): ConnectionIdentity {
+  const adapterId = input.adapterId.trim();
+  if (!adapterId) throw new Error('CONNECTION_ADAPTER_ID_REQUIRED');
+  const semanticKey = [
+    input.instance.instanceId,
+    adapterId,
+    input.principal.principalId,
+    input.credentialReference?.reference ?? '',
+  ].join('\u0000');
+  const connectionId = `conn_${createHash('sha256').update(semanticKey).digest('hex').slice(0, 32)}`;
+  return {
+    schemaVersion: 1,
+    connectionId,
+    forgeInstanceId: input.instance.instanceId,
+    adapterId,
+    principalId: input.principal.principalId,
+    ...(input.credentialReference ? { credentialReference: input.credentialReference } : {}),
+    createdAt: (input.now ?? (() => new Date().toISOString()))(),
+  };
+}

package/packages/kernel/identity/domain/scope.ts

@@ -0,0 +1,63 @@
+/** Portable semantic scope. It must never encode a local checkout or filesystem path. */
+export type ScopeKind = 'workspace' | 'project' | 'requirement' | 'plan' | 'plan_step' | 'work';
+
+export interface ScopeRef {
+  schemaVersion: 1;
+  kind: ScopeKind;
+  id: string;
+}
+
+/** Node-local execution placement. This is replaceable runtime state, not semantic identity. */
+export interface ExecutionPlacement {
+  schemaVersion: 1;
+  forgeInstanceId?: string;
+  repositoryId?: string;
+  checkoutId?: string;
+}
+
+export type SemanticRecordOrigin = 'local' | 'imported' | 'synced' | 'migration';
+
+/**
+ * Bounded metadata for one revisioned semantic record. The payload remains owned
+ * by its domain; this envelope supplies portable scope, provenance and revision.
+ */
+export interface SemanticRecordMetadata {
+  schemaVersion: 1;
+  scope: ScopeRef;
+  revision: number;
+  updatedAt: string;
+  origin: SemanticRecordOrigin;
+  forgeInstanceId?: string;
+  principalId?: string;
+  sourceRevision?: string;
+}
+
+/** Optimistic-concurrency precondition. null means the record must not exist. */
+export interface SemanticRecordWriteCondition {
+  expectedRevision: number | null;
+}
+
+export interface SemanticRecordEnvelope<T> {
+  metadata: SemanticRecordMetadata;
+  value: T;
+}
+
+export function scopeRef(kind: ScopeKind, id: string): ScopeRef {
+  const normalized = id.trim();
+  if (!normalized) throw new Error('SEMANTIC_SCOPE_ID_REQUIRED');
+  return { schemaVersion: 1, kind, id: normalized.slice(0, 512) };
+}
+
+export function executionPlacement(input: Omit<ExecutionPlacement, 'schemaVersion'>): ExecutionPlacement {
+  const forgeInstanceId = input.forgeInstanceId?.trim() || undefined;
+  const repositoryId = input.repositoryId?.trim() || undefined;
+  const checkoutId = input.checkoutId?.trim() || undefined;
+  if (!forgeInstanceId && !repositoryId && !checkoutId) throw new Error('EXECUTION_PLACEMENT_IDENTITY_REQUIRED');
+  return { schemaVersion: 1, ...(forgeInstanceId ? { forgeInstanceId } : {}), ...(repositoryId ? { repositoryId } : {}), ...(checkoutId ? { checkoutId } : {}) };
+}
+
+export function semanticRecordMetadata(input: Omit<SemanticRecordMetadata, 'schemaVersion'>): SemanticRecordMetadata {
+  if (!Number.isSafeInteger(input.revision) || input.revision < 0) throw new Error('SEMANTIC_RECORD_REVISION_INVALID');
+  if (Number.isNaN(Date.parse(input.updatedAt))) throw new Error('SEMANTIC_RECORD_UPDATED_AT_INVALID');
+  return { schemaVersion: 1, ...input };
+}

package/packages/kernel/identity/domain/semantic-sync.ts

@@ -0,0 +1,81 @@
+import type { SemanticRecordEnvelope, SemanticRecordWriteCondition } from './scope';
+
+export const SEMANTIC_SYNC_RECORD_KINDS = ['workspace', 'project', 'requirement', 'plan', 'work'] as const;
+export type SemanticSyncRecordKind = (typeof SEMANTIC_SYNC_RECORD_KINDS)[number];
+
+export const MAX_SEMANTIC_SYNC_RECORDS = 1_000;
+export const MAX_SEMANTIC_SYNC_BUNDLE_BYTES = 2 * 1024 * 1024;
+export const MAX_SEMANTIC_SYNC_JOURNAL_ENTRIES = 256;
+export const MAX_SEMANTIC_SYNC_JOURNAL_KEY_SAMPLES = 4;
+
+export interface SemanticSyncRecord<T = unknown> {
+  schemaVersion: 1;
+  kind: SemanticSyncRecordKind;
+  id: string;
+  envelope: SemanticRecordEnvelope<T>;
+  /** Optimistic precondition against the destination replica-store revision. null means first import. */
+  condition: SemanticRecordWriteCondition;
+  fingerprint: string;
+}
+
+export interface SemanticSyncBundle {
+  schemaVersion: 1;
+  kind: 'forge_semantic_sync_bundle';
+  workspaceId: string;
+  projectId: string;
+  sourceForgeInstanceId: string;
+  generatedAt: string;
+  records: SemanticSyncRecord[];
+  contentFingerprint: string;
+}
+
+export interface SemanticSyncImportConflict {
+  recordKey: string;
+  code: 'local_authority_conflict' | 'replica_revision_conflict';
+  expectedRevision?: number | null;
+  actualRevision?: number;
+}
+
+export interface SemanticSyncImportReceipt {
+  schemaVersion: 1;
+  workspaceId: string;
+  projectId: string;
+  sourceForgeInstanceId: string;
+  targetForgeInstanceId: string;
+  bundleFingerprint: string;
+  importedAt: string;
+  applied: string[];
+  converged: string[];
+  replicaRevisions: Record<string, number>;
+}
+
+export function semanticSyncRecordKey(kind: SemanticSyncRecordKind, id: string): string {
+  const normalized = id.trim();
+  if (!SEMANTIC_SYNC_RECORD_KINDS.includes(kind) || !normalized || normalized.length > 512) throw new Error('SEMANTIC_SYNC_RECORD_ID_INVALID');
+  return `${kind}:${normalized}`;
+}
+
+export function assertSemanticSyncRecordBounds(records: readonly SemanticSyncRecord[]): void {
+  if (records.length < 1 || records.length > MAX_SEMANTIC_SYNC_RECORDS) throw new Error('SEMANTIC_SYNC_RECORD_COUNT_INVALID');
+  const keys = new Set<string>();
+  for (const record of records) {
+    if (record.schemaVersion !== 1) throw new Error('SEMANTIC_SYNC_RECORD_SCHEMA_INVALID');
+    const key = semanticSyncRecordKey(record.kind, record.id);
+    if (keys.has(key)) throw new Error(`SEMANTIC_SYNC_RECORD_DUPLICATE: ${key}`);
+    keys.add(key);
+    if (record.envelope.metadata.scope.kind !== record.kind || record.envelope.metadata.scope.id !== record.id) {
+      throw new Error(`SEMANTIC_SYNC_SCOPE_MISMATCH: ${key}`);
+    }
+    const metadata = record.envelope.metadata;
+    if (metadata.schemaVersion !== 1 || !Number.isSafeInteger(metadata.revision) || metadata.revision < 0 || Number.isNaN(Date.parse(metadata.updatedAt))) {
+      throw new Error(`SEMANTIC_SYNC_METADATA_INVALID: ${key}`);
+    }
+    if (!['local', 'imported', 'synced', 'migration'].includes(metadata.origin)) {
+      throw new Error(`SEMANTIC_SYNC_METADATA_ORIGIN_INVALID: ${key}`);
+    }
+    if (record.condition.expectedRevision !== null && (!Number.isSafeInteger(record.condition.expectedRevision) || record.condition.expectedRevision < 0)) {
+      throw new Error(`SEMANTIC_SYNC_EXPECTED_REVISION_INVALID: ${key}`);
+    }
+    if (!/^[a-f0-9]{64}$/i.test(record.fingerprint)) throw new Error(`SEMANTIC_SYNC_FINGERPRINT_INVALID: ${key}`);
+  }
+}

package/packages/kernel/identity/domain/types.ts

@@ -0,0 +1,44 @@
+/** Stable semantic identity for one installed Forge authority. */
+export interface ForgeInstanceIdentity {
+  schemaVersion: 1;
+  instanceId: string;
+  createdAt: string;
+  label?: string;
+}
+
+export type PrincipalKind = 'user' | 'oauth_client' | 'bearer_client' | 'controller' | 'system' | 'service';
+
+export interface Principal {
+  principalId: string;
+  kind: PrincipalKind;
+  issuer?: string;
+}
+
+/** Reference to credentials owned by an adapter/secret store. Never raw secret material. */
+export interface CredentialReference {
+  reference: string;
+  kind: 'env' | 'file' | 'store' | 'keychain' | 'secret_ref';
+  provider?: string;
+}
+
+export interface CapabilityGrant {
+  grantId: string;
+  principalId: string;
+  capabilities: string[];
+  issuedAt: string;
+  expiresAt?: string;
+}
+
+/**
+ * Semantic adapter connection identity. Endpoint/tunnel/process/session metadata
+ * is intentionally absent so transport rotation cannot mint a Forge identity.
+ */
+export interface ConnectionIdentity {
+  schemaVersion: 1;
+  connectionId: string;
+  forgeInstanceId: string;
+  adapterId: string;
+  principalId: string;
+  credentialReference?: CredentialReference;
+  createdAt: string;
+}

package/packages/kernel/identity/domain/workspace.ts

@@ -0,0 +1,56 @@
+/** Portable Workspace/Project identity. Repository registration is node-local placement, never semantic identity. */
+export interface WorkspaceIdentity {
+  schemaVersion: 1;
+  workspaceId: string;
+  title: string;
+}
+
+export interface ProjectIdentity {
+  schemaVersion: 1;
+  projectId: string;
+  workspaceId: string;
+  displayName: string;
+  /** Stable digest of a portable source identity (for example a normalized Git remote), never a local path. */
+  sourceFingerprint?: string;
+}
+
+/** Node-local mapping from one portable Project to the repository/checkout used by this ForgeInstance. Never sync this record. */
+export interface ProjectPlacement {
+  schemaVersion: 1;
+  projectId: string;
+  forgeInstanceId: string;
+  repositoryId: string;
+  checkoutId?: string;
+}
+
+function boundedId(value: string, code: string): string {
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 512) throw new Error(code);
+  return normalized;
+}
+
+export function workspaceIdentity(input: Omit<WorkspaceIdentity, 'schemaVersion'>): WorkspaceIdentity {
+  const workspaceId = boundedId(input.workspaceId, 'WORKSPACE_ID_INVALID');
+  const title = input.title.trim();
+  if (!title || title.length > 512) throw new Error('WORKSPACE_TITLE_INVALID');
+  return { schemaVersion: 1, workspaceId, title };
+}
+
+export function projectIdentity(input: Omit<ProjectIdentity, 'schemaVersion'>): ProjectIdentity {
+  const projectId = boundedId(input.projectId, 'PROJECT_ID_INVALID');
+  const workspaceId = boundedId(input.workspaceId, 'WORKSPACE_ID_INVALID');
+  const displayName = input.displayName.trim();
+  if (!displayName || displayName.length > 512) throw new Error('PROJECT_DISPLAY_NAME_INVALID');
+  const sourceFingerprint = input.sourceFingerprint?.trim();
+  if (sourceFingerprint && !/^[a-f0-9]{64}$/i.test(sourceFingerprint)) throw new Error('PROJECT_SOURCE_FINGERPRINT_INVALID');
+  return { schemaVersion: 1, projectId, workspaceId, displayName, ...(sourceFingerprint ? { sourceFingerprint: sourceFingerprint.toLowerCase() } : {}) };
+}
+
+export function projectPlacement(input: Omit<ProjectPlacement, 'schemaVersion'>): ProjectPlacement {
+  const projectId = boundedId(input.projectId, 'PROJECT_ID_INVALID');
+  const forgeInstanceId = boundedId(input.forgeInstanceId, 'FORGE_INSTANCE_ID_INVALID');
+  const repositoryId = boundedId(input.repositoryId, 'PROJECT_REPOSITORY_ID_INVALID');
+  const checkoutId = input.checkoutId?.trim();
+  if (checkoutId && checkoutId.length > 512) throw new Error('PROJECT_CHECKOUT_ID_INVALID');
+  return { schemaVersion: 1, projectId, forgeInstanceId, repositoryId, ...(checkoutId ? { checkoutId } : {}) };
+}

package/packages/kernel/identity/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

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

@@ -0,0 +1,75 @@
+import { randomUUID } from 'crypto';
+import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { ForgeInstanceIdentity } from '../domain/types';
+
+export interface ForgeIdentityStoreOptions {
+  controllerHome: string;
+  now?: () => string;
+  preferredInstanceId?: string;
+  label?: string;
+}
+
+function normalizedInstanceId(value: string | undefined): string | undefined {
+  const id = value?.trim();
+  if (!id) return undefined;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{2,191}$/.test(id)) throw new Error('FORGE_INSTANCE_ID_INVALID');
+  return id;
+}
+
+export function forgeInstanceIdentityPath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'identity', 'forge-instance.json');
+}
+
+export function readForgeInstanceIdentity(controllerHome: string): ForgeInstanceIdentity | undefined {
+  const path = forgeInstanceIdentityPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as ForgeInstanceIdentity;
+    if (value.schemaVersion !== 1 || !normalizedInstanceId(value.instanceId) || typeof value.createdAt !== 'string') return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+export function ensureForgeInstanceIdentity(options: ForgeIdentityStoreOptions): ForgeInstanceIdentity {
+  const existing = readForgeInstanceIdentity(options.controllerHome);
+  const preferred = normalizedInstanceId(options.preferredInstanceId);
+  if (existing) {
+    if (preferred && existing.instanceId !== preferred) {
+      throw new Error(`FORGE_INSTANCE_ID_MISMATCH: existing=${existing.instanceId} requested=${preferred}`);
+    }
+    return existing;
+  }
+  const path = forgeInstanceIdentityPath(options.controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const identity: ForgeInstanceIdentity = {
+    schemaVersion: 1,
+    instanceId: preferred ?? `forge_${randomUUID().replaceAll('-', '')}`,
+    createdAt: (options.now ?? (() => new Date().toISOString()))(),
+    ...(options.label?.trim() ? { label: options.label.trim().slice(0, 160) } : {}),
+  };
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    writeFileSync(fd, `${JSON.stringify(identity, null, 2)}\n`, 'utf8');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    // link() is atomic and refuses to replace an existing semantic identity.
+    linkSync(temporary, path);
+    unlinkSync(temporary);
+    return identity;
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* best effort */ }
+    const raced = readForgeInstanceIdentity(options.controllerHome);
+    if (raced) {
+      if (preferred && raced.instanceId !== preferred) throw new Error(`FORGE_INSTANCE_ID_MISMATCH: existing=${raced.instanceId} requested=${preferred}`);
+      return raced;
+    }
+    throw error;
+  }
+}

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)] };
+}