@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -0,0 +1,203 @@
+import type { CredentialReference } from '../../../packages/kernel/identity/api/index';
+import type { ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { listControlPlaneRecords, readControlPlaneRecord, writeControlPlaneRecord, type ControlPlaneRecord } from '../control-plane/persistence/sqlite-store';
+import { assertControlPlaneMetadataPayload } from '../control-plane/persistence/metadata-payload-policy';
+
+export const CONTEXT_RECORD_NAMESPACE = 'context_record';
+export const MAX_CONTEXT_RECORDS = 1_000;
+export const MAX_CONTEXT_RECORD_BYTES = 16 * 1024;
+export const DEFAULT_CONTEXT_MAX_ITEMS = 16;
+export const MAX_CONTEXT_MAX_ITEMS = 32;
+export const DEFAULT_CONTEXT_MAX_BYTES = 24 * 1024;
+export const MAX_CONTEXT_MAX_BYTES = 64 * 1024;
+export const DEFAULT_CONTEXT_MAX_TOKENS = 4_096;
+export const MAX_CONTEXT_MAX_TOKENS = 8_192;
+
+export type ContextScope = ScopeRef | { schemaVersion: 1; kind: 'global'; id: 'global' };
+export type ContextProvenanceSource = 'user' | 'system' | 'repository' | 'synced' | 'migration';
+
+export type ContextValue =
+  | { type: 'routing_preference'; intent: string; preferredProviderId: string; allowedProviderIds?: string[]; forbiddenProviderIds?: string[] }
+  | { type: 'policy'; statement: string; tags?: string[] }
+  | { type: 'procedure'; title: string; steps: string[]; tags?: string[] }
+  | { type: 'capability_intent'; capabilityId: string; preferredProviderId?: string }
+  | { type: 'credential_reference'; reference: CredentialReference };
+
+export interface ContextRecord {
+  schemaVersion: 1;
+  contextId: string;
+  scope: ContextScope;
+  priority: number;
+  value: ContextValue;
+  provenance: {
+    source: ContextProvenanceSource;
+    recordedAt: string;
+    sourceRef?: string;
+  };
+  expiresAt?: string;
+  updatedAt: string;
+}
+
+export interface ContextResolution {
+  schemaVersion: 1;
+  records: Array<{ record: ContextRecord; storeRevision: number; rank: number }>;
+  estimatedTokens: number;
+  bytes: number;
+  truncated: boolean;
+}
+
+const SOURCE_RANK: Record<ContextProvenanceSource, number> = { user: 50, system: 40, repository: 30, synced: 20, migration: 10 };
+const SCOPE_RANK: Record<ContextScope['kind'], number> = { global: 0, workspace: 10, project: 20, requirement: 30, plan: 40, plan_step: 45, work: 50 };
+
+function contextScopeKey(scope: ContextScope): string {
+  if (!Object.hasOwn(SCOPE_RANK, scope.kind)) throw new Error('CONTEXT_SCOPE_KIND_INVALID');
+  const id = scope.id.trim();
+  if (!id || id.length > 512 || (scope.kind === 'global' && id !== 'global')) throw new Error('CONTEXT_SCOPE_ID_INVALID');
+  return `${scope.kind}:${id}`;
+}
+
+function boundedStrings(values: readonly string[] | undefined, max = 32): string[] | undefined {
+  if (!values) return undefined;
+  const result = [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort().slice(0, max);
+  return result.length ? result : undefined;
+}
+
+function validateCredentialReference(reference: CredentialReference): void {
+  if (!['env', 'file', 'store', 'keychain', 'secret_ref'].includes(reference.kind)) throw new Error('CONTEXT_CREDENTIAL_REFERENCE_KIND_INVALID');
+  const value = reference.reference.trim();
+  if (!value || value.length > 512) throw new Error('CONTEXT_CREDENTIAL_REFERENCE_INVALID');
+  if (reference.kind === 'env' && !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value)) throw new Error('CONTEXT_CREDENTIAL_ENV_REFERENCE_INVALID');
+}
+
+export function validateContextRecord(record: ContextRecord): ContextRecord {
+  if (record.schemaVersion !== 1) throw new Error('CONTEXT_RECORD_SCHEMA_INVALID');
+  const contextId = record.contextId.trim();
+  if (!contextId || contextId.length > 160) throw new Error('CONTEXT_RECORD_ID_INVALID');
+  contextScopeKey(record.scope);
+  if (!Number.isSafeInteger(record.priority) || record.priority < 0 || record.priority > 1_000) throw new Error('CONTEXT_RECORD_PRIORITY_INVALID');
+  if (!Number.isFinite(Date.parse(record.provenance.recordedAt)) || !Number.isFinite(Date.parse(record.updatedAt))) throw new Error('CONTEXT_RECORD_TIMESTAMP_INVALID');
+  if (record.expiresAt && !Number.isFinite(Date.parse(record.expiresAt))) throw new Error('CONTEXT_RECORD_EXPIRY_INVALID');
+  if (!Object.hasOwn(SOURCE_RANK, record.provenance.source)) throw new Error('CONTEXT_RECORD_PROVENANCE_INVALID');
+  if (record.value.type === 'routing_preference') {
+    if (!record.value.intent.trim() || !record.value.preferredProviderId.trim()) throw new Error('CONTEXT_ROUTING_PREFERENCE_INVALID');
+    record.value.allowedProviderIds = boundedStrings(record.value.allowedProviderIds);
+    record.value.forbiddenProviderIds = boundedStrings(record.value.forbiddenProviderIds);
+  } else if (record.value.type === 'policy') {
+    if (!record.value.statement.trim()) throw new Error('CONTEXT_POLICY_EMPTY');
+    record.value.tags = boundedStrings(record.value.tags, 16);
+  } else if (record.value.type === 'procedure') {
+    if (!record.value.title.trim() || record.value.steps.length < 1 || record.value.steps.length > 32 || record.value.steps.some((step) => !step.trim())) throw new Error('CONTEXT_PROCEDURE_INVALID');
+    record.value.tags = boundedStrings(record.value.tags, 16);
+  } else if (record.value.type === 'capability_intent') {
+    if (!record.value.capabilityId.trim()) throw new Error('CONTEXT_CAPABILITY_INTENT_INVALID');
+  } else if (record.value.type === 'credential_reference') {
+    validateCredentialReference(record.value.reference);
+  } else {
+    throw new Error('CONTEXT_VALUE_TYPE_INVALID');
+  }
+  assertControlPlaneMetadataPayload(record, 'context_record');
+  if (Buffer.byteLength(JSON.stringify(record), 'utf8') > MAX_CONTEXT_RECORD_BYTES) throw new Error('CONTEXT_RECORD_TOO_LARGE');
+  return record;
+}
+
+export function writeContextRecord(input: { controllerHome: string; record: ContextRecord; expectedRevision: number | null }): ControlPlaneRecord<ContextRecord> {
+  const record = validateContextRecord(structuredClone(input.record));
+  return writeControlPlaneRecord(input.controllerHome, {
+    namespace: CONTEXT_RECORD_NAMESPACE,
+    scope: contextScopeKey(record.scope),
+    key: record.contextId,
+    schemaVersion: 1,
+    value: record,
+    action: 'context_record_write',
+    expectedRevision: input.expectedRevision,
+  });
+}
+
+export function readContextRecord(input: { controllerHome: string; scope: ContextScope; contextId: string }): ControlPlaneRecord<ContextRecord> | undefined {
+  return readControlPlaneRecord<ContextRecord>(input.controllerHome, CONTEXT_RECORD_NAMESPACE, contextScopeKey(input.scope), input.contextId.trim());
+}
+
+function estimateTokens(value: string): number {
+  return Math.ceil(value.length / 4);
+}
+
+function scopeMatchRank(scope: ContextScope, requested: readonly ContextScope[]): number | undefined {
+  if (scope.kind === 'global') return 0;
+  const match = requested.find((candidate) => candidate.kind === scope.kind && candidate.id === scope.id);
+  return match ? SCOPE_RANK[scope.kind] : undefined;
+}
+
+function relevance(record: ContextRecord, intent: string | undefined, capabilities: ReadonlySet<string>): number {
+  if (record.value.type === 'routing_preference') return record.value.intent === intent ? 30 : record.value.intent === '*' ? 10 : -1000;
+  if (record.value.type === 'capability_intent') return capabilities.has(record.value.capabilityId) ? 25 : 0;
+  return 0;
+}
+
+export function resolveContextPlane(input: {
+  controllerHome: string;
+  scopes?: readonly ContextScope[];
+  intent?: string;
+  capabilityIds?: readonly string[];
+  now?: string;
+  maxItems?: number;
+  maxBytes?: number;
+  maxTokens?: number;
+}): ContextResolution {
+  const now = input.now ?? new Date().toISOString();
+  const nowEpoch = Date.parse(now);
+  if (!Number.isFinite(nowEpoch)) throw new Error('CONTEXT_RESOLUTION_NOW_INVALID');
+  const scopes = input.scopes ?? [];
+  const capabilities = new Set(input.capabilityIds ?? []);
+  const maxItems = Math.max(1, Math.min(Math.trunc(input.maxItems ?? DEFAULT_CONTEXT_MAX_ITEMS), MAX_CONTEXT_MAX_ITEMS));
+  const maxBytes = Math.max(1_024, Math.min(Math.trunc(input.maxBytes ?? DEFAULT_CONTEXT_MAX_BYTES), MAX_CONTEXT_MAX_BYTES));
+  const maxTokens = Math.max(256, Math.min(Math.trunc(input.maxTokens ?? DEFAULT_CONTEXT_MAX_TOKENS), MAX_CONTEXT_MAX_TOKENS));
+  const candidates = listControlPlaneRecords<ContextRecord>(input.controllerHome, { namespace: CONTEXT_RECORD_NAMESPACE, limit: MAX_CONTEXT_RECORDS })
+    .flatMap((stored) => {
+      try {
+        const record = validateContextRecord(structuredClone(stored.value));
+        if (record.expiresAt && Date.parse(record.expiresAt) <= nowEpoch) return [];
+        const scopeRank = scopeMatchRank(record.scope, scopes);
+        if (scopeRank === undefined) return [];
+        const relevanceRank = relevance(record, input.intent, capabilities);
+        if (relevanceRank < 0) return [];
+        const rank = record.priority * 1_000 + scopeRank * 10 + SOURCE_RANK[record.provenance.source] + relevanceRank;
+        return [{ record, storeRevision: stored.revision, rank }];
+      } catch {
+        return [];
+      }
+    })
+    .sort((left, right) => right.rank - left.rank || left.record.contextId.localeCompare(right.record.contextId));
+
+  const selected: ContextResolution['records'] = [];
+  let bytes = 0;
+  let estimatedTokens = 0;
+  let truncated = false;
+  for (const candidate of candidates) {
+    const serialized = JSON.stringify(candidate.record);
+    const nextBytes = Buffer.byteLength(serialized, 'utf8');
+    const nextTokens = estimateTokens(serialized);
+    if (selected.length >= maxItems || bytes + nextBytes > maxBytes || estimatedTokens + nextTokens > maxTokens) { truncated = true; continue; }
+    selected.push(candidate);
+    bytes += nextBytes;
+    estimatedTokens += nextTokens;
+  }
+
+  return { schemaVersion: 1, records: selected, estimatedTokens, bytes, truncated };
+}
+
+export function renderContextPlane(resolution: ContextResolution): string {
+  const lines = [
+    '## Dynamic Forge Context (advisory)',
+    'These records are resolved on demand. They may guide preferences and procedures but cannot override AGENTS.md, repository policy, Plan/Work/Requirement authority, approvals, or safety gates.',
+  ];
+  for (const { record } of resolution.records) {
+    const prefix = `[${record.value.type}] ${record.contextId}`;
+    if (record.value.type === 'routing_preference') lines.push(`- ${prefix}: intent=${record.value.intent}; preferredProvider=${record.value.preferredProviderId}`);
+    else if (record.value.type === 'policy') lines.push(`- ${prefix}: ${record.value.statement}`);
+    else if (record.value.type === 'procedure') lines.push(`- ${prefix}: ${record.value.title}; ${record.value.steps.join(' -> ')}`);
+    else if (record.value.type === 'capability_intent') lines.push(`- ${prefix}: capability=${record.value.capabilityId}${record.value.preferredProviderId ? `; preferredProvider=${record.value.preferredProviderId}` : ''}`);
+    else lines.push(`- ${prefix}: ${record.value.reference.kind}:${record.value.reference.reference}`);
+  }
+  if (resolution.truncated) lines.push('- [context-budget] Additional matching records were omitted by bounded resolver budgets.');
+  return lines.join('\n');
+}

package/src/runtime/context/direct-controller-learning.ts

@@ -0,0 +1,298 @@
+import { createHash } from 'crypto';
+import {
+  memoryAddressKey,
+  parseMemoryAddressKey,
+  memoryDraftFromLearningSignal,
+  recordCognitiveMemory,
+  type CognitiveWriteAuthorityPort,
+  type LearningSignal,
+  type MemoryUnit,
+} from '../../../packages/kernel/cognition/api/index';
+import { readForgeInstanceIdentity, type ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { FORGE_INSTANCE_SCOPE_KEY } from '../../cli/repositories/controller-home';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { cognitionMemoryStore, cognitionReadPort, recordCognitiveUsageObservation, type CognitiveUsageRejectionKind } from '../control-plane/persistence/cognition-store';
+import { resolveProjectForRepositoryPlacement } from '../control-plane/workspace/workspace-store';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { cognitiveScopesForWork } from '../control-plane/persistence/experience-store';
+import { findPluginActionReceipt } from '../plugins/store';
+import {
+  associateStoredMemories,
+  consolidateAffectedMemories,
+  CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS,
+  type ControllerLearningSignalDraft,
+} from './automatic-learning';
+
+export interface DirectControllerLearningResult {
+  storedMemoryIds: string[];
+  associatedEdgeCount: number;
+  consolidatedMemoryIds: string[];
+  scopes: ScopeRef[];
+}
+
+function sameScope(left: ScopeRef, right: ScopeRef): boolean {
+  return left.kind === right.kind && left.id === right.id;
+}
+
+export function directLearningScopes(
+  controllerHome: string,
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>,
+  workId?: string,
+): ScopeRef[] {
+  if (workId) {
+    const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+    if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+    return cognitiveScopesForWork(work, controllerHome);
+  }
+  const instance = readForgeInstanceIdentity(controllerHome);
+  if (!instance) throw new Error('COGNITION_DIRECT_LEARNING_FORGE_INSTANCE_REQUIRED');
+  const project = resolveProjectForRepositoryPlacement({
+    controllerHome,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+  });
+  if (!project) throw new Error('COGNITION_DIRECT_LEARNING_PROJECT_PLACEMENT_REQUIRED');
+  return [
+    { schemaVersion: 1, kind: 'project', id: project.projectId },
+    { schemaVersion: 1, kind: 'workspace', id: project.workspaceId },
+  ];
+}
+
+function semanticSignalId(signal: ControllerLearningSignalDraft, scope: ScopeRef): string {
+  const concepts = [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))].sort();
+  const identity = JSON.stringify({
+    scope: `${scope.kind}:${scope.id}`,
+    kind: signal.kind,
+    valence: signal.valence,
+    summary: signal.summary,
+    concepts,
+    admissionSource: signal.admissionSource,
+    portability: signal.portability,
+  });
+  return createHash('sha256').update(identity).digest('hex').slice(0, 32);
+}
+
+function directSourceId(input: {
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+}): string {
+  const identity = [
+    input.principalId?.trim() ?? '',
+    input.controllerType?.trim() ?? '',
+    input.controllerInstanceId?.trim() ?? '',
+    input.sessionId?.trim() ?? '',
+  ].join(':');
+  return `mcp-learning:${createHash('sha256').update(identity || 'anonymous-controller').digest('hex').slice(0, 24)}`;
+}
+
+function directLearningAuthority(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId'>;
+  scopes: readonly ScopeRef[];
+  principalId?: string;
+  sourceId: string;
+  sourceWorkId?: string;
+}): CognitiveWriteAuthorityPort {
+  const scopeAllowed = (scope: ScopeRef) => input.scopes.some(candidate => sameScope(candidate, scope));
+  return {
+    assertMemoryWrite(memory: MemoryUnit) {
+      if (!scopeAllowed(memory.scope)
+        || memory.provenance.sourceKind !== 'controller'
+        || memory.provenance.sourceId !== input.sourceId
+        || memory.provenance.sourceWorkId !== input.sourceWorkId
+        || memory.provenance.sourceRoundId) {
+        throw new Error('COGNITION_DIRECT_LEARNING_AUTHORITY_INVALID');
+      }
+      if (memory.scope.kind === 'workspace' && !memory.facets.includes('portability.portable')) {
+        throw new Error('COGNITION_DIRECT_LEARNING_WORKSPACE_PORTABILITY_REQUIRED');
+      }
+    },
+    assertEdgeWrite() {
+      throw new Error('COGNITION_DIRECT_LEARNING_EDGE_NOT_ALLOWED');
+    },
+    evidenceAvailable(ref, scope) {
+      if (!scopeAllowed(scope)) return false;
+      const receipt = findPluginActionReceipt(input.controllerHome, ref);
+      if (!receipt) return false;
+      if (receipt.repoId === input.repository.repoId || receipt.workRepoId === input.repository.repoId) return true;
+      const principal = input.principalId?.trim();
+      return receipt.scopeKey === FORGE_INSTANCE_SCOPE_KEY
+        && Boolean(principal)
+        && receipt.origin?.actor === principal;
+    },
+  };
+}
+
+/**
+ * Persist semantic learning selected by the model without creating a learning lifecycle.
+ *
+ * The caller supplies meaning plus an optional already-existing Work identity. Forge derives
+ * reachable semantic scope, source identity and time. Work provenance never fabricates a
+ * ControllerRound; ControllerRound authority remains intentionally absent.
+ */
+export interface DirectControllerLearningFeedbackDraft {
+  memoryAddress: string;
+  decision: 'used' | 'rejected';
+  reason: string;
+  rejectionKind?: CognitiveUsageRejectionKind;
+}
+
+export interface DirectControllerLearningFeedbackResult {
+  observationIds: string[];
+  scopes: ScopeRef[];
+}
+
+export function recordDirectControllerLearningFeedback(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  feedback: readonly DirectControllerLearningFeedbackDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  now?: string;
+  workId?: string;
+}): DirectControllerLearningFeedbackResult {
+  if (!input.feedback.length || input.feedback.length > 32) throw new Error('COGNITION_DIRECT_FEEDBACK_ITEMS_INVALID');
+  const principalId = input.principalId?.trim();
+  if (!principalId) throw new Error('COGNITION_DIRECT_FEEDBACK_PRINCIPAL_REQUIRED');
+  const interactionId = input.sessionId?.trim() || input.controllerInstanceId?.trim();
+  if (!interactionId) throw new Error('COGNITION_DIRECT_FEEDBACK_SESSION_REQUIRED');
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const allowedScopes = new Set(scopes.map(scope => `${scope.kind}:${scope.id}`));
+  const now = input.now ?? new Date().toISOString();
+  const read = cognitionReadPort(input.controllerHome);
+  const observations = input.feedback.map((draft, index) => {
+    const address = parseMemoryAddressKey(draft.memoryAddress);
+    if (!address || !allowedScopes.has(`${address.scope.kind}:${address.scope.id}`)) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_SCOPE_INVALID: ${index}`);
+    }
+    if (!read.readByAddresses([address]).length) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_NOT_FOUND: ${index}`);
+    }
+    const reason = draft.reason.trim();
+    if (!reason || reason.length > 1_000) throw new Error(`COGNITION_DIRECT_FEEDBACK_REASON_INVALID: ${index}`);
+    if (draft.decision === 'rejected' && !draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+    }
+    if (draft.decision === 'used' && draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+    }
+    const observationId = `usage:${createHash('sha256')
+      .update(JSON.stringify({
+        actor: principalId,
+        interaction: interactionId,
+        address: memoryAddressKey(address),
+        decision: draft.decision,
+        rejectionKind: draft.rejectionKind ?? '',
+        reason,
+      }))
+      .digest('hex').slice(0, 32)}`;
+    return recordCognitiveUsageObservation(input.controllerHome, {
+      observationId,
+      address,
+      actorId: principalId,
+      decision: draft.decision,
+      reason,
+      ...(draft.rejectionKind ? { rejectionKind: draft.rejectionKind } : {}),
+      observedAt: now,
+    });
+  });
+  return { observationIds: observations.map(item => item.observationId), scopes };
+}
+
+export function persistDirectControllerLearning(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  signals: readonly ControllerLearningSignalDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+  workId?: string;
+  now?: string;
+}): DirectControllerLearningResult {
+  if (!input.signals.length || input.signals.length > CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS) {
+    throw new Error('COGNITION_DIRECT_LEARNING_SIGNALS_INVALID');
+  }
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const observedAt = input.now ?? new Date().toISOString();
+  const sourceId = directSourceId(input);
+  const projectScope = scopes.find(scope => scope.kind === 'project')!;
+  const workspaceScope = scopes.find(scope => scope.kind === 'workspace')!;
+  const store = cognitionMemoryStore(input.controllerHome);
+  const authority = directLearningAuthority({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    scopes,
+    principalId: input.principalId,
+    sourceId,
+    sourceWorkId: input.workId,
+  });
+
+  const drafts = input.signals.map(signal => {
+    const scope = scopes.find(candidate => candidate.kind === signal.scopeKind)
+      ?? (signal.scopeKind === 'project' ? projectScope : signal.scopeKind === 'workspace' ? workspaceScope : undefined);
+    if (!scope) {
+      throw new Error(`COGNITION_LEARNING_SCOPE_UNREACHABLE: ${signal.scopeKind}`);
+    }
+    const id = semanticSignalId(signal, scope);
+    const learning: LearningSignal = {
+      schemaVersion: 1,
+      id: `direct:${id}`,
+      scope,
+      kind: signal.kind,
+      valence: signal.valence,
+      summary: signal.summary,
+      concepts: [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))],
+      facets: [...new Set(signal.facets.map(value => value.trim()).filter(Boolean))],
+      admissionSource: signal.admissionSource,
+      portability: signal.portability,
+      salience: signal.salience,
+      confidence: signal.confidence,
+      utility: signal.utility,
+      sourceKind: 'controller',
+      sourceId,
+      observedAt,
+      evidenceRefs: [...new Set(signal.evidenceRefs)],
+      counterEvidenceRefs: [...new Set(signal.counterEvidenceRefs)],
+      ...(signal.expiresAt ? { expiresAt: signal.expiresAt } : {}),
+    };
+    const draft = memoryDraftFromLearningSignal(learning);
+    return input.workId ? {
+      ...draft,
+      provenance: {
+        ...draft.provenance,
+        sourceWorkId: input.workId,
+      },
+    } : draft;
+  });
+
+  // Validate all evidence before any write so a multi-signal call cannot partially commit.
+  for (const draft of drafts) {
+    authority.assertMemoryWrite({ ...draft, schemaVersion: 1, revision: 1 });
+    for (const ref of [...draft.provenance.evidenceRefs, ...draft.counterEvidenceRefs]) {
+      if (!authority.evidenceAvailable(ref, draft.scope)) {
+        throw new Error(`COGNITION_DIRECT_LEARNING_EVIDENCE_UNAVAILABLE: ${ref}`);
+      }
+    }
+  }
+
+  const stored = store.transaction(() => drafts.map(draft =>
+    recordCognitiveMemory(store, authority, draft)));
+  const associatedEdgeCount = associateStoredMemories({
+    controllerHome: input.controllerHome,
+    memories: stored,
+    now: observedAt,
+  });
+  const consolidatedMemoryIds = scopes.flatMap(scope =>
+    consolidateAffectedMemories(input.controllerHome, scope, stored, observedAt).map(candidate => candidate.memory.id));
+  return {
+    storedMemoryIds: stored.map(memory => memory.id),
+    associatedEdgeCount,
+    consolidatedMemoryIds: [...new Set(consolidatedMemoryIds)],
+    scopes,
+  };
+}

