@caupulican/pi-adaptative 0.80.86 → 0.80.89

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

@@ -0,0 +1,171 @@
+/**
+ * Pure policy-engine primitives (Phase 0.6): a hard-constraint evaluator, break-even
+ * scoring helpers, and reason-code formatting. No provider calls, no I/O, no wiring into
+ * prompt construction, model routing, or validation yet.
+ *
+ * The one invariant every helper here must uphold: a hard constraint can never be
+ * overridden by a positive expected saving. Scoring only runs for candidates that already
+ * cleared the hard-constraint layer.
+ */
+const AGGRESSIVE_CONTEXT_ACTIONS = new Set([
+    "summarize",
+    "drop_from_prompt",
+    "pack_to_artifact",
+]);
+function pushUnique(codes, code) {
+    if (!codes.includes(code))
+        codes.push(code);
+}
+/**
+ * Evaluate hard constraints for a single candidate action. Returns the (possibly empty)
+ * list of violated constraint codes; any non-empty result means the action must be
+ * rejected outright, never merely down-weighted by scoring.
+ */
+export function evaluateHardConstraints(action, features, flags) {
+    const codes = [];
+    if (AGGRESSIVE_CONTEXT_ACTIONS.has(action)) {
+        if (features.isPinned)
+            pushUnique(codes, "pinned_user_instruction");
+        if (flags.isApprovalOrDenial)
+            pushUnique(codes, "approval_or_denial");
+        if (flags.isSafetyConstraint)
+            pushUnique(codes, "safety_constraint");
+        if (features.isOpenRequirement)
+            pushUnique(codes, "open_requirement");
+        if (flags.isActiveBlocker)
+            pushUnique(codes, "active_blocker");
+        if (features.isLatestFailure)
+            pushUnique(codes, "latest_unresolved_failure");
+        if (features.isCurrentDiff)
+            pushUnique(codes, "current_diff_summary");
+        if (flags.isCurrentValidationResult)
+            pushUnique(codes, "current_validation_result");
+        if (flags.isPathOrToolScope)
+            pushUnique(codes, "path_or_tool_scope");
+    }
+    // drop_from_prompt discards content outright, so it requires a retrieval path that
+    // already exists. pack_to_artifact is the first-capture operation that *creates* the
+    // retrieval path (tool-output-artifacts.md: measure -> digest/preview/artifact -> prompt
+    // item), so it must not be rejected merely for lacking one; it only needs a working
+    // artifact store to write into.
+    if (action === "drop_from_prompt" && !flags.hasAvailableRetrievalPath) {
+        pushUnique(codes, "missing_retrieval_path");
+    }
+    if (action === "pack_to_artifact" && !flags.artifactStoreAvailable) {
+        pushUnique(codes, "missing_retrieval_path");
+    }
+    if (action === "summarize" && features.isDecisionBearing && !flags.hasEvidenceRefForSummary) {
+        pushUnique(codes, "missing_retrieval_path");
+    }
+    if (action === "route_cheap") {
+        if (features.taskRisk === "high" || features.taskRisk === "unknown" || features.taskRisk === undefined) {
+            pushUnique(codes, "unknown_risk");
+        }
+        if (flags.isHighImpactOrBroadMultiFileEdit)
+            pushUnique(codes, "unknown_risk");
+        if (flags.priorAttemptFailedForReasoningOrArchitecture)
+            pushUnique(codes, "unknown_risk");
+        if (!flags.validationAvailableAndStrong)
+            pushUnique(codes, "unknown_risk");
+        if (!flags.pathOrToolBoundariesEnforced)
+            pushUnique(codes, "path_or_tool_scope");
+    }
+    return codes;
+}
+export function computeContextRetentionSaving(inputs) {
+    const rawCost = inputs.expectedRemainingTurns * inputs.rawTokens * inputs.marginalInputTokenCost;
+    const compactCost = inputs.expectedRemainingTurns * inputs.compactTokens * inputs.marginalInputTokenCost;
+    const oneTimeCost = inputs.packCostTokens +
+        inputs.probabilityNeededAgain * inputs.retrievalCostTokens +
+        inputs.probabilityErrorIfDropped * inputs.errorCostTokens +
+        inputs.cacheImpactTokens;
+    return rawCost - compactCost - oneTimeCost;
+}
+/**
+ * N_break_even(i) from decision-math-and-research.md: the number of remaining turns at
+ * which packing/summarizing first becomes worthwhile. Returns +Infinity when the raw vs.
+ * compact token gap never pays for itself (per-turn saving is zero or negative).
+ */
+export function computeBreakEvenRemainingTurns(inputs) {
+    const perTurnSaving = (inputs.rawTokens - inputs.compactTokens) * inputs.marginalInputTokenCost;
+    if (perTurnSaving <= 0)
+        return Number.POSITIVE_INFINITY;
+    const oneTimeCost = inputs.packCostTokens +
+        inputs.probabilityNeededAgain * inputs.retrievalCostTokens +
+        inputs.probabilityErrorIfDropped * inputs.errorCostTokens +
+        inputs.cacheImpactTokens +
+        inputs.margin;
+    return oneTimeCost / perTurnSaving;
+}
+/**
+ * Hard cap override from policy-engine-spec.md: oversized raw tool output must be packed
+ * regardless of break-even math, unless the item is pinned, current, or the latest
+ * failure.
+ */
+export function exceedsHardOutputCap(rawTokens, maxRawToolOutputTokens, features) {
+    if (features.isPinned || features.isCurrentDiff || features.isLatestFailure)
+        return false;
+    return rawTokens > maxRawToolOutputTokens;
+}
+/**
+ * Score one context-retention candidate. Hard constraints are checked first and, if any
+ * fire, the candidate is returned as unappliable (infinite cost, zero savings) no matter
+ * what the break-even math says — a hard constraint can never be overridden by savings.
+ */
+export function scoreContextRetentionCandidate(input) {
+    const hardConstraints = evaluateHardConstraints(input.action, input.features, input.flags);
+    if (hardConstraints.length > 0) {
+        return {
+            action: input.action,
+            expectedCostTokens: Number.POSITIVE_INFINITY,
+            expectedSavingsTokens: 0,
+            expectedReliabilityRisk: 1,
+            cacheImpactTokens: input.saving.cacheImpactTokens,
+            reworkRiskTokens: input.saving.probabilityErrorIfDropped * input.saving.errorCostTokens,
+            confidence: "low",
+            reasonCodes: hardConstraints,
+        };
+    }
+    const saving = computeContextRetentionSaving(input.saving);
+    const applied = saving > input.margin;
+    const decisionBearingLowConfidence = input.features.isDecisionBearing && input.confidence === "low";
+    return {
+        action: input.action,
+        expectedCostTokens: input.saving.packCostTokens + input.saving.cacheImpactTokens,
+        expectedSavingsTokens: Math.max(0, saving),
+        expectedReliabilityRisk: input.saving.probabilityErrorIfDropped,
+        cacheImpactTokens: input.saving.cacheImpactTokens,
+        reworkRiskTokens: input.saving.probabilityErrorIfDropped * input.saving.errorCostTokens,
+        confidence: input.confidence,
+        reasonCodes: applied && !decisionBearingLowConfidence
+            ? ["saving_above_margin"]
+            : decisionBearingLowConfidence
+                ? ["low_confidence_decision_bearing"]
+                : ["saving_below_margin"],
+    };
+}
+const HARD_CONSTRAINT_REASON_TEXT = {
+    pinned_user_instruction: "item is a pinned user instruction and must remain present verbatim",
+    approval_or_denial: "item records a user approval or denial and cannot be summarized or dropped",
+    safety_constraint: "item is a safety/security constraint and must remain present verbatim",
+    open_requirement: "item is an open requirement for the active goal and cannot be dropped while active",
+    active_blocker: "item is an active blocker and must remain present until resolved",
+    latest_unresolved_failure: "item is the latest unresolved failure; dropping it risks repeating the mistake",
+    current_diff_summary: "item is the current diff summary during active code changes",
+    current_validation_result: "item is the current validation command/result and cannot be dropped while pending",
+    missing_retrieval_path: "no retrieval path (artifact/evidence ref) exists to recover this content if evicted",
+    path_or_tool_scope: "item encodes an active path/tool scope restriction that must stay enforced",
+    unknown_risk: "task risk is high or unknown and this action requires stronger reliability guarantees",
+};
+export function formatHardConstraintReason(code) {
+    return HARD_CONSTRAINT_REASON_TEXT[code];
+}
+/** Human-readable, deterministic summary of a scored candidate's reason codes. */
+export function formatCandidateReason(candidate) {
+    const hardCodes = candidate.reasonCodes.filter((code) => code in HARD_CONSTRAINT_REASON_TEXT);
+    if (hardCodes.length > 0) {
+        return `${candidate.action} rejected: ${hardCodes.map(formatHardConstraintReason).join("; ")}`;
+    }
+    return `${candidate.action}: ${candidate.reasonCodes.join(", ")}`;
+}
+//# sourceMappingURL=policy-engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.js","sourceRoot":"","sources":["../../../src/core/context/policy-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,0BAA0B,GAA8B,IAAI,GAAG,CAAC;IACrE,WAAW;IACX,kBAAkB;IAClB,kBAAkB;CAClB,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,KAAiC,EAAE,IAA8B,EAAQ;IAC5F,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CAC5C;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACtC,MAAoB,EACpB,QAAwB,EACxB,KAA0B,EACG;IAC7B,MAAM,KAAK,GAA+B,EAAE,CAAC;IAE7C,IAAI,0BAA0B,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,QAAQ,CAAC,QAAQ;YAAE,UAAU,CAAC,KAAK,EAAE,yBAAyB,CAAC,CAAC;QACpE,IAAI,KAAK,CAAC,kBAAkB;YAAE,UAAU,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;QACtE,IAAI,KAAK,CAAC,kBAAkB;YAAE,UAAU,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;QACrE,IAAI,QAAQ,CAAC,iBAAiB;YAAE,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;QACtE,IAAI,KAAK,CAAC,eAAe;YAAE,UAAU,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;QAC/D,IAAI,QAAQ,CAAC,eAAe;YAAE,UAAU,CAAC,KAAK,EAAE,2BAA2B,CAAC,CAAC;QAC7E,IAAI,QAAQ,CAAC,aAAa;YAAE,UAAU,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;QACtE,IAAI,KAAK,CAAC,yBAAyB;YAAE,UAAU,CAAC,KAAK,EAAE,2BAA2B,CAAC,CAAC;QACpF,IAAI,KAAK,CAAC,iBAAiB;YAAE,UAAU,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;IACtE,CAAC;IAED,mFAAmF;IACnF,qFAAqF;IACrF,yFAAyF;IACzF,oFAAoF;IACpF,gCAAgC;IAChC,IAAI,MAAM,KAAK,kBAAkB,IAAI,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAC;QACvE,UAAU,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,MAAM,KAAK,kBAAkB,IAAI,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC;QACpE,UAAU,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,MAAM,KAAK,WAAW,IAAI,QAAQ,CAAC,iBAAiB,IAAI,CAAC,KAAK,CAAC,wBAAwB,EAAE,CAAC;QAC7F,UAAU,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;QAC9B,IAAI,QAAQ,CAAC,QAAQ,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACxG,UAAU,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,KAAK,CAAC,gCAAgC;YAAE,UAAU,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QAC9E,IAAI,KAAK,CAAC,4CAA4C;YAAE,UAAU,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QAC1F,IAAI,CAAC,KAAK,CAAC,4BAA4B;YAAE,UAAU,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK,CAAC,4BAA4B;YAAE,UAAU,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,KAAK,CAAC;AAAA,CACb;AAoBD,MAAM,UAAU,6BAA6B,CAAC,MAAoC,EAAU;IAC3F,MAAM,OAAO,GAAG,MAAM,CAAC,sBAAsB,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,sBAAsB,CAAC;IACjG,MAAM,WAAW,GAAG,MAAM,CAAC,sBAAsB,GAAG,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,sBAAsB,CAAC;IACzG,MAAM,WAAW,GAChB,MAAM,CAAC,cAAc;QACrB,MAAM,CAAC,sBAAsB,GAAG,MAAM,CAAC,mBAAmB;QAC1D,MAAM,CAAC,yBAAyB,GAAG,MAAM,CAAC,eAAe;QACzD,MAAM,CAAC,iBAAiB,CAAC;IAC1B,OAAO,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC;AAAA,CAC3C;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAC7C,MAAyF,EAChF;IACT,MAAM,aAAa,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,sBAAsB,CAAC;IAChG,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC;IACxD,MAAM,WAAW,GAChB,MAAM,CAAC,cAAc;QACrB,MAAM,CAAC,sBAAsB,GAAG,MAAM,CAAC,mBAAmB;QAC1D,MAAM,CAAC,yBAAyB,GAAG,MAAM,CAAC,eAAe;QACzD,MAAM,CAAC,iBAAiB;QACxB,MAAM,CAAC,MAAM,CAAC;IACf,OAAO,WAAW,GAAG,aAAa,CAAC;AAAA,CACnC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CACnC,SAAiB,EACjB,sBAA8B,EAC9B,QAAgF,EACtE;IACV,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,aAAa,IAAI,QAAQ,CAAC,eAAe;QAAE,OAAO,KAAK,CAAC;IAC1F,OAAO,SAAS,GAAG,sBAAsB,CAAC;AAAA,CAC1C;AAWD;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAqC,EAAwB;IAC3G,MAAM,eAAe,GAAG,uBAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3F,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO;YACN,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,kBAAkB,EAAE,MAAM,CAAC,iBAAiB;YAC5C,qBAAqB,EAAE,CAAC;YACxB,uBAAuB,EAAE,CAAC;YAC1B,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,iBAAiB;YACjD,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC,yBAAyB,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe;YACvF,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,eAAe;SAC5B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,6BAA6B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACtC,MAAM,4BAA4B,GAAG,KAAK,CAAC,QAAQ,CAAC,iBAAiB,IAAI,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC;IAEpG,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,iBAAiB;QAChF,qBAAqB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC;QAC1C,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC,yBAAyB;QAC/D,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,iBAAiB;QACjD,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC,yBAAyB,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe;QACvF,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EACV,OAAO,IAAI,CAAC,4BAA4B;YACvC,CAAC,CAAC,CAAC,qBAAqB,CAAC;YACzB,CAAC,CAAC,4BAA4B;gBAC7B,CAAC,CAAC,CAAC,iCAAiC,CAAC;gBACrC,CAAC,CAAC,CAAC,qBAAqB,CAAC;KAC5B,CAAC;AAAA,CACF;AAED,MAAM,2BAA2B,GAA6C;IAC7E,uBAAuB,EAAE,oEAAoE;IAC7F,kBAAkB,EAAE,4EAA4E;IAChG,iBAAiB,EAAE,uEAAuE;IAC1F,gBAAgB,EAAE,oFAAoF;IACtG,cAAc,EAAE,kEAAkE;IAClF,yBAAyB,EAAE,gFAAgF;IAC3G,oBAAoB,EAAE,6DAA6D;IACnF,yBAAyB,EAAE,mFAAmF;IAC9G,sBAAsB,EAAE,qFAAqF;IAC7G,kBAAkB,EAAE,4EAA4E;IAChG,YAAY,EAAE,uFAAuF;CACrG,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAA8B,EAAU;IAClF,OAAO,2BAA2B,CAAC,IAAI,CAAC,CAAC;AAAA,CACzC;AAED,kFAAkF;AAClF,MAAM,UAAU,qBAAqB,CAAC,SAA+D,EAAU;IAC9G,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,MAAM,CAC7C,CAAC,IAAI,EAAoC,EAAE,CAAC,IAAI,IAAI,2BAA2B,CAC/E,CAAC;IACF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,GAAG,SAAS,CAAC,MAAM,cAAc,SAAS,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAChG,CAAC;IACD,OAAO,GAAG,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAAA,CAClE","sourcesContent":["/**\n * Pure policy-engine primitives (Phase 0.6): a hard-constraint evaluator, break-even\n * scoring helpers, and reason-code formatting. No provider calls, no I/O, no wiring into\n * prompt construction, model routing, or validation yet.\n *\n * The one invariant every helper here must uphold: a hard constraint can never be\n * overridden by a positive expected saving. Scoring only runs for candidates that already\n * cleared the hard-constraint layer.\n */\n\nimport type {\n\tHardConstraintFlags,\n\tPolicyAction,\n\tPolicyCandidateScore,\n\tPolicyFeatures,\n\tPolicyHardConstraintCode,\n} from \"./policy-types.ts\";\n\nconst AGGRESSIVE_CONTEXT_ACTIONS: ReadonlySet<PolicyAction> = new Set([\n\t\"summarize\",\n\t\"drop_from_prompt\",\n\t\"pack_to_artifact\",\n]);\n\nfunction pushUnique(codes: PolicyHardConstraintCode[], code: PolicyHardConstraintCode): void {\n\tif (!codes.includes(code)) codes.push(code);\n}\n\n/**\n * Evaluate hard constraints for a single candidate action. Returns the (possibly empty)\n * list of violated constraint codes; any non-empty result means the action must be\n * rejected outright, never merely down-weighted by scoring.\n */\nexport function evaluateHardConstraints(\n\taction: PolicyAction,\n\tfeatures: PolicyFeatures,\n\tflags: HardConstraintFlags,\n): PolicyHardConstraintCode[] {\n\tconst codes: PolicyHardConstraintCode[] = [];\n\n\tif (AGGRESSIVE_CONTEXT_ACTIONS.has(action)) {\n\t\tif (features.isPinned) pushUnique(codes, \"pinned_user_instruction\");\n\t\tif (flags.isApprovalOrDenial) pushUnique(codes, \"approval_or_denial\");\n\t\tif (flags.isSafetyConstraint) pushUnique(codes, \"safety_constraint\");\n\t\tif (features.isOpenRequirement) pushUnique(codes, \"open_requirement\");\n\t\tif (flags.isActiveBlocker) pushUnique(codes, \"active_blocker\");\n\t\tif (features.isLatestFailure) pushUnique(codes, \"latest_unresolved_failure\");\n\t\tif (features.isCurrentDiff) pushUnique(codes, \"current_diff_summary\");\n\t\tif (flags.isCurrentValidationResult) pushUnique(codes, \"current_validation_result\");\n\t\tif (flags.isPathOrToolScope) pushUnique(codes, \"path_or_tool_scope\");\n\t}\n\n\t// drop_from_prompt discards content outright, so it requires a retrieval path that\n\t// already exists. pack_to_artifact is the first-capture operation that *creates* the\n\t// retrieval path (tool-output-artifacts.md: measure -> digest/preview/artifact -> prompt\n\t// item), so it must not be rejected merely for lacking one; it only needs a working\n\t// artifact store to write into.\n\tif (action === \"drop_from_prompt\" && !flags.hasAvailableRetrievalPath) {\n\t\tpushUnique(codes, \"missing_retrieval_path\");\n\t}\n\tif (action === \"pack_to_artifact\" && !flags.artifactStoreAvailable) {\n\t\tpushUnique(codes, \"missing_retrieval_path\");\n\t}\n\n\tif (action === \"summarize\" && features.isDecisionBearing && !flags.hasEvidenceRefForSummary) {\n\t\tpushUnique(codes, \"missing_retrieval_path\");\n\t}\n\n\tif (action === \"route_cheap\") {\n\t\tif (features.taskRisk === \"high\" || features.taskRisk === \"unknown\" || features.taskRisk === undefined) {\n\t\t\tpushUnique(codes, \"unknown_risk\");\n\t\t}\n\t\tif (flags.isHighImpactOrBroadMultiFileEdit) pushUnique(codes, \"unknown_risk\");\n\t\tif (flags.priorAttemptFailedForReasoningOrArchitecture) pushUnique(codes, \"unknown_risk\");\n\t\tif (!flags.validationAvailableAndStrong) pushUnique(codes, \"unknown_risk\");\n\t\tif (!flags.pathOrToolBoundariesEnforced) pushUnique(codes, \"path_or_tool_scope\");\n\t}\n\n\treturn codes;\n}\n\n/**\n * Inputs to the context-retention break-even formula from decision-math-and-research.md:\n * saving(i) = N_remaining * (T_raw - T_digest) * C_token - C_pack - P_need*C_retrieve\n *             - P_error*C_error - C_cache\n */\nexport interface ContextRetentionSavingInputs {\n\trawTokens: number;\n\tcompactTokens: number;\n\texpectedRemainingTurns: number;\n\tmarginalInputTokenCost: number;\n\tpackCostTokens: number;\n\tprobabilityNeededAgain: number;\n\tretrievalCostTokens: number;\n\tprobabilityErrorIfDropped: number;\n\terrorCostTokens: number;\n\tcacheImpactTokens: number;\n}\n\nexport function computeContextRetentionSaving(inputs: ContextRetentionSavingInputs): number {\n\tconst rawCost = inputs.expectedRemainingTurns * inputs.rawTokens * inputs.marginalInputTokenCost;\n\tconst compactCost = inputs.expectedRemainingTurns * inputs.compactTokens * inputs.marginalInputTokenCost;\n\tconst oneTimeCost =\n\t\tinputs.packCostTokens +\n\t\tinputs.probabilityNeededAgain * inputs.retrievalCostTokens +\n\t\tinputs.probabilityErrorIfDropped * inputs.errorCostTokens +\n\t\tinputs.cacheImpactTokens;\n\treturn rawCost - compactCost - oneTimeCost;\n}\n\n/**\n * N_break_even(i) from decision-math-and-research.md: the number of remaining turns at\n * which packing/summarizing first becomes worthwhile. Returns +Infinity when the raw vs.\n * compact token gap never pays for itself (per-turn saving is zero or negative).\n */\nexport function computeBreakEvenRemainingTurns(\n\tinputs: Omit<ContextRetentionSavingInputs, \"expectedRemainingTurns\"> & { margin: number },\n): number {\n\tconst perTurnSaving = (inputs.rawTokens - inputs.compactTokens) * inputs.marginalInputTokenCost;\n\tif (perTurnSaving <= 0) return Number.POSITIVE_INFINITY;\n\tconst oneTimeCost =\n\t\tinputs.packCostTokens +\n\t\tinputs.probabilityNeededAgain * inputs.retrievalCostTokens +\n\t\tinputs.probabilityErrorIfDropped * inputs.errorCostTokens +\n\t\tinputs.cacheImpactTokens +\n\t\tinputs.margin;\n\treturn oneTimeCost / perTurnSaving;\n}\n\n/**\n * Hard cap override from policy-engine-spec.md: oversized raw tool output must be packed\n * regardless of break-even math, unless the item is pinned, current, or the latest\n * failure.\n */\nexport function exceedsHardOutputCap(\n\trawTokens: number,\n\tmaxRawToolOutputTokens: number,\n\tfeatures: Pick<PolicyFeatures, \"isPinned\" | \"isCurrentDiff\" | \"isLatestFailure\">,\n): boolean {\n\tif (features.isPinned || features.isCurrentDiff || features.isLatestFailure) return false;\n\treturn rawTokens > maxRawToolOutputTokens;\n}\n\nexport interface ContextRetentionCandidateInput {\n\taction: PolicyAction;\n\tfeatures: PolicyFeatures;\n\tflags: HardConstraintFlags;\n\tsaving: ContextRetentionSavingInputs;\n\tmargin: number;\n\tconfidence: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * Score one context-retention candidate. Hard constraints are checked first and, if any\n * fire, the candidate is returned as unappliable (infinite cost, zero savings) no matter\n * what the break-even math says — a hard constraint can never be overridden by savings.\n */\nexport function scoreContextRetentionCandidate(input: ContextRetentionCandidateInput): PolicyCandidateScore {\n\tconst hardConstraints = evaluateHardConstraints(input.action, input.features, input.flags);\n\tif (hardConstraints.length > 0) {\n\t\treturn {\n\t\t\taction: input.action,\n\t\t\texpectedCostTokens: Number.POSITIVE_INFINITY,\n\t\t\texpectedSavingsTokens: 0,\n\t\t\texpectedReliabilityRisk: 1,\n\t\t\tcacheImpactTokens: input.saving.cacheImpactTokens,\n\t\t\treworkRiskTokens: input.saving.probabilityErrorIfDropped * input.saving.errorCostTokens,\n\t\t\tconfidence: \"low\",\n\t\t\treasonCodes: hardConstraints,\n\t\t};\n\t}\n\n\tconst saving = computeContextRetentionSaving(input.saving);\n\tconst applied = saving > input.margin;\n\tconst decisionBearingLowConfidence = input.features.isDecisionBearing && input.confidence === \"low\";\n\n\treturn {\n\t\taction: input.action,\n\t\texpectedCostTokens: input.saving.packCostTokens + input.saving.cacheImpactTokens,\n\t\texpectedSavingsTokens: Math.max(0, saving),\n\t\texpectedReliabilityRisk: input.saving.probabilityErrorIfDropped,\n\t\tcacheImpactTokens: input.saving.cacheImpactTokens,\n\t\treworkRiskTokens: input.saving.probabilityErrorIfDropped * input.saving.errorCostTokens,\n\t\tconfidence: input.confidence,\n\t\treasonCodes:\n\t\t\tapplied && !decisionBearingLowConfidence\n\t\t\t\t? [\"saving_above_margin\"]\n\t\t\t\t: decisionBearingLowConfidence\n\t\t\t\t\t? [\"low_confidence_decision_bearing\"]\n\t\t\t\t\t: [\"saving_below_margin\"],\n\t};\n}\n\nconst HARD_CONSTRAINT_REASON_TEXT: Record<PolicyHardConstraintCode, string> = {\n\tpinned_user_instruction: \"item is a pinned user instruction and must remain present verbatim\",\n\tapproval_or_denial: \"item records a user approval or denial and cannot be summarized or dropped\",\n\tsafety_constraint: \"item is a safety/security constraint and must remain present verbatim\",\n\topen_requirement: \"item is an open requirement for the active goal and cannot be dropped while active\",\n\tactive_blocker: \"item is an active blocker and must remain present until resolved\",\n\tlatest_unresolved_failure: \"item is the latest unresolved failure; dropping it risks repeating the mistake\",\n\tcurrent_diff_summary: \"item is the current diff summary during active code changes\",\n\tcurrent_validation_result: \"item is the current validation command/result and cannot be dropped while pending\",\n\tmissing_retrieval_path: \"no retrieval path (artifact/evidence ref) exists to recover this content if evicted\",\n\tpath_or_tool_scope: \"item encodes an active path/tool scope restriction that must stay enforced\",\n\tunknown_risk: \"task risk is high or unknown and this action requires stronger reliability guarantees\",\n};\n\nexport function formatHardConstraintReason(code: PolicyHardConstraintCode): string {\n\treturn HARD_CONSTRAINT_REASON_TEXT[code];\n}\n\n/** Human-readable, deterministic summary of a scored candidate's reason codes. */\nexport function formatCandidateReason(candidate: Pick<PolicyCandidateScore, \"action\" | \"reasonCodes\">): string {\n\tconst hardCodes = candidate.reasonCodes.filter(\n\t\t(code): code is PolicyHardConstraintCode => code in HARD_CONSTRAINT_REASON_TEXT,\n\t);\n\tif (hardCodes.length > 0) {\n\t\treturn `${candidate.action} rejected: ${hardCodes.map(formatHardConstraintReason).join(\"; \")}`;\n\t}\n\treturn `${candidate.action}: ${candidate.reasonCodes.join(\", \")}`;\n}\n"]}

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

