@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/learning/learning-audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"learning-audit.js","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport type { DurableChangeLayer, DurableChangeProposal } from \"./learning-gate.ts\";\nimport type { ReflectionWrite } from \"./reflection-engine.ts\";\n\n/**\n * Audit + rollback metadata for durable learning changes. Every reflection-sourced write that the\n * learning policy applies (or converts to a proposal) leaves one of these records in the session\n * log, so `/autonomy diagnostics` can explain what changed, why, and how to undo it — and\n * `rollbackLearningWrite` can execute the inverse operation.\n */\n\nexport type LearningRollbackKind = \"memory_remove\" | \"memory_restore\" | \"memory_add\" | \"archive_skill\";\n\nexport interface LearningRollbackPlan {\n\tkind: LearningRollbackKind;\n\t/** Text currently present because of the change (to remove/replace), or the skill name to archive. */\n\ttarget?: string;\n\t/** Original text to restore (memory_restore/memory_add). */\n\tprevious?: string;\n\tinstructions: string;\n}\n\n// \"apply_failed\" is distinct from \"apply\": the gate decided to apply, but the underlying write tool\n// (e.g. the memory tool) refused it (budget exceeded, drift, threat) without throwing. It must never\n// be treated as \"apply\" by a rollback-eligibility check — there is nothing durable to undo.\nexport type LearningAuditAction = \"apply\" | \"apply_failed\" | \"propose\" | \"rollback\";\n\n/** reasonCode for an \"apply_failed\" audit — distinct from the gate's own reasonCode (e.g.\n * \"eligible_auto_apply\") so the record is honest about WHERE it stopped: the gate approved the\n * write, but the write tool refused it after the fact. */\nexport const APPLY_WRITE_REFUSED_REASON_CODE = \"apply_write_refused\";\n\nexport interface LearningAuditRecord {\n\tid: string;\n\tproposalId: string;\n\tlayer: DurableChangeLayer;\n\taction: LearningAuditAction;\n\tsummary: string;\n\treasonCode: string;\n\tdecision: LearningDecision;\n\trollback?: LearningRollbackPlan;\n\t/** For action \"rollback\": the audit id of the applied change this record undoes. */\n\trollbackOf?: string;\n\tcreatedAt: string;\n}\n\nfunction describeWrite(write: ReflectionWrite): string {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn `Add ${write.section} memory: ${write.text}`;\n\t\tcase \"memory_replace\":\n\t\t\treturn `Replace memory \"${write.target}\" with \"${write.text}\"`;\n\t\tcase \"memory_remove\":\n\t\t\treturn `Remove memory: ${write.target}`;\n\t\tcase \"promote_skill\":\n\t\t\treturn `Promote skill \"${write.name}\": ${write.description}`;\n\t}\n}\n\nexport function proposalFromReflectionWrite(write: ReflectionWrite, proposalId: string): DurableChangeProposal {\n\treturn {\n\t\tid: proposalId,\n\t\tlayer: write.kind === \"promote_skill\" ? \"skill\" : \"memory\",\n\t\tsummary: describeWrite(write),\n\t\trollbackPlan: rollbackPlanForReflectionWrite(write).instructions,\n\t};\n}\n\n/**\n * Contradiction count a reflection write carries against existing durable knowledge. A\n * `memory_replace`/`memory_remove` is only emitted when the reflection engine CONFRONTS an existing\n * fact (it supersedes or deletes it) — that supersession is the gate's contradiction signal, so such\n * a write must route through approval rather than silently overwriting prior memory. A `memory_add`\n * or `promote_skill` is purely additive and contradicts nothing.\n */\nexport function contradictionsForReflectionWrite(write: ReflectionWrite): number {\n\tswitch (write.kind) {\n\t\tcase \"memory_replace\":\n\t\tcase \"memory_remove\":\n\t\t\treturn 1;\n\t\tcase \"memory_add\":\n\t\tcase \"promote_skill\":\n\t\t\treturn 0;\n\t}\n}\n\nexport function rollbackPlanForReflectionWrite(write: ReflectionWrite): LearningRollbackPlan {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_remove\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tinstructions: `Remove the added ${write.section} memory text.`,\n\t\t\t};\n\t\tcase \"memory_replace\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_restore\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Replace the new memory text with the original text it overwrote.\",\n\t\t\t};\n\t\tcase \"memory_remove\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_add\",\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Re-add the removed text to the MEMORY file (it may originally have lived in USER).\",\n\t\t\t};\n\t\tcase \"promote_skill\":\n\t\t\treturn {\n\t\t\t\tkind: \"archive_skill\",\n\t\t\t\ttarget: write.name,\n\t\t\t\tinstructions: \"Archive the promoted skill so it no longer loads.\",\n\t\t\t};\n\t}\n}\n\nconst AUDIT_ACTIONS: readonly string[] = [\"apply\", \"apply_failed\", \"propose\", \"rollback\"];\nconst ROLLBACK_KINDS: readonly string[] = [\"memory_remove\", \"memory_restore\", \"memory_add\", \"archive_skill\"];\nconst LAYERS: readonly string[] = [\"memory\", \"skill\", \"prompt\", \"extension\", \"tool\", \"script\", \"settings\", \"source\"];\n\nfunction isOptionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nfunction isLearningRollbackPlan(value: unknown): value is LearningRollbackPlan {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst plan = value as Record<string, unknown>;\n\tif (typeof plan.kind !== \"string\" || !ROLLBACK_KINDS.includes(plan.kind)) return false;\n\tif (!isOptionalString(plan.target) || !isOptionalString(plan.previous)) return false;\n\treturn typeof plan.instructions === \"string\";\n}\n\nfunction isLearningDecisionShape(value: unknown): value is LearningDecision {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst decision = value as Record<string, unknown>;\n\treturn (\n\t\t(decision.kind === \"no-op\" || decision.kind === \"proposal\" || decision.kind === \"apply\") &&\n\t\ttypeof decision.reasonCode === \"string\" &&\n\t\ttypeof decision.confidence === \"number\" &&\n\t\ttypeof decision.summary === \"string\" &&\n\t\ttypeof decision.requiresApproval === \"boolean\"\n\t);\n}\n\nexport function isLearningAuditRecord(value: unknown): value is LearningAuditRecord {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst record = value as Record<string, unknown>;\n\tif (typeof record.id !== \"string\" || record.id.length === 0) return false;\n\tif (typeof record.proposalId !== \"string\") return false;\n\tif (typeof record.layer !== \"string\" || !LAYERS.includes(record.layer)) return false;\n\tif (typeof record.action !== \"string\" || !AUDIT_ACTIONS.includes(record.action)) return false;\n\tif (typeof record.summary !== \"string\" || typeof record.reasonCode !== \"string\") return false;\n\tif (!isLearningDecisionShape(record.decision)) return false;\n\tif (record.rollback !== undefined && !isLearningRollbackPlan(record.rollback)) return false;\n\tif (!isOptionalString(record.rollbackOf)) return false;\n\treturn typeof record.createdAt === \"string\";\n}\n\nexport function cloneLearningAuditRecordForStorage(record: LearningAuditRecord): LearningAuditRecord {\n\treturn {\n\t\t...record,\n\t\tdecision: { ...record.decision },\n\t\t...(record.rollback ? { rollback: { ...record.rollback } } : {}),\n\t};\n}\n\nexport const LEARNING_AUDIT_CUSTOM_TYPE = \"learning_audit\";\n\nexport interface LearningAuditSnapshotPayload {\n\tversion: 1;\n\trecord: LearningAuditRecord;\n}\n\nexport function appendLearningAuditSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trecord: LearningAuditRecord,\n): string {\n\tconst payload: LearningAuditSnapshotPayload = {\n\t\tversion: 1,\n\t\trecord: cloneLearningAuditRecordForStorage(record),\n\t};\n\treturn sessionManager.appendCustomEntry(LEARNING_AUDIT_CUSTOM_TYPE, payload);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function getLearningAuditSnapshots(entries: readonly SessionEntry[]): LearningAuditRecord[] {\n\tconst records: LearningAuditRecord[] = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== LEARNING_AUDIT_CUSTOM_TYPE) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload)) continue;\n\t\tif (payload.version !== 1) continue;\n\t\tif (!(\"record\" in payload)) continue;\n\t\tconst record = payload.record;\n\t\tif (isLearningAuditRecord(record)) {\n\t\t\trecords.push(cloneLearningAuditRecordForStorage(record));\n\t\t}\n\t}\n\n\treturn records;\n}\n"]}
+{"version":3,"file":"learning-audit.js","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport type { DurableChangeLayer, DurableChangeProposal } from \"./learning-gate.ts\";\nimport type { ReflectionWrite } from \"./reflection-engine.ts\";\n\n/**\n * Audit + rollback metadata for durable learning changes. Every reflection-sourced write that the\n * learning policy applies (or converts to a proposal) leaves one of these records in the session\n * log, so `/autonomy diagnostics` can explain what changed, why, and how to undo it — and\n * `rollbackLearningWrite` can execute the inverse operation.\n */\n\nexport type LearningRollbackKind = \"memory_remove\" | \"memory_restore\" | \"memory_add\" | \"archive_skill\";\n\nexport interface LearningRollbackPlan {\n\tkind: LearningRollbackKind;\n\t/** Text currently present because of the change (to remove/replace), or the skill name to archive. */\n\ttarget?: string;\n\t/** Original text to restore (memory_restore/memory_add). */\n\tprevious?: string;\n\tinstructions: string;\n}\n\n// \"apply_failed\" is distinct from \"apply\": the gate decided to apply, but the underlying write tool\n// (e.g. the memory tool) refused it (budget exceeded, drift, threat) without throwing. It must never\n// be treated as \"apply\" by a rollback-eligibility check — there is nothing durable to undo.\nexport type LearningAuditAction = \"apply\" | \"apply_failed\" | \"propose\" | \"rollback\";\n\n/** reasonCode for an \"apply_failed\" audit — distinct from the gate's own reasonCode (e.g.\n * \"eligible_auto_apply\") so the record is honest about WHERE it stopped: the gate approved the\n * write, but the write tool refused it after the fact. */\nexport const APPLY_WRITE_REFUSED_REASON_CODE = \"apply_write_refused\";\n\nexport interface LearningAuditRecord {\n\tid: string;\n\tproposalId: string;\n\tlayer: DurableChangeLayer;\n\taction: LearningAuditAction;\n\tsummary: string;\n\treasonCode: string;\n\tdecision: LearningDecision;\n\trollback?: LearningRollbackPlan;\n\t/** For action \"rollback\": the audit id of the applied change this record undoes. */\n\trollbackOf?: string;\n\tcreatedAt: string;\n}\n\nfunction describeWrite(write: ReflectionWrite): string {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn `Add ${write.section} memory: ${write.text}`;\n\t\tcase \"memory_replace\":\n\t\t\treturn `Replace memory \"${write.target}\" with \"${write.text}\"`;\n\t\tcase \"memory_remove\":\n\t\t\treturn `Remove memory: ${write.target}`;\n\t\tcase \"promote_skill\":\n\t\t\treturn `Promote skill \"${write.name}\": ${write.description}`;\n\t}\n}\n\nexport function proposalFromReflectionWrite(write: ReflectionWrite, proposalId: string): DurableChangeProposal {\n\treturn {\n\t\tid: proposalId,\n\t\tlayer: write.kind === \"promote_skill\" ? \"skill\" : \"memory\",\n\t\tsummary: describeWrite(write),\n\t\trollbackPlan: rollbackPlanForReflectionWrite(write).instructions,\n\t};\n}\n\n/**\n * Contradiction count a reflection write carries against existing durable knowledge. A\n * `memory_replace`/`memory_remove` is only emitted when the reflection engine CONFRONTS an existing\n * fact (it supersedes or deletes it) — that supersession is the gate's contradiction signal, so such\n * a write must route through approval rather than silently overwriting prior memory. A `memory_add`\n * or `promote_skill` is purely additive and contradicts nothing.\n */\nexport function contradictionsForReflectionWrite(write: ReflectionWrite): number {\n\tswitch (write.kind) {\n\t\tcase \"memory_replace\":\n\t\tcase \"memory_remove\":\n\t\t\treturn 1;\n\t\tcase \"memory_add\":\n\t\tcase \"promote_skill\":\n\t\t\treturn 0;\n\t}\n}\n\nexport function rollbackPlanForReflectionWrite(write: ReflectionWrite): LearningRollbackPlan {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_remove\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tinstructions: `Remove the added ${write.section} memory text.`,\n\t\t\t};\n\t\tcase \"memory_replace\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_restore\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Replace the new memory text with the original text it overwrote.\",\n\t\t\t};\n\t\tcase \"memory_remove\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_add\",\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Re-add the removed text to the MEMORY file (it may originally have lived in USER).\",\n\t\t\t};\n\t\tcase \"promote_skill\":\n\t\t\treturn {\n\t\t\t\tkind: \"archive_skill\",\n\t\t\t\ttarget: write.name,\n\t\t\t\tinstructions: \"Archive the promoted skill so it no longer loads.\",\n\t\t\t};\n\t}\n}\n\nconst AUDIT_ACTIONS: readonly string[] = [\"apply\", \"apply_failed\", \"propose\", \"rollback\"];\nconst ROLLBACK_KINDS: readonly string[] = [\"memory_remove\", \"memory_restore\", \"memory_add\", \"archive_skill\"];\nconst LAYERS: readonly string[] = [\"memory\", \"skill\", \"prompt\", \"extension\", \"tool\", \"script\", \"settings\", \"source\"];\n\nfunction isOptionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nfunction isLearningRollbackPlan(value: unknown): value is LearningRollbackPlan {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst plan = value as Record<string, unknown>;\n\tif (typeof plan.kind !== \"string\" || !ROLLBACK_KINDS.includes(plan.kind)) return false;\n\tif (!isOptionalString(plan.target) || !isOptionalString(plan.previous)) return false;\n\treturn typeof plan.instructions === \"string\";\n}\n\nfunction isLearningDecisionShape(value: unknown): value is LearningDecision {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst decision = value as Record<string, unknown>;\n\treturn (\n\t\t(decision.kind === \"no-op\" || decision.kind === \"proposal\" || decision.kind === \"apply\") &&\n\t\ttypeof decision.reasonCode === \"string\" &&\n\t\ttypeof decision.confidence === \"number\" &&\n\t\ttypeof decision.summary === \"string\" &&\n\t\ttypeof decision.requiresApproval === \"boolean\"\n\t);\n}\n\nexport function isLearningAuditRecord(value: unknown): value is LearningAuditRecord {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst record = value as Record<string, unknown>;\n\tif (typeof record.id !== \"string\" || record.id.length === 0) return false;\n\tif (typeof record.proposalId !== \"string\") return false;\n\tif (typeof record.layer !== \"string\" || !LAYERS.includes(record.layer)) return false;\n\tif (typeof record.action !== \"string\" || !AUDIT_ACTIONS.includes(record.action)) return false;\n\tif (typeof record.summary !== \"string\" || typeof record.reasonCode !== \"string\") return false;\n\tif (!isLearningDecisionShape(record.decision)) return false;\n\tif (record.rollback !== undefined && !isLearningRollbackPlan(record.rollback)) return false;\n\tif (!isOptionalString(record.rollbackOf)) return false;\n\treturn typeof record.createdAt === \"string\";\n}\n\nexport function cloneLearningAuditRecordForStorage(record: LearningAuditRecord): LearningAuditRecord {\n\treturn {\n\t\t...record,\n\t\tdecision: { ...record.decision },\n\t\t...(record.rollback ? { rollback: { ...record.rollback } } : {}),\n\t};\n}\n\nexport const LEARNING_AUDIT_CUSTOM_TYPE = \"learning_audit\";\n\nexport type LearningAuditSnapshotPayload = SessionSnapshotPayload<\"record\", LearningAuditRecord>;\n\nconst LEARNING_AUDIT_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningAuditRecord, \"record\"> = {\n\tcustomType: LEARNING_AUDIT_CUSTOM_TYPE,\n\tvalueKey: \"record\",\n\tisValue: isLearningAuditRecord,\n\tclone: cloneLearningAuditRecordForStorage,\n};\n\nexport function appendLearningAuditSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trecord: LearningAuditRecord,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_AUDIT_SNAPSHOT_CODEC, record);\n}\n\nexport function getLearningAuditSnapshots(entries: readonly SessionEntry[]): LearningAuditRecord[] {\n\treturn getSessionSnapshots(entries, LEARNING_AUDIT_SNAPSHOT_CODEC);\n}\n"]}

