@caupulican/pi-adaptative 0.80.86 → 0.80.89

package/dist/core/context/context-prompt-enforcement.d.ts

@@ -0,0 +1,86 @@
+/**
+ * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike
+ * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN
+ * change the provider-visible message array -- but only ever via stub-in-place on
+ * artifact-backed tool_output results, never by removing a message or breaking
+ * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims
+ * artifact references, and never writes a new artifact -- it only replaces the visible
+ * text of an already artifact-backed message with a bounded pointer to the existing
+ * artifact, retrievable via the `artifact_retrieve` tool.
+ *
+ * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the
+ * setting must be enabled, the item must be outside the recent-message safety window, not
+ * an errored tool result, not already stubbed by this module or already packed by legacy
+ * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool
+ * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see
+ * below for why that specific action, not `pack_to_artifact`).
+ *
+ * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new
+ * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see
+ * tool-output-artifacts.md's "measure -> digest/preview/artifact -> prompt item" pipeline).
+ * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being
+ * performed (evicting raw content from the live prompt in favor of that existing path);
+ * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.
+ *
+ * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the
+ * latter only proves the artifact still exists in the store; it says nothing about whether
+ * the model can currently act on the stub's instruction to call `artifact_retrieve`.
+ * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a
+ * default/global tool -- see agent-session.ts's companion-activation enforcement), so active
+ * tools can differ turn to turn. Stubbing content with an unactionable pointer would be
+ * strictly worse than leaving the raw content in place.
+ */
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import type { PromptPolicyShadowReport } from "./context-prompt-policy.ts";
+export interface ContextPromptEnforcementSettings {
+    enabled: boolean;
+    preserveRecentMessages: number;
+    minChars: number;
+    /**
+     * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,
+     * not a persisted setting. Callers must derive this from the live active-tool set (e.g.
+     * `AgentSession.getActiveToolNames().includes("artifact_retrieve")`), never assume it.
+     */
+    retrievalToolAvailable: boolean;
+    /**
+     * Brain-curator relevance lookup (runtime fact, like `retrievalToolAvailable`; never
+     * persisted). ASYMMETRIC by design: an explicit high-confidence irrelevance verdict may
+     * evict an otherwise-eligible item from within the recent window (never past the absolute
+     * floor), but an advisory can never keep an item the policy wants gone, never stub a
+     * hard-constraint-protected item, and its absence is byte-for-byte today's behavior.
+     */
+    brainRelevance?: (itemId: string) => {
+        relevant: boolean;
+        confidence: number;
+    } | undefined;
+}
+export type PromptEnforcementSkipReason = "message_mismatch" | "within_recent_window" | "errored_tool_result" | "already_stubbed_or_packed" | "not_artifact_backed" | "retrieval_tool_unavailable" | "hard_constraint_rejected" | "missing_artifact_id" | "below_min_chars";
+export interface PromptEnforcementItemReport {
+    itemId: string;
+    toolCallId: string;
+    messageIndex: number;
+    enforced: boolean;
+    action?: "artifact_stub";
+    artifactId?: string;
+    originalChars?: number;
+    skipReason?: PromptEnforcementSkipReason;
+    /** Set when a brain-curator irrelevance verdict allowed eviction inside the recent window. */
+    advisory?: "brain_irrelevant";
+}
+export interface PromptEnforcementReport {
+    turnIndex: number;
+    items: PromptEnforcementItemReport[];
+}
+export interface EnforcePromptPolicyResult {
+    messages: AgentMessage[];
+    report: PromptEnforcementReport;
+}
+/**
+ * Apply the first enforcement pilot to `messages` (expected to be the provider-visible
+ * array after existing context-gc has already run). Returns a new array only when at least
+ * one item was actually stubbed; otherwise returns the same `messages` reference unchanged
+ * (in particular, always true when `settings.enabled` is false). Never mutates `messages`
+ * or any message object within it -- every stubbed entry is a fresh object.
+ */
+export declare function enforcePromptPolicy(messages: AgentMessage[], shadowReport: PromptPolicyShadowReport, settings: ContextPromptEnforcementSettings): EnforcePromptPolicyResult;
+//# sourceMappingURL=context-prompt-enforcement.d.ts.map

