@noetic-tools/context 1.1.0 → 1.2.0

package/dist/context/cache-anchoring.d.ts

@@ -0,0 +1,103 @@
+import type { AnchorPin, ContextCacheConfig, ContextCacheStore, ContextEpoch, ContextLayer, ExecutionContext, LayerChurn, LLMResponse, ReanchorReason } from '@noetic-tools/types';
+export type { AnchorPin, ContextCacheConfig, ContextCacheStore, ContextEpoch, LayerChurn, ReanchorReason, } from '@noetic-tools/types';
+/** Defaults for prompt-cache anchoring. See `ContextCacheConfig` for what each one does. */
+export declare const DEFAULT_CONTEXT_CACHE: Required<ContextCacheConfig>;
+/** Fills a partial config with the defaults. */
+export declare function resolveCacheConfig(config?: ContextCacheConfig): Required<ContextCacheConfig>;
+/**
+ * The run of assemblies that share a cacheable prompt prefix.
+ *
+ * A thread at top level, because its turns build one growing conversation. A
+ * child execution keys on itself instead: it inherits its parent's `threadId`
+ * but assembles a different view, so sharing pins would replay a prefix that was
+ * never sent on its behalf.
+ */
+export declare function lineageKey(ctx: ExecutionContext): string;
+/**
+ * Where a layer's pin lives within its epoch.
+ *
+ * The layer id alone, deliberately — the epoch is already scoped to one cache
+ * lineage, and layer ids are unique within a layer set. Folding the layer's
+ * `scope` into the key (as the eventual-recall cache does, where one map spans
+ * every thread) would rotate it every turn for an `'execution'`-scoped layer,
+ * so each turn would retract the "old" pin and add a "new" one for the very
+ * same layer — republishing its content in full, forever.
+ */
+export declare function pinKey(layer: ContextLayer): string;
+export declare function createContextCacheStore(): ContextCacheStore;
+/** Drop a lineage's epoch — used when a child execution ends. */
+export declare function dropLineage(store: ContextCacheStore, key: string): void;
+/** Read a layer's churn record, creating an empty one on first sight. */
+export declare function churnFor(store: ContextCacheStore, key: string): LayerChurn;
+/** Share of watched assemblies in which a layer's output changed, 0–1. */
+export declare function churnRate(churn: LayerChurn): number;
+interface OpenEpochParams {
+    store: ContextCacheStore;
+    key: string;
+    reason: ReanchorReason;
+    instructionsHash: string;
+    layers: ReadonlyArray<ContextLayer>;
+    config: Required<ContextCacheConfig>;
+}
+/**
+ * Start a fresh epoch for a lineage, dropping every pin so the next assembly
+ * re-anchors against current recall output.
+ *
+ * This is the only point at which `'auto'` layers change band: placement is held
+ * still inside an epoch so the prefix cannot shift under the model mid-run.
+ * Churn carries across, decayed, so a layer's band is not relearnt from nothing
+ * each time.
+ */
+export declare function openEpoch({ store, key, reason, instructionsHash, layers, config, }: OpenEpochParams): ContextEpoch;
+/**
+ * Record a lineage as most recently used.
+ *
+ * `Map` keeps first-insertion order, so re-setting an existing key would leave
+ * it where it was and let eviction drop the busiest lineage. Deleting first
+ * moves it to the end, which is what makes eviction least-recently-used.
+ */
+export declare function touchLineage(store: ContextCacheStore, key: string, epoch?: ContextEpoch): void;
+/**
+ * Why the coming assembly must re-anchor, or `undefined` to carry the epoch on.
+ * Ordered cheapest-check first; delta pressure is decided later, once the
+ * supersedes are actually built.
+ */
+export declare function reanchorReason({ epoch, key, instructionsHash, store, config, }: {
+    epoch: ContextEpoch | undefined;
+    key: string;
+    instructionsHash: string;
+    store: ContextCacheStore;
+    config: Required<ContextCacheConfig>;
+}): ReanchorReason | undefined;
+interface NoteCacheOutcomeParams {
+    store: ContextCacheStore;
+    key: string;
+    response: LLMResponse;
+    config: Required<ContextCacheConfig>;
+    /** Tokens the prefix was expected to have cached — system plus anchor band. */
+    expectedTokens: number;
+}
+/**
+ * Judge, from the model's own token report, whether the prompt prefix survived,
+ * and record a re-anchor for the next assembly if it did not.
+ *
+ * Records intent only; pins are never touched here, so a response that steering
+ * later rejects cannot leave the epoch half-rebuilt.
+ *
+ * Three things stop this eating itself:
+ *
+ * - Only the first round counts. Later rounds replay the same view plus tool
+ *   traffic and so hit the cache whatever the first round did — summing them
+ *   hides a total miss behind a busy tool loop.
+ * - Young epochs are spared. The assembly right after a re-anchor writes the
+ *   cache rather than reading it, so its near-zero read is expected, not a miss.
+ * - A provider that reports nothing, or misses persistently, is marked blind and
+ *   stops being consulted. Age and delta pressure still bound the epoch.
+ */
+export declare function noteCacheOutcome({ store, key, response, config, expectedTokens, }: NoteCacheOutcomeParams): void;
+/**
+ * Record a layer's rendered output as the bytes to replay for the rest of the
+ * epoch. The caller sets `epoch.anchorTokens` from the assembled band, which is
+ * measured the same way as the supersedes it gets compared against.
+ */
+export declare function pin(epoch: ContextEpoch, key: string, entry: AnchorPin): void;

