@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -0,0 +1,64 @@
+import type { ScopeRef } from '../../identity/api/index';
+import {
+  validateMemoryEdge,
+  validateMemoryUnit,
+  type MemoryEdge,
+  type MemoryEdgeDraft,
+  type MemoryUnit,
+  type MemoryUnitDraft,
+} from '../domain/memory';
+
+/** Persistence is supplied by trusted composition; it is not a transport-facing authority. */
+export interface CognitiveMemoryStorePort {
+  transaction<T>(operation: () => T): T;
+  read(scope: ScopeRef, id: string): MemoryUnit | undefined;
+  write(memory: MemoryUnit, expectedRevision: number | null): MemoryUnit;
+  writeEdge(edge: MemoryEdge): MemoryEdge;
+}
+
+/**
+ * The Cognitive Plane owns knowledge semantics, never lifecycle authority.
+ * Existing Kernel authorities decide whether a concrete producer may write.
+ */
+export interface CognitiveWriteAuthorityPort {
+  assertMemoryWrite(memory: MemoryUnit): void;
+  assertEdgeWrite(edge: MemoryEdge): void;
+  evidenceAvailable(ref: string, scope: ScopeRef, sourceWorkId?: string): boolean;
+}
+
+function assertEvidence(authority: CognitiveWriteAuthorityPort, memory: MemoryUnit): void {
+  for (const ref of [...memory.provenance.evidenceRefs, ...memory.counterEvidenceRefs]) {
+    if (!authority.evidenceAvailable(ref, memory.scope, memory.provenance.sourceWorkId)) {
+      throw new Error('COGNITION_EVIDENCE_UNAVAILABLE');
+    }
+  }
+}
+
+export function recordCognitiveMemory(
+  store: CognitiveMemoryStorePort,
+  authority: CognitiveWriteAuthorityPort,
+  draft: MemoryUnitDraft,
+): MemoryUnit {
+  return store.transaction(() => {
+    const existing = store.read(draft.scope, draft.id);
+    const memory = validateMemoryUnit({ ...structuredClone(draft), schemaVersion: 1, revision: (existing?.revision ?? 0) + 1 });
+    authority.assertMemoryWrite(memory);
+    assertEvidence(authority, memory);
+    return store.write(memory, existing?.revision ?? null);
+  });
+}
+
+export function recordCognitiveMemoryEdge(
+  store: CognitiveMemoryStorePort,
+  authority: CognitiveWriteAuthorityPort,
+  draft: MemoryEdgeDraft,
+): MemoryEdge {
+  return store.transaction(() => {
+    const edge = validateMemoryEdge({ ...structuredClone(draft), schemaVersion: 1 });
+    authority.assertEdgeWrite(edge);
+    for (const ref of edge.evidenceRefs) {
+      if (!authority.evidenceAvailable(ref, edge.scope, edge.sourceWorkId)) throw new Error('COGNITION_EDGE_EVIDENCE_UNAVAILABLE');
+    }
+    return store.writeEdge(edge);
+  });
+}

package/packages/kernel/cognition/domain/learning.ts