package/dist/core/context/context-prompt-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-enforcement.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-prompt-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAE3E,MAAM,WAAW,gCAAgC;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAC3F;AAED,MAAM,MAAM,2BAA2B,GACpC,kBAAkB,GAClB,sBAAsB,GACtB,qBAAqB,GACrB,2BAA2B,GAC3B,qBAAqB,GACrB,4BAA4B,GAC5B,0BAA0B,GAC1B,qBAAqB,GACrB,iBAAiB,CAAC;AAErB,MAAM,WAAW,2BAA2B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,2BAA2B,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,uBAAuB,CAAC;CAChC;AA4CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,YAAY,EAAE,EACxB,YAAY,EAAE,wBAAwB,EACtC,QAAQ,EAAE,gCAAgC,GACxC,yBAAyB,CA+F3B","sourcesContent":["/**\n * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike\n * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN\n * change the provider-visible message array -- but only ever via stub-in-place on\n * artifact-backed tool_output results, never by removing a message or breaking\n * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims\n * artifact references, and never writes a new artifact -- it only replaces the visible\n * text of an already artifact-backed message with a bounded pointer to the existing\n * artifact, retrievable via the `artifact_retrieve` tool.\n *\n * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the\n * setting must be enabled, the item must be outside the recent-message safety window, not\n * an errored tool result, not already stubbed by this module or already packed by legacy\n * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool\n * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see\n * below for why that specific action, not `pack_to_artifact`).\n *\n * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new\n * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see\n * tool-output-artifacts.md's \"measure -> digest/preview/artifact -> prompt item\" pipeline).\n * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being\n * performed (evicting raw content from the live prompt in favor of that existing path);\n * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.\n *\n * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the\n * latter only proves the artifact still exists in the store; it says nothing about whether\n * the model can currently act on the stub's instruction to call `artifact_retrieve`.\n * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a\n * default/global tool -- see agent-session.ts's companion-activation enforcement), so active\n * tools can differ turn to turn. Stubbing content with an unactionable pointer would be\n * strictly worse than leaving the raw content in place.\n */\n\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { ToolResultMessage } from \"@caupulican/pi-ai\";\nimport { CURATION_RELEVANCE_MIN_CONFIDENCE } from \"./brain-curator.ts\";\nimport type { PromptPolicyShadowReport } from \"./context-prompt-policy.ts\";\n\nexport interface ContextPromptEnforcementSettings {\n\tenabled: boolean;\n\tpreserveRecentMessages: number;\n\tminChars: number;\n\t/**\n\t * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,\n\t * not a persisted setting. Callers must derive this from the live active-tool set (e.g.\n\t * `AgentSession.getActiveToolNames().includes(\"artifact_retrieve\")`), never assume it.\n\t */\n\tretrievalToolAvailable: boolean;\n\t/**\n\t * Brain-curator relevance lookup (runtime fact, like `retrievalToolAvailable`; never\n\t * persisted). ASYMMETRIC by design: an explicit high-confidence irrelevance verdict may\n\t * evict an otherwise-eligible item from within the recent window (never past the absolute\n\t * floor), but an advisory can never keep an item the policy wants gone, never stub a\n\t * hard-constraint-protected item, and its absence is byte-for-byte today's behavior.\n\t */\n\tbrainRelevance?: (itemId: string) => { relevant: boolean; confidence: number } | undefined;\n}\n\nexport type PromptEnforcementSkipReason =\n\t| \"message_mismatch\"\n\t| \"within_recent_window\"\n\t| \"errored_tool_result\"\n\t| \"already_stubbed_or_packed\"\n\t| \"not_artifact_backed\"\n\t| \"retrieval_tool_unavailable\"\n\t| \"hard_constraint_rejected\"\n\t| \"missing_artifact_id\"\n\t| \"below_min_chars\";\n\nexport interface PromptEnforcementItemReport {\n\titemId: string;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tenforced: boolean;\n\taction?: \"artifact_stub\";\n\tartifactId?: string;\n\toriginalChars?: number;\n\tskipReason?: PromptEnforcementSkipReason;\n\t/** Set when a brain-curator irrelevance verdict allowed eviction inside the recent window. */\n\tadvisory?: \"brain_irrelevant\";\n}\n\nexport interface PromptEnforcementReport {\n\tturnIndex: number;\n\titems: PromptEnforcementItemReport[];\n}\n\nexport interface EnforcePromptPolicyResult {\n\tmessages: AgentMessage[];\n\treport: PromptEnforcementReport;\n}\n\nconst ENFORCEMENT_ABSOLUTE_RECENT_FLOOR = 4;\n\nfunction extractDetailsArtifactId(details: unknown): string | undefined {\n\tif (typeof details !== \"object\" || details === null) return undefined;\n\tconst artifactId = (details as { artifactId?: unknown }).artifactId;\n\treturn typeof artifactId === \"string\" ? artifactId : undefined;\n}\n\n/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */\nfunction isAlreadyStubbedOrPacked(details: unknown): boolean {\n\tif (typeof details !== \"object\" || details === null) return false;\n\tconst record = details as { promptPolicy?: { enforced?: unknown }; contextGc?: { packed?: unknown } };\n\treturn record.promptPolicy?.enforced === true || record.contextGc?.packed === true;\n}\n\nfunction toolResultText(message: ToolResultMessage): string {\n\tconst parts: string[] = [];\n\tfor (const part of message.content) {\n\t\tif (part.type === \"text\") parts.push(part.text);\n\t}\n\treturn parts.join(\"\\n\");\n}\n\nfunction buildStubText(toolName: string, originalChars: number, artifactId: string): string {\n\treturn `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId \"${artifactId}\".]`;\n}\n\nfunction skip(\n\titem: { itemId: string; toolCallId: string; messageIndex: number },\n\tskipReason: PromptEnforcementSkipReason,\n\textra?: { artifactId?: string; originalChars?: number },\n): PromptEnforcementItemReport {\n\treturn {\n\t\titemId: item.itemId,\n\t\ttoolCallId: item.toolCallId,\n\t\tmessageIndex: item.messageIndex,\n\t\tenforced: false,\n\t\tskipReason,\n\t\t...extra,\n\t};\n}\n\n/**\n * Apply the first enforcement pilot to `messages` (expected to be the provider-visible\n * array after existing context-gc has already run). Returns a new array only when at least\n * one item was actually stubbed; otherwise returns the same `messages` reference unchanged\n * (in particular, always true when `settings.enabled` is false). Never mutates `messages`\n * or any message object within it -- every stubbed entry is a fresh object.\n */\nexport function enforcePromptPolicy(\n\tmessages: AgentMessage[],\n\tshadowReport: PromptPolicyShadowReport,\n\tsettings: ContextPromptEnforcementSettings,\n): EnforcePromptPolicyResult {\n\tif (!settings.enabled) {\n\t\treturn { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };\n\t}\n\n\tconst recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);\n\t// Advisory evictions may reach inside the recent window but NEVER past this absolute floor:\n\t// the last few messages are what the model is actively reasoning over.\n\tconst absoluteFloorIndex = Math.max(0, messages.length - ENFORCEMENT_ABSOLUTE_RECENT_FLOOR);\n\tconst nextMessages = messages.slice();\n\tlet changed = false;\n\tconst items: PromptEnforcementItemReport[] = [];\n\n\tfor (const planItem of shadowReport.items) {\n\t\tconst message = messages[planItem.messageIndex];\n\t\tif (!message || message.role !== \"toolResult\" || message.toolCallId !== planItem.toolCallId) {\n\t\t\titems.push(skip(planItem, \"message_mismatch\"));\n\t\t\tcontinue;\n\t\t}\n\t\tlet advisoryEviction = false;\n\t\tif (planItem.messageIndex >= recentCutoffIndex) {\n\t\t\tconst advisory = settings.brainRelevance?.(planItem.itemId);\n\t\t\tadvisoryEviction =\n\t\t\t\tadvisory !== undefined &&\n\t\t\t\t!advisory.relevant &&\n\t\t\t\tadvisory.confidence >= CURATION_RELEVANCE_MIN_CONFIDENCE &&\n\t\t\t\tplanItem.messageIndex < absoluteFloorIndex;\n\t\t\tif (!advisoryEviction) {\n\t\t\t\titems.push(skip(planItem, \"within_recent_window\"));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tif (message.isError) {\n\t\t\titems.push(skip(planItem, \"errored_tool_result\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (isAlreadyStubbedOrPacked(message.details)) {\n\t\t\titems.push(skip(planItem, \"already_stubbed_or_packed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!planItem.hasAvailableRetrievalPath) {\n\t\t\titems.push(skip(planItem, \"not_artifact_backed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!settings.retrievalToolAvailable) {\n\t\t\titems.push(skip(planItem, \"retrieval_tool_unavailable\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.hardConstraints.dropFromPrompt.length > 0) {\n\t\t\titems.push(skip(planItem, \"hard_constraint_rejected\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst artifactId = extractDetailsArtifactId(message.details);\n\t\tif (!artifactId) {\n\t\t\titems.push(skip(planItem, \"missing_artifact_id\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst originalChars = toolResultText(message).length;\n\t\tif (originalChars < settings.minChars) {\n\t\t\titems.push(skip(planItem, \"below_min_chars\", { artifactId, originalChars }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst existingDetails = typeof message.details === \"object\" && message.details !== null ? message.details : {};\n\t\tnextMessages[planItem.messageIndex] = {\n\t\t\t...message,\n\t\t\tcontent: [{ type: \"text\", text: buildStubText(message.toolName, originalChars, artifactId) }],\n\t\t\tdetails: {\n\t\t\t\t...existingDetails,\n\t\t\t\tpromptPolicy: {\n\t\t\t\t\tenforced: true,\n\t\t\t\t\taction: \"artifact_stub\",\n\t\t\t\t\tartifactId,\n\t\t\t\t\toriginalChars,\n\t\t\t\t\treason: \"stale_artifact_backed_tool_output\",\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t\tchanged = true;\n\t\titems.push({\n\t\t\titemId: planItem.itemId,\n\t\t\ttoolCallId: planItem.toolCallId,\n\t\t\tmessageIndex: planItem.messageIndex,\n\t\t\tenforced: true,\n\t\t\taction: \"artifact_stub\",\n\t\t\tartifactId,\n\t\t\toriginalChars,\n\t\t\t...(advisoryEviction ? { advisory: \"brain_irrelevant\" as const } : {}),\n\t\t});\n\t}\n\n\treturn {\n\t\tmessages: changed ? nextMessages : messages,\n\t\treport: { turnIndex: shadowReport.turnIndex, items },\n\t};\n}\n"]}

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

