@caupulican/pi-adaptative 0.80.86 → 0.80.88

package/dist/core/context/context-prompt-policy.js

@@ -0,0 +1,73 @@
+/**
+ * Observe-first shadow/planning layer, one step closer to prompt construction than
+ * context-audit.ts (Phase 1). This module re-shapes an already-computed `ContextAuditReport`
+ * into a deterministic per-item policy plan, and can correlate that plan against the
+ * legacy context-gc's actual packed records. It never enforces anything: `appliedAction` is
+ * a literal `"keep_raw"` on every item -- the type itself makes it impossible for this
+ * module to report having changed prompt behavior. Nothing here mutates messages, the
+ * transcript, or artifact references; it only reads an already-computed report.
+ *
+ * Single source of truth for feature/flag construction remains context-audit.ts
+ * (`buildPolicyFeatures`/`buildHardConstraintFlags`): this module reuses the hard-constraint
+ * codes already computed there rather than reconstructing them, so there is exactly one
+ * place that decides how a tool_output item's PolicyFeatures/HardConstraintFlags are built.
+ */
+/**
+ * Deterministic re-shaping of an audit report into the shadow policy plan shape. Pure: no
+ * I/O, no mutation, given the same audit report this always returns an equal result.
+ */
+export function planPromptPolicy(auditReport) {
+    return {
+        turnIndex: auditReport.turnIndex,
+        items: auditReport.items.map((entry) => ({
+            itemId: entry.item.id,
+            kind: entry.item.kind,
+            retentionClass: entry.item.retentionClass,
+            source: entry.item.source,
+            toolCallId: entry.toolCallId,
+            messageIndex: entry.messageIndex,
+            primaryRefType: entry.item.primaryRef?.type,
+            hasAvailableRetrievalPath: entry.item.primaryRef?.type === "artifact",
+            allowedRetentionActions: entry.retention.allowedActions,
+            hardConstraints: {
+                keepRaw: entry.keepRawHardConstraints,
+                packToArtifact: entry.packToArtifactHardConstraints,
+                dropFromPrompt: entry.dropFromPromptHardConstraints,
+                summarize: entry.summarizeHardConstraints,
+            },
+            appliedAction: "keep_raw",
+        })),
+    };
+}
+/**
+ * Report-only correlation between the shadow plan and what the legacy context-gc pass
+ * actually did this turn. Does not influence context-gc in any way -- it runs after gc has
+ * already produced its report, purely to observe what each side did/would do.
+ *
+ * Deliberately does not derive an "agrees with legacy gc" boolean: legacy context-gc
+ * "packing" summarizes/stubs a tool result in place (provider-visible content shrinks in
+ * place), while the policy action `pack_to_artifact` means artifact-backed capture and
+ * out-of-band retrieval -- a different operation with different semantics, not a
+ * calibrated equivalent. Collapsing them into one "agreement" boolean would overclaim
+ * semantic agreement between the two and risk a later enforcement slice mistaking this
+ * observe-only diagnostic for a calibrated authority. The raw booleans below are reported
+ * as-is; comparing them is left to the reader.
+ */
+export function correlateWithContextGc(shadowReport, gcReport) {
+    const packedByToolCallId = new Map();
+    for (const record of gcReport.records)
+        packedByToolCallId.set(record.toolCallId, record);
+    const entries = shadowReport.items.map((item) => {
+        const gcRecord = packedByToolCallId.get(item.toolCallId);
+        return {
+            itemId: item.itemId,
+            toolCallId: item.toolCallId,
+            actuallyPackedByLegacyGc: gcRecord !== undefined,
+            gcPackReason: gcRecord?.reason,
+            policyWouldAllowPack: item.hardConstraints.packToArtifact.length === 0,
+            policyWouldAllowDrop: item.hardConstraints.dropFromPrompt.length === 0,
+        };
+    });
+    return { turnIndex: shadowReport.turnIndex, entries };
+}
+//# sourceMappingURL=context-prompt-policy.js.map

package/dist/core/context/context-prompt-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-policy.js","sourceRoot":"","sources":["../../../src/core/context/context-prompt-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA8CH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAA+B,EAA4B;IAC3F,OAAO;QACN,SAAS,EAAE,WAAW,CAAC,SAAS;QAChC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACxC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE;YACrB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI;YACrB,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc;YACzC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;YACzB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI;YAC3C,yBAAyB,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,UAAU;YACrE,uBAAuB,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc;YACvD,eAAe,EAAE;gBAChB,OAAO,EAAE,KAAK,CAAC,sBAAsB;gBACrC,cAAc,EAAE,KAAK,CAAC,6BAA6B;gBACnD,cAAc,EAAE,KAAK,CAAC,6BAA6B;gBACnD,SAAS,EAAE,KAAK,CAAC,wBAAwB;aACzC;YACD,aAAa,EAAE,UAAU;SACzB,CAAC,CAAC;KACH,CAAC;AAAA,CACF;AAmBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACrC,YAAsC,EACtC,QAAyB,EACS;IAClC,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAiC,CAAC;IACpE,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,OAAO;QAAE,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAEzF,MAAM,OAAO,GAAqC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAClF,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzD,OAAO;YACN,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,wBAAwB,EAAE,QAAQ,KAAK,SAAS;YAChD,YAAY,EAAE,QAAQ,EAAE,MAAM;YAC9B,oBAAoB,EAAE,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;YACtE,oBAAoB,EAAE,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;SACtE,CAAC;IAAA,CACF,CAAC,CAAC;IAEH,OAAO,EAAE,SAAS,EAAE,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC;AAAA,CACtD","sourcesContent":["/**\n * Observe-first shadow/planning layer, one step closer to prompt construction than\n * context-audit.ts (Phase 1). This module re-shapes an already-computed `ContextAuditReport`\n * into a deterministic per-item policy plan, and can correlate that plan against the\n * legacy context-gc's actual packed records. It never enforces anything: `appliedAction` is\n * a literal `\"keep_raw\"` on every item -- the type itself makes it impossible for this\n * module to report having changed prompt behavior. Nothing here mutates messages, the\n * transcript, or artifact references; it only reads an already-computed report.\n *\n * Single source of truth for feature/flag construction remains context-audit.ts\n * (`buildPolicyFeatures`/`buildHardConstraintFlags`): this module reuses the hard-constraint\n * codes already computed there rather than reconstructing them, so there is exactly one\n * place that decides how a tool_output item's PolicyFeatures/HardConstraintFlags are built.\n */\n\nimport type { ContextGcPackedRecord, ContextGcReport } from \"../context-gc.ts\";\nimport type { ContextAuditReport } from \"./context-audit.ts\";\nimport type { ContextEvidenceRef, ContextItemKind, ContextRetentionClass, ContextSource } from \"./context-item.ts\";\nimport type { RetentionAction } from \"./context-retention.ts\";\nimport type { PolicyHardConstraintCode } from \"./policy-types.ts\";\n\nexport interface PromptPolicyHardConstraints {\n\tkeepRaw: PolicyHardConstraintCode[];\n\tpackToArtifact: PolicyHardConstraintCode[];\n\tdropFromPrompt: PolicyHardConstraintCode[];\n\tsummarize: PolicyHardConstraintCode[];\n}\n\nexport interface PromptPolicyItemReport {\n\titemId: string;\n\tkind: ContextItemKind;\n\tretentionClass: ContextRetentionClass;\n\tsource: ContextSource;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tprimaryRefType: ContextEvidenceRef[\"type\"] | undefined;\n\t/**\n\t * True only for a resolved artifact ref, never for a transcript ref -- the same\n\t * fail-closed resolved-artifact-only rule context-audit.ts uses (a transcript ref is\n\t * provenance, not a live retrieval mechanism; see that module's doc comment).\n\t */\n\thasAvailableRetrievalPath: boolean;\n\t/** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */\n\tallowedRetentionActions: RetentionAction[];\n\thardConstraints: PromptPolicyHardConstraints;\n\t/**\n\t * This shadow/planning pass never changes behavior: the applied action is always\n\t * \"keep_raw\", regardless of what the hard-constraint/retention analysis above would\n\t * otherwise allow. Typed as a literal so nothing here can ever report applying anything\n\t * else.\n\t */\n\tappliedAction: \"keep_raw\";\n}\n\nexport interface PromptPolicyShadowReport {\n\tturnIndex: number;\n\titems: PromptPolicyItemReport[];\n}\n\n/**\n * Deterministic re-shaping of an audit report into the shadow policy plan shape. Pure: no\n * I/O, no mutation, given the same audit report this always returns an equal result.\n */\nexport function planPromptPolicy(auditReport: ContextAuditReport): PromptPolicyShadowReport {\n\treturn {\n\t\tturnIndex: auditReport.turnIndex,\n\t\titems: auditReport.items.map((entry) => ({\n\t\t\titemId: entry.item.id,\n\t\t\tkind: entry.item.kind,\n\t\t\tretentionClass: entry.item.retentionClass,\n\t\t\tsource: entry.item.source,\n\t\t\ttoolCallId: entry.toolCallId,\n\t\t\tmessageIndex: entry.messageIndex,\n\t\t\tprimaryRefType: entry.item.primaryRef?.type,\n\t\t\thasAvailableRetrievalPath: entry.item.primaryRef?.type === \"artifact\",\n\t\t\tallowedRetentionActions: entry.retention.allowedActions,\n\t\t\thardConstraints: {\n\t\t\t\tkeepRaw: entry.keepRawHardConstraints,\n\t\t\t\tpackToArtifact: entry.packToArtifactHardConstraints,\n\t\t\t\tdropFromPrompt: entry.dropFromPromptHardConstraints,\n\t\t\t\tsummarize: entry.summarizeHardConstraints,\n\t\t\t},\n\t\t\tappliedAction: \"keep_raw\",\n\t\t})),\n\t};\n}\n\nexport interface PromptPolicyGcCorrelationEntry {\n\titemId: string;\n\ttoolCallId: string;\n\t/** True if the legacy context-gc pass actually packed this item's tool result this turn. */\n\tactuallyPackedByLegacyGc: boolean;\n\tgcPackReason?: ContextGcPackedRecord[\"reason\"];\n\t/** True if the shadow plan's pack_to_artifact hard constraints did not reject packing. */\n\tpolicyWouldAllowPack: boolean;\n\t/** True if the shadow plan's drop_from_prompt hard constraints did not reject dropping. */\n\tpolicyWouldAllowDrop: boolean;\n}\n\nexport interface PromptPolicyGcCorrelationReport {\n\tturnIndex: number;\n\tentries: PromptPolicyGcCorrelationEntry[];\n}\n\n/**\n * Report-only correlation between the shadow plan and what the legacy context-gc pass\n * actually did this turn. Does not influence context-gc in any way -- it runs after gc has\n * already produced its report, purely to observe what each side did/would do.\n *\n * Deliberately does not derive an \"agrees with legacy gc\" boolean: legacy context-gc\n * \"packing\" summarizes/stubs a tool result in place (provider-visible content shrinks in\n * place), while the policy action `pack_to_artifact` means artifact-backed capture and\n * out-of-band retrieval -- a different operation with different semantics, not a\n * calibrated equivalent. Collapsing them into one \"agreement\" boolean would overclaim\n * semantic agreement between the two and risk a later enforcement slice mistaking this\n * observe-only diagnostic for a calibrated authority. The raw booleans below are reported\n * as-is; comparing them is left to the reader.\n */\nexport function correlateWithContextGc(\n\tshadowReport: PromptPolicyShadowReport,\n\tgcReport: ContextGcReport,\n): PromptPolicyGcCorrelationReport {\n\tconst packedByToolCallId = new Map<string, ContextGcPackedRecord>();\n\tfor (const record of gcReport.records) packedByToolCallId.set(record.toolCallId, record);\n\n\tconst entries: PromptPolicyGcCorrelationEntry[] = shadowReport.items.map((item) => {\n\t\tconst gcRecord = packedByToolCallId.get(item.toolCallId);\n\t\treturn {\n\t\t\titemId: item.itemId,\n\t\t\ttoolCallId: item.toolCallId,\n\t\t\tactuallyPackedByLegacyGc: gcRecord !== undefined,\n\t\t\tgcPackReason: gcRecord?.reason,\n\t\t\tpolicyWouldAllowPack: item.hardConstraints.packToArtifact.length === 0,\n\t\t\tpolicyWouldAllowDrop: item.hardConstraints.dropFromPrompt.length === 0,\n\t\t};\n\t});\n\n\treturn { turnIndex: shadowReport.turnIndex, entries };\n}\n"]}