package/dist/context/cache-anchoring.js

@@ -0,0 +1,273 @@
+//#region Config
+/** Defaults for prompt-cache anchoring. See `ContextCacheConfig` for what each one does. */
+export const DEFAULT_CONTEXT_CACHE = {
+    enabled: true,
+    minCachedTokens: 100,
+    minEpochAssemblies: 2,
+    maxEpochAssemblies: 50,
+    deltaBudgetFraction: 0.15,
+    autoDemoteChurn: 0.5,
+    autoPromoteChurn: 0.2,
+    minChurnSamples: 3,
+    churnDecay: 0.5,
+};
+/** Fills a partial config with the defaults. */
+export function resolveCacheConfig(config) {
+    return {
+        ...DEFAULT_CONTEXT_CACHE,
+        ...config,
+    };
+}
+/**
+ * Judged assemblies that may come back a miss before the runtime stops steering
+ * on the provider's cache figures. A provider that never caches would otherwise
+ * re-anchor on every turn forever, for no gain.
+ */
+const MAX_CONSECUTIVE_MISSES = 3;
+/** Lineages retained per harness before the least recently used is dropped. */
+const MAX_LINEAGES = 256;
+//#endregion
+//#region Keys
+/**
+ * The run of assemblies that share a cacheable prompt prefix.
+ *
+ * A thread at top level, because its turns build one growing conversation. A
+ * child execution keys on itself instead: it inherits its parent's `threadId`
+ * but assembles a different view, so sharing pins would replay a prefix that was
+ * never sent on its behalf.
+ */
+export function lineageKey(ctx) {
+    return ctx.depth === 0 ? `t:${ctx.threadId}` : `x:${ctx.executionId}`;
+}
+/**
+ * Where a layer's pin lives within its epoch.
+ *
+ * The layer id alone, deliberately — the epoch is already scoped to one cache
+ * lineage, and layer ids are unique within a layer set. Folding the layer's
+ * `scope` into the key (as the eventual-recall cache does, where one map spans
+ * every thread) would rotate it every turn for an `'execution'`-scoped layer,
+ * so each turn would retract the "old" pin and add a "new" one for the very
+ * same layer — republishing its content in full, forever.
+ */
+export function pinKey(layer) {
+    return layer.id;
+}
+//#endregion
+//#region Store
+export function createContextCacheStore() {
+    return {
+        epochs: new Map(),
+        churn: new Map(),
+        pendingReanchor: new Map(),
+    };
+}
+/** Drop a lineage's epoch — used when a child execution ends. */
+export function dropLineage(store, key) {
+    store.epochs.delete(key);
+    store.pendingReanchor.delete(key);
+}
+/** Read a layer's churn record, creating an empty one on first sight. */
+export function churnFor(store, key) {
+    const found = store.churn.get(key);
+    if (found) {
+        return found;
+    }
+    const fresh = {
+        observed: 0,
+        changed: 0,
+        rebillTokens: 0,
+    };
+    store.churn.set(key, fresh);
+    return fresh;
+}
+/** Share of watched assemblies in which a layer's output changed, 0–1. */
+export function churnRate(churn) {
+    return churn.observed === 0 ? 0 : churn.changed / churn.observed;
+}
+/**
+ * Start a fresh epoch for a lineage, dropping every pin so the next assembly
+ * re-anchors against current recall output.
+ *
+ * This is the only point at which `'auto'` layers change band: placement is held
+ * still inside an epoch so the prefix cannot shift under the model mid-run.
+ * Churn carries across, decayed, so a layer's band is not relearnt from nothing
+ * each time.
+ */
+export function openEpoch({ store, key, reason, instructionsHash, layers, config, }) {
+    const previous = store.epochs.get(key);
+    const generation = previous ? Number(previous.id.split('#')[1] ?? 0) + 1 : 0;
+    const autoBand = new Map();
+    for (const layer of layers) {
+        const k = pinKey(layer);
+        autoBand.set(k, chooseBand({
+            store,
+            key: k,
+            current: previous?.autoBand.get(k),
+            config,
+        }));
+    }
+    decayChurn({
+        store,
+        layers,
+        decay: config.churnDecay,
+    });
+    const epoch = {
+        id: `${key}#${generation}`,
+        pins: new Map(),
+        autoBand,
+        instructionsHash,
+        assemblies: 0,
+        anchorTokens: 0,
+        deltaTokens: 0,
+        // A provider that has already shown it reports nothing stays untrusted
+        // across epochs; there is no reason to expect it to start.
+        cacheBlind: previous?.cacheBlind ?? false,
+        // Misses carry across epochs. A miss is what CAUSED this re-anchor, so
+        // resetting here would make the give-up threshold unreachable and leave a
+        // never-caching provider re-anchoring on every turn forever.
+        misses: previous?.misses ?? 0,
+        lastReanchorReason: reason,
+    };
+    store.pendingReanchor.delete(key);
+    touchLineage(store, key, epoch);
+    evictOldestLineages(store);
+    return epoch;
+}
+/**
+ * Record a lineage as most recently used.
+ *
+ * `Map` keeps first-insertion order, so re-setting an existing key would leave
+ * it where it was and let eviction drop the busiest lineage. Deleting first
+ * moves it to the end, which is what makes eviction least-recently-used.
+ */
+export function touchLineage(store, key, epoch) {
+    const current = epoch ?? store.epochs.get(key);
+    if (!current) {
+        return;
+    }
+    store.epochs.delete(key);
+    store.epochs.set(key, current);
+}
+/**
+ * The band an `'auto'` layer takes for the coming epoch.
+ *
+ * The promote and demote thresholds leave a gap on purpose: a layer sitting
+ * between them keeps the band it already had, so one hovering near the boundary
+ * does not flip every epoch and undo the stability the bands exist to provide.
+ */
+function chooseBand({ store, key, current, config, }) {
+    const churn = store.churn.get(key);
+    const band = current ?? 'anchor';
+    if (!churn || churn.observed < config.minChurnSamples) {
+        return band;
+    }
+    const rate = churnRate(churn);
+    if (rate >= config.autoDemoteChurn) {
+        return 'live';
+    }
+    if (rate <= config.autoPromoteChurn) {
+        return 'anchor';
+    }
+    return band;
+}
+function decayChurn({ store, layers, decay, }) {
+    for (const layer of layers) {
+        const churn = store.churn.get(pinKey(layer));
+        if (!churn) {
+            continue;
+        }
+        churn.observed *= decay;
+        churn.changed *= decay;
+        churn.rebillTokens *= decay;
+    }
+}
+/** Keep the lineage map bounded on a long-lived harness that spawns many children. */
+function evictOldestLineages(store) {
+    while (store.epochs.size > MAX_LINEAGES) {
+        const oldest = store.epochs.keys().next();
+        if (oldest.done) {
+            return;
+        }
+        dropLineage(store, oldest.value);
+    }
+}
+/**
+ * Why the coming assembly must re-anchor, or `undefined` to carry the epoch on.
+ * Ordered cheapest-check first; delta pressure is decided later, once the
+ * supersedes are actually built.
+ */
+export function reanchorReason({ epoch, key, instructionsHash, store, config, }) {
+    if (!epoch) {
+        return 'cold-start';
+    }
+    if (epoch.instructionsHash !== instructionsHash) {
+        return 'instructions-changed';
+    }
+    const pending = store.pendingReanchor.get(key);
+    if (pending) {
+        return pending;
+    }
+    if (epoch.assemblies >= config.maxEpochAssemblies) {
+        return 'max-age';
+    }
+    return undefined;
+}
+/**
+ * Judge, from the model's own token report, whether the prompt prefix survived,
+ * and record a re-anchor for the next assembly if it did not.
+ *
+ * Records intent only; pins are never touched here, so a response that steering
+ * later rejects cannot leave the epoch half-rebuilt.
+ *
+ * Three things stop this eating itself:
+ *
+ * - Only the first round counts. Later rounds replay the same view plus tool
+ *   traffic and so hit the cache whatever the first round did — summing them
+ *   hides a total miss behind a busy tool loop.
+ * - Young epochs are spared. The assembly right after a re-anchor writes the
+ *   cache rather than reading it, so its near-zero read is expected, not a miss.
+ * - A provider that reports nothing, or misses persistently, is marked blind and
+ *   stops being consulted. Age and delta pressure still bound the epoch.
+ */
+export function noteCacheOutcome({ store, key, response, config, expectedTokens, }) {
+    const epoch = store.epochs.get(key);
+    if (!epoch || epoch.cacheBlind) {
+        return;
+    }
+    const round = response.rounds?.[0] ?? response.usage;
+    if (!round || round.cachedTokens === undefined) {
+        epoch.cacheBlind = true;
+        return;
+    }
+    // Reads of zero alongside a write mean the prefix was just stored, not missed.
+    if ((round.cacheWriteTokens ?? 0) > 0 && round.cachedTokens === 0) {
+        return;
+    }
+    if (epoch.assemblies < config.minEpochAssemblies) {
+        return;
+    }
+    // Judge against what there actually was to cache: a short prompt can never
+    // reach a fixed floor, and holding it to one would re-anchor forever.
+    const floor = Math.min(config.minCachedTokens, expectedTokens * 0.5);
+    if (round.cachedTokens >= floor) {
+        epoch.misses = 0;
+        return;
+    }
+    epoch.misses += 1;
+    if (epoch.misses >= MAX_CONSECUTIVE_MISSES) {
+        epoch.cacheBlind = true;
+        return;
+    }
+    store.pendingReanchor.set(key, 'cache-miss');
+}
+//#endregion
+//#region Pins
+/**
+ * Record a layer's rendered output as the bytes to replay for the rest of the
+ * epoch. The caller sets `epoch.anchorTokens` from the assembled band, which is
+ * measured the same way as the supersedes it gets compared against.
+ */
+export function pin(epoch, key, entry) {
+    epoch.pins.set(key, entry);
+}
+//#endregion