@@ -0,0 +1,168 @@
+/**
+ * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike
+ * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN
+ * change the provider-visible message array -- but only ever via stub-in-place on
+ * artifact-backed tool_output results, never by removing a message or breaking
+ * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims
+ * artifact references, and never writes a new artifact -- it only replaces the visible
+ * text of an already artifact-backed message with a bounded pointer to the existing
+ * artifact, retrievable via the `artifact_retrieve` tool.
+ *
+ * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the
+ * setting must be enabled, the item must be outside the recent-message safety window, not
+ * an errored tool result, not already stubbed by this module or already packed by legacy
+ * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool
+ * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see
+ * below for why that specific action, not `pack_to_artifact`).
+ *
+ * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new
+ * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see
+ * tool-output-artifacts.md's "measure -> digest/preview/artifact -> prompt item" pipeline).
+ * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being
+ * performed (evicting raw content from the live prompt in favor of that existing path);
+ * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.
+ *
+ * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the
+ * latter only proves the artifact still exists in the store; it says nothing about whether
+ * the model can currently act on the stub's instruction to call `artifact_retrieve`.
+ * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a
+ * default/global tool -- see agent-session.ts's companion-activation enforcement), so active
+ * tools can differ turn to turn. Stubbing content with an unactionable pointer would be
+ * strictly worse than leaving the raw content in place.
+ */
+import { CURATION_RELEVANCE_MIN_CONFIDENCE } from "./brain-curator.js";
+const ENFORCEMENT_ABSOLUTE_RECENT_FLOOR = 4;
+function extractDetailsArtifactId(details) {
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const artifactId = details.artifactId;
+    return typeof artifactId === "string" ? artifactId : undefined;
+}
+/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */
+function isAlreadyStubbedOrPacked(details) {
+    if (typeof details !== "object" || details === null)
+        return false;
+    const record = details;
+    return record.promptPolicy?.enforced === true || record.contextGc?.packed === true;
+}
+function toolResultText(message) {
+    const parts = [];
+    for (const part of message.content) {
+        if (part.type === "text")
+            parts.push(part.text);
+    }
+    return parts.join("\n");
+}
+function buildStubText(toolName, originalChars, artifactId) {
+    return `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId "${artifactId}".]`;
+}
+function skip(item, skipReason, extra) {
+    return {
+        itemId: item.itemId,
+        toolCallId: item.toolCallId,
+        messageIndex: item.messageIndex,
+        enforced: false,
+        skipReason,
+        ...extra,
+    };
+}
+/**
+ * Apply the first enforcement pilot to `messages` (expected to be the provider-visible
+ * array after existing context-gc has already run). Returns a new array only when at least
+ * one item was actually stubbed; otherwise returns the same `messages` reference unchanged
+ * (in particular, always true when `settings.enabled` is false). Never mutates `messages`
+ * or any message object within it -- every stubbed entry is a fresh object.
+ */
+export function enforcePromptPolicy(messages, shadowReport, settings) {
+    if (!settings.enabled) {
+        return { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };
+    }
+    const recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);
+    // Advisory evictions may reach inside the recent window but NEVER past this absolute floor:
+    // the last few messages are what the model is actively reasoning over.
+    const absoluteFloorIndex = Math.max(0, messages.length - ENFORCEMENT_ABSOLUTE_RECENT_FLOOR);
+    const nextMessages = messages.slice();
+    let changed = false;
+    const items = [];
+    for (const planItem of shadowReport.items) {
+        const message = messages[planItem.messageIndex];
+        if (!message || message.role !== "toolResult" || message.toolCallId !== planItem.toolCallId) {
+            items.push(skip(planItem, "message_mismatch"));
+            continue;
+        }
+        let advisoryEviction = false;
+        if (planItem.messageIndex >= recentCutoffIndex) {
+            const advisory = settings.brainRelevance?.(planItem.itemId);
+            advisoryEviction =
+                advisory !== undefined &&
+                    !advisory.relevant &&
+                    advisory.confidence >= CURATION_RELEVANCE_MIN_CONFIDENCE &&
+                    planItem.messageIndex < absoluteFloorIndex;
+            if (!advisoryEviction) {
+                items.push(skip(planItem, "within_recent_window"));
+                continue;
+            }
+        }
+        if (message.isError) {
+            items.push(skip(planItem, "errored_tool_result"));
+            continue;
+        }
+        if (isAlreadyStubbedOrPacked(message.details)) {
+            items.push(skip(planItem, "already_stubbed_or_packed"));
+            continue;
+        }
+        if (!planItem.hasAvailableRetrievalPath) {
+            items.push(skip(planItem, "not_artifact_backed"));
+            continue;
+        }
+        if (!settings.retrievalToolAvailable) {
+            items.push(skip(planItem, "retrieval_tool_unavailable"));
+            continue;
+        }
+        if (planItem.hardConstraints.dropFromPrompt.length > 0) {
+            items.push(skip(planItem, "hard_constraint_rejected"));
+            continue;
+        }
+        const artifactId = extractDetailsArtifactId(message.details);
+        if (!artifactId) {
+            items.push(skip(planItem, "missing_artifact_id"));
+            continue;
+        }
+        const originalChars = toolResultText(message).length;
+        if (originalChars < settings.minChars) {
+            items.push(skip(planItem, "below_min_chars", { artifactId, originalChars }));
+            continue;
+        }
+        const existingDetails = typeof message.details === "object" && message.details !== null ? message.details : {};
+        nextMessages[planItem.messageIndex] = {
+            ...message,
+            content: [{ type: "text", text: buildStubText(message.toolName, originalChars, artifactId) }],
+            details: {
+                ...existingDetails,
+                promptPolicy: {
+                    enforced: true,
+                    action: "artifact_stub",
+                    artifactId,
+                    originalChars,
+                    reason: "stale_artifact_backed_tool_output",
+                },
+            },
+        };
+        changed = true;
+        items.push({
+            itemId: planItem.itemId,
+            toolCallId: planItem.toolCallId,
+            messageIndex: planItem.messageIndex,
+            enforced: true,
+            action: "artifact_stub",
+            artifactId,
+            originalChars,
+            ...(advisoryEviction ? { advisory: "brain_irrelevant" } : {}),
+        });
+    }
+    return {
+        messages: changed ? nextMessages : messages,
+        report: { turnIndex: shadowReport.turnIndex, items },
+    };
+}
+//# sourceMappingURL=context-prompt-enforcement.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-enforcement.js","sourceRoot":"","sources":["../../../src/core/context/context-prompt-enforcement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * First enforcement pilot for the context-policy layer (opt-in, default disabled). Unlike\n * context-audit.ts/context-prompt-policy.ts (both strictly observe-only), this module CAN\n * change the provider-visible message array -- but only ever via stub-in-place on\n * artifact-backed tool_output results, never by removing a message or breaking\n * assistant/toolResult pairing. It never touches the transcript, never releases/reclaims\n * artifact references, and never writes a new artifact -- it only replaces the visible\n * text of an already artifact-backed message with a bounded pointer to the existing\n * artifact, retrievable via the `artifact_retrieve` tool.\n *\n * Eligibility for stubbing is deliberately conservative (see `enforcePromptPolicy`): the\n * setting must be enabled, the item must be outside the recent-message safety window, not\n * an errored tool result, not already stubbed by this module or already packed by legacy\n * context-gc this turn, must have a resolvable artifact id, the `artifact_retrieve` tool\n * must actually be active this turn, and must clear `hardConstraints.dropFromPrompt` (see\n * below for why that specific action, not `pack_to_artifact`).\n *\n * Why `dropFromPrompt`, not `packToArtifact`: this operation does not create a new\n * artifact -- it reuses the ref an earlier `pack_to_artifact` capture already produced (see\n * tool-output-artifacts.md's \"measure -> digest/preview/artifact -> prompt item\" pipeline).\n * `drop_from_prompt` requires an existing retrieval path and is exactly the operation being\n * performed (evicting raw content from the live prompt in favor of that existing path);\n * `pack_to_artifact` is the distinct first-capture operation, which we never invoke here.\n *\n * Why `retrievalToolAvailable` is checked separately from `hasAvailableRetrievalPath`: the\n * latter only proves the artifact still exists in the store; it says nothing about whether\n * the model can currently act on the stub's instruction to call `artifact_retrieve`.\n * `artifact_retrieve` is a companion affordance (auto-activated alongside grep/find, not a\n * default/global tool -- see agent-session.ts's companion-activation enforcement), so active\n * tools can differ turn to turn. Stubbing content with an unactionable pointer would be\n * strictly worse than leaving the raw content in place.\n */\n\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { ToolResultMessage } from \"@caupulican/pi-ai\";\nimport { CURATION_RELEVANCE_MIN_CONFIDENCE } from \"./brain-curator.ts\";\nimport type { PromptPolicyShadowReport } from \"./context-prompt-policy.ts\";\n\nexport interface ContextPromptEnforcementSettings {\n\tenabled: boolean;\n\tpreserveRecentMessages: number;\n\tminChars: number;\n\t/**\n\t * Whether the `artifact_retrieve` tool is actually active this turn -- a runtime fact,\n\t * not a persisted setting. Callers must derive this from the live active-tool set (e.g.\n\t * `AgentSession.getActiveToolNames().includes(\"artifact_retrieve\")`), never assume it.\n\t */\n\tretrievalToolAvailable: boolean;\n\t/**\n\t * Brain-curator relevance lookup (runtime fact, like `retrievalToolAvailable`; never\n\t * persisted). ASYMMETRIC by design: an explicit high-confidence irrelevance verdict may\n\t * evict an otherwise-eligible item from within the recent window (never past the absolute\n\t * floor), but an advisory can never keep an item the policy wants gone, never stub a\n\t * hard-constraint-protected item, and its absence is byte-for-byte today's behavior.\n\t */\n\tbrainRelevance?: (itemId: string) => { relevant: boolean; confidence: number } | undefined;\n}\n\nexport type PromptEnforcementSkipReason =\n\t| \"message_mismatch\"\n\t| \"within_recent_window\"\n\t| \"errored_tool_result\"\n\t| \"already_stubbed_or_packed\"\n\t| \"not_artifact_backed\"\n\t| \"retrieval_tool_unavailable\"\n\t| \"hard_constraint_rejected\"\n\t| \"missing_artifact_id\"\n\t| \"below_min_chars\";\n\nexport interface PromptEnforcementItemReport {\n\titemId: string;\n\ttoolCallId: string;\n\tmessageIndex: number;\n\tenforced: boolean;\n\taction?: \"artifact_stub\";\n\tartifactId?: string;\n\toriginalChars?: number;\n\tskipReason?: PromptEnforcementSkipReason;\n\t/** Set when a brain-curator irrelevance verdict allowed eviction inside the recent window. */\n\tadvisory?: \"brain_irrelevant\";\n}\n\nexport interface PromptEnforcementReport {\n\tturnIndex: number;\n\titems: PromptEnforcementItemReport[];\n}\n\nexport interface EnforcePromptPolicyResult {\n\tmessages: AgentMessage[];\n\treport: PromptEnforcementReport;\n}\n\nconst ENFORCEMENT_ABSOLUTE_RECENT_FLOOR = 4;\n\nfunction extractDetailsArtifactId(details: unknown): string | undefined {\n\tif (typeof details !== \"object\" || details === null) return undefined;\n\tconst artifactId = (details as { artifactId?: unknown }).artifactId;\n\treturn typeof artifactId === \"string\" ? artifactId : undefined;\n}\n\n/** True if legacy context-gc already packed this message this turn, or this module already stubbed it. */\nfunction isAlreadyStubbedOrPacked(details: unknown): boolean {\n\tif (typeof details !== \"object\" || details === null) return false;\n\tconst record = details as { promptPolicy?: { enforced?: unknown }; contextGc?: { packed?: unknown } };\n\treturn record.promptPolicy?.enforced === true || record.contextGc?.packed === true;\n}\n\nfunction toolResultText(message: ToolResultMessage): string {\n\tconst parts: string[] = [];\n\tfor (const part of message.content) {\n\t\tif (part.type === \"text\") parts.push(part.text);\n\t}\n\treturn parts.join(\"\\n\");\n}\n\nfunction buildStubText(toolName: string, originalChars: number, artifactId: string): string {\n\treturn `[content replaced by prompt-policy: originally ${originalChars} chars from a stale ${toolName} tool result. Retrieve the full output with artifact_retrieve using artifactId \"${artifactId}\".]`;\n}\n\nfunction skip(\n\titem: { itemId: string; toolCallId: string; messageIndex: number },\n\tskipReason: PromptEnforcementSkipReason,\n\textra?: { artifactId?: string; originalChars?: number },\n): PromptEnforcementItemReport {\n\treturn {\n\t\titemId: item.itemId,\n\t\ttoolCallId: item.toolCallId,\n\t\tmessageIndex: item.messageIndex,\n\t\tenforced: false,\n\t\tskipReason,\n\t\t...extra,\n\t};\n}\n\n/**\n * Apply the first enforcement pilot to `messages` (expected to be the provider-visible\n * array after existing context-gc has already run). Returns a new array only when at least\n * one item was actually stubbed; otherwise returns the same `messages` reference unchanged\n * (in particular, always true when `settings.enabled` is false). Never mutates `messages`\n * or any message object within it -- every stubbed entry is a fresh object.\n */\nexport function enforcePromptPolicy(\n\tmessages: AgentMessage[],\n\tshadowReport: PromptPolicyShadowReport,\n\tsettings: ContextPromptEnforcementSettings,\n): EnforcePromptPolicyResult {\n\tif (!settings.enabled) {\n\t\treturn { messages, report: { turnIndex: shadowReport.turnIndex, items: [] } };\n\t}\n\n\tconst recentCutoffIndex = Math.max(0, messages.length - settings.preserveRecentMessages);\n\t// Advisory evictions may reach inside the recent window but NEVER past this absolute floor:\n\t// the last few messages are what the model is actively reasoning over.\n\tconst absoluteFloorIndex = Math.max(0, messages.length - ENFORCEMENT_ABSOLUTE_RECENT_FLOOR);\n\tconst nextMessages = messages.slice();\n\tlet changed = false;\n\tconst items: PromptEnforcementItemReport[] = [];\n\n\tfor (const planItem of shadowReport.items) {\n\t\tconst message = messages[planItem.messageIndex];\n\t\tif (!message || message.role !== \"toolResult\" || message.toolCallId !== planItem.toolCallId) {\n\t\t\titems.push(skip(planItem, \"message_mismatch\"));\n\t\t\tcontinue;\n\t\t}\n\t\tlet advisoryEviction = false;\n\t\tif (planItem.messageIndex >= recentCutoffIndex) {\n\t\t\tconst advisory = settings.brainRelevance?.(planItem.itemId);\n\t\t\tadvisoryEviction =\n\t\t\t\tadvisory !== undefined &&\n\t\t\t\t!advisory.relevant &&\n\t\t\t\tadvisory.confidence >= CURATION_RELEVANCE_MIN_CONFIDENCE &&\n\t\t\t\tplanItem.messageIndex < absoluteFloorIndex;\n\t\t\tif (!advisoryEviction) {\n\t\t\t\titems.push(skip(planItem, \"within_recent_window\"));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tif (message.isError) {\n\t\t\titems.push(skip(planItem, \"errored_tool_result\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (isAlreadyStubbedOrPacked(message.details)) {\n\t\t\titems.push(skip(planItem, \"already_stubbed_or_packed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!planItem.hasAvailableRetrievalPath) {\n\t\t\titems.push(skip(planItem, \"not_artifact_backed\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (!settings.retrievalToolAvailable) {\n\t\t\titems.push(skip(planItem, \"retrieval_tool_unavailable\"));\n\t\t\tcontinue;\n\t\t}\n\t\tif (planItem.hardConstraints.dropFromPrompt.length > 0) {\n\t\t\titems.push(skip(planItem, \"hard_constraint_rejected\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst artifactId = extractDetailsArtifactId(message.details);\n\t\tif (!artifactId) {\n\t\t\titems.push(skip(planItem, \"missing_artifact_id\"));\n\t\t\tcontinue;\n\t\t}\n\t\tconst originalChars = toolResultText(message).length;\n\t\tif (originalChars < settings.minChars) {\n\t\t\titems.push(skip(planItem, \"below_min_chars\", { artifactId, originalChars }));\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst existingDetails = typeof message.details === \"object\" && message.details !== null ? message.details : {};\n\t\tnextMessages[planItem.messageIndex] = {\n\t\t\t...message,\n\t\t\tcontent: [{ type: \"text\", text: buildStubText(message.toolName, originalChars, artifactId) }],\n\t\t\tdetails: {\n\t\t\t\t...existingDetails,\n\t\t\t\tpromptPolicy: {\n\t\t\t\t\tenforced: true,\n\t\t\t\t\taction: \"artifact_stub\",\n\t\t\t\t\tartifactId,\n\t\t\t\t\toriginalChars,\n\t\t\t\t\treason: \"stale_artifact_backed_tool_output\",\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t\tchanged = true;\n\t\titems.push({\n\t\t\titemId: planItem.itemId,\n\t\t\ttoolCallId: planItem.toolCallId,\n\t\t\tmessageIndex: planItem.messageIndex,\n\t\t\tenforced: true,\n\t\t\taction: \"artifact_stub\",\n\t\t\tartifactId,\n\t\t\toriginalChars,\n\t\t\t...(advisoryEviction ? { advisory: \"brain_irrelevant\" as const } : {}),\n\t\t});\n\t}\n\n\treturn {\n\t\tmessages: changed ? nextMessages : messages,\n\t\treport: { turnIndex: shadowReport.turnIndex, items },\n\t};\n}\n"]}