package/dist/core/context/context-retention.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure retention-eligibility helpers for ContextItem.
+ *
+ * These functions only classify what a runtime policy is *allowed* to do with an item;
+ * they do not mutate, evict, or summarize anything themselves, and they never touch the
+ * transcript or artifact stores. Per contracts-and-retention.md, dropping from model
+ * context must never mean deleting from storage: these helpers only ever describe prompt
+ * inclusion, not deletion.
+ */
+import { type ContextItem } from "./context-item.ts";
+export type RetentionAction = "keep_raw" | "summarize" | "pack_to_artifact" | "drop_from_prompt";
+export interface RetentionEligibility {
+    /** Actions a runtime policy may choose between for this item, most-preserving first. */
+    allowedActions: RetentionAction[];
+    /** True if the item's semantics must stay present verbatim; only "keep_raw" is allowed. */
+    hardRetained: boolean;
+    reasonCodes: string[];
+}
+/**
+ * True if `kind`/`retentionClass` combination must never be dropped or summarized away,
+ * regardless of budget pressure. Mirrors the "Hard retention rules" in
+ * contracts-and-retention.md: pinned items and the explicitly hard-retained kinds
+ * (user instructions, approvals, denials, safety constraints).
+ */
+export declare function isHardRetained(item: ContextItem): boolean;
+/**
+ * Determine which prompt-retention actions are permitted for an item. This is the pure
+ * policy helper referenced by implementation-phases.md Phase 1: it must never allow
+ * dropping pinned/open/latest-failure items, and it must never allow summarizing
+ * decision-bearing content that has no evidence/retrieval path.
+ */
+export declare function evaluateRetentionEligibility(item: ContextItem): RetentionEligibility;
+export declare function canDropFromPrompt(item: ContextItem): boolean;
+export declare function canSummarize(item: ContextItem): boolean;
+export declare function canPackToArtifact(item: ContextItem): boolean;
+//# sourceMappingURL=context-retention.d.ts.map

package/dist/core/context/context-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-retention.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,WAAW,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEjG,MAAM,WAAW,oBAAoB;IACpC,wFAAwF;IACxF,cAAc,EAAE,eAAe,EAAE,CAAC;IAClC,2FAA2F;IAC3F,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,WAAW,GAAG,oBAAoB,CAiEpF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE5D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE5D","sourcesContent":["/**\n * Pure retention-eligibility helpers for ContextItem.\n *\n * These functions only classify what a runtime policy is *allowed* to do with an item;\n * they do not mutate, evict, or summarize anything themselves, and they never touch the\n * transcript or artifact stores. Per contracts-and-retention.md, dropping from model\n * context must never mean deleting from storage: these helpers only ever describe prompt\n * inclusion, not deletion.\n */\n\nimport { type ContextItem, HARD_RETAINED_CONTEXT_KINDS } from \"./context-item.ts\";\n\nexport type RetentionAction = \"keep_raw\" | \"summarize\" | \"pack_to_artifact\" | \"drop_from_prompt\";\n\nexport interface RetentionEligibility {\n\t/** Actions a runtime policy may choose between for this item, most-preserving first. */\n\tallowedActions: RetentionAction[];\n\t/** True if the item's semantics must stay present verbatim; only \"keep_raw\" is allowed. */\n\thardRetained: boolean;\n\treasonCodes: string[];\n}\n\n/**\n * True if the item carries a ref at all. This is item-level and store-free by design: it\n * does not check whether an artifact ref is still resolvable in a live artifact store\n * (that check belongs to a store-aware layer, e.g. `HardConstraintFlags` in\n * policy-types.ts). Do not treat this as \"retrieval is available\" when wiring a real store.\n */\nfunction hasReferencedEvidence(item: ContextItem): boolean {\n\treturn item.primaryRef !== undefined || (item.evidenceRefs?.length ?? 0) > 0;\n}\n\n/**\n * True if `kind`/`retentionClass` combination must never be dropped or summarized away,\n * regardless of budget pressure. Mirrors the \"Hard retention rules\" in\n * contracts-and-retention.md: pinned items and the explicitly hard-retained kinds\n * (user instructions, approvals, denials, safety constraints).\n */\nexport function isHardRetained(item: ContextItem): boolean {\n\treturn item.retentionClass === \"pinned\" || HARD_RETAINED_CONTEXT_KINDS.has(item.kind);\n}\n\n/**\n * Determine which prompt-retention actions are permitted for an item. This is the pure\n * policy helper referenced by implementation-phases.md Phase 1: it must never allow\n * dropping pinned/open/latest-failure items, and it must never allow summarizing\n * decision-bearing content that has no evidence/retrieval path.\n */\nexport function evaluateRetentionEligibility(item: ContextItem): RetentionEligibility {\n\tif (isHardRetained(item)) {\n\t\treturn {\n\t\t\tallowedActions: [\"keep_raw\"],\n\t\t\thardRetained: true,\n\t\t\treasonCodes: [item.retentionClass === \"pinned\" ? \"pinned_hard_retained\" : \"hard_retained_kind\"],\n\t\t};\n\t}\n\n\tconst retrievable = hasReferencedEvidence(item);\n\n\tswitch (item.retentionClass) {\n\t\tcase \"active\":\n\t\t\t// Current working state (active goal, open requirement, plan, blocker):\n\t\t\t// must stay present while active. Summarizing requires evidence so the\n\t\t\t// summary does not silently lose decision-bearing facts.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable ? [\"keep_raw\", \"summarize\"] : [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"active_summarizable\"] : [\"active_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"decision_bearing\":\n\t\t\t// Evidence for a current decision (latest failing check, current diff, etc.):\n\t\t\t// keep while the decision is pending. Only summarizable with an evidence ref\n\t\t\t// so exact identifiers remain recoverable.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable ? [\"keep_raw\", \"summarize\"] : [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"decision_bearing_summarizable\"] : [\"decision_bearing_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"useful\":\n\t\t\t// Can be summarized or evicted if budget is tight AND retrieval is available.\n\t\t\t// With no retrieval/source ref, the conservative default is keep_raw only.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable\n\t\t\t\t\t? [\"keep_raw\", \"summarize\", \"pack_to_artifact\", \"drop_from_prompt\"]\n\t\t\t\t\t: [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"useful_retrievable\"] : [\"useful_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"ephemeral\":\n\t\t\t// Should not be resent raw after immediate use (broad search output, command\n\t\t\t// logs, old file reads). Packing/dropping requires a retrieval path per the\n\t\t\t// \"retrieval precedes aggressive eviction\" ground rule.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable\n\t\t\t\t\t? [\"keep_raw\", \"pack_to_artifact\", \"drop_from_prompt\"]\n\t\t\t\t\t: [\"keep_raw\", \"pack_to_artifact\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"ephemeral_retrievable\"] : [\"ephemeral_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"expired\":\n\t\t\t// Should not be included in prompt unless explicitly retrieved.\n\t\t\treturn {\n\t\t\t\tallowedActions: [\"drop_from_prompt\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: [\"expired\"],\n\t\t\t};\n\t\tdefault:\n\t\t\treturn {\n\t\t\t\tallowedActions: [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: [\"unknown_retention_class\"],\n\t\t\t};\n\t}\n}\n\nexport function canDropFromPrompt(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"drop_from_prompt\");\n}\n\nexport function canSummarize(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"summarize\");\n}\n\nexport function canPackToArtifact(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"pack_to_artifact\");\n}\n"]}