package/dist/context/layer-lifecycle.d.ts

@@ -172,15 +172,13 @@ export interface RecallCache {
 export declare function createRecallCache(): RecallCache;
 export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
 export declare function initLayers({ layers, ctx, storage, store }: InitLayersParams): Promise<void>;
-export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<{
-    layerId: string;
-    items: Item[];
-    tokenCount: number;
-}[]>;
+export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<RecallEntry[]>;
 type RecallEntry = {
     layerId: string;
     items: Item[];
     tokenCount: number;
+    /** See `RecallLayerOutput.mutatedState` — set when `recall` returned new state. */
+    mutatedState?: boolean;
 };
 interface RecallLayersModeParams extends RecallLayersParams {
     /** When true, treat every layer as atomic regardless of its `recallMode`. */

package/dist/context/layer-lifecycle.js

@@ -278,12 +278,16 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
                 });
                 continue;
             }
+            // Returning state means the render changed something, so it cannot be
+            // replayed from a pin — flag it so view assembly never anchors it.
+            const mutatedState = result.state !== undefined;
             results.push({
                 layerId: layer.id,
                 items: layerSchemas.parseMany(result.items),
                 tokenCount: result.tokenCount,
+                mutatedState,
             });
-            if (result.state !== undefined) {
+            if (mutatedState) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
         }