@@ -0,0 +1,102 @@
+/**
+ * Pure policy-engine contracts (Phase 0.6). No behavior change: nothing here is wired
+ * into prompt construction, model routing, or validation yet. See
+ * docs/context-management-rework/policy-engine-spec.md for the design this mirrors.
+ */
+import type { ContextArtifactRef, ContextEvidenceRef, ContextRetentionClass } from "./context-item.ts";
+export type PolicyMode = "off" | "shadow" | "enforce_safe" | "enforce_all";
+export type PolicyDecisionKind = "context_retention" | "artifact_retrieval" | "tool_rerun" | "model_route" | "validation" | "goal_continuation";
+export type PolicyAction = "keep_raw" | "pack_to_artifact" | "summarize" | "drop_from_prompt" | "retrieve_artifact_slice" | "rerun_narrowed_tool" | "route_cheap" | "route_medium" | "route_expensive" | "run_validation" | "skip_optional_validation" | "continue_goal" | "stop_and_ask";
+/**
+ * Fixed, closed set of hard-constraint reason codes. The policy engine never invents a
+ * new code at runtime: every hard rejection maps to one of these.
+ */
+export type PolicyHardConstraintCode = "pinned_user_instruction" | "approval_or_denial" | "safety_constraint" | "open_requirement" | "active_blocker" | "latest_unresolved_failure" | "current_diff_summary" | "current_validation_result" | "missing_retrieval_path" | "path_or_tool_scope" | "unknown_risk";
+export interface PolicyFeatures {
+    turnIndex: number;
+    expectedRemainingTurns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    artifactBytes: number;
+    charEstimate: number;
+    calibratedTokenEstimate: number;
+    promptSection: "stable_prefix" | "volatile_tail" | "artifact" | "memory";
+    retentionClass?: ContextRetentionClass;
+    isReproducible: boolean;
+    isDecisionBearing: boolean;
+    isPinned: boolean;
+    isOpenRequirement: boolean;
+    isLatestFailure: boolean;
+    isCurrentDiff: boolean;
+    cacheHitProbability?: number;
+    cacheMissCostTokens?: number;
+    probabilityNeededAgain: number;
+    probabilityErrorIfDropped: number;
+    retrievalCostTokens: number;
+    packCostTokens: number;
+    retryCostTokens: number;
+    failureCostTokens: number;
+    validationCostTokens: number;
+    modelTier?: "cheap" | "medium" | "expensive" | "learning";
+    taskRisk?: "low" | "medium" | "high" | "unknown";
+}
+export interface PolicyCandidateScore {
+    action: PolicyAction;
+    expectedCostTokens: number;
+    expectedSavingsTokens: number;
+    expectedReliabilityRisk: number;
+    cacheImpactTokens: number;
+    reworkRiskTokens: number;
+    confidence: "low" | "medium" | "high";
+    reasonCodes: string[];
+}
+export interface PolicyDecision {
+    kind: PolicyDecisionKind;
+    selectedAction: PolicyAction;
+    mode: PolicyMode;
+    applied: boolean;
+    hardConstraints: PolicyHardConstraintCode[];
+    candidates: PolicyCandidateScore[];
+    selectedReasonCodes: string[];
+    estimatedCostTokens: number;
+    estimatedSavingsTokens: number;
+    estimatedReliabilityRisk: number;
+    cacheImpactTokens: number;
+    reworkRiskTokens: number;
+    artifactRefs: ContextArtifactRef[];
+    evidenceRefs: ContextEvidenceRef[];
+}
+/**
+ * Flags a caller supplies alongside `PolicyFeatures` so the hard-constraint evaluator can
+ * distinguish reason codes `PolicyFeatures` alone does not carry (e.g. approvals/denials
+ * and safety constraints are not modeled as separate `PolicyFeatures` booleans).
+ */
+export interface HardConstraintFlags {
+    isApprovalOrDenial: boolean;
+    isSafetyConstraint: boolean;
+    isActiveBlocker: boolean;
+    isCurrentValidationResult: boolean;
+    isPathOrToolScope: boolean;
+    /**
+     * True only if the item's existing ref is currently resolvable, not merely present.
+     * An artifact ref is resolvable only if the artifact store/payload is available; a
+     * transcript/memory/runtime ref is resolvable independent of the artifact store. Callers
+     * must compute this by checking the concrete ref kind against its backing store, not by
+     * treating "some ref is attached" as sufficient.
+     */
+    hasAvailableRetrievalPath: boolean;
+    artifactStoreAvailable: boolean;
+    /** Only relevant when the candidate action is "summarize" on decision-bearing content. */
+    hasEvidenceRefForSummary: boolean;
+    /** Only relevant for model-routing candidates ("route_cheap"). */
+    pathOrToolBoundariesEnforced: boolean;
+    /** Only relevant for model-routing candidates ("route_cheap"). */
+    validationAvailableAndStrong: boolean;
+    /** Only relevant for model-routing candidates ("route_cheap"). */
+    priorAttemptFailedForReasoningOrArchitecture: boolean;
+    /** Only relevant for model-routing candidates ("route_cheap"). */
+    isHighImpactOrBroadMultiFileEdit: boolean;
+}
+//# sourceMappingURL=policy-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy-types.d.ts","sourceRoot":"","sources":["../../../src/core/context/policy-types.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure policy-engine contracts (Phase 0.6). No behavior change: nothing here is wired\n * into prompt construction, model routing, or validation yet. See\n * docs/context-management-rework/policy-engine-spec.md for the design this mirrors.\n */\n\nimport type { ContextArtifactRef, ContextEvidenceRef, ContextRetentionClass } from \"./context-item.ts\";\n\nexport type PolicyMode = \"off\" | \"shadow\" | \"enforce_safe\" | \"enforce_all\";\n\nexport type PolicyDecisionKind =\n\t| \"context_retention\"\n\t| \"artifact_retrieval\"\n\t| \"tool_rerun\"\n\t| \"model_route\"\n\t| \"validation\"\n\t| \"goal_continuation\";\n\nexport type PolicyAction =\n\t| \"keep_raw\"\n\t| \"pack_to_artifact\"\n\t| \"summarize\"\n\t| \"drop_from_prompt\"\n\t| \"retrieve_artifact_slice\"\n\t| \"rerun_narrowed_tool\"\n\t| \"route_cheap\"\n\t| \"route_medium\"\n\t| \"route_expensive\"\n\t| \"run_validation\"\n\t| \"skip_optional_validation\"\n\t| \"continue_goal\"\n\t| \"stop_and_ask\";\n\n/**\n * Fixed, closed set of hard-constraint reason codes. The policy engine never invents a\n * new code at runtime: every hard rejection maps to one of these.\n */\nexport type PolicyHardConstraintCode =\n\t| \"pinned_user_instruction\"\n\t| \"approval_or_denial\"\n\t| \"safety_constraint\"\n\t| \"open_requirement\"\n\t| \"active_blocker\"\n\t| \"latest_unresolved_failure\"\n\t| \"current_diff_summary\"\n\t| \"current_validation_result\"\n\t| \"missing_retrieval_path\"\n\t| \"path_or_tool_scope\"\n\t| \"unknown_risk\";\n\nexport interface PolicyFeatures {\n\tturnIndex: number;\n\texpectedRemainingTurns: number;\n\tinputTokens: number;\n\toutputTokens: number;\n\tcacheReadTokens: number;\n\tcacheWriteTokens: number;\n\tartifactBytes: number;\n\tcharEstimate: number;\n\tcalibratedTokenEstimate: number;\n\tpromptSection: \"stable_prefix\" | \"volatile_tail\" | \"artifact\" | \"memory\";\n\tretentionClass?: ContextRetentionClass;\n\tisReproducible: boolean;\n\tisDecisionBearing: boolean;\n\tisPinned: boolean;\n\tisOpenRequirement: boolean;\n\tisLatestFailure: boolean;\n\tisCurrentDiff: boolean;\n\tcacheHitProbability?: number;\n\tcacheMissCostTokens?: number;\n\tprobabilityNeededAgain: number;\n\tprobabilityErrorIfDropped: number;\n\tretrievalCostTokens: number;\n\tpackCostTokens: number;\n\tretryCostTokens: number;\n\tfailureCostTokens: number;\n\tvalidationCostTokens: number;\n\tmodelTier?: \"cheap\" | \"medium\" | \"expensive\" | \"learning\";\n\ttaskRisk?: \"low\" | \"medium\" | \"high\" | \"unknown\";\n}\n\nexport interface PolicyCandidateScore {\n\taction: PolicyAction;\n\texpectedCostTokens: number;\n\texpectedSavingsTokens: number;\n\texpectedReliabilityRisk: number;\n\tcacheImpactTokens: number;\n\treworkRiskTokens: number;\n\tconfidence: \"low\" | \"medium\" | \"high\";\n\treasonCodes: string[];\n}\n\nexport interface PolicyDecision {\n\tkind: PolicyDecisionKind;\n\tselectedAction: PolicyAction;\n\tmode: PolicyMode;\n\tapplied: boolean;\n\thardConstraints: PolicyHardConstraintCode[];\n\tcandidates: PolicyCandidateScore[];\n\tselectedReasonCodes: string[];\n\testimatedCostTokens: number;\n\testimatedSavingsTokens: number;\n\testimatedReliabilityRisk: number;\n\tcacheImpactTokens: number;\n\treworkRiskTokens: number;\n\tartifactRefs: ContextArtifactRef[];\n\tevidenceRefs: ContextEvidenceRef[];\n}\n\n/**\n * Flags a caller supplies alongside `PolicyFeatures` so the hard-constraint evaluator can\n * distinguish reason codes `PolicyFeatures` alone does not carry (e.g. approvals/denials\n * and safety constraints are not modeled as separate `PolicyFeatures` booleans).\n */\nexport interface HardConstraintFlags {\n\tisApprovalOrDenial: boolean;\n\tisSafetyConstraint: boolean;\n\tisActiveBlocker: boolean;\n\tisCurrentValidationResult: boolean;\n\tisPathOrToolScope: boolean;\n\t/**\n\t * True only if the item's existing ref is currently resolvable, not merely present.\n\t * An artifact ref is resolvable only if the artifact store/payload is available; a\n\t * transcript/memory/runtime ref is resolvable independent of the artifact store. Callers\n\t * must compute this by checking the concrete ref kind against its backing store, not by\n\t * treating \"some ref is attached\" as sufficient.\n\t */\n\thasAvailableRetrievalPath: boolean;\n\tartifactStoreAvailable: boolean;\n\t/** Only relevant when the candidate action is \"summarize\" on decision-bearing content. */\n\thasEvidenceRefForSummary: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tpathOrToolBoundariesEnforced: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tvalidationAvailableAndStrong: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tpriorAttemptFailedForReasoningOrArchitecture: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tisHighImpactOrBroadMultiFileEdit: boolean;\n}\n"]}

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