package/dist/core/context/context-retention.js

@@ -0,0 +1,108 @@
+/**
+ * Pure retention-eligibility helpers for ContextItem.
+ *
+ * These functions only classify what a runtime policy is *allowed* to do with an item;
+ * they do not mutate, evict, or summarize anything themselves, and they never touch the
+ * transcript or artifact stores. Per contracts-and-retention.md, dropping from model
+ * context must never mean deleting from storage: these helpers only ever describe prompt
+ * inclusion, not deletion.
+ */
+import { HARD_RETAINED_CONTEXT_KINDS } from "./context-item.js";
+/**
+ * True if the item carries a ref at all. This is item-level and store-free by design: it
+ * does not check whether an artifact ref is still resolvable in a live artifact store
+ * (that check belongs to a store-aware layer, e.g. `HardConstraintFlags` in
+ * policy-types.ts). Do not treat this as "retrieval is available" when wiring a real store.
+ */
+function hasReferencedEvidence(item) {
+    return item.primaryRef !== undefined || (item.evidenceRefs?.length ?? 0) > 0;
+}
+/**
+ * True if `kind`/`retentionClass` combination must never be dropped or summarized away,
+ * regardless of budget pressure. Mirrors the "Hard retention rules" in
+ * contracts-and-retention.md: pinned items and the explicitly hard-retained kinds
+ * (user instructions, approvals, denials, safety constraints).
+ */
+export function isHardRetained(item) {
+    return item.retentionClass === "pinned" || HARD_RETAINED_CONTEXT_KINDS.has(item.kind);
+}
+/**
+ * Determine which prompt-retention actions are permitted for an item. This is the pure
+ * policy helper referenced by implementation-phases.md Phase 1: it must never allow
+ * dropping pinned/open/latest-failure items, and it must never allow summarizing
+ * decision-bearing content that has no evidence/retrieval path.
+ */
+export function evaluateRetentionEligibility(item) {
+    if (isHardRetained(item)) {
+        return {
+            allowedActions: ["keep_raw"],
+            hardRetained: true,
+            reasonCodes: [item.retentionClass === "pinned" ? "pinned_hard_retained" : "hard_retained_kind"],
+        };
+    }
+    const retrievable = hasReferencedEvidence(item);
+    switch (item.retentionClass) {
+        case "active":
+            // Current working state (active goal, open requirement, plan, blocker):
+            // must stay present while active. Summarizing requires evidence so the
+            // summary does not silently lose decision-bearing facts.
+            return {
+                allowedActions: retrievable ? ["keep_raw", "summarize"] : ["keep_raw"],
+                hardRetained: false,
+                reasonCodes: retrievable ? ["active_summarizable"] : ["active_no_retrieval_path"],
+            };
+        case "decision_bearing":
+            // Evidence for a current decision (latest failing check, current diff, etc.):
+            // keep while the decision is pending. Only summarizable with an evidence ref
+            // so exact identifiers remain recoverable.
+            return {
+                allowedActions: retrievable ? ["keep_raw", "summarize"] : ["keep_raw"],
+                hardRetained: false,
+                reasonCodes: retrievable ? ["decision_bearing_summarizable"] : ["decision_bearing_no_retrieval_path"],
+            };
+        case "useful":
+            // Can be summarized or evicted if budget is tight AND retrieval is available.
+            // With no retrieval/source ref, the conservative default is keep_raw only.
+            return {
+                allowedActions: retrievable
+                    ? ["keep_raw", "summarize", "pack_to_artifact", "drop_from_prompt"]
+                    : ["keep_raw"],
+                hardRetained: false,
+                reasonCodes: retrievable ? ["useful_retrievable"] : ["useful_no_retrieval_path"],
+            };
+        case "ephemeral":
+            // Should not be resent raw after immediate use (broad search output, command
+            // logs, old file reads). Packing/dropping requires a retrieval path per the
+            // "retrieval precedes aggressive eviction" ground rule.
+            return {
+                allowedActions: retrievable
+                    ? ["keep_raw", "pack_to_artifact", "drop_from_prompt"]
+                    : ["keep_raw", "pack_to_artifact"],
+                hardRetained: false,
+                reasonCodes: retrievable ? ["ephemeral_retrievable"] : ["ephemeral_no_retrieval_path"],
+            };
+        case "expired":
+            // Should not be included in prompt unless explicitly retrieved.
+            return {
+                allowedActions: ["drop_from_prompt"],
+                hardRetained: false,
+                reasonCodes: ["expired"],
+            };
+        default:
+            return {
+                allowedActions: ["keep_raw"],
+                hardRetained: false,
+                reasonCodes: ["unknown_retention_class"],
+            };
+    }
+}
+export function canDropFromPrompt(item) {
+    return evaluateRetentionEligibility(item).allowedActions.includes("drop_from_prompt");
+}
+export function canSummarize(item) {
+    return evaluateRetentionEligibility(item).allowedActions.includes("summarize");
+}
+export function canPackToArtifact(item) {
+    return evaluateRetentionEligibility(item).allowedActions.includes("pack_to_artifact");
+}
+//# sourceMappingURL=context-retention.js.map