@@ -340,7 +344,13 @@ export async function recallLayersEventual({ cache, forceAtomic, ...params }) {
             cache.stale.delete(key);
             continue;
         }
-        results.push(cached);
+        // Serving from cache commits nothing, so the flag from the render that
+        // populated it must not ride along — it would force the layer out of the
+        // anchor band for good, on turns where its recall never even ran.
+        results.push({
+            ...cached,
+            mutatedState: false,
+        });
     }
     return results;
 }

package/dist/context/layer-usage.d.ts

@@ -1,13 +1,28 @@
-import type { Context, LastLayerUsage, RecallLayerOutput, Tool } from '@noetic-tools/types';
+import type { Context, EpochUsage, LastLayerUsage, RecallLayerOutput, Tool } from '@noetic-tools/types';
+/** How a layer's output was banded and pinned for this assembly. */
+export interface LayerServeInfo {
+    placement: 'anchor' | 'live';
+    served: 'fresh' | 'pinned';
+    changed: boolean;
+    churnRate: number;
+    rebillTokens: number;
+}
 interface ComputeLayerUsageParams {
     ctx: Context;
     modelId: string;
     instructions?: string;
     tools?: ReadonlyArray<Tool>;
-    /** Per-layer recall output assembled into the context view for this LLM call. */
+    /**
+     * Per-layer output as it was ACTUALLY served into the view — pinned replays
+     * included. Passing raw recall output here would report content the model
+     * never saw.
+     */
     recallResults: ReadonlyArray<RecallLayerOutput>;
+    /** Banding and pin status per layer id. Absent when context caching is off. */
+    serveInfo?: ReadonlyMap<string, LayerServeInfo>;
+    epoch?: EpochUsage;
 }