@@ -0,0 +1,7 @@
+/**
+ * Pure policy-engine contracts (Phase 0.6). No behavior change: nothing here is wired
+ * into prompt construction, model routing, or validation yet. See
+ * docs/context-management-rework/policy-engine-spec.md for the design this mirrors.
+ */
+export {};
+//# sourceMappingURL=policy-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy-types.js","sourceRoot":"","sources":["../../../src/core/context/policy-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG","sourcesContent":["/**\n * Pure policy-engine contracts (Phase 0.6). No behavior change: nothing here is wired\n * into prompt construction, model routing, or validation yet. See\n * docs/context-management-rework/policy-engine-spec.md for the design this mirrors.\n */\n\nimport type { ContextArtifactRef, ContextEvidenceRef, ContextRetentionClass } from \"./context-item.ts\";\n\nexport type PolicyMode = \"off\" | \"shadow\" | \"enforce_safe\" | \"enforce_all\";\n\nexport type PolicyDecisionKind =\n\t| \"context_retention\"\n\t| \"artifact_retrieval\"\n\t| \"tool_rerun\"\n\t| \"model_route\"\n\t| \"validation\"\n\t| \"goal_continuation\";\n\nexport type PolicyAction =\n\t| \"keep_raw\"\n\t| \"pack_to_artifact\"\n\t| \"summarize\"\n\t| \"drop_from_prompt\"\n\t| \"retrieve_artifact_slice\"\n\t| \"rerun_narrowed_tool\"\n\t| \"route_cheap\"\n\t| \"route_medium\"\n\t| \"route_expensive\"\n\t| \"run_validation\"\n\t| \"skip_optional_validation\"\n\t| \"continue_goal\"\n\t| \"stop_and_ask\";\n\n/**\n * Fixed, closed set of hard-constraint reason codes. The policy engine never invents a\n * new code at runtime: every hard rejection maps to one of these.\n */\nexport type PolicyHardConstraintCode =\n\t| \"pinned_user_instruction\"\n\t| \"approval_or_denial\"\n\t| \"safety_constraint\"\n\t| \"open_requirement\"\n\t| \"active_blocker\"\n\t| \"latest_unresolved_failure\"\n\t| \"current_diff_summary\"\n\t| \"current_validation_result\"\n\t| \"missing_retrieval_path\"\n\t| \"path_or_tool_scope\"\n\t| \"unknown_risk\";\n\nexport interface PolicyFeatures {\n\tturnIndex: number;\n\texpectedRemainingTurns: number;\n\tinputTokens: number;\n\toutputTokens: number;\n\tcacheReadTokens: number;\n\tcacheWriteTokens: number;\n\tartifactBytes: number;\n\tcharEstimate: number;\n\tcalibratedTokenEstimate: number;\n\tpromptSection: \"stable_prefix\" | \"volatile_tail\" | \"artifact\" | \"memory\";\n\tretentionClass?: ContextRetentionClass;\n\tisReproducible: boolean;\n\tisDecisionBearing: boolean;\n\tisPinned: boolean;\n\tisOpenRequirement: boolean;\n\tisLatestFailure: boolean;\n\tisCurrentDiff: boolean;\n\tcacheHitProbability?: number;\n\tcacheMissCostTokens?: number;\n\tprobabilityNeededAgain: number;\n\tprobabilityErrorIfDropped: number;\n\tretrievalCostTokens: number;\n\tpackCostTokens: number;\n\tretryCostTokens: number;\n\tfailureCostTokens: number;\n\tvalidationCostTokens: number;\n\tmodelTier?: \"cheap\" | \"medium\" | \"expensive\" | \"learning\";\n\ttaskRisk?: \"low\" | \"medium\" | \"high\" | \"unknown\";\n}\n\nexport interface PolicyCandidateScore {\n\taction: PolicyAction;\n\texpectedCostTokens: number;\n\texpectedSavingsTokens: number;\n\texpectedReliabilityRisk: number;\n\tcacheImpactTokens: number;\n\treworkRiskTokens: number;\n\tconfidence: \"low\" | \"medium\" | \"high\";\n\treasonCodes: string[];\n}\n\nexport interface PolicyDecision {\n\tkind: PolicyDecisionKind;\n\tselectedAction: PolicyAction;\n\tmode: PolicyMode;\n\tapplied: boolean;\n\thardConstraints: PolicyHardConstraintCode[];\n\tcandidates: PolicyCandidateScore[];\n\tselectedReasonCodes: string[];\n\testimatedCostTokens: number;\n\testimatedSavingsTokens: number;\n\testimatedReliabilityRisk: number;\n\tcacheImpactTokens: number;\n\treworkRiskTokens: number;\n\tartifactRefs: ContextArtifactRef[];\n\tevidenceRefs: ContextEvidenceRef[];\n}\n\n/**\n * Flags a caller supplies alongside `PolicyFeatures` so the hard-constraint evaluator can\n * distinguish reason codes `PolicyFeatures` alone does not carry (e.g. approvals/denials\n * and safety constraints are not modeled as separate `PolicyFeatures` booleans).\n */\nexport interface HardConstraintFlags {\n\tisApprovalOrDenial: boolean;\n\tisSafetyConstraint: boolean;\n\tisActiveBlocker: boolean;\n\tisCurrentValidationResult: boolean;\n\tisPathOrToolScope: boolean;\n\t/**\n\t * True only if the item's existing ref is currently resolvable, not merely present.\n\t * An artifact ref is resolvable only if the artifact store/payload is available; a\n\t * transcript/memory/runtime ref is resolvable independent of the artifact store. Callers\n\t * must compute this by checking the concrete ref kind against its backing store, not by\n\t * treating \"some ref is attached\" as sufficient.\n\t */\n\thasAvailableRetrievalPath: boolean;\n\tartifactStoreAvailable: boolean;\n\t/** Only relevant when the candidate action is \"summarize\" on decision-bearing content. */\n\thasEvidenceRefForSummary: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tpathOrToolBoundariesEnforced: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tvalidationAvailableAndStrong: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tpriorAttemptFailedForReasoningOrArchitecture: boolean;\n\t/** Only relevant for model-routing candidates (\"route_cheap\"). */\n\tisHighImpactOrBroadMultiFileEdit: boolean;\n}\n"]}