package/dist/core/context/context-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-retention.js","sourceRoot":"","sources":["../../../src/core/context/context-retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAoB,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAYlF;;;;;GAKG;AACH,SAAS,qBAAqB,CAAC,IAAiB,EAAW;IAC1D,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AAAA,CAC7E;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAiB,EAAW;IAC1D,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,IAAI,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACtF;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAiB,EAAwB;IACrF,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO;YACN,cAAc,EAAE,CAAC,UAAU,CAAC;YAC5B,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,CAAC,IAAI,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,oBAAoB,CAAC;SAC/F,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAEhD,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;QAC7B,KAAK,QAAQ;YACZ,wEAAwE;YACxE,uEAAuE;YACvE,yDAAyD;YACzD,OAAO;gBACN,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtE,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC;aACjF,CAAC;QACH,KAAK,kBAAkB;YACtB,8EAA8E;YAC9E,6EAA6E;YAC7E,2CAA2C;YAC3C,OAAO;gBACN,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtE,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC,CAAC,oCAAoC,CAAC;aACrG,CAAC;QACH,KAAK,QAAQ;YACZ,8EAA8E;YAC9E,2EAA2E;YAC3E,OAAO;gBACN,cAAc,EAAE,WAAW;oBAC1B,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,CAAC;oBACnE,CAAC,CAAC,CAAC,UAAU,CAAC;gBACf,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC;aAChF,CAAC;QACH,KAAK,WAAW;YACf,6EAA6E;YAC7E,4EAA4E;YAC5E,wDAAwD;YACxD,OAAO;gBACN,cAAc,EAAE,WAAW;oBAC1B,CAAC,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,CAAC;oBACtD,CAAC,CAAC,CAAC,UAAU,EAAE,kBAAkB,CAAC;gBACnC,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC;aACtF,CAAC;QACH,KAAK,SAAS;YACb,gEAAgE;YAChE,OAAO;gBACN,cAAc,EAAE,CAAC,kBAAkB,CAAC;gBACpC,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,CAAC,SAAS,CAAC;aACxB,CAAC;QACH;YACC,OAAO;gBACN,cAAc,EAAE,CAAC,UAAU,CAAC;gBAC5B,YAAY,EAAE,KAAK;gBACnB,WAAW,EAAE,CAAC,yBAAyB,CAAC;aACxC,CAAC;IACJ,CAAC;AAAA,CACD;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAW;IAC7D,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AAAA,CACtF;AAED,MAAM,UAAU,YAAY,CAAC,IAAiB,EAAW;IACxD,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAAA,CAC/E;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAW;IAC7D,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AAAA,CACtF","sourcesContent":["/**\n * Pure retention-eligibility helpers for ContextItem.\n *\n * These functions only classify what a runtime policy is *allowed* to do with an item;\n * they do not mutate, evict, or summarize anything themselves, and they never touch the\n * transcript or artifact stores. Per contracts-and-retention.md, dropping from model\n * context must never mean deleting from storage: these helpers only ever describe prompt\n * inclusion, not deletion.\n */\n\nimport { type ContextItem, HARD_RETAINED_CONTEXT_KINDS } from \"./context-item.ts\";\n\nexport type RetentionAction = \"keep_raw\" | \"summarize\" | \"pack_to_artifact\" | \"drop_from_prompt\";\n\nexport interface RetentionEligibility {\n\t/** Actions a runtime policy may choose between for this item, most-preserving first. */\n\tallowedActions: RetentionAction[];\n\t/** True if the item's semantics must stay present verbatim; only \"keep_raw\" is allowed. */\n\thardRetained: boolean;\n\treasonCodes: string[];\n}\n\n/**\n * True if the item carries a ref at all. This is item-level and store-free by design: it\n * does not check whether an artifact ref is still resolvable in a live artifact store\n * (that check belongs to a store-aware layer, e.g. `HardConstraintFlags` in\n * policy-types.ts). Do not treat this as \"retrieval is available\" when wiring a real store.\n */\nfunction hasReferencedEvidence(item: ContextItem): boolean {\n\treturn item.primaryRef !== undefined || (item.evidenceRefs?.length ?? 0) > 0;\n}\n\n/**\n * True if `kind`/`retentionClass` combination must never be dropped or summarized away,\n * regardless of budget pressure. Mirrors the \"Hard retention rules\" in\n * contracts-and-retention.md: pinned items and the explicitly hard-retained kinds\n * (user instructions, approvals, denials, safety constraints).\n */\nexport function isHardRetained(item: ContextItem): boolean {\n\treturn item.retentionClass === \"pinned\" || HARD_RETAINED_CONTEXT_KINDS.has(item.kind);\n}\n\n/**\n * Determine which prompt-retention actions are permitted for an item. This is the pure\n * policy helper referenced by implementation-phases.md Phase 1: it must never allow\n * dropping pinned/open/latest-failure items, and it must never allow summarizing\n * decision-bearing content that has no evidence/retrieval path.\n */\nexport function evaluateRetentionEligibility(item: ContextItem): RetentionEligibility {\n\tif (isHardRetained(item)) {\n\t\treturn {\n\t\t\tallowedActions: [\"keep_raw\"],\n\t\t\thardRetained: true,\n\t\t\treasonCodes: [item.retentionClass === \"pinned\" ? \"pinned_hard_retained\" : \"hard_retained_kind\"],\n\t\t};\n\t}\n\n\tconst retrievable = hasReferencedEvidence(item);\n\n\tswitch (item.retentionClass) {\n\t\tcase \"active\":\n\t\t\t// Current working state (active goal, open requirement, plan, blocker):\n\t\t\t// must stay present while active. Summarizing requires evidence so the\n\t\t\t// summary does not silently lose decision-bearing facts.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable ? [\"keep_raw\", \"summarize\"] : [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"active_summarizable\"] : [\"active_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"decision_bearing\":\n\t\t\t// Evidence for a current decision (latest failing check, current diff, etc.):\n\t\t\t// keep while the decision is pending. Only summarizable with an evidence ref\n\t\t\t// so exact identifiers remain recoverable.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable ? [\"keep_raw\", \"summarize\"] : [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"decision_bearing_summarizable\"] : [\"decision_bearing_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"useful\":\n\t\t\t// Can be summarized or evicted if budget is tight AND retrieval is available.\n\t\t\t// With no retrieval/source ref, the conservative default is keep_raw only.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable\n\t\t\t\t\t? [\"keep_raw\", \"summarize\", \"pack_to_artifact\", \"drop_from_prompt\"]\n\t\t\t\t\t: [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"useful_retrievable\"] : [\"useful_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"ephemeral\":\n\t\t\t// Should not be resent raw after immediate use (broad search output, command\n\t\t\t// logs, old file reads). Packing/dropping requires a retrieval path per the\n\t\t\t// \"retrieval precedes aggressive eviction\" ground rule.\n\t\t\treturn {\n\t\t\t\tallowedActions: retrievable\n\t\t\t\t\t? [\"keep_raw\", \"pack_to_artifact\", \"drop_from_prompt\"]\n\t\t\t\t\t: [\"keep_raw\", \"pack_to_artifact\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: retrievable ? [\"ephemeral_retrievable\"] : [\"ephemeral_no_retrieval_path\"],\n\t\t\t};\n\t\tcase \"expired\":\n\t\t\t// Should not be included in prompt unless explicitly retrieved.\n\t\t\treturn {\n\t\t\t\tallowedActions: [\"drop_from_prompt\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: [\"expired\"],\n\t\t\t};\n\t\tdefault:\n\t\t\treturn {\n\t\t\t\tallowedActions: [\"keep_raw\"],\n\t\t\t\thardRetained: false,\n\t\t\t\treasonCodes: [\"unknown_retention_class\"],\n\t\t\t};\n\t}\n}\n\nexport function canDropFromPrompt(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"drop_from_prompt\");\n}\n\nexport function canSummarize(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"summarize\");\n}\n\nexport function canPackToArtifact(item: ContextItem): boolean {\n\treturn evaluateRetentionEligibility(item).allowedActions.includes(\"pack_to_artifact\");\n}\n"]}

package/dist/core/context/context-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Context store abstraction (Phase 2): the operational index for context item metadata,
+ * retention/policy decisions, and retrieval records. Per memory-architecture.md, this is
+ * an index/state/cache layer, not the sole audit source — transcript and artifacts remain
+ * canonical. An in-memory implementation is provided for tests; sqlite-runtime-index.ts
+ * provides an explicit SQLite implementation for callers that opt into it.
+ *
+ * Nothing here is wired into session persistence or prompt construction by default yet.
+ */
+import type { ContextItem } from "./context-item.ts";
+import type { PolicyDecision } from "./policy-types.ts";
+export type RetrievalSliceKind = "metadata" | "preview" | "lines_around_error" | "file_range" | "search_sample" | "transcript_slice" | "full_artifact";
+export interface RetrievalRecord {
+    id: string;
+    contextItemId: string;
+    requestedAtTurn: number;
+    sliceKind: RetrievalSliceKind;
+    resultSummary: string;
+}
+export interface PolicyDecisionRecord {
+    id: string;
+    contextItemId?: string;
+    decision: PolicyDecision;
+    recordedAtTurn: number;
+}
+export interface ContextStore {
+    upsertItem(item: ContextItem): void;
+    getItem(id: string): ContextItem | undefined;
+    listItems(): ContextItem[];
+    removeItem(id: string): void;
+    recordPolicyDecision(record: PolicyDecisionRecord): void;
+    listPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[];
+    recordRetrieval(record: RetrievalRecord): void;
+    listRetrievals(contextItemId?: string): RetrievalRecord[];
+}
+export declare function createInMemoryContextStore(): ContextStore;
+//# sourceMappingURL=context-store.d.ts.map