-export declare function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }: ComputeLayerUsageParams): LastLayerUsage;
+export declare function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, serveInfo, epoch, }: ComputeLayerUsageParams): LastLayerUsage;
 /** Commit computed usage to the Context, replacing any prior snapshot. */
 export declare function commitLayerUsage(ctx: Context, usage: LastLayerUsage): void;
 export {};

package/dist/context/layer-usage.js

@@ -6,6 +6,13 @@ function canWriteLayerUsage(ctx) {
     }
     return desc.writable !== false;
 }
+const SERVED_FRESH_ANCHOR = {
+    placement: 'anchor',
+    served: 'fresh',
+    changed: false,
+    churnRate: 0,
+    rebillTokens: 0,
+};
 //#endregion
 //#region Helpers
 function estimateJsonTokens(value) {
@@ -18,12 +25,13 @@ function estimateJsonTokens(value) {
 }
 //#endregion
 //#region Public API
-export function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }) {
+export function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, serveInfo, epoch, }) {
     const layers = recallResults
         .map((r) => ({
         layerId: r.layerId,
         tokenCount: r.tokenCount,
         items: r.items,
+        ...(serveInfo?.get(r.layerId) ?? SERVED_FRESH_ANCHOR),
     }))
         .sort((a, b) => a.layerId.localeCompare(b.layerId));
     let historyTokens = 0;
@@ -42,6 +50,7 @@ export function computeLayerUsage({ ctx, modelId, instructions, tools, recallRes
         toolsTokens,
         historyTokens,
         totalUsedTokens,
+        epoch,
     };
 }
 /** Commit computed usage to the Context, replacing any prior snapshot. */

package/dist/context/layers/file-reference.js

@@ -688,6 +688,59 @@ async function recallFileReferences({ state, budget, }) {
         tokenCount: estimateTokens(content),
     };
 }