package/dist/core/context/sqlite-runtime-index.d.ts

@@ -0,0 +1,19 @@
+import { DatabaseSync } from "node:sqlite";
+import type { ContextStore } from "./context-store.ts";
+import type { MemoryIndexStore } from "./memory-index-store.ts";
+export declare const SQLITE_RUNTIME_INDEX_SCHEMA_VERSION = 1;
+export declare const SQLITE_CONTEXT_INDEX_TABLES: readonly ["context_items", "artifact_metadata", "policy_score_cache", "policy_decisions", "retrieval_records", "memory_index"];
+export interface SqliteRuntimeIndexOptions {
+    databasePath: string;
+    busyTimeoutMs?: number;
+}
+export interface SqliteContextStore extends ContextStore {
+    close(): void;
+}
+export interface SqliteMemoryIndexStore extends MemoryIndexStore {
+    close(): void;
+}
+export declare function migrateSqliteRuntimeIndex(database: DatabaseSync): void;
+export declare function createSqliteContextStore(options: SqliteRuntimeIndexOptions): SqliteContextStore;
+export declare function createSqliteMemoryIndexStore(options: SqliteRuntimeIndexOptions): SqliteMemoryIndexStore;
+//# sourceMappingURL=sqlite-runtime-index.d.ts.map