package/dist/core/context/context-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,MAAM,kBAAkB,GAC3B,UAAU,GACV,SAAS,GACT,oBAAoB,GACpB,YAAY,GACZ,eAAe,GACf,kBAAkB,GAClB,eAAe,CAAC;AAEnB,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAC7C,SAAS,IAAI,WAAW,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACzD,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAAC;IAEpE,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/C,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;CAC1D;AAED,wBAAgB,0BAA0B,IAAI,YAAY,CA0CzD","sourcesContent":["/**\n * Context store abstraction (Phase 2): the operational index for context item metadata,\n * retention/policy decisions, and retrieval records. Per memory-architecture.md, this is\n * an index/state/cache layer, not the sole audit source — transcript and artifacts remain\n * canonical. An in-memory implementation is provided for tests; sqlite-runtime-index.ts\n * provides an explicit SQLite implementation for callers that opt into it.\n *\n * Nothing here is wired into session persistence or prompt construction by default yet.\n */\n\nimport type { ContextItem } from \"./context-item.ts\";\nimport type { PolicyDecision } from \"./policy-types.ts\";\n\nexport type RetrievalSliceKind =\n\t| \"metadata\"\n\t| \"preview\"\n\t| \"lines_around_error\"\n\t| \"file_range\"\n\t| \"search_sample\"\n\t| \"transcript_slice\"\n\t| \"full_artifact\";\n\nexport interface RetrievalRecord {\n\tid: string;\n\tcontextItemId: string;\n\trequestedAtTurn: number;\n\tsliceKind: RetrievalSliceKind;\n\tresultSummary: string;\n}\n\nexport interface PolicyDecisionRecord {\n\tid: string;\n\tcontextItemId?: string;\n\tdecision: PolicyDecision;\n\trecordedAtTurn: number;\n}\n\nexport interface ContextStore {\n\tupsertItem(item: ContextItem): void;\n\tgetItem(id: string): ContextItem | undefined;\n\tlistItems(): ContextItem[];\n\tremoveItem(id: string): void;\n\n\trecordPolicyDecision(record: PolicyDecisionRecord): void;\n\tlistPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[];\n\n\trecordRetrieval(record: RetrievalRecord): void;\n\tlistRetrievals(contextItemId?: string): RetrievalRecord[];\n}\n\nexport function createInMemoryContextStore(): ContextStore {\n\tconst items = new Map<string, ContextItem>();\n\tconst policyDecisions: PolicyDecisionRecord[] = [];\n\tconst retrievals: RetrievalRecord[] = [];\n\n\treturn {\n\t\tupsertItem(item: ContextItem): void {\n\t\t\titems.set(item.id, item);\n\t\t},\n\n\t\tgetItem(id: string): ContextItem | undefined {\n\t\t\treturn items.get(id);\n\t\t},\n\n\t\tlistItems(): ContextItem[] {\n\t\t\treturn Array.from(items.values());\n\t\t},\n\n\t\tremoveItem(id: string): void {\n\t\t\titems.delete(id);\n\t\t},\n\n\t\trecordPolicyDecision(record: PolicyDecisionRecord): void {\n\t\t\tpolicyDecisions.push(record);\n\t\t},\n\n\t\tlistPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[] {\n\t\t\treturn contextItemId === undefined\n\t\t\t\t? policyDecisions.slice()\n\t\t\t\t: policyDecisions.filter((record) => record.contextItemId === contextItemId);\n\t\t},\n\n\t\trecordRetrieval(record: RetrievalRecord): void {\n\t\t\tretrievals.push(record);\n\t\t},\n\n\t\tlistRetrievals(contextItemId?: string): RetrievalRecord[] {\n\t\t\treturn contextItemId === undefined\n\t\t\t\t? retrievals.slice()\n\t\t\t\t: retrievals.filter((record) => record.contextItemId === contextItemId);\n\t\t},\n\t};\n}\n"]}

package/dist/core/context/context-store.js

@@ -0,0 +1,45 @@
+/**
+ * Context store abstraction (Phase 2): the operational index for context item metadata,
+ * retention/policy decisions, and retrieval records. Per memory-architecture.md, this is
+ * an index/state/cache layer, not the sole audit source — transcript and artifacts remain
+ * canonical. An in-memory implementation is provided for tests; sqlite-runtime-index.ts
+ * provides an explicit SQLite implementation for callers that opt into it.
+ *
+ * Nothing here is wired into session persistence or prompt construction by default yet.
+ */
+export function createInMemoryContextStore() {
+    const items = new Map();
+    const policyDecisions = [];
+    const retrievals = [];
+    return {
+        upsertItem(item) {
+            items.set(item.id, item);
+        },
+        getItem(id) {
+            return items.get(id);
+        },
+        listItems() {
+            return Array.from(items.values());
+        },
+        removeItem(id) {
+            items.delete(id);
+        },
+        recordPolicyDecision(record) {
+            policyDecisions.push(record);
+        },
+        listPolicyDecisions(contextItemId) {
+            return contextItemId === undefined
+                ? policyDecisions.slice()
+                : policyDecisions.filter((record) => record.contextItemId === contextItemId);
+        },
+        recordRetrieval(record) {
+            retrievals.push(record);
+        },
+        listRetrievals(contextItemId) {
+            return contextItemId === undefined
+                ? retrievals.slice()
+                : retrievals.filter((record) => record.contextItemId === contextItemId);
+        },
+    };
+}
+//# sourceMappingURL=context-store.js.map

package/dist/core/context/context-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.js","sourceRoot":"","sources":["../../../src/core/context/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0CH,MAAM,UAAU,0BAA0B,GAAiB;IAC1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,MAAM,eAAe,GAA2B,EAAE,CAAC;IACnD,MAAM,UAAU,GAAsB,EAAE,CAAC;IAEzC,OAAO;QACN,UAAU,CAAC,IAAiB,EAAQ;YACnC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAAA,CACzB;QAED,OAAO,CAAC,EAAU,EAA2B;YAC5C,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAAA,CACrB;QAED,SAAS,GAAkB;YAC1B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAAA,CAClC;QAED,UAAU,CAAC,EAAU,EAAQ;YAC5B,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAAA,CACjB;QAED,oBAAoB,CAAC,MAA4B,EAAQ;YACxD,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAAA,CAC7B;QAED,mBAAmB,CAAC,aAAsB,EAA0B;YACnE,OAAO,aAAa,KAAK,SAAS;gBACjC,CAAC,CAAC,eAAe,CAAC,KAAK,EAAE;gBACzB,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,KAAK,aAAa,CAAC,CAAC;QAAA,CAC9E;QAED,eAAe,CAAC,MAAuB,EAAQ;YAC9C,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAAA,CACxB;QAED,cAAc,CAAC,aAAsB,EAAqB;YACzD,OAAO,aAAa,KAAK,SAAS;gBACjC,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE;gBACpB,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,KAAK,aAAa,CAAC,CAAC;QAAA,CACzE;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Context store abstraction (Phase 2): the operational index for context item metadata,\n * retention/policy decisions, and retrieval records. Per memory-architecture.md, this is\n * an index/state/cache layer, not the sole audit source — transcript and artifacts remain\n * canonical. An in-memory implementation is provided for tests; sqlite-runtime-index.ts\n * provides an explicit SQLite implementation for callers that opt into it.\n *\n * Nothing here is wired into session persistence or prompt construction by default yet.\n */\n\nimport type { ContextItem } from \"./context-item.ts\";\nimport type { PolicyDecision } from \"./policy-types.ts\";\n\nexport type RetrievalSliceKind =\n\t| \"metadata\"\n\t| \"preview\"\n\t| \"lines_around_error\"\n\t| \"file_range\"\n\t| \"search_sample\"\n\t| \"transcript_slice\"\n\t| \"full_artifact\";\n\nexport interface RetrievalRecord {\n\tid: string;\n\tcontextItemId: string;\n\trequestedAtTurn: number;\n\tsliceKind: RetrievalSliceKind;\n\tresultSummary: string;\n}\n\nexport interface PolicyDecisionRecord {\n\tid: string;\n\tcontextItemId?: string;\n\tdecision: PolicyDecision;\n\trecordedAtTurn: number;\n}\n\nexport interface ContextStore {\n\tupsertItem(item: ContextItem): void;\n\tgetItem(id: string): ContextItem | undefined;\n\tlistItems(): ContextItem[];\n\tremoveItem(id: string): void;\n\n\trecordPolicyDecision(record: PolicyDecisionRecord): void;\n\tlistPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[];\n\n\trecordRetrieval(record: RetrievalRecord): void;\n\tlistRetrievals(contextItemId?: string): RetrievalRecord[];\n}\n\nexport function createInMemoryContextStore(): ContextStore {\n\tconst items = new Map<string, ContextItem>();\n\tconst policyDecisions: PolicyDecisionRecord[] = [];\n\tconst retrievals: RetrievalRecord[] = [];\n\n\treturn {\n\t\tupsertItem(item: ContextItem): void {\n\t\t\titems.set(item.id, item);\n\t\t},\n\n\t\tgetItem(id: string): ContextItem | undefined {\n\t\t\treturn items.get(id);\n\t\t},\n\n\t\tlistItems(): ContextItem[] {\n\t\t\treturn Array.from(items.values());\n\t\t},\n\n\t\tremoveItem(id: string): void {\n\t\t\titems.delete(id);\n\t\t},\n\n\t\trecordPolicyDecision(record: PolicyDecisionRecord): void {\n\t\t\tpolicyDecisions.push(record);\n\t\t},\n\n\t\tlistPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[] {\n\t\t\treturn contextItemId === undefined\n\t\t\t\t? policyDecisions.slice()\n\t\t\t\t: policyDecisions.filter((record) => record.contextItemId === contextItemId);\n\t\t},\n\n\t\trecordRetrieval(record: RetrievalRecord): void {\n\t\t\tretrievals.push(record);\n\t\t},\n\n\t\tlistRetrievals(contextItemId?: string): RetrievalRecord[] {\n\t\t\treturn contextItemId === undefined\n\t\t\t\t? retrievals.slice()\n\t\t\t\t: retrievals.filter((record) => record.contextItemId === contextItemId);\n\t\t},\n\t};\n}\n"]}