@@ -0,0 +1,106 @@
+import type { ScopeRef } from '../../identity/api/index';
+import type { MemoryPayloadRef, MemorySourceKind, MemoryUnitDraft } from './memory';
+
+/** Open vocabulary on purpose: kind describes the model-authored semantic delta; it is not an admission taxonomy. */
+export type LearningSignalKind = string;
+
+export type LearningValence = 'positive' | 'negative' | 'neutral';
+
+/** Admission source describes why a signal may become advisory memory; it is not lifecycle authority. */
+export type LearningAdmissionSource =
+  | 'explicit_human'
+  | 'controller_observation'
+  | 'verified_outcome'
+  | 'execution_quality'
+  | 'system_inference';
+
+/** Portability is semantic intent only; cross-scope writes still require the existing write authority. */
+export type LearningPortability = 'local' | 'portable';
+
+const LEARNING_KIND = /^[a-z0-9][a-z0-9._:-]{0,63}$/i;
+
+/** A learning trigger is domain-independent. Failure is only one possible signal. */
+export interface LearningSignal {
+  schemaVersion: 1;
+  id: string;
+  scope: ScopeRef;
+  kind: LearningSignalKind;
+  valence: LearningValence;
+  summary: string;
+  concepts: string[];
+  facets?: string[];
+  admissionSource: LearningAdmissionSource;
+  portability: LearningPortability;
+  /** Extraction-time importance, not truth confidence or learned usefulness. */
+  salience: number;
+  /** Evidentiary / semantic strength of the claim. */
+  confidence: number;
+  /** Initial retrieval-usefulness prior, independently learnable from usage feedback. */
+  utility: number;
+  sourceKind: MemorySourceKind;
+  sourceId?: string;
+  sourceWorkId?: string;
+  sourceRoundId?: string;
+  observedAt: string;
+  evidenceRefs: string[];
+  counterEvidenceRefs?: string[];
+  payloadRef?: MemoryPayloadRef;
+  expiresAt?: string;
+}
+
+function score(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`COGNITION_LEARNING_${label}_INVALID`);
+}
+
+export function validateLearningSignal(signal: LearningSignal): LearningSignal {
+  if (signal.schemaVersion !== 1 || !signal.id.trim() || signal.id.length > 512) throw new Error('COGNITION_LEARNING_ID_INVALID');
+  if (!signal.summary.trim() || signal.summary.length > 8_192) throw new Error('COGNITION_LEARNING_SUMMARY_INVALID');
+  if (typeof signal.kind !== 'string' || !LEARNING_KIND.test(signal.kind)) throw new Error('COGNITION_LEARNING_KIND_INVALID');
+  if (!signal.concepts.length || signal.concepts.length > 64 || new Set(signal.concepts).size !== signal.concepts.length) throw new Error('COGNITION_LEARNING_CONCEPTS_INVALID');
+  if (!Number.isFinite(Date.parse(signal.observedAt))) throw new Error('COGNITION_LEARNING_TIME_INVALID');
+  if (!['explicit_human', 'controller_observation', 'verified_outcome', 'execution_quality', 'system_inference'].includes(signal.admissionSource)) throw new Error('COGNITION_LEARNING_ADMISSION_SOURCE_INVALID');
+  if (!['local', 'portable'].includes(signal.portability)) throw new Error('COGNITION_LEARNING_PORTABILITY_INVALID');
+  // Scope/generalization is a model-authored semantic decision. Forge only enforces
+  // that Workspace memory was explicitly marked portable; admission source, kind,
+  // confidence and repetition count never authorize or forbid that decision.
+  if (signal.scope.kind === 'workspace' && signal.portability !== 'portable') throw new Error('COGNITION_LEARNING_WORKSPACE_PORTABILITY_REQUIRED');
+  score(signal.salience, 'SALIENCE'); score(signal.confidence, 'CONFIDENCE'); score(signal.utility, 'UTILITY');
+  if (signal.expiresAt && Date.parse(signal.expiresAt) <= Date.parse(signal.observedAt)) throw new Error('COGNITION_LEARNING_EXPIRY_INVALID');
+  return signal;
+}
+
+export function memoryDraftFromLearningSignal(input: LearningSignal): MemoryUnitDraft {
+  const signal = validateLearningSignal(input);
+  return {
+    id: `learning:${signal.id}`,
+    scope: signal.scope,
+    facets: [...new Set([
+      'learning',
+      'admission.advisory',
+      signal.kind,
+      `valence.${signal.valence}`,
+      `source.${signal.admissionSource}`,
+      `portability.${signal.portability}`,
+      ...(signal.facets ?? []),
+    ])].slice(0, 16),
+    canonicalText: signal.summary,
+    concepts: signal.concepts,
+    ...(signal.payloadRef ? { payloadRef: signal.payloadRef } : {}),
+    provenance: {
+      sourceKind: signal.sourceKind,
+      ...(signal.sourceId ? { sourceId: signal.sourceId } : {}),
+      ...(signal.sourceWorkId ? { sourceWorkId: signal.sourceWorkId } : {}),
+      ...(signal.sourceRoundId ? { sourceRoundId: signal.sourceRoundId } : {}),
+      recordedAt: signal.observedAt,
+      evidenceRefs: signal.evidenceRefs,
+    },
+    confidence: signal.confidence,
+    utility: signal.utility,
+    // The model has already decided this semantic delta is worth retaining.
+    // Kind is descriptive metadata, so it must not silently change retention tier.
+    tier: 'warm',
+    validFrom: signal.observedAt,
+    ...(signal.expiresAt ? { expiresAt: signal.expiresAt } : {}),
+    counterEvidenceRefs: signal.counterEvidenceRefs ?? [],
+  };
+}