package/dist/core/context/sqlite-runtime-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-runtime-index.d.ts","sourceRoot":"","sources":["../../../src/core/context/sqlite-runtime-index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,oBAAoB,CAAC;AAC9F,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGnF,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAErD,eAAO,MAAM,2BAA2B,gIAO9B,CAAC;AAEX,MAAM,WAAW,yBAAyB;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC/D,KAAK,IAAI,IAAI,CAAC;CACd;AA4BD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CA+FtE;AA4GD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAqH/F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,yBAAyB,GAAG,sBAAsB,CAkEvG","sourcesContent":["import { mkdirSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { DatabaseSync } from \"node:sqlite\";\nimport type { ContextItem } from \"./context-item.ts\";\nimport type { ContextStore, PolicyDecisionRecord, RetrievalRecord } from \"./context-store.ts\";\nimport type { MemoryIndexRecord, MemoryIndexStore } from \"./memory-index-store.ts\";\nimport type { PolicyDecision } from \"./policy-types.ts\";\n\nexport const SQLITE_RUNTIME_INDEX_SCHEMA_VERSION = 1;\n\nexport const SQLITE_CONTEXT_INDEX_TABLES = [\n\t\"context_items\",\n\t\"artifact_metadata\",\n\t\"policy_score_cache\",\n\t\"policy_decisions\",\n\t\"retrieval_records\",\n\t\"memory_index\",\n] as const;\n\nexport interface SqliteRuntimeIndexOptions {\n\tdatabasePath: string;\n\tbusyTimeoutMs?: number;\n}\n\nexport interface SqliteContextStore extends ContextStore {\n\tclose(): void;\n}\n\nexport interface SqliteMemoryIndexStore extends MemoryIndexStore {\n\tclose(): void;\n}\n\nfunction prepareDatabasePath(databasePath: string): void {\n\tif (databasePath === \":memory:\") return;\n\tmkdirSync(dirname(databasePath), { recursive: true });\n}\n\nfunction openDatabase(options: SqliteRuntimeIndexOptions): DatabaseSync {\n\tprepareDatabasePath(options.databasePath);\n\tconst database = new DatabaseSync(options.databasePath, {\n\t\tenableForeignKeyConstraints: true,\n\t\ttimeout: options.busyTimeoutMs ?? 5_000,\n\t});\n\tdatabase.exec(`\n\t\tPRAGMA foreign_keys = ON;\n\t\tPRAGMA busy_timeout = ${options.busyTimeoutMs ?? 5_000};\n\t\tPRAGMA journal_mode = WAL;\n\t`);\n\tmigrateSqliteRuntimeIndex(database);\n\treturn database;\n}\n\nfunction currentSchemaVersion(database: DatabaseSync): number {\n\tconst row = database.prepare(\"PRAGMA user_version\").get();\n\tconst value = row?.user_version;\n\treturn typeof value === \"number\" ? value : 0;\n}\n\nexport function migrateSqliteRuntimeIndex(database: DatabaseSync): void {\n\tconst version = currentSchemaVersion(database);\n\tif (version > SQLITE_RUNTIME_INDEX_SCHEMA_VERSION) {\n\t\tthrow new Error(\n\t\t\t`Unsupported Pi context runtime-index schema version ${version}; current runtime supports ${SQLITE_RUNTIME_INDEX_SCHEMA_VERSION}`,\n\t\t);\n\t}\n\n\ttry {\n\t\tdatabase.exec(`\n\t\t\tBEGIN IMMEDIATE;\n\n\t\t\tCREATE TABLE IF NOT EXISTS context_items (\n\t\t\t\tid TEXT PRIMARY KEY NOT NULL,\n\t\t\t\tkind TEXT NOT NULL,\n\t\t\t\tretention_class TEXT NOT NULL,\n\t\t\t\tsource TEXT NOT NULL,\n\t\t\t\tcreated_at_turn INTEGER NOT NULL,\n\t\t\t\tlast_used_at_turn INTEGER,\n\t\t\t\ttoken_estimate INTEGER NOT NULL,\n\t\t\t\tbyte_estimate INTEGER NOT NULL,\n\t\t\t\tpayload_json TEXT NOT NULL\n\t\t\t) STRICT;\n\n\t\t\tCREATE TABLE IF NOT EXISTS artifact_metadata (\n\t\t\t\tid TEXT PRIMARY KEY NOT NULL,\n\t\t\t\tkind TEXT NOT NULL,\n\t\t\t\tstorage_path TEXT,\n\t\t\t\tsession_entry_id TEXT,\n\t\t\t\ttool_name TEXT,\n\t\t\t\tcommand TEXT,\n\t\t\t\tpath TEXT,\n\t\t\t\tbyte_length INTEGER NOT NULL,\n\t\t\t\tline_count INTEGER,\n\t\t\t\tcreated_at_turn INTEGER NOT NULL,\n\t\t\t\treproducible INTEGER NOT NULL CHECK (reproducible IN (0, 1)),\n\t\t\t\tpayload_exists INTEGER NOT NULL DEFAULT 1 CHECK (payload_exists IN (0, 1)),\n\t\t\t\tpayload_json TEXT NOT NULL\n\t\t\t) STRICT;\n\n\t\t\tCREATE TABLE IF NOT EXISTS policy_score_cache (\n\t\t\t\tcache_key TEXT PRIMARY KEY NOT NULL,\n\t\t\t\tcreated_at_turn INTEGER NOT NULL,\n\t\t\t\tpayload_json TEXT NOT NULL\n\t\t\t) STRICT;\n\n\t\t\tCREATE TABLE IF NOT EXISTS policy_decisions (\n\t\t\t\tid TEXT PRIMARY KEY NOT NULL,\n\t\t\t\tcontext_item_id TEXT,\n\t\t\t\trecorded_at_turn INTEGER NOT NULL,\n\t\t\t\tdecision_kind TEXT NOT NULL,\n\t\t\t\tselected_action TEXT NOT NULL,\n\t\t\t\tmode TEXT NOT NULL,\n\t\t\t\tapplied INTEGER NOT NULL CHECK (applied IN (0, 1)),\n\t\t\t\tpayload_json TEXT NOT NULL\n\t\t\t) STRICT;\n\n\t\t\tCREATE INDEX IF NOT EXISTS idx_policy_decisions_context_item_id\n\t\t\t\tON policy_decisions(context_item_id, recorded_at_turn);\n\n\t\t\tCREATE TABLE IF NOT EXISTS retrieval_records (\n\t\t\t\tid TEXT PRIMARY KEY NOT NULL,\n\t\t\t\tcontext_item_id TEXT NOT NULL,\n\t\t\t\trequested_at_turn INTEGER NOT NULL,\n\t\t\t\tslice_kind TEXT NOT NULL,\n\t\t\t\tresult_summary TEXT NOT NULL,\n\t\t\t\tpayload_json TEXT NOT NULL\n\t\t\t) STRICT;\n\n\t\t\tCREATE INDEX IF NOT EXISTS idx_retrieval_records_context_item_id\n\t\t\t\tON retrieval_records(context_item_id, requested_at_turn);\n\n\t\t\tCREATE TABLE IF NOT EXISTS memory_index (\n\t\t\t\tprovider_id TEXT NOT NULL,\n\t\t\t\titem_id TEXT NOT NULL,\n\t\t\t\tscope TEXT NOT NULL,\n\t\t\t\tkind TEXT NOT NULL,\n\t\t\t\ttitle TEXT,\n\t\t\t\tsummary TEXT NOT NULL,\n\t\t\t\tindexed_at_turn INTEGER NOT NULL,\n\t\t\t\tstale INTEGER NOT NULL CHECK (stale IN (0, 1)),\n\t\t\t\tpayload_json TEXT NOT NULL,\n\t\t\t\tPRIMARY KEY (provider_id, item_id)\n\t\t\t) STRICT;\n\n\t\t\tCREATE INDEX IF NOT EXISTS idx_memory_index_scope\n\t\t\t\tON memory_index(scope, provider_id, item_id);\n\n\t\t\tPRAGMA user_version = ${SQLITE_RUNTIME_INDEX_SCHEMA_VERSION};\n\t\t\tCOMMIT;\n\t\t`);\n\t} catch (error) {\n\t\tif (database.isTransaction) database.exec(\"ROLLBACK;\");\n\t\tthrow error;\n\t}\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction parseJsonRecord<T>(json: string, isValid: (value: unknown) => value is T): T | undefined {\n\ttry {\n\t\tconst parsed: unknown = JSON.parse(json);\n\t\treturn isValid(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction textColumn(row: Record<string, unknown> | undefined, column: string): string | undefined {\n\tconst value = row?.[column];\n\treturn typeof value === \"string\" ? value : undefined;\n}\n\nfunction isContextItem(value: unknown): value is ContextItem {\n\tif (!isRecord(value)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.kind === \"string\" &&\n\t\ttypeof value.retentionClass === \"string\" &&\n\t\ttypeof value.source === \"string\" &&\n\t\ttypeof value.createdAtTurn === \"number\" &&\n\t\ttypeof value.tokenEstimate === \"number\" &&\n\t\ttypeof value.byteEstimate === \"number\"\n\t);\n}\n\nfunction isPolicyDecision(value: unknown): value is PolicyDecision {\n\tif (!isRecord(value)) return false;\n\treturn (\n\t\ttypeof value.kind === \"string\" &&\n\t\ttypeof value.selectedAction === \"string\" &&\n\t\ttypeof value.mode === \"string\" &&\n\t\ttypeof value.applied === \"boolean\" &&\n\t\tArray.isArray(value.hardConstraints) &&\n\t\tArray.isArray(value.candidates) &&\n\t\tArray.isArray(value.selectedReasonCodes) &&\n\t\ttypeof value.estimatedCostTokens === \"number\" &&\n\t\ttypeof value.estimatedSavingsTokens === \"number\" &&\n\t\ttypeof value.estimatedReliabilityRisk === \"number\" &&\n\t\ttypeof value.cacheImpactTokens === \"number\" &&\n\t\ttypeof value.reworkRiskTokens === \"number\" &&\n\t\tArray.isArray(value.artifactRefs) &&\n\t\tArray.isArray(value.evidenceRefs)\n\t);\n}\n\nfunction isPolicyDecisionRecord(value: unknown): value is PolicyDecisionRecord {\n\tif (!isRecord(value)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\t(value.contextItemId === undefined || typeof value.contextItemId === \"string\") &&\n\t\ttypeof value.recordedAtTurn === \"number\" &&\n\t\tisPolicyDecision(value.decision)\n\t);\n}\n\nfunction isRetrievalRecord(value: unknown): value is RetrievalRecord {\n\tif (!isRecord(value)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.contextItemId === \"string\" &&\n\t\ttypeof value.requestedAtTurn === \"number\" &&\n\t\ttypeof value.sliceKind === \"string\" &&\n\t\ttypeof value.resultSummary === \"string\"\n\t);\n}\n\nfunction isMemoryIndexRecord(value: unknown): value is MemoryIndexRecord {\n\tif (!isRecord(value) || !isRecord(value.ref)) return false;\n\treturn (\n\t\ttypeof value.ref.providerId === \"string\" &&\n\t\ttypeof value.ref.itemId === \"string\" &&\n\t\ttypeof value.ref.scope === \"string\" &&\n\t\ttypeof value.ref.kind === \"string\" &&\n\t\t(value.title === undefined || typeof value.title === \"string\") &&\n\t\ttypeof value.summary === \"string\" &&\n\t\ttypeof value.indexedAtTurn === \"number\" &&\n\t\ttypeof value.stale === \"boolean\"\n\t);\n}\n\nfunction contextItemFromRow(row: Record<string, unknown> | undefined): ContextItem | undefined {\n\tconst payload = textColumn(row, \"payload_json\");\n\treturn payload === undefined ? undefined : parseJsonRecord(payload, isContextItem);\n}\n\nfunction policyDecisionRecordFromRow(row: Record<string, unknown> | undefined): PolicyDecisionRecord | undefined {\n\tconst payload = textColumn(row, \"payload_json\");\n\treturn payload === undefined ? undefined : parseJsonRecord(payload, isPolicyDecisionRecord);\n}\n\nfunction retrievalRecordFromRow(row: Record<string, unknown> | undefined): RetrievalRecord | undefined {\n\tconst payload = textColumn(row, \"payload_json\");\n\treturn payload === undefined ? undefined : parseJsonRecord(payload, isRetrievalRecord);\n}\n\nfunction memoryIndexRecordFromRow(row: Record<string, unknown> | undefined): MemoryIndexRecord | undefined {\n\tconst payload = textColumn(row, \"payload_json\");\n\treturn payload === undefined ? undefined : parseJsonRecord(payload, isMemoryIndexRecord);\n}\n\nexport function createSqliteContextStore(options: SqliteRuntimeIndexOptions): SqliteContextStore {\n\tconst database = openDatabase(options);\n\tconst upsertItem = database.prepare(`\n\t\tINSERT INTO context_items (\n\t\t\tid, kind, retention_class, source, created_at_turn, last_used_at_turn, token_estimate, byte_estimate, payload_json\n\t\t) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n\t\tON CONFLICT(id) DO UPDATE SET\n\t\t\tkind = excluded.kind,\n\t\t\tretention_class = excluded.retention_class,\n\t\t\tsource = excluded.source,\n\t\t\tcreated_at_turn = excluded.created_at_turn,\n\t\t\tlast_used_at_turn = excluded.last_used_at_turn,\n\t\t\ttoken_estimate = excluded.token_estimate,\n\t\t\tbyte_estimate = excluded.byte_estimate,\n\t\t\tpayload_json = excluded.payload_json\n\t`);\n\tconst getItem = database.prepare(\"SELECT payload_json FROM context_items WHERE id = ?\");\n\tconst listItems = database.prepare(\"SELECT payload_json FROM context_items ORDER BY created_at_turn, id\");\n\tconst removeItem = database.prepare(\"DELETE FROM context_items WHERE id = ?\");\n\tconst recordPolicyDecision = database.prepare(`\n\t\tINSERT INTO policy_decisions (\n\t\t\tid, context_item_id, recorded_at_turn, decision_kind, selected_action, mode, applied, payload_json\n\t\t) VALUES (?, ?, ?, ?, ?, ?, ?, ?)\n\t`);\n\tconst listAllPolicyDecisions = database.prepare(\n\t\t\"SELECT payload_json FROM policy_decisions ORDER BY recorded_at_turn, id\",\n\t);\n\tconst listPolicyDecisionsByItem = database.prepare(\n\t\t\"SELECT payload_json FROM policy_decisions WHERE context_item_id = ? ORDER BY recorded_at_turn, id\",\n\t);\n\tconst recordRetrieval = database.prepare(`\n\t\tINSERT INTO retrieval_records (\n\t\t\tid, context_item_id, requested_at_turn, slice_kind, result_summary, payload_json\n\t\t) VALUES (?, ?, ?, ?, ?, ?)\n\t`);\n\tconst listAllRetrievals = database.prepare(\n\t\t\"SELECT payload_json FROM retrieval_records ORDER BY requested_at_turn, id\",\n\t);\n\tconst listRetrievalsByItem = database.prepare(\n\t\t\"SELECT payload_json FROM retrieval_records WHERE context_item_id = ? ORDER BY requested_at_turn, id\",\n\t);\n\n\treturn {\n\t\tupsertItem(item: ContextItem): void {\n\t\t\tupsertItem.run(\n\t\t\t\titem.id,\n\t\t\t\titem.kind,\n\t\t\t\titem.retentionClass,\n\t\t\t\titem.source,\n\t\t\t\titem.createdAtTurn,\n\t\t\t\titem.lastUsedAtTurn ?? null,\n\t\t\t\titem.tokenEstimate,\n\t\t\t\titem.byteEstimate,\n\t\t\t\tJSON.stringify(item),\n\t\t\t);\n\t\t},\n\n\t\tgetItem(id: string): ContextItem | undefined {\n\t\t\treturn contextItemFromRow(getItem.get(id));\n\t\t},\n\n\t\tlistItems(): ContextItem[] {\n\t\t\treturn listItems.all().flatMap((row) => {\n\t\t\t\tconst item = contextItemFromRow(row);\n\t\t\t\treturn item === undefined ? [] : [item];\n\t\t\t});\n\t\t},\n\n\t\tremoveItem(id: string): void {\n\t\t\tremoveItem.run(id);\n\t\t},\n\n\t\trecordPolicyDecision(record: PolicyDecisionRecord): void {\n\t\t\trecordPolicyDecision.run(\n\t\t\t\trecord.id,\n\t\t\t\trecord.contextItemId ?? null,\n\t\t\t\trecord.recordedAtTurn,\n\t\t\t\trecord.decision.kind,\n\t\t\t\trecord.decision.selectedAction,\n\t\t\t\trecord.decision.mode,\n\t\t\t\trecord.decision.applied ? 1 : 0,\n\t\t\t\tJSON.stringify(record),\n\t\t\t);\n\t\t},\n\n\t\tlistPolicyDecisions(contextItemId?: string): PolicyDecisionRecord[] {\n\t\t\tconst rows =\n\t\t\t\tcontextItemId === undefined ? listAllPolicyDecisions.all() : listPolicyDecisionsByItem.all(contextItemId);\n\t\t\treturn rows.flatMap((row) => {\n\t\t\t\tconst record = policyDecisionRecordFromRow(row);\n\t\t\t\treturn record === undefined ? [] : [record];\n\t\t\t});\n\t\t},\n\n\t\trecordRetrieval(record: RetrievalRecord): void {\n\t\t\trecordRetrieval.run(\n\t\t\t\trecord.id,\n\t\t\t\trecord.contextItemId,\n\t\t\t\trecord.requestedAtTurn,\n\t\t\t\trecord.sliceKind,\n\t\t\t\trecord.resultSummary,\n\t\t\t\tJSON.stringify(record),\n\t\t\t);\n\t\t},\n\n\t\tlistRetrievals(contextItemId?: string): RetrievalRecord[] {\n\t\t\tconst rows = contextItemId === undefined ? listAllRetrievals.all() : listRetrievalsByItem.all(contextItemId);\n\t\t\treturn rows.flatMap((row) => {\n\t\t\t\tconst record = retrievalRecordFromRow(row);\n\t\t\t\treturn record === undefined ? [] : [record];\n\t\t\t});\n\t\t},\n\n\t\tclose(): void {\n\t\t\tdatabase[Symbol.dispose]();\n\t\t},\n\t};\n}\n\nexport function createSqliteMemoryIndexStore(options: SqliteRuntimeIndexOptions): SqliteMemoryIndexStore {\n\tconst database = openDatabase(options);\n\tconst upsert = database.prepare(`\n\t\tINSERT INTO memory_index (\n\t\t\tprovider_id, item_id, scope, kind, title, summary, indexed_at_turn, stale, payload_json\n\t\t) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n\t\tON CONFLICT(provider_id, item_id) DO UPDATE SET\n\t\t\tscope = excluded.scope,\n\t\t\tkind = excluded.kind,\n\t\t\ttitle = excluded.title,\n\t\t\tsummary = excluded.summary,\n\t\t\tindexed_at_turn = excluded.indexed_at_turn,\n\t\t\tstale = excluded.stale,\n\t\t\tpayload_json = excluded.payload_json\n\t`);\n\tconst get = database.prepare(\"SELECT payload_json FROM memory_index WHERE provider_id = ? AND item_id = ?\");\n\tconst listAll = database.prepare(\"SELECT payload_json FROM memory_index ORDER BY provider_id, item_id\");\n\tconst listByScope = database.prepare(\n\t\t\"SELECT payload_json FROM memory_index WHERE scope = ? ORDER BY provider_id, item_id\",\n\t);\n\tconst markStale = database.prepare(\n\t\t\"UPDATE memory_index SET stale = 1, payload_json = ? WHERE provider_id = ? AND item_id = ?\",\n\t);\n\tconst remove = database.prepare(\"DELETE FROM memory_index WHERE provider_id = ? AND item_id = ?\");\n\n\treturn {\n\t\tupsert(record: MemoryIndexRecord): void {\n\t\t\tupsert.run(\n\t\t\t\trecord.ref.providerId,\n\t\t\t\trecord.ref.itemId,\n\t\t\t\trecord.ref.scope,\n\t\t\t\trecord.ref.kind,\n\t\t\t\trecord.title ?? null,\n\t\t\t\trecord.summary,\n\t\t\t\trecord.indexedAtTurn,\n\t\t\t\trecord.stale ? 1 : 0,\n\t\t\t\tJSON.stringify(record),\n\t\t\t);\n\t\t},\n\n\t\tget(providerId: string, itemId: string): MemoryIndexRecord | undefined {\n\t\t\treturn memoryIndexRecordFromRow(get.get(providerId, itemId));\n\t\t},\n\n\t\tlist(scope?: MemoryIndexRecord[\"ref\"][\"scope\"]): MemoryIndexRecord[] {\n\t\t\tconst rows = scope === undefined ? listAll.all() : listByScope.all(scope);\n\t\t\treturn rows.flatMap((row) => {\n\t\t\t\tconst record = memoryIndexRecordFromRow(row);\n\t\t\t\treturn record === undefined ? [] : [record];\n\t\t\t});\n\t\t},\n\n\t\tmarkStale(providerId: string, itemId: string): void {\n\t\t\tconst existing = memoryIndexRecordFromRow(get.get(providerId, itemId));\n\t\t\tif (existing === undefined) return;\n\t\t\tmarkStale.run(JSON.stringify({ ...existing, stale: true }), providerId, itemId);\n\t\t},\n\n\t\tremove(providerId: string, itemId: string): void {\n\t\t\tremove.run(providerId, itemId);\n\t\t},\n\n\t\tclose(): void {\n\t\t\tdatabase[Symbol.dispose]();\n\t\t},\n\t};\n}\n"]}