package/dist/core/context/memory-diagnostics.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Safe, leak-free diagnostic projections of the memory-retrieval/prompt-inclusion state,
+ * for the context_audit tool (src/core/extensions/builtin.ts). Nothing here queries a
+ * provider or touches the OKF directory -- callers must pass in already-computed reports
+ * (AgentSession's existing no-arg, latest-stored-only getters).
+ *
+ * `sanitizeMemoryRetrievalReportForDiagnostics` is ALLOW-LIST based, not deny-list: it
+ * builds its output by explicitly copying only known-safe fields, never by spreading the
+ * source report and deleting unsafe ones. A spread-then-delete approach would silently
+ * re-expose any new content-bearing field added to `MemoryRetrievalReport` later; an
+ * allow-list cannot leak a field it was never told to copy.
+ */
+import type { MemoryPolicyRejectionReason } from "./memory-provider-contract.ts";
+import type { MemoryProviderRetrievalStatus, MemoryRetrievalReport } from "./memory-retrieval.ts";
+export type MemoryPromptInclusionStatus = "disabled" | "include_disabled" | "no_results" | "empty_block" | "included" | "failed";
+export interface MemoryPromptInclusionReport {
+    status: MemoryPromptInclusionStatus;
+    enabled: boolean;
+    includeInPrompt: boolean;
+    selectedItemCount: number;
+    includedCount: number;
+    omittedCount: number;
+    blockChars: number;
+    sourceLabel?: string;
+}
+export declare function defaultMemoryPromptInclusionReport(): MemoryPromptInclusionReport;
+/** Safe per-provider projection: fixed enums and counts only, never `error` (may embed a filesystem path). */
+export interface MemoryRetrievalProviderDiagnostics {
+    providerId: string;
+    status: MemoryProviderRetrievalStatus;
+    rejectionReasons: MemoryPolicyRejectionReason[];
+    resultCount: number;
+}
+export interface MemoryRetrievalDiagnostics {
+    enabled: boolean;
+    maxResults: number;
+    providerReports: MemoryRetrievalProviderDiagnostics[];
+    selectedItemCount: number;
+}
+/**
+ * Projects a live `MemoryRetrievalReport` down to only safe, bounded metadata. Drops
+ * `request.query`, every `results[]`/`contextItems[]` content field, and
+ * `providerReports[].error` entirely (never redacted -- redaction logic is itself a place
+ * a leak could slip back in).
+ */
+export declare function sanitizeMemoryRetrievalReportForDiagnostics(report: MemoryRetrievalReport, settings: {
+    enabled: boolean;
+    maxResults: number;
+}): MemoryRetrievalDiagnostics;
+//# sourceMappingURL=memory-diagnostics.d.ts.map

package/dist/core/context/memory-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/core/context/memory-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAElG,MAAM,MAAM,2BAA2B,GACpC,UAAU,GACV,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,UAAU,GACV,QAAQ,CAAC;AAEZ,MAAM,WAAW,2BAA2B;IAC3C,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,kCAAkC,IAAI,2BAA2B,CAUhF;AAED,8GAA8G;AAC9G,MAAM,WAAW,kCAAkC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,6BAA6B,CAAC;IACtC,gBAAgB,EAAE,2BAA2B,EAAE,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,kCAAkC,EAAE,CAAC;IACtD,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,2CAA2C,CAC1D,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChD,0BAA0B,CAY5B","sourcesContent":["/**\n * Safe, leak-free diagnostic projections of the memory-retrieval/prompt-inclusion state,\n * for the context_audit tool (src/core/extensions/builtin.ts). Nothing here queries a\n * provider or touches the OKF directory -- callers must pass in already-computed reports\n * (AgentSession's existing no-arg, latest-stored-only getters).\n *\n * `sanitizeMemoryRetrievalReportForDiagnostics` is ALLOW-LIST based, not deny-list: it\n * builds its output by explicitly copying only known-safe fields, never by spreading the\n * source report and deleting unsafe ones. A spread-then-delete approach would silently\n * re-expose any new content-bearing field added to `MemoryRetrievalReport` later; an\n * allow-list cannot leak a field it was never told to copy.\n */\n\nimport type { MemoryPolicyRejectionReason } from \"./memory-provider-contract.ts\";\nimport type { MemoryProviderRetrievalStatus, MemoryRetrievalReport } from \"./memory-retrieval.ts\";\n\nexport type MemoryPromptInclusionStatus =\n\t| \"disabled\"\n\t| \"include_disabled\"\n\t| \"no_results\"\n\t| \"empty_block\"\n\t| \"included\"\n\t| \"failed\";\n\nexport interface MemoryPromptInclusionReport {\n\tstatus: MemoryPromptInclusionStatus;\n\tenabled: boolean;\n\tincludeInPrompt: boolean;\n\tselectedItemCount: number;\n\tincludedCount: number;\n\tomittedCount: number;\n\tblockChars: number;\n\tsourceLabel?: string;\n}\n\nexport function defaultMemoryPromptInclusionReport(): MemoryPromptInclusionReport {\n\treturn {\n\t\tstatus: \"disabled\",\n\t\tenabled: false,\n\t\tincludeInPrompt: false,\n\t\tselectedItemCount: 0,\n\t\tincludedCount: 0,\n\t\tomittedCount: 0,\n\t\tblockChars: 0,\n\t};\n}\n\n/** Safe per-provider projection: fixed enums and counts only, never `error` (may embed a filesystem path). */\nexport interface MemoryRetrievalProviderDiagnostics {\n\tproviderId: string;\n\tstatus: MemoryProviderRetrievalStatus;\n\trejectionReasons: MemoryPolicyRejectionReason[];\n\tresultCount: number;\n}\n\nexport interface MemoryRetrievalDiagnostics {\n\tenabled: boolean;\n\tmaxResults: number;\n\tproviderReports: MemoryRetrievalProviderDiagnostics[];\n\tselectedItemCount: number;\n}\n\n/**\n * Projects a live `MemoryRetrievalReport` down to only safe, bounded metadata. Drops\n * `request.query`, every `results[]`/`contextItems[]` content field, and\n * `providerReports[].error` entirely (never redacted -- redaction logic is itself a place\n * a leak could slip back in).\n */\nexport function sanitizeMemoryRetrievalReportForDiagnostics(\n\treport: MemoryRetrievalReport,\n\tsettings: { enabled: boolean; maxResults: number },\n): MemoryRetrievalDiagnostics {\n\treturn {\n\t\tenabled: settings.enabled,\n\t\tmaxResults: settings.maxResults,\n\t\tproviderReports: report.providerReports.map((providerReport) => ({\n\t\t\tproviderId: providerReport.providerId,\n\t\t\tstatus: providerReport.status,\n\t\t\trejectionReasons: [...providerReport.rejectionReasons],\n\t\t\tresultCount: providerReport.resultCount,\n\t\t})),\n\t\tselectedItemCount: report.contextItems.length,\n\t};\n}\n"]}

package/dist/core/context/memory-diagnostics.js