package/packages/kernel/cognition/domain/memory.ts

@@ -0,0 +1,254 @@
+import type { ScopeRef } from '../../identity/api/index';
+
+export const COGNITIVE_MEMORY_SCHEMA_VERSION = 1 as const;
+export const COGNITIVE_IR_VERSION = 'forge-cognitive-ir/v1' as const;
+
+export type MemoryTier = 'hot' | 'warm' | 'cold';
+export type MemorySourceKind = 'experience' | 'outcome' | 'knowledge' | 'controller' | 'system' | 'external';
+
+/** Open vocabulary on purpose: memory facets are descriptive, not lifecycle authority. */
+export type MemoryFacet = string;
+export type MemoryRelation = string;
+
+export interface MemoryPayloadRef {
+  algorithm: 'sha256';
+  digest: string;
+  mediaType: string;
+  bytes: number;
+}
+
+export interface MemoryAddress {
+  scope: ScopeRef;
+  id: string;
+}
+
+export interface MemoryProvenance {
+  sourceKind: MemorySourceKind;
+  sourceId?: string;
+  sourceWorkId?: string;
+  sourceRoundId?: string;
+  recordedAt: string;
+  evidenceRefs: string[];
+}
+
+export interface MemoryUnit {
+  schemaVersion: typeof COGNITIVE_MEMORY_SCHEMA_VERSION;
+  id: string;
+  revision: number;
+  scope: ScopeRef;
+  facets: MemoryFacet[];
+  canonicalText: string;
+  concepts: string[];
+  payloadRef?: MemoryPayloadRef;
+  provenance: MemoryProvenance;
+  confidence: number;
+  utility: number;
+  tier: MemoryTier;
+  validFrom: string;
+  expiresAt?: string;
+  supersedesId?: string;
+  counterEvidenceRefs: string[];
+  retractedAt?: string;
+  retractionReason?: string;
+}
+
+export type MemoryUnitDraft = Omit<MemoryUnit, 'schemaVersion' | 'revision'>;
+
+export interface MemoryEdge {
+  schemaVersion: typeof COGNITIVE_MEMORY_SCHEMA_VERSION;
+  id: string;
+  scope: ScopeRef;
+  fromId: string;
+  toId: string;
+  relation: MemoryRelation;
+  weight: number;
+  evidenceRefs: string[];
+  sourceWorkId?: string;
+  sourceRoundId?: string;
+  recordedAt: string;
+  expiresAt?: string;
+  retractedAt?: string;
+}
+
+export type MemoryEdgeDraft = Omit<MemoryEdge, 'schemaVersion'>;
+
+export interface CognitiveIRFact {
+  subject: string;
+  predicate: string;
+  object?: string;
+  value?: string | number | boolean;
+  confidence?: number;
+}
+
+export interface CognitiveIR {
+  version: typeof COGNITIVE_IR_VERSION;
+  memoryId: string;
+  concepts: string[];
+  facts: CognitiveIRFact[];
+  relations: Array<{ relation: string; targetId: string; weight: number }>;
+  conditions: string[];
+  evidenceRefs: string[];
+}
+
+export interface ActivationReason {
+  signal: 'exact' | 'graph' | 'lexical' | 'semantic' | 'recency' | 'utility' | 'confidence' | 'conflict' | 'usage';
+  score: number;
+  detail: string;
+}
+
+export interface ActivationItem {
+  memory: MemoryUnit;
+  score: number;
+  reasons: ActivationReason[];
+  activationPath: string[];
+}
+
+export interface ActivationPack {
+  schemaVersion: 1;
+  query: string;
+  generatedAt: string;
+  items: ActivationItem[];
+  gaps: string[];
+  truncated: boolean;
+  inspectedCandidates: number;
+  estimatedBytes: number;
+}
+
+const IDENTIFIER = /^[a-z0-9][a-z0-9._:/-]{0,255}$/i;
+const FACET = /^[a-z0-9][a-z0-9._:-]{0,63}$/i;
+const RELATION = /^[a-z0-9][a-z0-9._:-]{0,95}$/i;
+const DIGEST = /^[a-f0-9]{64}$/;
+const VALID_SCOPE_KINDS: readonly ScopeRef['kind'][] = ['workspace', 'project', 'requirement', 'plan', 'plan_step', 'work'];
+
+function requireText(value: string, label: string, max: number): void {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(`COGNITION_${label}_INVALID`);
+}
+
+function requireTimestamp(value: string, label: string): void {
+  if (!Number.isFinite(Date.parse(value))) throw new Error(`COGNITION_${label}_INVALID`);
+}
+
+function requireScore(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`COGNITION_${label}_INVALID`);
+}
+
+function uniqueStrings(values: readonly string[], label: string, maxItems: number, pattern?: RegExp): void {
+  if (!Array.isArray(values) || values.length > maxItems || new Set(values).size !== values.length) throw new Error(`COGNITION_${label}_INVALID`);
+  for (const value of values) {
+    requireText(value, label, 512);
+    if (pattern && !pattern.test(value)) throw new Error(`COGNITION_${label}_INVALID`);
+  }
+}
+
+export function validateCognitiveScope(scope: ScopeRef): ScopeRef {
+  if (scope.schemaVersion !== 1 || !VALID_SCOPE_KINDS.includes(scope.kind)) throw new Error('COGNITION_SCOPE_INVALID');
+  requireText(scope.id, 'SCOPE_ID', 512);
+  return scope;
+}
+
+export function validateMemoryPayloadRef(ref: MemoryPayloadRef): MemoryPayloadRef {
+  if (ref.algorithm !== 'sha256' || !DIGEST.test(ref.digest)) throw new Error('COGNITION_PAYLOAD_DIGEST_INVALID');
+  requireText(ref.mediaType, 'PAYLOAD_MEDIA_TYPE', 128);
+  if (!Number.isSafeInteger(ref.bytes) || ref.bytes < 0) throw new Error('COGNITION_PAYLOAD_BYTES_INVALID');
+  return ref;
+}
+
+export function memoryAddressKey(address: MemoryAddress): string {
+  validateCognitiveScope(address.scope);
+  requireText(address.id, 'MEMORY_ID', 512);
+  return JSON.stringify([address.scope.kind, address.scope.id, address.id]);
+}
+
+export function parseMemoryAddressKey(value: string): MemoryAddress | undefined {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!Array.isArray(parsed) || parsed.length !== 3 || parsed.some(item => typeof item !== 'string')) return undefined;
+    const [kind, scopeId, id] = parsed as [ScopeRef['kind'], string, string];
+    if (!VALID_SCOPE_KINDS.includes(kind) || !scopeId.trim() || !id.trim()) return undefined;
+    const address = { scope: { schemaVersion: 1 as const, kind, id: scopeId }, id };
+    validateCognitiveScope(address.scope);
+    requireText(address.id, 'MEMORY_ID', 512);
+    return address;
+  } catch {
+    return undefined;
+  }
+}
+
+export function memoryAddressOf(memory: MemoryUnit): MemoryAddress {
+  return { scope: memory.scope, id: memory.id };
+}
+
+export function memoryAddressLabel(address: MemoryAddress): string {
+  return `mem://${address.scope.kind}/${encodeURIComponent(address.scope.id)}/${encodeURIComponent(address.id)}`;
+}
+
+export function validateMemoryUnit(unit: MemoryUnit): MemoryUnit {
+  if (unit.schemaVersion !== 1 || !Number.isSafeInteger(unit.revision) || unit.revision < 1) throw new Error('COGNITION_MEMORY_VERSION_INVALID');
+  validateCognitiveScope(unit.scope);
+  requireText(unit.id, 'MEMORY_ID', 512);
+  requireText(unit.canonicalText, 'CANONICAL_TEXT', 8_192);
+  uniqueStrings(unit.facets, 'FACET', 16, FACET);
+  uniqueStrings(unit.concepts, 'CONCEPT', 64, IDENTIFIER);
+  if (!unit.facets.length || !unit.concepts.length) throw new Error('COGNITION_MEMORY_CLASSIFICATION_REQUIRED');
+  requireScore(unit.confidence, 'CONFIDENCE');
+  requireScore(unit.utility, 'UTILITY');
+  if (!['hot', 'warm', 'cold'].includes(unit.tier)) throw new Error('COGNITION_TIER_INVALID');
+  requireTimestamp(unit.validFrom, 'VALID_FROM');
+  requireTimestamp(unit.provenance.recordedAt, 'PROVENANCE_TIME');
+  uniqueStrings(unit.provenance.evidenceRefs, 'EVIDENCE', 64);
+  uniqueStrings(unit.counterEvidenceRefs, 'COUNTER_EVIDENCE', 64);
+  if (unit.expiresAt) {
+    requireTimestamp(unit.expiresAt, 'EXPIRY');
+    if (Date.parse(unit.expiresAt) <= Date.parse(unit.validFrom)) throw new Error('COGNITION_EXPIRY_INVALID');
+  }
+  if (unit.payloadRef) validateMemoryPayloadRef(unit.payloadRef);
+  if (unit.supersedesId) requireText(unit.supersedesId, 'SUPERSEDES_ID', 512);
+  if (unit.retractedAt) {
+    requireTimestamp(unit.retractedAt, 'RETRACTION_TIME');
+    requireText(unit.retractionReason ?? '', 'RETRACTION_REASON', 1_000);
+  }
+  return unit;
+}
+
+export function validateMemoryEdge(edge: MemoryEdge): MemoryEdge {
+  if (edge.schemaVersion !== 1) throw new Error('COGNITION_EDGE_VERSION_INVALID');
+  validateCognitiveScope(edge.scope);
+  requireText(edge.id, 'EDGE_ID', 512);
+  requireText(edge.fromId, 'EDGE_FROM', 512);
+  requireText(edge.toId, 'EDGE_TO', 512);
+  if (edge.fromId === edge.toId) throw new Error('COGNITION_EDGE_SELF_INVALID');
+  requireText(edge.relation, 'RELATION', 96);
+  if (!RELATION.test(edge.relation)) throw new Error('COGNITION_RELATION_INVALID');
+  requireScore(edge.weight, 'EDGE_WEIGHT');
+  uniqueStrings(edge.evidenceRefs, 'EDGE_EVIDENCE', 64);
+  requireTimestamp(edge.recordedAt, 'EDGE_TIME');
+  if (edge.expiresAt) requireTimestamp(edge.expiresAt, 'EDGE_EXPIRY');
+  if (edge.retractedAt) requireTimestamp(edge.retractedAt, 'EDGE_RETRACTION');
+  return edge;
+}
+
+const COGNITIVE_ENGLISH_FUNCTION_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'been', 'by', 'for', 'from', 'in', 'into', 'is', 'it',
+  'of', 'on', 'or', 'that', 'the', 'this', 'to', 'was', 'were', 'with',
+]);
+
+export function cognitiveTerms(text: string): Set<string> {
+  const terms = new Set<string>();
+  for (const token of text.toLocaleLowerCase('en-US').match(/[a-z0-9_.:/-]+/g) ?? []) {
+    if (!COGNITIVE_ENGLISH_FUNCTION_WORDS.has(token)) terms.add(token);
+    // Structured concepts are canonical identities, but their lexical parts
+    // are a rebuildable retrieval projection. Thus `forge cognition` can cue
+    // `forge.cognition` without inventing a keyword ontology.
+    if (/[._:/-]/.test(token)) {
+      for (const part of token.split(/[._:/-]+/).filter(Boolean)) {
+        if (!COGNITIVE_ENGLISH_FUNCTION_WORDS.has(part)) terms.add(part);
+      }
+    }
+  }
+  for (const run of text.match(/\p{Script=Han}+/gu) ?? []) {
+    const chars = [...run];
+    if (chars.length === 1) terms.add(run);
+    for (let index = 0; index + 1 < chars.length; index++) terms.add(chars[index]! + chars[index + 1]!);
+  }
+  return terms;
+}

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

@@ -1,2 +1,3 @@
 export * from '../application/controller-service';
 export * from '../application/controller-round-service';
+export * from '../application/continuation-service';