+/**
+ * Splits a rendered `# Referenced Files` block back into one entry per file,
+ * keyed by the `## <path>` heading.
+ */
+function splitFileBlocks(items) {
+    const blocks = new Map();
+    for (const item of items) {
+        if (item.type !== 'message' || !('content' in item)) {
+            continue;
+        }
+        for (const part of item.content ?? []) {
+            if (!('text' in part) || typeof part.text !== 'string') {
+                continue;
+            }
+            for (const chunk of part.text.split(/\n(?=## )/)) {
+                const heading = chunk.match(/^## (.+)$/m);
+                if (heading?.[1]) {
+                    blocks.set(heading[1].trim(), chunk.trim());
+                }
+            }
+        }
+    }
+    return blocks;
+}
+/**
+ * Describes what changed about the tracked files rather than re-sending all of
+ * them. The whole set is usually large and usually stable, so a change to one
+ * file would otherwise cost a full republish.
+ */
+async function renderFileReferenceDelta({ prev, next, }) {
+    const before = splitFileBlocks(prev);
+    const after = splitFileBlocks(next);
+    const changed = [];
+    for (const [path, block] of after) {
+        if (before.get(path) !== block) {
+            changed.push(block);
+        }
+    }
+    const dropped = [
+        ...before.keys(),
+    ].filter((path) => !after.has(path));
+    if (changed.length === 0 && dropped.length === 0) {
+        return null;
+    }
+    const parts = [];
+    if (changed.length > 0) {
+        parts.push(changed.join('\n\n'));
+    }
+    if (dropped.length > 0) {
+        parts.push(`No longer referenced: ${dropped.join(', ')}`);
+    }
+    return parts.join('\n\n');
+}
 //#endregion
 //#region Layer Factory
 /**
@@ -713,6 +766,9 @@ export function fileReference(opts) {
         scope: 'thread',
         budget: 'auto',
         rerenderTiming: 'immediate',
+        // A large payload that changes rarely, and only a file at a time — the case
+        // anchoring plus a compact supersede is worth the most on.
+        placement: 'anchor',
         timeouts: {
             // onItemAppend reads files AND runs an LLM scoring call per new
             // reference (parallelized) — the 5s pipeline default silently drops the
@@ -723,6 +779,7 @@ export function fileReference(opts) {
             init: () => initFileReferenceState(runtime.baseDir),
             onItemAppend: (args) => onFileReferenceItemAppend(args, runtime),
             recall: recallFileReferences,
+            renderDelta: renderFileReferenceDelta,
         },
     };
 }

package/dist/context/layers/static-content.d.ts

@@ -17,6 +17,7 @@ export declare function staticContent(opts: StaticContentOpts): {
     id: string;
     slot: number;
     scope: ContextScope;
+    placement: "anchor";
     hooks: {
         init(): Promise<{
             state: string;

package/dist/context/layers/static-content.js

@@ -12,6 +12,9 @@ export function staticContent(opts) {
         id: opts.id ?? 'static-content',
         slot: opts.slot ?? Slot.WORKING_MEMORY + 5,
         scope: opts.scope ?? 'resource',
+        // Loaded once in `init` and never rewritten, so it can be pinned outright
+        // rather than waiting for churn telemetry to work that out.
+        placement: 'anchor',
         hooks: {
             async init() {
                 const raw = await opts.load();

package/dist/context/layers/steering.d.ts

@@ -11,6 +11,7 @@ export declare function steering(config: SteeringConfig): {
     name: string;
     slot: 90;
     scope: ContextScope;
+    placement: "live";
     budget: {
         min: number;
         max: number;

package/dist/context/layers/steering.js

@@ -162,6 +162,11 @@ export function steering(config) {
         name: 'Steering',
         slot: Slot.STEERING,
         scope,
+        // `recall` drains the pending queue as it renders, so its output can never
+        // be replayed from a pin — the drain is already committed, and serving an
+        // older render would lose the feedback for good. Rendering after history
+        // also puts guidance where the model weighs it most.
+        placement: 'live',
         budget: {
             min: 0,
             max: 500,

package/dist/context/layers/temporal-context.js

@@ -211,6 +211,12 @@ export function temporalContext(config) {
         // Grounding sits near the top of the window, before reasoning content.
         slot: Slot.REMINDER,
         scope: config?.scope ?? 'resource',
+        // The `<current_datetime>` block changes every turn by construction, so
+        // anchoring it would re-bill the whole window each time. Churn telemetry
+        // would reach the same verdict — this just skips the learning cost. With
+        // grounding off, only the slow-moving fact ledger remains, which is worth
+        // anchoring, so leave that to `'auto'`.
+        placement: groundDateTime ? 'live' : 'auto',
         budget: {
             min: 0,
             max: injectLedger ? 800 : 200,

package/dist/context/projector.d.ts

@@ -1,19 +1,38 @@
 import type { Item, ProjectionPolicy } from '@noetic-tools/types';
 interface AssembleViewParams {
     systemPromptItems: Item[];
+    /** Anchor band — layer output rendered before history, where a prompt cache can hold it. */
     layerOutputItems: Item[];
     historyItems: Item[];
+    /** Live band — layer output rendered after history, slot-ascending. */
+    liveLayerItems?: Item[];
+    /** Supersedes for anchored layers whose pinned output went stale. */
+    deltaItems?: Item[];
+    /** Items that must land last, after everything else. Never dropped. */
+    tailItems?: Item[];
     policy?: ProjectionPolicy;
 }
 /**
- * Assemble the model's context window from system prompt items, context-layer
- * recall output (slot-ascending), and conversation history.
+ * Assemble the model's context window in bands:
  *
- * Without a `policy` the inputs are concatenated as-is (optionally sliding the
- * history window by `windowSize`). With a `policy` the assembled view is held to
- * a hard token budget: system items are always kept; layer output is kept
- * low-slot-first (highest-slot dropped when tight); history takes the remainder,
- * keeping the most recent turns.
+ * ```
+ * system | anchor layers | history | live layers | supersedes | tail
+ * ```
+ *
+ * The split exists for the prompt cache, which matches on a prefix. Stable
+ * layer output sits ahead of history where it can be cached; volatile output
+ * sits after it, where re-rendering costs almost nothing. Both bands arrive
+ * slot-ascending.
+ *
+ * Without a `policy` the bands are concatenated as-is (optionally sliding the
+ * history window by `windowSize`). With a `policy` the view is held to a hard
+ * token budget, claimed in this order: system items, then anchor output, then
+ * live output, then supersedes, then the tail — with history taking whatever
+ * remains and keeping the most recent turns.
+ *
+ * Supersedes are claimed ahead of history, and all together or not at all: a
+ * dropped supersede would leave the model reading a pinned block the runtime
+ * knows is stale. The caller re-anchors instead — see `prepareBandedView`.
  */
-export declare function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }: AssembleViewParams): Item[];
+export declare function assembleView({ systemPromptItems, layerOutputItems, historyItems, liveLayerItems, deltaItems, tailItems, policy, }: AssembleViewParams): Item[];
 export {};