@@ -0,0 +1,43 @@
+/**
+ * Safe, leak-free diagnostic projections of the memory-retrieval/prompt-inclusion state,
+ * for the context_audit tool (src/core/extensions/builtin.ts). Nothing here queries a
+ * provider or touches the OKF directory -- callers must pass in already-computed reports
+ * (AgentSession's existing no-arg, latest-stored-only getters).
+ *
+ * `sanitizeMemoryRetrievalReportForDiagnostics` is ALLOW-LIST based, not deny-list: it
+ * builds its output by explicitly copying only known-safe fields, never by spreading the
+ * source report and deleting unsafe ones. A spread-then-delete approach would silently
+ * re-expose any new content-bearing field added to `MemoryRetrievalReport` later; an
+ * allow-list cannot leak a field it was never told to copy.
+ */
+export function defaultMemoryPromptInclusionReport() {
+    return {
+        status: "disabled",
+        enabled: false,
+        includeInPrompt: false,
+        selectedItemCount: 0,
+        includedCount: 0,
+        omittedCount: 0,
+        blockChars: 0,
+    };
+}
+/**
+ * Projects a live `MemoryRetrievalReport` down to only safe, bounded metadata. Drops
+ * `request.query`, every `results[]`/`contextItems[]` content field, and
+ * `providerReports[].error` entirely (never redacted -- redaction logic is itself a place
+ * a leak could slip back in).
+ */
+export function sanitizeMemoryRetrievalReportForDiagnostics(report, settings) {
+    return {
+        enabled: settings.enabled,
+        maxResults: settings.maxResults,
+        providerReports: report.providerReports.map((providerReport) => ({
+            providerId: providerReport.providerId,
+            status: providerReport.status,
+            rejectionReasons: [...providerReport.rejectionReasons],
+            resultCount: providerReport.resultCount,
+        })),
+        selectedItemCount: report.contextItems.length,
+    };
+}
+//# sourceMappingURL=memory-diagnostics.js.map

package/dist/core/context/memory-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-diagnostics.js","sourceRoot":"","sources":["../../../src/core/context/memory-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,MAAM,UAAU,kCAAkC,GAAgC;IACjF,OAAO;QACN,MAAM,EAAE,UAAU;QAClB,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,KAAK;QACtB,iBAAiB,EAAE,CAAC;QACpB,aAAa,EAAE,CAAC;QAChB,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,CAAC;KACb,CAAC;AAAA,CACF;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,2CAA2C,CAC1D,MAA6B,EAC7B,QAAkD,EACrB;IAC7B,OAAO;QACN,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,eAAe,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;YAChE,UAAU,EAAE,cAAc,CAAC,UAAU;YACrC,MAAM,EAAE,cAAc,CAAC,MAAM;YAC7B,gBAAgB,EAAE,CAAC,GAAG,cAAc,CAAC,gBAAgB,CAAC;YACtD,WAAW,EAAE,cAAc,CAAC,WAAW;SACvC,CAAC,CAAC;QACH,iBAAiB,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM;KAC7C,CAAC;AAAA,CACF","sourcesContent":["/**\n * Safe, leak-free diagnostic projections of the memory-retrieval/prompt-inclusion state,\n * for the context_audit tool (src/core/extensions/builtin.ts). Nothing here queries a\n * provider or touches the OKF directory -- callers must pass in already-computed reports\n * (AgentSession's existing no-arg, latest-stored-only getters).\n *\n * `sanitizeMemoryRetrievalReportForDiagnostics` is ALLOW-LIST based, not deny-list: it\n * builds its output by explicitly copying only known-safe fields, never by spreading the\n * source report and deleting unsafe ones. A spread-then-delete approach would silently\n * re-expose any new content-bearing field added to `MemoryRetrievalReport` later; an\n * allow-list cannot leak a field it was never told to copy.\n */\n\nimport type { MemoryPolicyRejectionReason } from \"./memory-provider-contract.ts\";\nimport type { MemoryProviderRetrievalStatus, MemoryRetrievalReport } from \"./memory-retrieval.ts\";\n\nexport type MemoryPromptInclusionStatus =\n\t| \"disabled\"\n\t| \"include_disabled\"\n\t| \"no_results\"\n\t| \"empty_block\"\n\t| \"included\"\n\t| \"failed\";\n\nexport interface MemoryPromptInclusionReport {\n\tstatus: MemoryPromptInclusionStatus;\n\tenabled: boolean;\n\tincludeInPrompt: boolean;\n\tselectedItemCount: number;\n\tincludedCount: number;\n\tomittedCount: number;\n\tblockChars: number;\n\tsourceLabel?: string;\n}\n\nexport function defaultMemoryPromptInclusionReport(): MemoryPromptInclusionReport {\n\treturn {\n\t\tstatus: \"disabled\",\n\t\tenabled: false,\n\t\tincludeInPrompt: false,\n\t\tselectedItemCount: 0,\n\t\tincludedCount: 0,\n\t\tomittedCount: 0,\n\t\tblockChars: 0,\n\t};\n}\n\n/** Safe per-provider projection: fixed enums and counts only, never `error` (may embed a filesystem path). */\nexport interface MemoryRetrievalProviderDiagnostics {\n\tproviderId: string;\n\tstatus: MemoryProviderRetrievalStatus;\n\trejectionReasons: MemoryPolicyRejectionReason[];\n\tresultCount: number;\n}\n\nexport interface MemoryRetrievalDiagnostics {\n\tenabled: boolean;\n\tmaxResults: number;\n\tproviderReports: MemoryRetrievalProviderDiagnostics[];\n\tselectedItemCount: number;\n}\n\n/**\n * Projects a live `MemoryRetrievalReport` down to only safe, bounded metadata. Drops\n * `request.query`, every `results[]`/`contextItems[]` content field, and\n * `providerReports[].error` entirely (never redacted -- redaction logic is itself a place\n * a leak could slip back in).\n */\nexport function sanitizeMemoryRetrievalReportForDiagnostics(\n\treport: MemoryRetrievalReport,\n\tsettings: { enabled: boolean; maxResults: number },\n): MemoryRetrievalDiagnostics {\n\treturn {\n\t\tenabled: settings.enabled,\n\t\tmaxResults: settings.maxResults,\n\t\tproviderReports: report.providerReports.map((providerReport) => ({\n\t\t\tproviderId: providerReport.providerId,\n\t\t\tstatus: providerReport.status,\n\t\t\trejectionReasons: [...providerReport.rejectionReasons],\n\t\t\tresultCount: providerReport.resultCount,\n\t\t})),\n\t\tselectedItemCount: report.contextItems.length,\n\t};\n}\n"]}

package/dist/core/context/memory-index-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Memory index store abstraction (Phase 2): the operational index over durable memory
+ * refs (Pi OKF and, later, external providers), so retrieval can rank/filter without
+ * re-querying every source on every turn. This is an index/cache layer per
+ * memory-architecture.md, not the durable memory itself; the OKF bundle (or a provider)
+ * remains canonical for the underlying content.
+ *
+ * This module does not hardcode Automata or any specific provider: `ContextMemoryRef`
+ * already carries an opaque `providerId`, and nothing here special-cases a provider name.
+ * No external provider queries or writes happen here — this is metadata indexing only.
+ */
+import type { ContextMemoryRef, MemoryScope } from "./context-item.ts";
+export interface MemoryIndexRecord {
+    ref: ContextMemoryRef;
+    title?: string;
+    summary: string;
+    indexedAtTurn: number;
+    stale: boolean;
+}
+export interface MemoryIndexStore {
+    upsert(record: MemoryIndexRecord): void;
+    get(providerId: string, itemId: string): MemoryIndexRecord | undefined;
+    list(scope?: MemoryScope): MemoryIndexRecord[];
+    markStale(providerId: string, itemId: string): void;
+    remove(providerId: string, itemId: string): void;
+}
+export declare function createInMemoryMemoryIndexStore(): MemoryIndexStore;
+//# sourceMappingURL=memory-index-store.d.ts.map

