@moretea-labs/forge 1.8.0 → 1.8.1

package/src/cli/repository/session-cache.ts

@@ -11,12 +11,31 @@ export interface SessionCacheMetrics {
   invalidations: number;
 }
 
+export interface SessionCacheEntryCounts {
+  ranges: number;
+  searches: number;
+  structural: number;
+  gitSnapshots: number;
+  checks: number;
+  total: number;
+}
+
+export interface SessionCacheEntryLimits {
+  ranges: number;
+  searches: number;
+  structural: number;
+  gitSnapshots: number;
+  checks: number;
+}
+
 export interface SessionCacheGlobalDiagnostics {
   activeEntries: number;
   maxEntries: number;
   ttlMs: number;
   evictions: number;
   sessionIds: string[];
+  derivedEntries: SessionCacheEntryCounts;
+  derivedEntryLimitsPerSession: SessionCacheEntryLimits;
 }
 
 export interface SessionIdentity {
@@ -99,6 +118,32 @@ function rangeKey(path: string, start: number, end: number): string {
   return `${path}:${start}-${end}`;
 }
 
+// One Context Plane request materializes at most ~30 files and one aggregate
+// lexical/structural result. Keep several progressive waves hot without letting
+// one long-lived MCP session retain an unbounded history of derived object graphs.
+const SESSION_CACHE_ENTRY_LIMITS: SessionCacheEntryLimits = {
+  ranges: 96,
+  searches: 48,
+  structural: 24,
+  gitSnapshots: 4,
+  checks: 32,
+};
+
+function putBoundedLru<K, V>(map: Map<K, V>, key: K, value: V, maxEntries: number): void {
+  if (map.has(key)) map.delete(key);
+  map.set(key, value);
+  while (map.size > maxEntries) {
+    const oldest = map.keys().next().value as K | undefined;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+function promoteLruHit<K, V>(map: Map<K, V>, key: K, value: V): void {
+  map.delete(key);
+  map.set(key, value);
+}
+
 export class RepositorySessionCache {
   private identity: SessionIdentity;
   private readonly repoRoot: string;
@@ -146,6 +191,22 @@ export class RepositorySessionCache {
     };
   }
 
+  entryCounts(): SessionCacheEntryCounts {
+    const ranges = this.ranges.size;
+    const searches = this.searches.size;
+    const structural = this.structural.size;
+    const gitSnapshots = this.gitSnapshots.size;
+    const checks = this.checks.size;
+    return {
+      ranges,
+      searches,
+      structural,
+      gitSnapshots,
+      checks,
+      total: ranges + searches + structural + gitSnapshots + checks,
+    };
+  }
+
   currentIdentity(): SessionIdentity {
     return { ...this.identity };
   }
@@ -205,18 +266,20 @@ export class RepositorySessionCache {
     const key = rangeKey(relativePath, startLine, endLine);
     const exact = this.ranges.get(key);
     if (exact && exact.fileSha === sha) {
+      promoteLruHit(this.ranges, key, exact);
       this.metrics.cacheHit += 1;
       this.metrics.bytesAvoided += exact.bytes;
       return exact;
     }
     // Try covering supersets: same path/sha with wider range.
-    for (const entry of this.ranges.values()) {
+    for (const [coveringKey, entry] of this.ranges) {
       if (
         entry.path === relativePath
         && entry.fileSha === sha
         && entry.startLine <= startLine
         && (entry.endLine >= endLine || entry.endLine >= entry.totalLines)
       ) {
+        promoteLruHit(this.ranges, coveringKey, entry);
         this.metrics.cacheHit += 1;
         this.metrics.bytesAvoided += Math.max(0, entry.bytes);
         const resolvedEndLine = Math.min(endLine, entry.totalLines);
@@ -233,13 +296,14 @@ export class RepositorySessionCache {
   }
 
   putRange(entry: FileRangeCacheEntry): void {
-    this.ranges.set(rangeKey(entry.path, entry.startLine, entry.endLine), entry);
+    putBoundedLru(this.ranges, rangeKey(entry.path, entry.startLine, entry.endLine), entry, SESSION_CACHE_ENTRY_LIMITS.ranges);
   }
 
   getSearch(query: string, includeKey: string): SearchCacheEntry | null {
     const key = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${includeKey}|${query}`;
     const hit = this.searches.get(key);
     if (hit) {
+      promoteLruHit(this.searches, key, hit);
       this.metrics.cacheHit += 1;
       this.metrics.scanAvoided += 1;
       return hit;
@@ -250,13 +314,14 @@ export class RepositorySessionCache {
 
   putSearch(entry: SearchCacheEntry): void {
     const key = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${entry.includeKey}|${entry.query}`;
-    this.searches.set(key, entry);
+    putBoundedLru(this.searches, key, entry, SESSION_CACHE_ENTRY_LIMITS.searches);
   }
 
   getStructural(key: string, ttlMs = 30_000): unknown | null {
     const scopedKey = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${key}`;
     const hit = this.structural.get(scopedKey);
     if (hit && Date.now() - hit.at <= ttlMs) {
+      promoteLruHit(this.structural, scopedKey, hit);
       this.metrics.cacheHit += 1;
       this.metrics.scanAvoided += 1;
       return hit.value;
@@ -277,13 +342,14 @@ export class RepositorySessionCache {
 
   putStructural(key: string, value: unknown): void {
     const scopedKey = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${key}`;
-    this.structural.set(scopedKey, { at: Date.now(), value });
+    putBoundedLru(this.structural, scopedKey, { at: Date.now(), value }, SESSION_CACHE_ENTRY_LIMITS.structural);
   }
 
   getGitSnapshot(): unknown | null {
     const key = `${this.identity.head}|${this.identity.workingTreeFingerprint}`;
     const hit = this.gitSnapshots.get(key);
     if (hit) {
+      promoteLruHit(this.gitSnapshots, key, hit);
       this.metrics.cacheHit += 1;
       return hit.value;
     }
@@ -293,13 +359,14 @@ export class RepositorySessionCache {
 
   putGitSnapshot(value: unknown): void {
     const key = `${this.identity.head}|${this.identity.workingTreeFingerprint}`;
-    this.gitSnapshots.set(key, { at: Date.now(), value });
+    putBoundedLru(this.gitSnapshots, key, { at: Date.now(), value }, SESSION_CACHE_ENTRY_LIMITS.gitSnapshots);
   }
 
   getCheck(checkId: string): unknown | null {
     const key = `${this.identity.workingTreeFingerprint}|${checkId}`;
     const hit = this.checks.get(key);
     if (hit !== undefined) {
+      promoteLruHit(this.checks, key, hit);
       this.metrics.cacheHit += 1;
       return hit;
     }
@@ -308,7 +375,7 @@ export class RepositorySessionCache {
   }
 
   putCheck(checkId: string, value: unknown): void {
-    this.checks.set(`${this.identity.workingTreeFingerprint}|${checkId}`, value);
+    putBoundedLru(this.checks, `${this.identity.workingTreeFingerprint}|${checkId}`, value, SESSION_CACHE_ENTRY_LIMITS.checks);
   }
 
   /** Precise invalidation when one file changes. */
@@ -460,12 +527,31 @@ export function clearSessionCachesForSession(sessionId: string): number {
 
 export function sessionCacheGlobalDiagnostics(): SessionCacheGlobalDiagnostics {
   pruneSessionCaches();
+  const derivedEntries: SessionCacheEntryCounts = {
+    ranges: 0,
+    searches: 0,
+    structural: 0,
+    gitSnapshots: 0,
+    checks: 0,
+    total: 0,
+  };
+  for (const cache of globalSessions.values()) {
+    const counts = cache.entryCounts();
+    derivedEntries.ranges += counts.ranges;
+    derivedEntries.searches += counts.searches;
+    derivedEntries.structural += counts.structural;
+    derivedEntries.gitSnapshots += counts.gitSnapshots;
+    derivedEntries.checks += counts.checks;
+    derivedEntries.total += counts.total;
+  }
   return {
     activeEntries: globalSessions.size,
     maxEntries: SESSION_CACHE_MAX_ENTRIES,
     ttlMs: SESSION_CACHE_TTL_MS,
     evictions: sessionCacheEvictions,
     sessionIds: [...new Set([...globalSessions.keys()].map((key) => key.split('|', 1)[0]))],
+    derivedEntries,
+    derivedEntryLimitsPerSession: { ...SESSION_CACHE_ENTRY_LIMITS },
   };
 }
 

package/src/runtime/context/assistant-context.ts

@@ -4,6 +4,7 @@ import { relative, resolve, sep } from 'path';
 import { performance } from 'perf_hooks';
 import type { ProjectKnowledgeSource } from '../../../packages/kernel/work/api/index';
 import { matchesExperienceApplicability, type ExperienceApplicability, type ExperienceRecord } from '../../../packages/kernel/memory/api/index';
+import { memoryAddressKey, memoryAddressLabel, type ActivationPack } from '../../../packages/kernel/cognition/api/index';
 import { assertControlPlaneMetadataPayload } from '../control-plane/persistence/metadata-payload-policy';
 import { DEFAULT_CONTEXT_MAX_BYTES, DEFAULT_CONTEXT_MAX_ITEMS, DEFAULT_CONTEXT_MAX_TOKENS, MAX_CONTEXT_MAX_BYTES, MAX_CONTEXT_MAX_ITEMS, MAX_CONTEXT_MAX_TOKENS } from './context-plane';
 
@@ -16,9 +17,10 @@ export interface AssistantContextItem {
   kind: 'knowledge' | 'experience'; id: string; text: string; rank: number;
   sourceCoverage?: Array<{ sourceId: string; uri: string; digest: string; sourceRevision: string; modifiedAt: string }>;
   provenance: { uri: string; digest?: string; revision?: number; sourceRevision?: string; modifiedAt: string; startLine?: number; endLine?: number; evidenceRefs?: string[] };
+  activation?: { score: number; reasons: string[]; path: string[]; facets: string[]; concepts: string[] };
 }
 export interface AssistantContextResolution {
-  schemaVersion: 1; projectId: string; items: AssistantContextItem[];
+  schemaVersion: 1; projectId?: string; items: AssistantContextItem[];
   gaps: string[]; missingRequiredSources: string[]; truncated: boolean; bytes: number; estimatedTokens: number;
 }
 
@@ -76,11 +78,12 @@ function budget(value: number | undefined, fallback: number, max: number): numbe
 }
 
 export function resolveAssistantContext(input: {
-  projectId: string; query: string; sources: readonly ProjectKnowledgeSource[]; knowledge: KnowledgeSourcePort;
-  experiences?: readonly ExperienceRecord[]; applicability?: ExperienceApplicability; now?: string;
+  projectId?: string; query: string; sources: readonly ProjectKnowledgeSource[]; knowledge: KnowledgeSourcePort;
+  experiences?: readonly ExperienceRecord[]; activation?: ActivationPack; applicability?: ExperienceApplicability; now?: string;
   maxItems?: number; maxBytes?: number; maxTokens?: number; maxReadBytes?: number; maxReadMs?: number; gaps?: readonly string[];
 }): AssistantContextResolution {
-  if (!input.projectId.trim()) throw new Error('ASSISTANT_CONTEXT_PROJECT_REQUIRED');
+  const projectId = input.projectId?.trim() || undefined;
+  if (input.sources.length > 0 && !projectId) throw new Error('ASSISTANT_CONTEXT_PROJECT_REQUIRED_FOR_KNOWLEDGE');
   const now = Date.parse(input.now ?? new Date().toISOString());
   if (!Number.isFinite(now)) throw new Error('ASSISTANT_CONTEXT_TIME_INVALID');
   const maxItems = budget(input.maxItems, DEFAULT_CONTEXT_MAX_ITEMS, MAX_CONTEXT_MAX_ITEMS);
@@ -120,13 +123,23 @@ export function resolveAssistantContext(input: {
       if (source.required) missing.add(source.id);
     }
   }
+  const activatedAddresses = new Set<string>();
+  for (const activated of input.activation?.items ?? []) {
+    const memory = activated.memory;
+    const address = { scope: memory.scope, id: memory.id };
+    const kind: AssistantContextItem['kind'] = ['experience', 'outcome'].includes(memory.provenance.sourceKind) ? 'experience' : 'knowledge';
+    candidates.push({ kind, id: memoryAddressKey(address), text: `[memory:${memory.facets.join(',')}] ${memory.canonicalText}${memory.counterEvidenceRefs.length ? '\nCounterevidence: ' + memory.counterEvidenceRefs.join(', ') : ''}`, rank: Math.round(activated.score * 1000), activation: { score: activated.score, reasons: activated.reasons.map(reason => `${reason.signal}:${reason.detail}`), path: activated.activationPath, facets: memory.facets, concepts: memory.concepts }, provenance: { uri: memoryAddressLabel(address), revision: memory.revision, modifiedAt: memory.provenance.recordedAt, evidenceRefs: memory.provenance.evidenceRefs } });
+    activatedAddresses.add(memoryAddressKey(address));
+  }
+  if (input.activation) gaps.push(...input.activation.gaps.map(gap => `cognition:${gap}`));
   for (const record of (input.experiences ?? []).slice(0, 32)) {
+    if (activatedAddresses.has(memoryAddressKey({ scope: record.scope, id: record.id }))) continue;
     if (record.retractedAt || record.expiresAt && Date.parse(record.expiresAt) <= now || !matchesExperienceApplicability(record.applicability, input.applicability ?? {})) continue;
     // The caller supplies lineage-filtered records; explicit foreign projects are never admitted.
-    if (record.scope.kind === 'project' && record.scope.id !== input.projectId) continue;
+    if (record.scope.kind === 'project' && (!projectId || record.scope.id !== projectId)) continue;
     const relevance = score(record.statement, terms);
     if (!relevance) continue;
-    candidates.push({ kind: 'experience', id: record.id, text: `[${record.kind}] ${record.statement}${record.counterEvidenceRefs.length ? '\nCounterevidence: ' + record.counterEvidenceRefs.join(', ') : ''}`, rank: relevance * 100,
+    candidates.push({ kind: 'experience', id: memoryAddressKey({ scope: record.scope, id: record.id }), text: `[${record.kind}] ${record.statement}${record.counterEvidenceRefs.length ? '\nCounterevidence: ' + record.counterEvidenceRefs.join(', ') : ''}`, rank: relevance * 100,
       provenance: { uri: `experience:${record.scope.kind}:${record.scope.id}:${record.id}`, revision: record.revision, modifiedAt: record.recordedAt, evidenceRefs: record.evidenceRefs } });
   }
   candidates.sort((a, b) => b.rank - a.rank || b.provenance.modifiedAt.localeCompare(a.provenance.modifiedAt) || a.id.localeCompare(b.id));
@@ -145,7 +158,7 @@ export function resolveAssistantContext(input: {
     }
     items.push(item); bytes += size; estimatedTokens += tokens;
   }
-  return { schemaVersion: 1, projectId: input.projectId, items, gaps: [...new Set(gaps)], missingRequiredSources: [...missing], truncated: gaps.some(g => /budget|limit/.test(g)), bytes, estimatedTokens };
+  return { schemaVersion: 1, ...(projectId ? { projectId } : {}), items, gaps: [...new Set(gaps)], missingRequiredSources: [...missing], truncated: gaps.some(g => /budget|limit/.test(g)), bytes, estimatedTokens };
 }
 
 export function renderAssistantContext(context: AssistantContextResolution): string {

package/src/runtime/context/assistant-work-context.ts

@@ -1,14 +1,18 @@
 import { getRepository } from '../../cli/repositories/registry';
 import { configuredBrainRoot } from '../../cli/commands/brain-root';
-import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { getWorkContract, semanticWorkState } from '../../../packages/kernel/work/api/index';
 import type { ScopeRef } from '../../../packages/kernel/identity/api/index';
-import { getControllerRoundRelay, getControllerSession } from '../../../packages/kernel/controller/api/index';
+import { getControllerRoundRelay } from '../../../packages/kernel/controller/api/index';
 import { recordExperience, recordOutcomeObservation, queryExperiences, type ExperienceApplicability, type ExperienceDraft, type ExperienceRecord, type OutcomeObservation } from '../../../packages/kernel/memory/api/index';
-import { controllerExperienceStore, controllerOutcomeObservationStore, experienceScopesForWork, type ExperienceWriteIdentity } from '../control-plane/persistence/experience-store';
+import { memoryUnitFromExperience, recordCognitiveMemory, recordCognitiveMemoryEdge, type CognitiveWriteAuthorityPort, type MemoryEdgeDraft, type MemoryProvenance, type MemoryUnit, type MemoryUnitDraft } from '../../../packages/kernel/cognition/api/index';
+import { assertMemoryWriteAuthority, canonicalWorkflowEvidenceAvailable, cognitiveScopesForWork, controllerExperienceStore, controllerOutcomeObservationStore, experienceScopesForWork, type ExperienceWriteIdentity } from '../control-plane/persistence/experience-store';
+import { cognitionMemoryStore } from '../control-plane/persistence/cognition-store';
 import { listControlPlaneRecords } from '../control-plane/persistence/sqlite-store';
 import { WORKFLOW_RUN_NAMESPACE, type WorkflowRunRecord } from '../control-plane/persistence/workflow-run-store';
 import { loadProjectEngineeringContract } from './project-engineering-contract';
 import { fileKnowledgeSourcePort, renderAssistantContext, resolveAssistantContext, type AssistantContextResolution } from './assistant-context';
+import { applyCognitiveSkillCanary } from './cognitive-skill-canary';
+import { cognitiveUsageFeedbackForContext, resolveCognitiveAttention } from './cognitive-attention';
 
 function cleanApplicability(value: ExperienceApplicability | undefined): ExperienceApplicability | undefined {
   if (!value) return undefined;
@@ -60,26 +64,46 @@ export function prepareAssistantWorkContext(input: {
   const repository = getRepository(input.repoId, input.controllerHome);
   const repoRoot = repository.checkouts.find(checkout => checkout.checkoutId === work.checkoutId)?.canonicalRoot ?? repository.canonicalRoot;
   // Semantic Project identity comes from Work lineage/portable placement. The engineering contract is an optional knowledge-source contract, not identity authority.
-  const scopes = experienceScopesForWork(work, input.controllerHome);
-  const boundProject = scopes.find(scope => scope.kind === 'project')?.id;
-  // Project knowledge is advisory enrichment. A Work that has not yet been
-  // bound to a Project must still be able to claim and continue its durable
-  // ControllerRound; missing optional context is not a lifecycle blocker.
-  if (!boundProject) return undefined;
-  const loaded = loadProjectEngineeringContract({ repoRoot, sourceRevision: 'working-tree', now: () => input.now ?? new Date().toISOString() });
-  if (loaded.status === 'ready' && boundProject !== loaded.contract.projectId) throw new Error('ASSISTANT_CONTEXT_PROJECT_BINDING_MISMATCH');
+  const experienceScopes = experienceScopesForWork(work, input.controllerHome);
+  const cognitiveScopes = cognitiveScopesForWork(work, input.controllerHome);
+  const boundProject = experienceScopes.find(scope => scope.kind === 'project')?.id;
+  // Project knowledge is optional enrichment. Generic cognition authority is
+  // scoped by Work lineage and must remain available even when no Project is bound.
+  const loaded = boundProject
+    ? loadProjectEngineeringContract({ repoRoot, sourceRevision: 'working-tree', now: () => input.now ?? new Date().toISOString() })
+    : undefined;
+  if (loaded?.status === 'ready' && boundProject !== loaded.contract.projectId) throw new Error('ASSISTANT_CONTEXT_PROJECT_BINDING_MISMATCH');
   const now = input.now ?? new Date().toISOString();
-  const sources = loaded.status === 'ready' ? loaded.contract.knowledgeSources ?? [] : [];
+  const sources = loaded?.status === 'ready' ? loaded.contract.knowledgeSources ?? [] : [];
   const applicability = effectiveApplicability({
     explicit: input.applicability,
     declared: sources.map(source => source.applicability),
     published: publicationApplicability(input.controllerHome, work.workId),
   });
-  const experiences = queryExperiences(controllerExperienceStore({ controllerHome: input.controllerHome, repoId: input.repoId, ...(input.now ? { now: () => input.now! } : {}) }), { scopes, applicability: applicability.value, now });
-  return resolveAssistantContext({ projectId: boundProject, query: input.query ?? work.objective,
+  const experiences = queryExperiences(controllerExperienceStore({ controllerHome: input.controllerHome, repoId: input.repoId, ...(input.now ? { now: () => input.now! } : {}) }), { scopes: experienceScopes, applicability: applicability.value, now });
+  const query = input.query ?? work.objective;
+  const usageFeedback = cognitiveUsageFeedbackForContext({
+    controllerHome: input.controllerHome,
+    repoId: input.repoId,
+    scopes: cognitiveScopes,
+    ...(boundProject ? { projectId: boundProject } : {}),
+  });
+  const transientMemories = experiences.records.map(memoryUnitFromExperience);
+  const activation = resolveCognitiveAttention({
+    controllerHome: input.controllerHome,
+    scopes: cognitiveScopes,
+    query,
+    now,
+    maxItems: 6,
+    maxBytes: 12 * 1024,
+    transientMemories,
+    usageFeedback,
+  });
+  const context = resolveAssistantContext({ ...(boundProject ? { projectId: boundProject } : {}), query,
     sources,
     knowledge: fileKnowledgeSourcePort({ repoRoot, brainRoot: configuredBrainRoot(), sourceRevision: 'working-tree' }),
-    experiences: experiences.records, gaps: [...experiences.gaps, ...(applicability.conflict ? ['assistant_context_applicability_conflict'] : [])], applicability: applicability.value, now });
+    experiences: experiences.records, activation, gaps: [...experiences.gaps, ...(applicability.conflict ? ['assistant_context_applicability_conflict'] : [])], applicability: applicability.value, now });
+  return applyCognitiveSkillCanary(context);
 }
 
 export function renderAssistantWorkContext(input: Parameters<typeof prepareAssistantWorkContext>[0]): string | undefined {
@@ -94,25 +118,63 @@ export function renderAssistantWorkContext(input: Parameters<typeof prepareAssis
 
 export type ControllerOutcomeObservationDraft = Omit<OutcomeObservation, 'schemaVersion' | 'sourceWorkId' | 'sourceRoundId'>;
 export type ControllerExperienceDraft = Omit<ExperienceDraft, 'sourceWorkId' | 'sourceRoundId'>;
+export type ControllerMemoryDraft = Omit<MemoryUnitDraft, 'provenance' | 'validFrom'> & {
+  provenance: Omit<MemoryProvenance, 'sourceWorkId' | 'sourceRoundId' | 'recordedAt'>;
+  validFrom?: string;
+};
+export type ControllerMemoryEdgeDraft = Omit<MemoryEdgeDraft, 'sourceWorkId' | 'sourceRoundId' | 'recordedAt'> & { recordedAt?: string };
 
 function learningStoreOptions(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; now?: string }) {
   return { controllerHome: input.controllerHome, repoId: input.repoId, identity: input.identity, ...(input.now ? { now: () => input.now! } : {}) };
 }
 
-function currentLearningRound(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; now?: string }): { sourceWorkId: string; sourceRoundId: string } {
-  const store = learningStoreOptions(input);
-  const relay = getControllerRoundRelay(store, input.identity.workId);
-  if (relay) {
-    if (relay.status !== 'claimed' || relay.authorityId !== input.identity.authorityId) throw new Error('LEARNING_LOOP_CONTROLLER_ROUND_AUTHORITY_MISMATCH');
-    return { sourceWorkId: input.identity.workId, sourceRoundId: `${relay.relayScopeId}:${relay.roundCount}` };
-  }
-  const owner = getControllerSession(store, input.identity.workId);
-  if (!owner || owner.controllerId !== input.identity.controllerId || !owner.claimGeneration) throw new Error('LEARNING_LOOP_CONTROLLER_CLAIM_REQUIRED');
-  return { sourceWorkId: input.identity.workId, sourceRoundId: `${input.identity.workId}:${owner.claimGeneration}` };
+function currentLearningProvenance(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; now?: string }): { sourceWorkId: string; sourceRoundId: string } {
+  const work = getWorkContract({ controllerHome: input.controllerHome, repoId: input.repoId }, input.identity.workId);
+  if (!work || semanticWorkState(work) !== 'open') throw new Error('LEARNING_LOOP_WORK_NOT_ACTIVE');
+  const revision = Number(work.semanticRevision);
+  return {
+    sourceWorkId: work.workId,
+    // sourceRoundId is retained as a storage compatibility field. It now records
+    // Work semantic provenance rather than granting ControllerRound authority.
+    sourceRoundId: `work:${work.workId}:r${Number.isSafeInteger(revision) && revision > 0 ? revision : 'legacy'}`,
+  };
+}
+
+function controllerCognitionAuthority(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; now?: string }): CognitiveWriteAuthorityPort {
+  const options = learningStoreOptions(input);
+  const requireLineage = (sourceWorkId: string | undefined, sourceRoundId: string | undefined, scope: ScopeRef) => {
+    if (!sourceWorkId || !sourceRoundId) throw new Error('COGNITION_CONTROLLER_LINEAGE_REQUIRED');
+    assertMemoryWriteAuthority(options, scope, sourceWorkId, sourceRoundId);
+  };
+  return {
+    assertMemoryWrite(memory) { requireLineage(memory.provenance.sourceWorkId, memory.provenance.sourceRoundId, memory.scope); },
+    assertEdgeWrite(edge) { requireLineage(edge.sourceWorkId, edge.sourceRoundId, edge.scope); },
+    evidenceAvailable(ref, scope, sourceWorkId) { return Boolean(sourceWorkId && canonicalWorkflowEvidenceAvailable(options, ref, scope, sourceWorkId)); },
+  };
+}
+
+export function recordControllerMemory(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; draft: ControllerMemoryDraft; now?: string }): MemoryUnit {
+  const lineage = currentLearningProvenance(input);
+  const recordedAt = input.now ?? new Date().toISOString();
+  return recordCognitiveMemory(cognitionMemoryStore(input.controllerHome), controllerCognitionAuthority(input), {
+    ...input.draft,
+    provenance: { ...input.draft.provenance, sourceWorkId: lineage.sourceWorkId, sourceRoundId: lineage.sourceRoundId, recordedAt },
+    validFrom: input.draft.validFrom ?? recordedAt,
+  });
+}
+
+export function recordControllerMemoryEdge(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; draft: ControllerMemoryEdgeDraft; now?: string }) {
+  const lineage = currentLearningProvenance(input);
+  return recordCognitiveMemoryEdge(cognitionMemoryStore(input.controllerHome), controllerCognitionAuthority(input), {
+    ...input.draft,
+    sourceWorkId: lineage.sourceWorkId,
+    sourceRoundId: lineage.sourceRoundId,
+    recordedAt: input.draft.recordedAt ?? input.now ?? new Date().toISOString(),
+  });
 }
 
 export function recordControllerOutcome(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; draft: ControllerOutcomeObservationDraft; now?: string }): OutcomeObservation {
-  const lineage = currentLearningRound(input);
+  const lineage = currentLearningProvenance(input);
   return recordOutcomeObservation(controllerOutcomeObservationStore(learningStoreOptions(input)), {
     ...input.draft, schemaVersion: 1, sourceWorkId: lineage.sourceWorkId, sourceRoundId: lineage.sourceRoundId,
   }, input.now);
@@ -131,7 +193,7 @@ function outcomeEvidenceWithObservedMetric(input: { controllerHome: string; repo
 }
 
 export function recordControllerExperience(input: { controllerHome: string; repoId: string; identity: ExperienceWriteIdentity; draft: ControllerExperienceDraft; qualityAdjustmentFingerprint?: string; now?: string }): ExperienceRecord {
-  const lineage = currentLearningRound(input);
+  const lineage = currentLearningProvenance(input);
   let evidenceRefs = [...input.draft.evidenceRefs];
   if (input.qualityAdjustmentFingerprint) {
     const relay = getControllerRoundRelay(learningStoreOptions(input), input.identity.workId);