package/src/runtime/context/project-engineering-contract.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, relative, resolve, sep } from 'path';
+import {
+  DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH,
+  validateProjectEngineeringContract,
+  type ProjectEngineeringContract,
+  type ProjectEngineeringContractReceipt,
+} from '../../../packages/kernel/work/api/index';
+
+export type ProjectEngineeringContractLoadResult =
+  | { status: 'missing'; contractPath: string }
+  | { status: 'ready'; contractPath: string; contract: ProjectEngineeringContract; receipt: ProjectEngineeringContractReceipt };
+
+function boundedRepositoryPath(repoRoot: string, requested: string): { absolute: string; relative: string } {
+  if (isAbsolute(requested)) throw new Error('PROJECT_ENGINEERING_CONTRACT_PATH_MUST_BE_REPOSITORY_RELATIVE');
+  const root = resolve(repoRoot);
+  const absolute = resolve(root, requested);
+  const rel = relative(root, absolute).split(sep).join('/');
+  if (!rel || rel.startsWith('../') || rel === '..') throw new Error('PROJECT_ENGINEERING_CONTRACT_PATH_OUTSIDE_REPOSITORY');
+  return { absolute, relative: rel };
+}
+
+export function loadProjectEngineeringContract(input: {
+  repoRoot: string;
+  sourceRevision: string;
+  contractPath?: string;
+  now?: () => string;
+}): ProjectEngineeringContractLoadResult {
+  const sourceRevision = input.sourceRevision.trim();
+  if (!sourceRevision) throw new Error('PROJECT_ENGINEERING_CONTRACT_SOURCE_REVISION_REQUIRED');
+  const path = boundedRepositoryPath(input.repoRoot, input.contractPath ?? DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH);
+  if (!existsSync(path.absolute)) return { status: 'missing', contractPath: path.relative };
+  const raw = readFileSync(path.absolute, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('PROJECT_ENGINEERING_CONTRACT_JSON_INVALID');
+  }
+  const contract = validateProjectEngineeringContract(parsed);
+  return {
+    status: 'ready',
+    contractPath: path.relative,
+    contract,
+    receipt: {
+      schemaVersion: 1,
+      contractPath: path.relative,
+      projectId: contract.projectId,
+      contractId: contract.contractId,
+      contractVersion: contract.contractVersion,
+      sourceRevision,
+      contentDigest: createHash('sha256').update(raw).digest('hex'),
+      provenance: {
+        source: 'repository',
+        loadedAt: (input.now ?? (() => new Date().toISOString()))(),
+      },
+    },
+  };
+}