package/dist/core/context/memory-index-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-index-store.d.ts","sourceRoot":"","sources":["../../../src/core/context/memory-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,gBAAgB,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACvE,IAAI,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,iBAAiB,EAAE,CAAC;IAC/C,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAMD,wBAAgB,8BAA8B,IAAI,gBAAgB,CA0BjE","sourcesContent":["/**\n * Memory index store abstraction (Phase 2): the operational index over durable memory\n * refs (Pi OKF and, later, external providers), so retrieval can rank/filter without\n * re-querying every source on every turn. This is an index/cache layer per\n * memory-architecture.md, not the durable memory itself; the OKF bundle (or a provider)\n * remains canonical for the underlying content.\n *\n * This module does not hardcode Automata or any specific provider: `ContextMemoryRef`\n * already carries an opaque `providerId`, and nothing here special-cases a provider name.\n * No external provider queries or writes happen here — this is metadata indexing only.\n */\n\nimport type { ContextMemoryRef, MemoryScope } from \"./context-item.ts\";\n\nexport interface MemoryIndexRecord {\n\tref: ContextMemoryRef;\n\ttitle?: string;\n\tsummary: string;\n\tindexedAtTurn: number;\n\tstale: boolean;\n}\n\nexport interface MemoryIndexStore {\n\tupsert(record: MemoryIndexRecord): void;\n\tget(providerId: string, itemId: string): MemoryIndexRecord | undefined;\n\tlist(scope?: MemoryScope): MemoryIndexRecord[];\n\tmarkStale(providerId: string, itemId: string): void;\n\tremove(providerId: string, itemId: string): void;\n}\n\nfunction indexKey(providerId: string, itemId: string): string {\n\treturn `${providerId}\\0${itemId}`;\n}\n\nexport function createInMemoryMemoryIndexStore(): MemoryIndexStore {\n\tconst records = new Map<string, MemoryIndexRecord>();\n\n\treturn {\n\t\tupsert(record: MemoryIndexRecord): void {\n\t\t\trecords.set(indexKey(record.ref.providerId, record.ref.itemId), record);\n\t\t},\n\n\t\tget(providerId: string, itemId: string): MemoryIndexRecord | undefined {\n\t\t\treturn records.get(indexKey(providerId, itemId));\n\t\t},\n\n\t\tlist(scope?: MemoryScope): MemoryIndexRecord[] {\n\t\t\tconst all = Array.from(records.values());\n\t\t\treturn scope === undefined ? all : all.filter((record) => record.ref.scope === scope);\n\t\t},\n\n\t\tmarkStale(providerId: string, itemId: string): void {\n\t\t\tconst record = records.get(indexKey(providerId, itemId));\n\t\t\tif (record) record.stale = true;\n\t\t},\n\n\t\tremove(providerId: string, itemId: string): void {\n\t\t\trecords.delete(indexKey(providerId, itemId));\n\t\t},\n\t};\n}\n"]}

package/dist/core/context/memory-index-store.js

@@ -0,0 +1,38 @@
+/**
+ * Memory index store abstraction (Phase 2): the operational index over durable memory
+ * refs (Pi OKF and, later, external providers), so retrieval can rank/filter without
+ * re-querying every source on every turn. This is an index/cache layer per
+ * memory-architecture.md, not the durable memory itself; the OKF bundle (or a provider)
+ * remains canonical for the underlying content.
+ *
+ * This module does not hardcode Automata or any specific provider: `ContextMemoryRef`
+ * already carries an opaque `providerId`, and nothing here special-cases a provider name.
+ * No external provider queries or writes happen here — this is metadata indexing only.
+ */
+function indexKey(providerId, itemId) {
+    return `${providerId}\0${itemId}`;
+}
+export function createInMemoryMemoryIndexStore() {
+    const records = new Map();
+    return {
+        upsert(record) {
+            records.set(indexKey(record.ref.providerId, record.ref.itemId), record);
+        },
+        get(providerId, itemId) {
+            return records.get(indexKey(providerId, itemId));
+        },
+        list(scope) {
+            const all = Array.from(records.values());
+            return scope === undefined ? all : all.filter((record) => record.ref.scope === scope);
+        },
+        markStale(providerId, itemId) {
+            const record = records.get(indexKey(providerId, itemId));
+            if (record)
+                record.stale = true;
+        },
+        remove(providerId, itemId) {
+            records.delete(indexKey(providerId, itemId));
+        },
+    };
+}
+//# sourceMappingURL=memory-index-store.js.map

package/dist/core/context/memory-index-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-index-store.js","sourceRoot":"","sources":["../../../src/core/context/memory-index-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoBH,SAAS,QAAQ,CAAC,UAAkB,EAAE,MAAc,EAAU;IAC7D,OAAO,GAAG,UAAU,KAAK,MAAM,EAAE,CAAC;AAAA,CAClC;AAED,MAAM,UAAU,8BAA8B,GAAqB;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,OAAO;QACN,MAAM,CAAC,MAAyB,EAAQ;YACvC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QAAA,CACxE;QAED,GAAG,CAAC,UAAkB,EAAE,MAAc,EAAiC;YACtE,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QAAA,CACjD;QAED,IAAI,CAAC,KAAmB,EAAuB;YAC9C,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YACzC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QAAA,CACtF;QAED,SAAS,CAAC,UAAkB,EAAE,MAAc,EAAQ;YACnD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;YACzD,IAAI,MAAM;gBAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;QAAA,CAChC;QAED,MAAM,CAAC,UAAkB,EAAE,MAAc,EAAQ;YAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;QAAA,CAC7C;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Memory index store abstraction (Phase 2): the operational index over durable memory\n * refs (Pi OKF and, later, external providers), so retrieval can rank/filter without\n * re-querying every source on every turn. This is an index/cache layer per\n * memory-architecture.md, not the durable memory itself; the OKF bundle (or a provider)\n * remains canonical for the underlying content.\n *\n * This module does not hardcode Automata or any specific provider: `ContextMemoryRef`\n * already carries an opaque `providerId`, and nothing here special-cases a provider name.\n * No external provider queries or writes happen here — this is metadata indexing only.\n */\n\nimport type { ContextMemoryRef, MemoryScope } from \"./context-item.ts\";\n\nexport interface MemoryIndexRecord {\n\tref: ContextMemoryRef;\n\ttitle?: string;\n\tsummary: string;\n\tindexedAtTurn: number;\n\tstale: boolean;\n}\n\nexport interface MemoryIndexStore {\n\tupsert(record: MemoryIndexRecord): void;\n\tget(providerId: string, itemId: string): MemoryIndexRecord | undefined;\n\tlist(scope?: MemoryScope): MemoryIndexRecord[];\n\tmarkStale(providerId: string, itemId: string): void;\n\tremove(providerId: string, itemId: string): void;\n}\n\nfunction indexKey(providerId: string, itemId: string): string {\n\treturn `${providerId}\\0${itemId}`;\n}\n\nexport function createInMemoryMemoryIndexStore(): MemoryIndexStore {\n\tconst records = new Map<string, MemoryIndexRecord>();\n\n\treturn {\n\t\tupsert(record: MemoryIndexRecord): void {\n\t\t\trecords.set(indexKey(record.ref.providerId, record.ref.itemId), record);\n\t\t},\n\n\t\tget(providerId: string, itemId: string): MemoryIndexRecord | undefined {\n\t\t\treturn records.get(indexKey(providerId, itemId));\n\t\t},\n\n\t\tlist(scope?: MemoryScope): MemoryIndexRecord[] {\n\t\t\tconst all = Array.from(records.values());\n\t\t\treturn scope === undefined ? all : all.filter((record) => record.ref.scope === scope);\n\t\t},\n\n\t\tmarkStale(providerId: string, itemId: string): void {\n\t\t\tconst record = records.get(indexKey(providerId, itemId));\n\t\t\tif (record) record.stale = true;\n\t\t},\n\n\t\tremove(providerId: string, itemId: string): void {\n\t\t\trecords.delete(indexKey(providerId, itemId));\n\t\t},\n\t};\n}\n"]}

package/dist/core/context/memory-prompt-block.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure bounding/formatting for the local-memory prompt-inclusion pilot (see
+ * memory-retrieval.ts for the observe-only retrieval this consumes). This module only ever
+ * builds bounded, plain text; it does not know about messages, the transcript, the
+ * untrusted-content boundary, or AgentSession -- all of that wiring lives in
+ * agent-session.ts, which wraps this module's output with `wrapUntrustedText` before
+ * appending it to the provider-visible prompt.
+ *
+ * These caps are the ONLY budget protection for the injected block: it is appended AFTER
+ * context-gc and prompt-policy enforcement have already run, so nothing downstream trims
+ * it. Treat `MAX_CHARS_PER_ITEM`/`MAX_TOTAL_CHARS` as load-bearing, not merely defensive.
+ */
+import type { ContextItem } from "./context-item.ts";
+export declare const MEMORY_PROMPT_BLOCK_MAX_CHARS_PER_ITEM = 300;
+export declare const MEMORY_PROMPT_BLOCK_MAX_TOTAL_CHARS = 2000;
+export interface MemoryPromptBlockOptions {
+    maxCharsPerItem?: number;
+    maxTotalChars?: number;
+}
+export interface MemoryPromptBlockResult {
+    /** undefined when there is nothing to include (no items, or all summaries empty). */
+    text: string | undefined;
+    includedCount: number;
+    omittedCount: number;
+}
+/**
+ * Builds a numbered, per-item-truncated list of memory item summaries, bounded to a hard
+ * total character budget. Always includes at least the first non-empty item (truncated to
+ * `maxCharsPerItem`, which is expected to be well under `maxTotalChars`), even if that item
+ * alone would otherwise exceed the total budget -- callers should never see a report with
+ * results but an empty block.
+ */
+export declare function buildMemoryPromptBlock(contextItems: readonly ContextItem[], options?: MemoryPromptBlockOptions): MemoryPromptBlockResult;
+//# sourceMappingURL=memory-prompt-block.d.ts.map