package/dist/core/context/context-prompt-policy.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+import type { ContextGcPackedRecord, ContextGcReport } from "../context-gc.ts";
+import type { ContextAuditReport } from "./context-audit.ts";
+import type { ContextEvidenceRef, ContextItemKind, ContextRetentionClass, ContextSource } from "./context-item.ts";
+import type { RetentionAction } from "./context-retention.ts";
+import type { PolicyHardConstraintCode } from "./policy-types.ts";
+export interface PromptPolicyHardConstraints {
+    keepRaw: PolicyHardConstraintCode[];
+    packToArtifact: PolicyHardConstraintCode[];
+    dropFromPrompt: PolicyHardConstraintCode[];
+    summarize: PolicyHardConstraintCode[];
+}
+export interface PromptPolicyItemReport {
+    itemId: string;
+    kind: ContextItemKind;
+    retentionClass: ContextRetentionClass;
+    source: ContextSource;
+    toolCallId: string;
+    messageIndex: number;
+    primaryRefType: ContextEvidenceRef["type"] | undefined;
+    /**
+     * True only for a resolved artifact ref, never for a transcript ref -- the same
+     * fail-closed resolved-artifact-only rule context-audit.ts uses (a transcript ref is
+     * provenance, not a live retrieval mechanism; see that module's doc comment).
+     */
+    hasAvailableRetrievalPath: boolean;
+    /** Coarse, store-free eligibility from context-retention.ts (treats any ref as retrievable). */
+    allowedRetentionActions: RetentionAction[];
+    hardConstraints: PromptPolicyHardConstraints;
+    /**
+     * This shadow/planning pass never changes behavior: the applied action is always
+     * "keep_raw", regardless of what the hard-constraint/retention analysis above would
+     * otherwise allow. Typed as a literal so nothing here can ever report applying anything
+     * else.
+     */
+    appliedAction: "keep_raw";
+}
+export interface PromptPolicyShadowReport {
+    turnIndex: number;
+    items: PromptPolicyItemReport[];
+}
+/**
+ * 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 declare function planPromptPolicy(auditReport: ContextAuditReport): PromptPolicyShadowReport;
+export interface PromptPolicyGcCorrelationEntry {
+    itemId: string;
+    toolCallId: string;
+    /** True if the legacy context-gc pass actually packed this item's tool result this turn. */
+    actuallyPackedByLegacyGc: boolean;
+    gcPackReason?: ContextGcPackedRecord["reason"];
+    /** True if the shadow plan's pack_to_artifact hard constraints did not reject packing. */
+    policyWouldAllowPack: boolean;
+    /** True if the shadow plan's drop_from_prompt hard constraints did not reject dropping. */
+    policyWouldAllowDrop: boolean;
+}
+export interface PromptPolicyGcCorrelationReport {
+    turnIndex: number;
+    entries: PromptPolicyGcCorrelationEntry[];
+}
+/**
+ * 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 declare function correlateWithContextGc(shadowReport: PromptPolicyShadowReport, gcReport: ContextGcReport): PromptPolicyGcCorrelationReport;
+//# sourceMappingURL=context-prompt-policy.d.ts.map

package/dist/core/context/context-prompt-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-prompt-policy.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-prompt-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,2BAA2B;IAC3C,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,cAAc,EAAE,wBAAwB,EAAE,CAAC;IAC3C,cAAc,EAAE,wBAAwB,EAAE,CAAC;IAC3C,SAAS,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,eAAe,CAAC;IACtB,cAAc,EAAE,qBAAqB,CAAC;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACvD;;;;OAIG;IACH,yBAAyB,EAAE,OAAO,CAAC;IACnC,gGAAgG;IAChG,uBAAuB,EAAE,eAAe,EAAE,CAAC;IAC3C,eAAe,EAAE,2BAA2B,CAAC;IAC7C;;;;;OAKG;IACH,aAAa,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,sBAAsB,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,kBAAkB,GAAG,wBAAwB,CAsB1F;AAED,MAAM,WAAW,8BAA8B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,wBAAwB,EAAE,OAAO,CAAC;IAClC,YAAY,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC/C,0FAA0F;IAC1F,oBAAoB,EAAE,OAAO,CAAC;IAC9B,2FAA2F;IAC3F,oBAAoB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,8BAA8B,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,wBAAwB,EACtC,QAAQ,EAAE,eAAe,GACvB,+BAA+B,CAiBjC","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-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"]}