package/dist/context/projector.js

@@ -57,33 +57,62 @@ function keepRecentWithinBudget(items, budget, windowSize) {
 //#endregion
 //#region Public API
 /**
- * Assemble the model's context window from system prompt items, context-layer
- * recall output (slot-ascending), and conversation history.
+ * Assemble the model's context window in bands:
  *
- * Without a `policy` the inputs are concatenated as-is (optionally sliding the
- * history window by `windowSize`). With a `policy` the assembled view is held to
- * a hard token budget: system items are always kept; layer output is kept
- * low-slot-first (highest-slot dropped when tight); history takes the remainder,
- * keeping the most recent turns.
+ * ```
+ * system | anchor layers | history | live layers | supersedes | tail
+ * ```
+ *
+ * The split exists for the prompt cache, which matches on a prefix. Stable
+ * layer output sits ahead of history where it can be cached; volatile output
+ * sits after it, where re-rendering costs almost nothing. Both bands arrive
+ * slot-ascending.
+ *
+ * Without a `policy` the bands are concatenated as-is (optionally sliding the
+ * history window by `windowSize`). With a `policy` the view is held to a hard
+ * token budget, claimed in this order: system items, then anchor output, then
+ * live output, then supersedes, then the tail — with history taking whatever
+ * remains and keeping the most recent turns.
+ *
+ * Supersedes are claimed ahead of history, and all together or not at all: a
+ * dropped supersede would leave the model reading a pinned block the runtime
+ * knows is stale. The caller re-anchors instead — see `prepareBandedView`.
  */
-export function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }) {
+export function assembleView({ systemPromptItems, layerOutputItems, historyItems, liveLayerItems = [], deltaItems = [], tailItems = [], policy, }) {
     if (!policy) {
         return [
             ...systemPromptItems,
             ...layerOutputItems,
             ...historyItems,
+            ...liveLayerItems,
+            ...deltaItems,
+            ...tailItems,
         ];
     }
     const budget = Math.max(0, policy.tokenBudget - policy.responseReserve);
     // System items are never dropped — they anchor the conversation.
-    const afterSystem = Math.max(0, budget - totalTokens(systemPromptItems));
-    const keptLayers = keepFrontWithinBudget(layerOutputItems, afterSystem);
-    const afterLayers = Math.max(0, afterSystem - totalTokens(keptLayers));
-    const keptHistory = keepRecentWithinBudget(historyItems, afterLayers, policy.windowSize);
+    let left = Math.max(0, budget - totalTokens(systemPromptItems));
+    const keptAnchor = keepFrontWithinBudget(layerOutputItems, left);
+    left = Math.max(0, left - totalTokens(keptAnchor));
+    const keptLive = keepFrontWithinBudget(liveLayerItems, left);
+    left = Math.max(0, left - totalTokens(keptLive));
+    // The tail carries steering guidance, which must reach the model whatever the
+    // budget says — it is the correction the retry exists to deliver.
+    left = Math.max(0, left - totalTokens(tailItems));
+    // Supersedes are never dropped either. Each one corrects a pinned block that
+    // is already in the view, so dropping one leaves the model reading content
+    // the runtime knows is stale — silent corruption, and far worse than losing
+    // a turn of history. History absorbs the cost; `deltaBudgetFraction` keeps
+    // the supersedes from growing large enough for that to hurt.
+    left = Math.max(0, left - totalTokens(deltaItems));
+    const keptHistory = keepRecentWithinBudget(historyItems, left, policy.windowSize);
     return [
         ...systemPromptItems,
-        ...keptLayers,
+        ...keptAnchor,
         ...keptHistory,
+        ...keptLive,
+        ...deltaItems,
+        ...tailItems,
     ];
 }
 //#endregion

package/dist/index.d.ts

@@ -6,6 +6,7 @@
 export type { ContextScope, ExecutionContext, ExecutionOutcome, LayerCallModelRequest, } from '@noetic-tools/types';
 export * from '@noetic-tools/types/contract';
 export * from './context/budget.js';
+export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
 export * from './context/layer-api.js';

package/dist/index.js

@@ -8,6 +8,7 @@
 // @noetic-tools/context remains the one-stop import for context-layer authoring.
 export * from '@noetic-tools/types/contract';
 export * from './context/budget.js';
+export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
 export * from './context/layer-api.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Context layer system for Noetic agents: the ContextLayer contract, lifecycle, budget/projection machinery, and built-in layer implementations.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@noetic-tools/types": "^3.0.0",
+    "@noetic-tools/types": "^3.1.0",
     "zod": "^4.0.0"
   },
   "scripts": {