package/dist/core/learning/learning-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learning-gate.d.ts","sourceRoot":"","sources":["../../../src/core/learning/learning-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAC3B,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEZ,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;2FACuF;IACvF,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC;AA2BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC9C,QAAQ,EAAE,qBAAqB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,gBAAgB,CAoHnB;AAQD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAc5E;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAS5F","sourcesContent":["import type { LearningDecision } from \"../autonomy/contracts.ts\";\n\nexport type DurableChangeLayer =\n\t| \"memory\"\n\t| \"skill\"\n\t| \"prompt\"\n\t| \"extension\"\n\t| \"tool\"\n\t| \"script\"\n\t| \"settings\"\n\t| \"source\";\n\nexport interface DurableChangeProposal {\n\tid: string;\n\tlayer: DurableChangeLayer;\n\tsummary: string;\n\tevidenceIds?: readonly string[];\n\trollbackPlan?: string;\n}\n\nexport interface LearningGateSettings {\n\tenabled: boolean;\n\tautoApplyEnabled: boolean;\n\tconfidenceThreshold: number;\n\tminObservations: number;\n\tallowedAutoApplyLayers: readonly DurableChangeLayer[];\n\trequireRollbackPlan?: boolean;\n\trequireEvidence?: boolean;\n\t/** default: false — a memory_replace/memory_remove (supersedes/deletes an existing fact) stays an\n\t * approval-gated proposal even when otherwise eligible, unless explicitly opted in. */\n\tautoApplySupersessions?: boolean;\n}\n\nconst MAX_DECISION_SUMMARY_LENGTH = 240;\n\nfunction boundedDecisionSummary(summary: string): string {\n\tif (summary.length <= MAX_DECISION_SUMMARY_LENGTH) return summary;\n\treturn `${summary.slice(0, MAX_DECISION_SUMMARY_LENGTH - 1)}…`;\n}\n\nfunction learningDecision(args: {\n\tkind: LearningDecision[\"kind\"];\n\treasonCode: string;\n\tconfidence: number;\n\tsummary: string;\n\trequiresApproval: boolean;\n\tcreatedAt?: string;\n}): LearningDecision {\n\treturn {\n\t\tkind: args.kind,\n\t\treasonCode: args.reasonCode,\n\t\tconfidence: args.confidence,\n\t\tsummary: boundedDecisionSummary(args.summary),\n\t\trequiresApproval: args.requiresApproval,\n\t\tcreatedAt: args.createdAt,\n\t};\n}\n\nexport function evaluateLearningDecision(args: {\n\tproposal: DurableChangeProposal;\n\tconfidence: number;\n\tobservations: number;\n\tcontradictions: number;\n\tsettings: LearningGateSettings;\n\tnow?: string;\n}): LearningDecision {\n\tconst { proposal, confidence, observations, contradictions, settings, now } = args;\n\n\tif (!settings.enabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"no-op\",\n\t\t\treasonCode: \"learning_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: false,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\t// A replace/remove supersedes or deletes an existing fact — the reflection engine's\n\t// confront-before-write conflict signal — so by default it routes through approval rather than\n\t// silently overwriting prior memory. With `autoApplySupersessions` opted in, that signal no longer\n\t// short-circuits the decision outright: it FALLS THROUGH to the standard eligibility chain below,\n\t// so a supersession auto-applies only when everything else (threshold/observations/evidence/\n\t// rollback/autoApplyEnabled/layer) also passes.\n\tif (contradictions > 0 && !settings.autoApplySupersessions) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"contradictions_present\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (confidence < settings.confidenceThreshold) {\n\t\t// Below-threshold confidence degrades to an approval-gated proposal, never a silent no-op:\n\t\t// learning stays fail-closed (it can only auto-apply above the threshold) while remaining\n\t\t// VISIBLE and audited. A silent no-op here disabled learning entirely under stock settings\n\t\t// (reflectionSourceConfidence < confidenceThreshold, reflection writes carrying no evidenceIds).\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"below_confidence_threshold\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (observations < settings.minObservations) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"insufficient_observations\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (settings.requireEvidence) {\n\t\tconst hasEvidence = !!(proposal.evidenceIds && proposal.evidenceIds.length > 0);\n\t\tif (!hasEvidence) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_evidence\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (settings.requireRollbackPlan) {\n\t\tconst hasRollback = proposal.rollbackPlan !== undefined && proposal.rollbackPlan.trim().length > 0;\n\t\tif (!hasRollback) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_rollback_plan\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (!settings.autoApplyEnabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"auto_apply_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tconst isAllowed = settings.allowedAutoApplyLayers.includes(proposal.layer);\n\tif (!isAllowed) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"layer_not_allowed_for_auto_apply\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\treturn learningDecision({\n\t\tkind: \"apply\",\n\t\treasonCode: \"eligible_auto_apply\",\n\t\tconfidence,\n\t\tsummary: proposal.summary,\n\t\trequiresApproval: false,\n\t\tcreatedAt: now,\n\t});\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function isLearningDecision(value: unknown): value is LearningDecision {\n\tif (!isPlainRecord(value)) return false;\n\n\tif (typeof value.kind !== \"string\" || ![\"no-op\", \"proposal\", \"apply\"].includes(value.kind)) {\n\t\treturn false;\n\t}\n\n\tif (typeof value.reasonCode !== \"string\") return false;\n\tif (typeof value.confidence !== \"number\" || !Number.isFinite(value.confidence)) return false;\n\tif (typeof value.summary !== \"string\") return false;\n\tif (typeof value.requiresApproval !== \"boolean\") return false;\n\tif (value.createdAt !== undefined && typeof value.createdAt !== \"string\") return false;\n\n\treturn true;\n}\n\nexport function cloneLearningDecisionForStorage(decision: LearningDecision): LearningDecision {\n\treturn {\n\t\tkind: decision.kind,\n\t\treasonCode: decision.reasonCode,\n\t\tconfidence: decision.confidence,\n\t\tsummary: decision.summary,\n\t\trequiresApproval: decision.requiresApproval,\n\t\tcreatedAt: decision.createdAt,\n\t};\n}\n"]}
+{"version":3,"file":"learning-gate.d.ts","sourceRoot":"","sources":["../../../src/core/learning/learning-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,MAAM,MAAM,kBAAkB,GAC3B,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEZ,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;2FACuF;IACvF,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC;AA2BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC9C,QAAQ,EAAE,qBAAqB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,gBAAgB,CAoHnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAc5E;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAS5F","sourcesContent":["import type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\n\nexport type DurableChangeLayer =\n\t| \"memory\"\n\t| \"skill\"\n\t| \"prompt\"\n\t| \"extension\"\n\t| \"tool\"\n\t| \"script\"\n\t| \"settings\"\n\t| \"source\";\n\nexport interface DurableChangeProposal {\n\tid: string;\n\tlayer: DurableChangeLayer;\n\tsummary: string;\n\tevidenceIds?: readonly string[];\n\trollbackPlan?: string;\n}\n\nexport interface LearningGateSettings {\n\tenabled: boolean;\n\tautoApplyEnabled: boolean;\n\tconfidenceThreshold: number;\n\tminObservations: number;\n\tallowedAutoApplyLayers: readonly DurableChangeLayer[];\n\trequireRollbackPlan?: boolean;\n\trequireEvidence?: boolean;\n\t/** default: false — a memory_replace/memory_remove (supersedes/deletes an existing fact) stays an\n\t * approval-gated proposal even when otherwise eligible, unless explicitly opted in. */\n\tautoApplySupersessions?: boolean;\n}\n\nconst MAX_DECISION_SUMMARY_LENGTH = 240;\n\nfunction boundedDecisionSummary(summary: string): string {\n\tif (summary.length <= MAX_DECISION_SUMMARY_LENGTH) return summary;\n\treturn `${summary.slice(0, MAX_DECISION_SUMMARY_LENGTH - 1)}…`;\n}\n\nfunction learningDecision(args: {\n\tkind: LearningDecision[\"kind\"];\n\treasonCode: string;\n\tconfidence: number;\n\tsummary: string;\n\trequiresApproval: boolean;\n\tcreatedAt?: string;\n}): LearningDecision {\n\treturn {\n\t\tkind: args.kind,\n\t\treasonCode: args.reasonCode,\n\t\tconfidence: args.confidence,\n\t\tsummary: boundedDecisionSummary(args.summary),\n\t\trequiresApproval: args.requiresApproval,\n\t\tcreatedAt: args.createdAt,\n\t};\n}\n\nexport function evaluateLearningDecision(args: {\n\tproposal: DurableChangeProposal;\n\tconfidence: number;\n\tobservations: number;\n\tcontradictions: number;\n\tsettings: LearningGateSettings;\n\tnow?: string;\n}): LearningDecision {\n\tconst { proposal, confidence, observations, contradictions, settings, now } = args;\n\n\tif (!settings.enabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"no-op\",\n\t\t\treasonCode: \"learning_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: false,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\t// A replace/remove supersedes or deletes an existing fact — the reflection engine's\n\t// confront-before-write conflict signal — so by default it routes through approval rather than\n\t// silently overwriting prior memory. With `autoApplySupersessions` opted in, that signal no longer\n\t// short-circuits the decision outright: it FALLS THROUGH to the standard eligibility chain below,\n\t// so a supersession auto-applies only when everything else (threshold/observations/evidence/\n\t// rollback/autoApplyEnabled/layer) also passes.\n\tif (contradictions > 0 && !settings.autoApplySupersessions) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"contradictions_present\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (confidence < settings.confidenceThreshold) {\n\t\t// Below-threshold confidence degrades to an approval-gated proposal, never a silent no-op:\n\t\t// learning stays fail-closed (it can only auto-apply above the threshold) while remaining\n\t\t// VISIBLE and audited. A silent no-op here disabled learning entirely under stock settings\n\t\t// (reflectionSourceConfidence < confidenceThreshold, reflection writes carrying no evidenceIds).\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"below_confidence_threshold\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (observations < settings.minObservations) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"insufficient_observations\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (settings.requireEvidence) {\n\t\tconst hasEvidence = !!(proposal.evidenceIds && proposal.evidenceIds.length > 0);\n\t\tif (!hasEvidence) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_evidence\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (settings.requireRollbackPlan) {\n\t\tconst hasRollback = proposal.rollbackPlan !== undefined && proposal.rollbackPlan.trim().length > 0;\n\t\tif (!hasRollback) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_rollback_plan\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (!settings.autoApplyEnabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"auto_apply_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tconst isAllowed = settings.allowedAutoApplyLayers.includes(proposal.layer);\n\tif (!isAllowed) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"layer_not_allowed_for_auto_apply\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\treturn learningDecision({\n\t\tkind: \"apply\",\n\t\treasonCode: \"eligible_auto_apply\",\n\t\tconfidence,\n\t\tsummary: proposal.summary,\n\t\trequiresApproval: false,\n\t\tcreatedAt: now,\n\t});\n}\n\nexport function isLearningDecision(value: unknown): value is LearningDecision {\n\tif (!isPlainRecord(value)) return false;\n\n\tif (typeof value.kind !== \"string\" || ![\"no-op\", \"proposal\", \"apply\"].includes(value.kind)) {\n\t\treturn false;\n\t}\n\n\tif (typeof value.reasonCode !== \"string\") return false;\n\tif (typeof value.confidence !== \"number\" || !Number.isFinite(value.confidence)) return false;\n\tif (typeof value.summary !== \"string\") return false;\n\tif (typeof value.requiresApproval !== \"boolean\") return false;\n\tif (value.createdAt !== undefined && typeof value.createdAt !== \"string\") return false;\n\n\treturn true;\n}\n\nexport function cloneLearningDecisionForStorage(decision: LearningDecision): LearningDecision {\n\treturn {\n\t\tkind: decision.kind,\n\t\treasonCode: decision.reasonCode,\n\t\tconfidence: decision.confidence,\n\t\tsummary: decision.summary,\n\t\trequiresApproval: decision.requiresApproval,\n\t\tcreatedAt: decision.createdAt,\n\t};\n}\n"]}

package/dist/core/learning/learning-gate.js

@@ -1,3 +1,4 @@
+import { isPlainRecord } from "../util/value-guards.js";
 const MAX_DECISION_SUMMARY_LENGTH = 240;
 function boundedDecisionSummary(summary) {
     if (summary.length <= MAX_DECISION_SUMMARY_LENGTH)
@@ -122,12 +123,6 @@ export function evaluateLearningDecision(args) {
         createdAt: now,
     });
 }
-function isPlainRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 export function isLearningDecision(value) {
     if (!isPlainRecord(value))
         return false;

package/dist/core/learning/learning-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"learning-gate.js","sourceRoot":"","sources":["../../../src/core/learning/learning-gate.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LearningDecision } from \"../autonomy/contracts.ts\";\n\nexport type DurableChangeLayer =\n\t| \"memory\"\n\t| \"skill\"\n\t| \"prompt\"\n\t| \"extension\"\n\t| \"tool\"\n\t| \"script\"\n\t| \"settings\"\n\t| \"source\";\n\nexport interface DurableChangeProposal {\n\tid: string;\n\tlayer: DurableChangeLayer;\n\tsummary: string;\n\tevidenceIds?: readonly string[];\n\trollbackPlan?: string;\n}\n\nexport interface LearningGateSettings {\n\tenabled: boolean;\n\tautoApplyEnabled: boolean;\n\tconfidenceThreshold: number;\n\tminObservations: number;\n\tallowedAutoApplyLayers: readonly DurableChangeLayer[];\n\trequireRollbackPlan?: boolean;\n\trequireEvidence?: boolean;\n\t/** default: false — a memory_replace/memory_remove (supersedes/deletes an existing fact) stays an\n\t * approval-gated proposal even when otherwise eligible, unless explicitly opted in. */\n\tautoApplySupersessions?: boolean;\n}\n\nconst MAX_DECISION_SUMMARY_LENGTH = 240;\n\nfunction boundedDecisionSummary(summary: string): string {\n\tif (summary.length <= MAX_DECISION_SUMMARY_LENGTH) return summary;\n\treturn `${summary.slice(0, MAX_DECISION_SUMMARY_LENGTH - 1)}…`;\n}\n\nfunction learningDecision(args: {\n\tkind: LearningDecision[\"kind\"];\n\treasonCode: string;\n\tconfidence: number;\n\tsummary: string;\n\trequiresApproval: boolean;\n\tcreatedAt?: string;\n}): LearningDecision {\n\treturn {\n\t\tkind: args.kind,\n\t\treasonCode: args.reasonCode,\n\t\tconfidence: args.confidence,\n\t\tsummary: boundedDecisionSummary(args.summary),\n\t\trequiresApproval: args.requiresApproval,\n\t\tcreatedAt: args.createdAt,\n\t};\n}\n\nexport function evaluateLearningDecision(args: {\n\tproposal: DurableChangeProposal;\n\tconfidence: number;\n\tobservations: number;\n\tcontradictions: number;\n\tsettings: LearningGateSettings;\n\tnow?: string;\n}): LearningDecision {\n\tconst { proposal, confidence, observations, contradictions, settings, now } = args;\n\n\tif (!settings.enabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"no-op\",\n\t\t\treasonCode: \"learning_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: false,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\t// A replace/remove supersedes or deletes an existing fact — the reflection engine's\n\t// confront-before-write conflict signal — so by default it routes through approval rather than\n\t// silently overwriting prior memory. With `autoApplySupersessions` opted in, that signal no longer\n\t// short-circuits the decision outright: it FALLS THROUGH to the standard eligibility chain below,\n\t// so a supersession auto-applies only when everything else (threshold/observations/evidence/\n\t// rollback/autoApplyEnabled/layer) also passes.\n\tif (contradictions > 0 && !settings.autoApplySupersessions) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"contradictions_present\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (confidence < settings.confidenceThreshold) {\n\t\t// Below-threshold confidence degrades to an approval-gated proposal, never a silent no-op:\n\t\t// learning stays fail-closed (it can only auto-apply above the threshold) while remaining\n\t\t// VISIBLE and audited. A silent no-op here disabled learning entirely under stock settings\n\t\t// (reflectionSourceConfidence < confidenceThreshold, reflection writes carrying no evidenceIds).\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"below_confidence_threshold\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (observations < settings.minObservations) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"insufficient_observations\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (settings.requireEvidence) {\n\t\tconst hasEvidence = !!(proposal.evidenceIds && proposal.evidenceIds.length > 0);\n\t\tif (!hasEvidence) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_evidence\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (settings.requireRollbackPlan) {\n\t\tconst hasRollback = proposal.rollbackPlan !== undefined && proposal.rollbackPlan.trim().length > 0;\n\t\tif (!hasRollback) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_rollback_plan\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (!settings.autoApplyEnabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"auto_apply_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tconst isAllowed = settings.allowedAutoApplyLayers.includes(proposal.layer);\n\tif (!isAllowed) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"layer_not_allowed_for_auto_apply\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\treturn learningDecision({\n\t\tkind: \"apply\",\n\t\treasonCode: \"eligible_auto_apply\",\n\t\tconfidence,\n\t\tsummary: proposal.summary,\n\t\trequiresApproval: false,\n\t\tcreatedAt: now,\n\t});\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function isLearningDecision(value: unknown): value is LearningDecision {\n\tif (!isPlainRecord(value)) return false;\n\n\tif (typeof value.kind !== \"string\" || ![\"no-op\", \"proposal\", \"apply\"].includes(value.kind)) {\n\t\treturn false;\n\t}\n\n\tif (typeof value.reasonCode !== \"string\") return false;\n\tif (typeof value.confidence !== \"number\" || !Number.isFinite(value.confidence)) return false;\n\tif (typeof value.summary !== \"string\") return false;\n\tif (typeof value.requiresApproval !== \"boolean\") return false;\n\tif (value.createdAt !== undefined && typeof value.createdAt !== \"string\") return false;\n\n\treturn true;\n}\n\nexport function cloneLearningDecisionForStorage(decision: LearningDecision): LearningDecision {\n\treturn {\n\t\tkind: decision.kind,\n\t\treasonCode: decision.reasonCode,\n\t\tconfidence: decision.confidence,\n\t\tsummary: decision.summary,\n\t\trequiresApproval: decision.requiresApproval,\n\t\tcreatedAt: decision.createdAt,\n\t};\n}\n"]}
+{"version":3,"file":"learning-gate.js","sourceRoot":"","sources":["../../../src/core/learning/learning-gate.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\n\nexport type DurableChangeLayer =\n\t| \"memory\"\n\t| \"skill\"\n\t| \"prompt\"\n\t| \"extension\"\n\t| \"tool\"\n\t| \"script\"\n\t| \"settings\"\n\t| \"source\";\n\nexport interface DurableChangeProposal {\n\tid: string;\n\tlayer: DurableChangeLayer;\n\tsummary: string;\n\tevidenceIds?: readonly string[];\n\trollbackPlan?: string;\n}\n\nexport interface LearningGateSettings {\n\tenabled: boolean;\n\tautoApplyEnabled: boolean;\n\tconfidenceThreshold: number;\n\tminObservations: number;\n\tallowedAutoApplyLayers: readonly DurableChangeLayer[];\n\trequireRollbackPlan?: boolean;\n\trequireEvidence?: boolean;\n\t/** default: false — a memory_replace/memory_remove (supersedes/deletes an existing fact) stays an\n\t * approval-gated proposal even when otherwise eligible, unless explicitly opted in. */\n\tautoApplySupersessions?: boolean;\n}\n\nconst MAX_DECISION_SUMMARY_LENGTH = 240;\n\nfunction boundedDecisionSummary(summary: string): string {\n\tif (summary.length <= MAX_DECISION_SUMMARY_LENGTH) return summary;\n\treturn `${summary.slice(0, MAX_DECISION_SUMMARY_LENGTH - 1)}…`;\n}\n\nfunction learningDecision(args: {\n\tkind: LearningDecision[\"kind\"];\n\treasonCode: string;\n\tconfidence: number;\n\tsummary: string;\n\trequiresApproval: boolean;\n\tcreatedAt?: string;\n}): LearningDecision {\n\treturn {\n\t\tkind: args.kind,\n\t\treasonCode: args.reasonCode,\n\t\tconfidence: args.confidence,\n\t\tsummary: boundedDecisionSummary(args.summary),\n\t\trequiresApproval: args.requiresApproval,\n\t\tcreatedAt: args.createdAt,\n\t};\n}\n\nexport function evaluateLearningDecision(args: {\n\tproposal: DurableChangeProposal;\n\tconfidence: number;\n\tobservations: number;\n\tcontradictions: number;\n\tsettings: LearningGateSettings;\n\tnow?: string;\n}): LearningDecision {\n\tconst { proposal, confidence, observations, contradictions, settings, now } = args;\n\n\tif (!settings.enabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"no-op\",\n\t\t\treasonCode: \"learning_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: false,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\t// A replace/remove supersedes or deletes an existing fact — the reflection engine's\n\t// confront-before-write conflict signal — so by default it routes through approval rather than\n\t// silently overwriting prior memory. With `autoApplySupersessions` opted in, that signal no longer\n\t// short-circuits the decision outright: it FALLS THROUGH to the standard eligibility chain below,\n\t// so a supersession auto-applies only when everything else (threshold/observations/evidence/\n\t// rollback/autoApplyEnabled/layer) also passes.\n\tif (contradictions > 0 && !settings.autoApplySupersessions) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"contradictions_present\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (confidence < settings.confidenceThreshold) {\n\t\t// Below-threshold confidence degrades to an approval-gated proposal, never a silent no-op:\n\t\t// learning stays fail-closed (it can only auto-apply above the threshold) while remaining\n\t\t// VISIBLE and audited. A silent no-op here disabled learning entirely under stock settings\n\t\t// (reflectionSourceConfidence < confidenceThreshold, reflection writes carrying no evidenceIds).\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"below_confidence_threshold\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (observations < settings.minObservations) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"insufficient_observations\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tif (settings.requireEvidence) {\n\t\tconst hasEvidence = !!(proposal.evidenceIds && proposal.evidenceIds.length > 0);\n\t\tif (!hasEvidence) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_evidence\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (settings.requireRollbackPlan) {\n\t\tconst hasRollback = proposal.rollbackPlan !== undefined && proposal.rollbackPlan.trim().length > 0;\n\t\tif (!hasRollback) {\n\t\t\treturn learningDecision({\n\t\t\t\tkind: \"proposal\",\n\t\t\t\treasonCode: \"missing_rollback_plan\",\n\t\t\t\tconfidence,\n\t\t\t\tsummary: proposal.summary,\n\t\t\t\trequiresApproval: true,\n\t\t\t\tcreatedAt: now,\n\t\t\t});\n\t\t}\n\t}\n\n\tif (!settings.autoApplyEnabled) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"auto_apply_disabled\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\tconst isAllowed = settings.allowedAutoApplyLayers.includes(proposal.layer);\n\tif (!isAllowed) {\n\t\treturn learningDecision({\n\t\t\tkind: \"proposal\",\n\t\t\treasonCode: \"layer_not_allowed_for_auto_apply\",\n\t\t\tconfidence,\n\t\t\tsummary: proposal.summary,\n\t\t\trequiresApproval: true,\n\t\t\tcreatedAt: now,\n\t\t});\n\t}\n\n\treturn learningDecision({\n\t\tkind: \"apply\",\n\t\treasonCode: \"eligible_auto_apply\",\n\t\tconfidence,\n\t\tsummary: proposal.summary,\n\t\trequiresApproval: false,\n\t\tcreatedAt: now,\n\t});\n}\n\nexport function isLearningDecision(value: unknown): value is LearningDecision {\n\tif (!isPlainRecord(value)) return false;\n\n\tif (typeof value.kind !== \"string\" || ![\"no-op\", \"proposal\", \"apply\"].includes(value.kind)) {\n\t\treturn false;\n\t}\n\n\tif (typeof value.reasonCode !== \"string\") return false;\n\tif (typeof value.confidence !== \"number\" || !Number.isFinite(value.confidence)) return false;\n\tif (typeof value.summary !== \"string\") return false;\n\tif (typeof value.requiresApproval !== \"boolean\") return false;\n\tif (value.createdAt !== undefined && typeof value.createdAt !== \"string\") return false;\n\n\treturn true;\n}\n\nexport function cloneLearningDecisionForStorage(decision: LearningDecision): LearningDecision {\n\treturn {\n\t\tkind: decision.kind,\n\t\treasonCode: decision.reasonCode,\n\t\tconfidence: decision.confidence,\n\t\tsummary: decision.summary,\n\t\trequiresApproval: decision.requiresApproval,\n\t\tcreatedAt: decision.createdAt,\n\t};\n}\n"]}

package/dist/core/learning/observation-store.d.ts

@@ -6,13 +6,22 @@
 export declare function observationKey(layer: string, summary: string): string;
 export declare class ObservationStore {
     private readonly filePath;
-    constructor(filePath: string);
-    static forAgentDir(agentDir: string): ObservationStore;
+    private readonly readOnly;
+    constructor(filePath: string, options?: {
+        readOnly?: boolean;
+    });
+    static forAgentDir(agentDir: string, options?: {
+        readOnly?: boolean;
+    }): ObservationStore;
     private load;
     private save;
     /** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */
     private evict;
-    /** Record one more observation of `key` and return the new (capped) count. */
+    /**
+     * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs
+     * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across
+     * sessions sharing an agentDir) can't both read the old count and drop one increment.
+     */
     increment(key: string, at?: string): number;
     /** Current observation count for `key` (0 if never observed). */
     get(key: string): number;

package/dist/core/learning/observation-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation-store.d.ts","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,QAAQ,EAAE,MAAM,EAE3B;IAED,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAErD;IAED,OAAO,CAAC,IAAI;IAoCZ,OAAO,CAAC,IAAI;IAKZ,6FAA6F;IAC7F,OAAO,CAAC,KAAK;IAab,8EAA8E;IAC9E,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1C;IAED,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvB;CACD","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\n\tconstructor(filePath: string) {\n\t\tthis.filePath = filePath;\n\t}\n\n\tstatic forAgentDir(agentDir: string): ObservationStore {\n\t\treturn new ObservationStore(join(agentDir, \"state\", \"learning-observations.json\"));\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\tmkdirSync(dirname(this.filePath), { recursive: true });\n\t\twriteFileSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`, \"utf-8\");\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/** Record one more observation of `key` and return the new (capped) count. */\n\tincrement(key: string, at?: string): number {\n\t\tconst file = this.load();\n\t\tconst now = at ?? new Date().toISOString();\n\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\tfile.observations[key] = { count, lastAt: now };\n\t\tthis.evict(file);\n\t\tthis.save(file);\n\t\treturn count;\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}
+{"version":3,"file":"observation-store.d.ts","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,EAG7D;IAED,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,gBAAgB,CAEvF;IAED,OAAO,CAAC,IAAI;IAoCZ,OAAO,CAAC,IAAI;IAIZ,6FAA6F;IAC7F,OAAO,CAAC,KAAK;IAab;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1C;IAED,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvB;CACD","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport { isWorkerSession } from \"../session-role.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate. The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(filePath: string, options?: { readOnly?: boolean }) {\n\t\tthis.filePath = filePath;\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tstatic forAgentDir(agentDir: string, options?: { readOnly?: boolean }): ObservationStore {\n\t\treturn new ObservationStore(stateFile(agentDir, \"learning-observations.json\"), options);\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\twriteFileAtomicSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`);\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/**\n\t * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs\n\t * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across\n\t * sessions sharing an agentDir) can't both read the old count and drop one increment.\n\t */\n\tincrement(key: string, at?: string): number {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): no lock, no dir, no write -- just the pure-read\n\t\t\t// equivalent of what a real increment would have returned.\n\t\t\tconst file = this.load();\n\t\t\treturn Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t}\n\t\tconst now = at ?? new Date().toISOString();\n\t\treturn withFileLockSync(this.filePath, () => {\n\t\t\tconst file = this.load();\n\t\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t\tfile.observations[key] = { count, lastAt: now };\n\t\t\tthis.evict(file);\n\t\t\tthis.save(file);\n\t\t\treturn count;\n\t\t});\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}

package/dist/core/learning/observation-store.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { stateFile } from "../agent-paths.js";
+import { isWorkerSession } from "../session-role.js";
+import { withFileLockSync, writeFileAtomicSync } from "../util/atomic-file.js";
 /**
- * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a
+ * Durable, BOUNDED evidence-strength store for the learning gate. The gate auto-applies a
  * durable change only once it has been *observed* enough times; a single reflection pass sees a
  * lesson once, so without persistence every proposal would look brand-new and never accumulate the
  * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by
@@ -26,11 +28,13 @@ export function observationKey(layer, summary) {
 }
 export class ObservationStore {
     filePath;
-    constructor(filePath) {
+    readOnly;
+    constructor(filePath, options) {
         this.filePath = filePath;
+        this.readOnly = options?.readOnly ?? isWorkerSession();
     }
-    static forAgentDir(agentDir) {
-        return new ObservationStore(join(agentDir, "state", "learning-observations.json"));
+    static forAgentDir(agentDir, options) {
+        return new ObservationStore(stateFile(agentDir, "learning-observations.json"), options);
     }
     load() {
         try {
@@ -66,8 +70,7 @@ export class ObservationStore {
         return { version: 1, observations: {} };
     }
     save(file) {
-        mkdirSync(dirname(this.filePath), { recursive: true });
-        writeFileSync(this.filePath, `${JSON.stringify(file, null, "\t")}\n`, "utf-8");
+        writeFileAtomicSync(this.filePath, `${JSON.stringify(file, null, "\t")}\n`);
     }
     /** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */
     evict(file) {
@@ -83,15 +86,27 @@ export class ObservationStore {
             delete file.observations[key];
         }
     }
-    /** Record one more observation of `key` and return the new (capped) count. */
+    /**
+     * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs
+     * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across
+     * sessions sharing an agentDir) can't both read the old count and drop one increment.
+     */
     increment(key, at) {
-        const file = this.load();
+        if (this.readOnly) {
+            // Zero-footprint (worker session): no lock, no dir, no write -- just the pure-read
+            // equivalent of what a real increment would have returned.
+            const file = this.load();
+            return Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
+        }
         const now = at ?? new Date().toISOString();
-        const count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
-        file.observations[key] = { count, lastAt: now };
-        this.evict(file);
-        this.save(file);
-        return count;
+        return withFileLockSync(this.filePath, () => {
+            const file = this.load();
+            const count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
+            file.observations[key] = { count, lastAt: now };
+            this.evict(file);
+            this.save(file);
+            return count;
+        });
     }
     /** Current observation count for `key` (0 if never observed). */
     get(key) {

package/dist/core/learning/observation-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"observation-store.js","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\n\tconstructor(filePath: string) {\n\t\tthis.filePath = filePath;\n\t}\n\n\tstatic forAgentDir(agentDir: string): ObservationStore {\n\t\treturn new ObservationStore(join(agentDir, \"state\", \"learning-observations.json\"));\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\tmkdirSync(dirname(this.filePath), { recursive: true });\n\t\twriteFileSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`, \"utf-8\");\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/** Record one more observation of `key` and return the new (capped) count. */\n\tincrement(key: string, at?: string): number {\n\t\tconst file = this.load();\n\t\tconst now = at ?? new Date().toISOString();\n\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\tfile.observations[key] = { count, lastAt: now };\n\t\tthis.evict(file);\n\t\tthis.save(file);\n\t\treturn count;\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}
+{"version":3,"file":"observation-store.js","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport { isWorkerSession } from \"../session-role.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate. The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(filePath: string, options?: { readOnly?: boolean }) {\n\t\tthis.filePath = filePath;\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tstatic forAgentDir(agentDir: string, options?: { readOnly?: boolean }): ObservationStore {\n\t\treturn new ObservationStore(stateFile(agentDir, \"learning-observations.json\"), options);\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\twriteFileAtomicSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`);\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/**\n\t * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs\n\t * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across\n\t * sessions sharing an agentDir) can't both read the old count and drop one increment.\n\t */\n\tincrement(key: string, at?: string): number {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): no lock, no dir, no write -- just the pure-read\n\t\t\t// equivalent of what a real increment would have returned.\n\t\t\tconst file = this.load();\n\t\t\treturn Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t}\n\t\tconst now = at ?? new Date().toISOString();\n\t\treturn withFileLockSync(this.filePath, () => {\n\t\t\tconst file = this.load();\n\t\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t\tfile.observations[key] = { count, lastAt: now };\n\t\t\tthis.evict(file);\n\t\t\tthis.save(file);\n\t\t\treturn count;\n\t\t});\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}

package/dist/core/learning/session-learning-decision.d.ts

@@ -1,10 +1,8 @@
 import type { SessionEntry, SessionManager } from "@caupulican/pi-agent-core/node";
 import type { LearningDecision } from "../autonomy/contracts.ts";
+import { type SessionSnapshotPayload } from "../session-snapshot.ts";
 export declare const LEARNING_DECISION_CUSTOM_TYPE = "learning_decision";
-export interface LearningDecisionSnapshotPayload {
-    version: 1;
-    decision: LearningDecision;
-}
+export type LearningDecisionSnapshotPayload = SessionSnapshotPayload<"decision", LearningDecision>;
 export declare function appendLearningDecisionSnapshot(sessionManager: Pick<SessionManager, "appendCustomEntry">, decision: LearningDecision): string;
 export declare function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[];
 //# sourceMappingURL=session-learning-decision.d.ts.map

package/dist/core/learning/session-learning-decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-learning-decision.d.ts","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,MAAM,WAAW,+BAA+B;IAC/C,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,gBAAgB,CAAC;CAC3B;AAED,wBAAgB,8BAA8B,CAC7C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,QAAQ,EAAE,gBAAgB,GACxB,MAAM,CAMR;AAQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAmBjG","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport interface LearningDecisionSnapshotPayload {\n\tversion: 1;\n\tdecision: LearningDecision;\n}\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\tconst payload: LearningDecisionSnapshotPayload = {\n\t\tversion: 1,\n\t\tdecision: cloneLearningDecisionForStorage(decision),\n\t};\n\treturn sessionManager.appendCustomEntry(LEARNING_DECISION_CUSTOM_TYPE, payload);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\tconst results: LearningDecision[] = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== LEARNING_DECISION_CUSTOM_TYPE) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload)) continue;\n\t\tif (payload.version !== 1) continue;\n\t\tif (!(\"decision\" in payload)) continue;\n\t\tconst decision = payload.decision;\n\t\tif (isLearningDecision(decision)) {\n\t\t\tresults.push(cloneLearningDecisionForStorage(decision));\n\t\t}\n\t}\n\n\treturn results;\n}\n"]}
+{"version":3,"file":"session-learning-decision.d.ts","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,MAAM,MAAM,+BAA+B,GAAG,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AASnG,wBAAgB,8BAA8B,CAC7C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,QAAQ,EAAE,gBAAgB,GACxB,MAAM,CAER;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAEjG","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport type LearningDecisionSnapshotPayload = SessionSnapshotPayload<\"decision\", LearningDecision>;\n\nconst LEARNING_DECISION_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningDecision, \"decision\"> = {\n\tcustomType: LEARNING_DECISION_CUSTOM_TYPE,\n\tvalueKey: \"decision\",\n\tisValue: isLearningDecision,\n\tclone: cloneLearningDecisionForStorage,\n};\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\treturn getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);\n}\n"]}

package/dist/core/learning/session-learning-decision.js

@@ -1,36 +1,16 @@
+import { appendSessionSnapshot, getSessionSnapshots, } from "../session-snapshot.js";
 import { cloneLearningDecisionForStorage, isLearningDecision } from "./learning-gate.js";
 export const LEARNING_DECISION_CUSTOM_TYPE = "learning_decision";
+const LEARNING_DECISION_SNAPSHOT_CODEC = {
+    customType: LEARNING_DECISION_CUSTOM_TYPE,
+    valueKey: "decision",
+    isValue: isLearningDecision,
+    clone: cloneLearningDecisionForStorage,
+};
 export function appendLearningDecisionSnapshot(sessionManager, decision) {
-    const payload = {
-        version: 1,
-        decision: cloneLearningDecisionForStorage(decision),
-    };
-    return sessionManager.appendCustomEntry(LEARNING_DECISION_CUSTOM_TYPE, payload);
-}
-function isPlainRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
+    return appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);
 }
 export function getLearningDecisionSnapshots(entries) {
-    const results = [];
-    for (const entry of entries) {
-        if (entry.type !== "custom" || entry.customType !== LEARNING_DECISION_CUSTOM_TYPE) {
-            continue;
-        }
-        const payload = entry.data;
-        if (!isPlainRecord(payload))
-            continue;
-        if (payload.version !== 1)
-            continue;
-        if (!("decision" in payload))
-            continue;
-        const decision = payload.decision;
-        if (isLearningDecision(decision)) {
-            results.push(cloneLearningDecisionForStorage(decision));
-        }
-    }
-    return results;
+    return getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);
 }
 //# sourceMappingURL=session-learning-decision.js.map

package/dist/core/learning/session-learning-decision.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-learning-decision.js","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEzF,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAOjE,MAAM,UAAU,8BAA8B,CAC7C,cAAyD,EACzD,QAA0B,EACjB;IACT,MAAM,OAAO,GAAoC;QAChD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,+BAA+B,CAAC,QAAQ,CAAC;KACnD,CAAC;IACF,OAAO,cAAc,CAAC,iBAAiB,CAAC,6BAA6B,EAAE,OAAO,CAAC,CAAC;AAAA,CAChF;AAED,SAAS,aAAa,CAAC,KAAc,EAAoC;IACxE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAAA,CAC5D;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAgC,EAAsB;IAClG,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,6BAA6B,EAAE,CAAC;YACnF,SAAS;QACV,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,SAAS;QACpC,IAAI,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC;YAAE,SAAS;QACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,IAAI,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC,CAAC;QACzD,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAC;AAAA,CACf","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport interface LearningDecisionSnapshotPayload {\n\tversion: 1;\n\tdecision: LearningDecision;\n}\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\tconst payload: LearningDecisionSnapshotPayload = {\n\t\tversion: 1,\n\t\tdecision: cloneLearningDecisionForStorage(decision),\n\t};\n\treturn sessionManager.appendCustomEntry(LEARNING_DECISION_CUSTOM_TYPE, payload);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\tconst results: LearningDecision[] = [];\n\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== LEARNING_DECISION_CUSTOM_TYPE) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst payload = entry.data;\n\t\tif (!isPlainRecord(payload)) continue;\n\t\tif (payload.version !== 1) continue;\n\t\tif (!(\"decision\" in payload)) continue;\n\t\tconst decision = payload.decision;\n\t\tif (isLearningDecision(decision)) {\n\t\t\tresults.push(cloneLearningDecisionForStorage(decision));\n\t\t}\n\t}\n\n\treturn results;\n}\n"]}
+{"version":3,"file":"session-learning-decision.js","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,qBAAqB,EACrB,mBAAmB,GAGnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEzF,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAIjE,MAAM,gCAAgC,GAAuD;IAC5F,UAAU,EAAE,6BAA6B;IACzC,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,+BAA+B;CACtC,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAC7C,cAAyD,EACzD,QAA0B,EACjB;IACT,OAAO,qBAAqB,CAAC,cAAc,EAAE,gCAAgC,EAAE,QAAQ,CAAC,CAAC;AAAA,CACzF;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAgC,EAAsB;IAClG,OAAO,mBAAmB,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC;AAAA,CACtE","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport type LearningDecisionSnapshotPayload = SessionSnapshotPayload<\"decision\", LearningDecision>;\n\nconst LEARNING_DECISION_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningDecision, \"decision\"> = {\n\tcustomType: LEARNING_DECISION_CUSTOM_TYPE,\n\tvalueKey: \"decision\",\n\tisValue: isLearningDecision,\n\tclone: cloneLearningDecisionForStorage,\n};\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\treturn getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);\n}\n"]}

package/dist/core/learning/skill-curator.d.ts

@@ -54,7 +54,11 @@ export declare class SkillCurator {
     private readonly archiveDir;
     private readonly usageFile;
     constructor(skillsDir: string);
-    /** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */
+    /**
+     * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.
+     * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions
+     * loading the same skill around the same time) can't both read the old usage map and drop a count.
+     */
     recordUse(name: string, now: number): void;
     /** Build the proposals from the current promoted-skill corpus. */
     proposeCuration(now: number, options?: Partial<Omit<CuratorOptions, "now">>): CurationProposals;

package/dist/core/learning/skill-curator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,uFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED,2FAA2F;IAC3F,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CASzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAezG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\tconst usage = this.loadUsage();\n\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\twriteFileSync(this.usageFile, JSON.stringify(usage, null, 2), \"utf-8\");\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\tlet release: (() => Promise<void>) | undefined;\n\t\ttry {\n\t\t\trelease = await lockfile.lock(this.skillsDir, { realpath: false, retries: 2 });\n\t\t\tconst archived: string[] = [];\n\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t}\n\t\t\treturn archived;\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t} finally {\n\t\t\tif (release) await release().catch(() => {});\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}
+{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,uFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBzG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}