package/src/runtime/context/semantic-navigation-contract.ts

@@ -32,10 +32,19 @@ export type SemanticNavigationOutcome =
   | { ok: true; result: SemanticNavigationResult }
   | { ok: false; code: string; message: string };
 
+export interface SemanticNavigationReadPolicy {
+  profile: string;
+  readGlobs: readonly string[];
+  denyGlobs: readonly string[];
+  maxFileBytes: number;
+}
+
 export interface SemanticNavigationAccess {
   cacheScope: string;
   sourceIdentity?: string;
   profile: string;
+  /** Serializable policy used by disposable semantic sidecars. */
+  readPolicy?: SemanticNavigationReadPolicy;
   allowRepositoryPath(relativePath: string): boolean;
 }
 

package/src/runtime/context/semantic-navigation.ts

@@ -1,5 +1,5 @@
 import { extname } from 'path';
-import { navigateTypeScriptSymbol } from './typescript-navigation';
+import { navigateTypeScriptInSidecar } from './typescript-navigation-process';
 import { navigateSwiftSymbols } from './swift-navigation';
 import { GenericLspSemanticProvider, type GenericLspProviderDescriptor } from './generic-lsp-provider';
 
@@ -25,39 +25,11 @@ const typeScriptProvider: SemanticNavigationProvider = {
     return extensionSupported && (!request.language || request.language.toLowerCase() === 'typescript');
   },
   async navigate(repoRoot, requests, access) {
-    return requests.map((request) => {
-      let policyDeniedReads = 0;
-      try {
-        const result = navigateTypeScriptSymbol(repoRoot, {
-          navigation: request.navigation,
-          path: request.path,
-          line: request.line,
-          column: request.column,
-          tsconfigPath: request.tsconfigPath,
-        }, {
-          cacheScope: access.cacheScope,
-          sourceIdentity: access.sourceIdentity,
-          allowRepositoryPath: (relativePath) => {
-            const allowed = access.allowRepositoryPath(relativePath);
-            if (!allowed) policyDeniedReads += 1;
-            return allowed;
-          },
-        });
-        return {
-          ok: true,
-          result: {
-            providerId: 'typescript-language-service',
-            language: 'typescript',
-            navigation: result.navigation,
-            target: result.target,
-            locations: result.locations,
-            policyDeniedReads,
-          },
-        } satisfies SemanticNavigationOutcome;
-      } catch (error) {
-        return { ok: false, code: 'SEMANTIC_NAVIGATION_FAILED', message: error instanceof Error ? error.message : String(error) } satisfies SemanticNavigationOutcome;
-      }
-    });
+    // A Forge-sized TypeScript LanguageService can return its live heap after
+    // dispose() while JSC/WebKit keeps the expanded allocator resident. Keep
+    // that allocator lifetime out of the canonical Runtime: one bounded batch
+    // runs in one short-lived sidecar and the OS reclaims it on process exit.
+    return navigateTypeScriptInSidecar(repoRoot, requests, access);
   },
 };