@inhuman.tools/turn 0.0.0-stage → 0.1.0

package/src/context/retention/resolve.ts

@@ -0,0 +1,306 @@
+/**
+ * Layering (design §4.4) and per-item rule resolution.
+ *
+ *   dist → managed → user        trusted: may loosen, replace per key
+ *   project, session, agent      narrowing only, and project/agent never touch
+ *                                user-authored kinds
+ *   tool self-declaration        narrowing only, its own tool key only (at admit)
+ *
+ * Session kv is narrowing-only by owner decision: the interpreter can reach
+ * `kv/set`, so a model must not be able to lengthen what it later reads.
+ */
+import { createHash } from "node:crypto";
+
+import { DEFAULT_CONTEXT_RETENTION, LEGACY_CONTEXT_RETENTION } from "./defaults.js";
+import { canonicalKeep, keepRank, narrowRule, narrows } from "./narrow.js";
+import {
+  contextRetentionSchema,
+  horizonList,
+  horizonSchema,
+  NONE_FORBIDDEN_KINDS,
+  parseRetentionLayer,
+  RETENTION_KINDS,
+  USER_AUTHORED_KINDS,
+  type ConcreteRule,
+  type ContextRetention,
+  type Horizon,
+  type RetentionLayer,
+  type RuleInput,
+} from "./schema.js";
+
+export type NarrowSource = "project" | "session" | "agent" | "tool";
+
+/** A resolved policy: the layered config plus the narrowing overlays that name tools. */
+export type ResolvedPolicy = ContextRetention & {
+  /** Narrowing overlays keyed like `tools`; applied on top of the matched rule at admit. */
+  readonly narrowTools: Readonly<Record<string, RuleInput>>;
+  /** First 12 hex of the policy digest. Diagnostic only. */
+  readonly hash: string;
+};
+
+export type ResolveInput = {
+  /** Trusted layers: a partial layer or the raw `contextRetention` block (object or JSON text). */
+  readonly managed?: unknown;
+  readonly user?: unknown;
+  /** Narrowing layers. */
+  readonly project?: unknown;
+  readonly session?: RetentionLayer;
+  readonly agent?: unknown;
+};
+
+export type ResolveResult = { readonly policy: ResolvedPolicy; readonly ignored: readonly string[] };
+
+function mergeRuleBag(
+  base: Readonly<Record<string, RuleInput>>,
+  layer: Readonly<Record<string, RuleInput>> | undefined,
+): Record<string, RuleInput> {
+  const out: Record<string, RuleInput> = { ...base };
+  for (const [key, rule] of Object.entries(layer ?? {})) out[key] = { ...out[key], ...rule };
+  return out;
+}
+
+function applyTrusted(base: ContextRetention, layer: RetentionLayer): ContextRetention {
+  return {
+    ...base,
+    defaults: { ...base.defaults, ...layer.defaults },
+    step: { ...base.step, ...layer.step },
+    kinds: mergeRuleBag(base.kinds, layer.kinds),
+    tools: mergeRuleBag(base.tools, layer.tools),
+    dialects: mergeRuleBag(base.dialects, layer.dialects),
+  };
+}
+
+function digest(policy: Omit<ResolvedPolicy, "hash">): string {
+  return createHash("sha256").update(JSON.stringify(policy)).digest("hex").slice(0, 12);
+}
+
+function seal(policy: Omit<ResolvedPolicy, "hash">): ResolvedPolicy {
+  return { ...policy, hash: digest(policy) };
+}
+
+function applyNarrowing(
+  policy: Omit<ResolvedPolicy, "hash">,
+  layer: RetentionLayer,
+  source: NarrowSource,
+  ignored: string[],
+): Omit<ResolvedPolicy, "hash"> {
+  let kinds: Record<string, RuleInput> = { ...policy.kinds };
+  const narrowTools: Record<string, RuleInput> = { ...policy.narrowTools };
+  let defaults = policy.defaults;
+  if (layer.step !== undefined) ignored.push(`${source}: step is not narrowable`);
+  if (layer.dialects !== undefined) ignored.push(`${source}: dialects are not narrowable`);
+  if (layer.defaults?.minChars !== undefined) {
+    defaults = { minChars: Math.min(defaults.minChars, layer.defaults.minChars) };
+  }
+  for (const [kind, rule] of Object.entries(layer.kinds ?? {})) {
+    if (source !== "session" && USER_AUTHORED_KINDS.has(kind)) {
+      ignored.push(`${source}: kind ${kind} is user-authored`);
+      continue;
+    }
+    const base = kinds[kind] ?? {};
+    if (!narrows(base, rule, kind)) {
+      ignored.push(`${source}: kinds.${kind} does not shorten retention`);
+      continue;
+    }
+    kinds = { ...kinds, [kind]: narrowRule(base, rule, kind) };
+  }
+  for (const [key, rule] of Object.entries(layer.tools ?? {})) {
+    narrowTools[key] = narrowRule(narrowTools[key] ?? {}, rule, null);
+  }
+  return { ...policy, defaults, kinds, narrowTools };
+}
+
+export function resolveRetention(input: ResolveInput = {}): ResolveResult {
+  const ignored: string[] = [];
+  let base: ContextRetention = DEFAULT_CONTEXT_RETENTION;
+  if (input.managed !== undefined) base = applyTrusted(base, parseRetentionLayer(input.managed));
+  if (input.user !== undefined) base = applyTrusted(base, parseRetentionLayer(input.user));
+  let policy: Omit<ResolvedPolicy, "hash"> = { ...base, narrowTools: {} };
+  if (input.project !== undefined) {
+    policy = applyNarrowing(policy, parseRetentionLayer(input.project), "project", ignored);
+  }
+  if (input.session !== undefined) policy = applyNarrowing(policy, input.session, "session", ignored);
+  if (input.agent !== undefined) policy = applyNarrowing(policy, parseRetentionLayer(input.agent), "agent", ignored);
+  return { policy: seal(policy), ignored };
+}
+
+/** The pre-retention rule set: everything lives until compaction (plus the owner's picture and note rules). */
+export const LEGACY_POLICY: ResolvedPolicy = seal({ ...LEGACY_CONTEXT_RETENTION, narrowTools: {} });
+
+function sessionHorizon(raw: string): Horizon[] | null {
+  const text = raw.trim();
+  if (text === "") return null;
+  let value: unknown = text;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    value = text;
+  }
+  const list = Array.isArray(value) ? value : [value];
+  const out: Horizon[] = [];
+  for (const entry of list) {
+    const parsed = horizonSchema.safeParse(entry);
+    if (!parsed.success) return null;
+    out.push(parsed.data);
+  }
+  return out.length === 0 ? null : out;
+}
+
+/**
+ * Session kv → a narrowing layer. `retention.<kind>` and
+ * `retention.tool.<key>` hold a JSON horizon (`"round"`, `{"rounds":2}`, or an array).
+ */
+export function sessionRetentionLayer(kvs: Readonly<Record<string, string>>): RetentionLayer {
+  const kinds: Record<string, RuleInput> = {};
+  const tools: Record<string, RuleInput> = {};
+  for (const [key, raw] of Object.entries(kvs)) {
+    if (!key.startsWith("retention.")) continue;
+    const keep = sessionHorizon(raw);
+    if (keep === null) continue;
+    const rest = key.slice("retention.".length);
+    // A kind name wins (`retention.tool.read` is the kind); anything else under `tool.` is a tool key.
+    if ((RETENTION_KINDS as readonly string[]).includes(rest)) {
+      kinds[rest] = { keep };
+      continue;
+    }
+    if (rest.startsWith("tool.")) {
+      const toolKey = rest.slice("tool.".length);
+      if (toolKey !== "") tools[toolKey] = { keep };
+    }
+  }
+  return {
+    ...(Object.keys(kinds).length === 0 ? {} : { kinds }),
+    ...(Object.keys(tools).length === 0 ? {} : { tools }),
+  };
+}
+
+// --- stamp text -----------------------------------------------------------------------------
+
+const policyCache = new Map<string, ResolvedPolicy | null>();
+
+export function serializePolicy(policy: ResolvedPolicy): string {
+  return JSON.stringify(policy);
+}
+
+/** Parse an R1 stamp. Empty or malformed is `null` (the caller inherits or falls back to legacy). */
+export function parsePolicy(json: string): ResolvedPolicy | null {
+  if (json === "") return null;
+  const hit = policyCache.get(json);
+  if (hit !== undefined) return hit;
+  let out: ResolvedPolicy | null = null;
+  try {
+    const raw = JSON.parse(json) as Record<string, unknown>;
+    const parsed = contextRetentionSchema.safeParse(raw);
+    if (parsed.success) {
+      const narrow = raw.narrowTools;
+      out = {
+        ...parsed.data,
+        narrowTools:
+          narrow != null && typeof narrow === "object" ? (parseRetentionLayer({ tools: narrow }).tools ?? {}) : {},
+        hash: typeof raw.hash === "string" ? raw.hash : "",
+      };
+    }
+  } catch {
+    out = null;
+  }
+  if (policyCache.size > 64) policyCache.clear();
+  policyCache.set(json, out);
+  return out;
+}
+
+// --- per-item rule --------------------------------------------------------------------------
+
+function globToRegExp(glob: string): RegExp {
+  return new RegExp(
+    `^${glob
+      .split("*")
+      .map((part) => part.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw`\$&`))
+      .join(".*")}$`,
+  );
+}
+
+function lookup<T>(bag: Readonly<Record<string, T>>, names: readonly string[]): T | undefined {
+  for (const name of names) {
+    if (name !== "" && Object.hasOwn(bag, name)) return bag[name];
+  }
+  let best: { readonly glob: string; readonly value: T } | undefined;
+  for (const [glob, value] of Object.entries(bag)) {
+    if (!glob.includes("*")) continue;
+    const re = globToRegExp(glob);
+    if (names.some((name) => name !== "" && re.test(name)) && (best === undefined || glob.length > best.glob.length)) {
+      best = { glob, value };
+    }
+  }
+  return best?.value;
+}
+
+function ruleKeep(rule: RuleInput | undefined, fallback: readonly Horizon[]): readonly Horizon[] {
+  const keep = horizonList(rule?.keep);
+  return keep.length === 0 ? fallback : keep;
+}
+
+export type RuleQuery = {
+  readonly kind: string;
+  /** Names to match `tools`, most specific first: `mcp:server/tool`, then the wire name. */
+  readonly names: readonly string[];
+  /** The tool's own narrowing hint (catalog `retention`). Applies to its own key only. */
+  readonly hint?: RuleInput;
+};
+
+/** The concrete rule for one item of `kind`. Pure over `policy`. */
+export function ruleFor(policy: ResolvedPolicy, query: RuleQuery): ConcreteRule {
+  const baseRule = policy.kinds[query.kind];
+  const toolRule = lookup(policy.tools, query.names);
+  let merged: RuleInput = { ...baseRule, ...toolRule };
+  const overlay = lookup(policy.narrowTools, query.names);
+  if (overlay !== undefined) merged = narrowRule(merged, overlay, query.kind);
+  if (query.hint !== undefined) merged = narrowRule(merged, query.hint, query.kind);
+  const errorRule = policy.kinds.error;
+  const onErrorRaw =
+    merged.onError === undefined
+      ? errorRule?.keep === undefined || errorRule.leave === undefined
+        ? null
+        : { keep: errorRule.keep, leave: errorRule.leave }
+      : merged.onError;
+  let leave = merged.leave ?? "stub";
+  if (leave === "none" && NONE_FORBIDDEN_KINDS.has(query.kind)) leave = "stub";
+  return {
+    keep: canonicalKeep(ruleKeep(merged, ["compaction"])),
+    leave,
+    minChars: merged.minChars ?? policy.defaults.minChars,
+    onError:
+      onErrorRaw === null
+        ? null
+        : {
+            keep: canonicalKeep(horizonList(onErrorRaw.keep)),
+            leave: onErrorRaw.leave === "none" ? "stub" : onErrorRaw.leave,
+          },
+  };
+}
+
+/** The rule of a non-tool item, judged by the policy of its own turn. */
+export function kindRule(policy: ResolvedPolicy, kind: string, dialect?: string): ConcreteRule {
+  const rule = ruleFor(policy, { kind, names: [] });
+  if (kind !== "thinking" || dialect === undefined) return rule;
+  const override = Object.hasOwn(policy.dialects, dialect) ? policy.dialects[dialect] : undefined;
+  if (override === undefined) return rule;
+  return {
+    ...rule,
+    keep: canonicalKeep(ruleKeep(override, rule.keep)),
+    leave: override.leave ?? rule.leave,
+  };
+}
+
+/**
+ * A failed item outlives its kind: the longer of the kind's horizon and the
+ * error overlay's wins, and the remainder is the overlay's when it won.
+ */
+export function effectiveRule(rule: ConcreteRule, failed: boolean): Pick<ConcreteRule, "keep" | "leave" | "minChars"> {
+  if (!failed || rule.onError === null) return rule;
+  if (keepRank(rule.onError.keep) > keepRank(rule.keep)) {
+    return { keep: rule.onError.keep, leave: rule.onError.leave, minChars: 0 };
+  }
+  return rule;
+}
+
+export { narrowKeep } from "./narrow.js";

package/src/context/retention/schema.ts

@@ -0,0 +1,173 @@
+/**
+ * `contextRetention` — JSON-configurable tail retention. Nothing here deletes
+ * graph state: a rule decides what a projected item leaves behind once its
+ * horizon has passed. Design: `tail-retention-design.md` §3–§4.
+ */
+import { z } from "zod";
+
+export const RETENTION_KINDS = [
+  "image.user",
+  "image.tool",
+  "tool.read",
+  "tool.search",
+  "tool.shell",
+  "tool.write",
+  "tool.args.write",
+  "tool.web.search",
+  "tool.web.fetch",
+  "tool.mcp",
+  "tool.program",
+  "tool.agent",
+  "tool.comm",
+  "tool.other",
+  "thinking",
+  "steer",
+  "approval-note",
+  "notification",
+  "system-note",
+  "error",
+] as const;
+export type RetentionKind = (typeof RETENTION_KINDS)[number];
+
+/** Authored by the user. Untrusted layers (project, agent, tool) cannot shorten these. */
+export const USER_AUTHORED_KINDS: ReadonlySet<string> = new Set(["steer", "approval-note", "image.user"]);
+
+/** Kinds whose item is a tool result row. `leave: "none"` is not allowed: every tool_call needs a tool row. */
+export const NONE_FORBIDDEN_KINDS: ReadonlySet<string> = new Set([
+  "tool.read",
+  "tool.search",
+  "tool.shell",
+  "tool.write",
+  "tool.web.search",
+  "tool.web.fetch",
+  "tool.mcp",
+  "tool.program",
+  "tool.agent",
+  "tool.comm",
+  "tool.other",
+  "error",
+]);
+
+export const horizonSchema = z.union([
+  z.enum(["round", "turn", "compaction", "forever"]),
+  z.object({ rounds: z.number().int().min(1) }).strict(),
+  z.object({ turns: z.number().int().min(1) }).strict(),
+  z.object({ newest: z.number().int().min(0) }).strict(),
+]);
+export type Horizon = z.output<typeof horizonSchema>;
+
+export const leaveSchema = z.union([
+  z.enum(["none", "stub", "summary"]),
+  z.object({ head: z.number().int().min(0).max(5000) }).strict(),
+]);
+export type Leave = z.output<typeof leaveSchema>;
+
+const keepSchema = z.union([horizonSchema, z.array(horizonSchema).min(1)]);
+
+export const ruleSchema = z.object({
+  keep: keepSchema.optional(),
+  leave: leaveSchema.optional(),
+  /** Never elide below this many painted chars. */
+  minChars: z.number().int().min(0).optional(),
+  /** Error overlay for this rule. `null` disables it. */
+  onError: z.object({ keep: keepSchema, leave: leaveSchema }).nullable().optional(),
+});
+export type RuleInput = z.output<typeof ruleSchema>;
+
+export const stepSchema = z.object({
+  turnBoundary: z.boolean().default(true),
+  everyRounds: z.number().int().min(1).nullable().default(4),
+  minFreedTokens: z.number().int().min(0).default(8000),
+  whenCacheCold: z.boolean().default(true),
+  atCompaction: z.literal(true).default(true),
+});
+export type StepConfig = z.output<typeof stepSchema>;
+
+export const contextRetentionSchema = z.object({
+  version: z.literal(1).default(1),
+  defaults: z.object({ minChars: z.number().int().min(0).default(800) }).prefault({}),
+  step: stepSchema.prefault({}),
+  kinds: z.record(z.string(), ruleSchema).default({}),
+  /** Keys: wire name ("shell"), "mcp:<server>/<tool>", globs ("mcp:github/*", "mcp:*"). */
+  tools: z.record(z.string(), ruleSchema).default({}),
+  /** Per-dialect thinking override, e.g. {"anthropic": {"keep": "forever"}}. */
+  dialects: z.record(z.string(), ruleSchema).default({}),
+});
+export type ContextRetention = z.output<typeof contextRetentionSchema>;
+
+/** A rule with every field concrete. This is what R2 stamps on a job. */
+export type ConcreteRule = {
+  readonly keep: readonly Horizon[];
+  readonly leave: Leave;
+  readonly minChars: number;
+  readonly onError: { readonly keep: readonly Horizon[]; readonly leave: Leave } | null;
+};
+
+/** A partial policy as one source wrote it. */
+export type RetentionLayer = {
+  readonly defaults?: { readonly minChars?: number };
+  readonly step?: Partial<StepConfig>;
+  readonly kinds?: Readonly<Record<string, RuleInput>>;
+  readonly tools?: Readonly<Record<string, RuleInput>>;
+  readonly dialects?: Readonly<Record<string, RuleInput>>;
+};
+
+export function horizonList(keep: RuleInput["keep"]): Horizon[] {
+  if (keep === undefined) return [];
+  return Array.isArray(keep) ? [...keep] : [keep];
+}
+
+function jsonOf(raw: unknown): unknown {
+  if (typeof raw !== "string") return raw;
+  if (raw.trim() === "") return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+const STEP_FIELDS: ReadonlyArray<readonly [keyof StepConfig, z.ZodType]> = [
+  ["turnBoundary", z.boolean()],
+  ["everyRounds", z.number().int().min(1).nullable()],
+  ["minFreedTokens", z.number().int().min(0)],
+  ["whenCacheCold", z.boolean()],
+];
+
+/**
+ * Tolerant parse of a `contextRetention` block (an object or its JSON text).
+ * An invalid field is dropped and never fatal, matching the rest of
+ * `config.json`. Only fields the author wrote survive: defaults are the dist
+ * layer's business, so the result is a partial layer.
+ */
+export function parseRetentionLayer(raw: unknown): RetentionLayer {
+  const value = jsonOf(raw);
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return {};
+  const rec = value as Record<string, unknown>;
+  let layer: RetentionLayer = {};
+  const defaults = z.object({ minChars: z.number().int().min(0).optional() }).safeParse(rec.defaults);
+  if (defaults.success && defaults.data.minChars !== undefined) {
+    layer = { ...layer, defaults: { minChars: defaults.data.minChars } };
+  }
+  if (rec.step != null && typeof rec.step === "object" && !Array.isArray(rec.step)) {
+    const written = rec.step as Record<string, unknown>;
+    const step: Partial<Record<keyof StepConfig, unknown>> = {};
+    for (const [key, schema] of STEP_FIELDS) {
+      const parsed = schema.safeParse(written[key]);
+      if (parsed.success) step[key] = parsed.data;
+    }
+    if (Object.keys(step).length > 0) layer = { ...layer, step: step as Partial<StepConfig> };
+  }
+  for (const section of ["kinds", "tools", "dialects"] as const) {
+    const bag = rec[section];
+    if (bag == null || typeof bag !== "object" || Array.isArray(bag)) continue;
+    const out: Record<string, RuleInput> = {};
+    for (const [key, ruleRaw] of Object.entries(bag as Record<string, unknown>)) {
+      if (section === "kinds" && !(RETENTION_KINDS as readonly string[]).includes(key)) continue;
+      const parsed = ruleSchema.safeParse(ruleRaw);
+      if (parsed.success) out[key] = parsed.data;
+    }
+    if (Object.keys(out).length > 0) layer = { ...layer, [section]: out };
+  }
+  return layer;
+}

package/src/context/retention/stamp.ts

@@ -0,0 +1,121 @@
+/**
+ * R2: the resolved horizon of one tool job, stamped at admit. The kind comes
+ * from catalog facts read once, so later catalog churn cannot reclassify
+ * history; the projection reads the stamp and nothing else.
+ */
+import {
+  AgentCallbackJob,
+  AgentCallJob,
+  AgentMessageJob,
+  AgentNotifyJob,
+  BotCallJob,
+  ContextNeedToolJob,
+  FileMutateToolJob,
+  MCPToolJob,
+  ProgrammaticJob,
+  ToolCallJob,
+  WebExtractToolJob,
+  WebSearchToolJob,
+} from "@inhuman.tools/harness-model";
+import { z } from "zod";
+
+import { ruleFor, type ResolvedPolicy } from "./resolve.js";
+import { horizonSchema, leaveSchema, type ConcreteRule, type RetentionKind, type RuleInput } from "./schema.js";
+
+const SEARCH_TOOLS: ReadonlySet<string> = new Set(["grep", "fff_search"]);
+const READ_TOOLS: ReadonlySet<string> = new Set(["read_file", "list_dir", "glob"]);
+const COMM_TOOLS: ReadonlySet<string> = new Set(["update_metadata"]);
+export const WRITE_ARG_TOOLS: ReadonlySet<string> = new Set(["write_file", "edit_file"]);
+
+export type RetainedJob = ToolCallJob | ProgrammaticJob;
+
+export function kindOfJob(job: RetainedJob, entryClass?: string): RetentionKind {
+  if (job instanceof ProgrammaticJob) return "tool.program";
+  if (job instanceof MCPToolJob) return "tool.mcp";
+  if (job instanceof WebSearchToolJob) return "tool.web.search";
+  if (job instanceof WebExtractToolJob) return "tool.web.fetch";
+  if (job instanceof FileMutateToolJob) return "tool.write";
+  if (job instanceof AgentCallJob || job instanceof BotCallJob || job instanceof AgentMessageJob) return "tool.agent";
+  if (job instanceof AgentCallbackJob || job instanceof AgentNotifyJob || job instanceof ContextNeedToolJob) {
+    return "tool.comm";
+  }
+  if (job.name === "shell") return "tool.shell";
+  if (SEARCH_TOOLS.has(job.name)) return "tool.search";
+  if (READ_TOOLS.has(job.name) || entryClass === "read") return "tool.read";
+  if (COMM_TOOLS.has(job.name)) return "tool.comm";
+  return "tool.other";
+}
+
+/** `tools` keys that can name this job, most specific first. */
+export function namesOfJob(job: RetainedJob): string[] {
+  if (job instanceof ProgrammaticJob) return [job.toolName];
+  if (job instanceof MCPToolJob) return [`mcp:${job.connectionKey}/${job.serverToolName}`, job.name];
+  return [job.name];
+}
+
+const stampSchema = z.object({
+  kind: z.string(),
+  keep: z.array(horizonSchema),
+  leave: leaveSchema,
+  minChars: z.number().int().min(0),
+  onError: z.object({ keep: z.array(horizonSchema), leave: leaveSchema }).nullable(),
+  args: z
+    .object({
+      keep: z.array(horizonSchema),
+      leave: leaveSchema,
+      minChars: z.number().int().min(0),
+    })
+    .optional(),
+});
+
+export type JobStamp = {
+  readonly kind: string;
+  readonly rule: ConcreteRule;
+  /** The rule for the call's own arguments (`write_file` / `edit_file` content). */
+  readonly args?: Pick<ConcreteRule, "keep" | "leave" | "minChars">;
+};
+
+export function stampJobRetention(
+  job: RetainedJob,
+  policy: ResolvedPolicy,
+  opts: { readonly entryClass?: string; readonly hint?: RuleInput } = {},
+): void {
+  const kind = kindOfJob(job, opts.entryClass);
+  const names = namesOfJob(job);
+  const rule = ruleFor(policy, { kind, names, ...(opts.hint === undefined ? {} : { hint: opts.hint }) });
+  const argsRule =
+    job instanceof ToolCallJob && WRITE_ARG_TOOLS.has(job.name)
+      ? ruleFor(policy, { kind: "tool.args.write", names: [] })
+      : undefined;
+  job.retentionJson = JSON.stringify({
+    kind,
+    keep: rule.keep,
+    leave: rule.leave,
+    minChars: rule.minChars,
+    onError: rule.onError,
+    ...(argsRule === undefined
+      ? {}
+      : { args: { keep: argsRule.keep, leave: argsRule.leave, minChars: argsRule.minChars } }),
+  });
+}
+
+const stamps = new Map<string, JobStamp | null>();
+
+export function parseJobStamp(json: string): JobStamp | null {
+  if (json === "") return null;
+  const hit = stamps.get(json);
+  if (hit !== undefined) return hit;
+  let out: JobStamp | null = null;
+  try {
+    const parsed = stampSchema.safeParse(JSON.parse(json));
+    if (parsed.success) {
+      const { kind, args, ...rule } = parsed.data;
+      out = { kind, rule, ...(args === undefined ? {} : { args }) };
+    }
+  } catch {
+    out = null;
+  }
+  if (stamps.size > 512) stamps.clear();
+  stamps.set(json, out);
+  return out;
+}

package/src/context/retention/step.ts

@@ -0,0 +1,85 @@
+/**
+ * R3: the retention clock. Deep horizons expire against `at`, which only moves
+ * at a step, so between steps the projected prefix is byte-stable and only the
+ * tail grows. The live inputs (wall clock, prior `warmUntilMs`, estimated
+ * savings) are read once here and recorded; the projection reads only `at`.
+ */
+import { CompletionExpectation, latestCompactCutoff, owningTurn } from "@inhuman.tools/harness-model";
+
+import { projectHistory } from "../history.js";
+import type { StepConfig } from "./schema.js";
+import { parseClock, policyOfTurn, type ClockReason, type RetentionClock } from "./view.js";
+
+export type StepFacts = {
+  readonly self: string;
+  readonly step: StepConfig;
+  /** Prior completion on the spine: its recorded clock target, and when its cache lapses. */
+  readonly prior: { readonly at: string | null; readonly warmUntilMs: number | null } | null;
+  readonly turnFirstRound: boolean;
+  readonly afterCutoff: boolean;
+  /** Rounds between the prior clock target and this completion. */
+  readonly roundsSinceAt: number;
+  readonly now: number;
+  /** Estimated tokens a step would free. Lazy: walks the spine. */
+  readonly freedTokens: () => number;
+};
+
+/** Pure: the order is compaction, turn, cold, every, freed, else hold. */
+export function decideRetentionStep(f: StepFacts): RetentionClock {
+  const step = (reason: ClockReason, extra: Partial<RetentionClock> = {}): RetentionClock => ({
+    at: f.self,
+    reason,
+    ...extra,
+  });
+  if (f.afterCutoff && f.step.atCompaction) return step("compaction");
+  const priorAt = f.prior?.at ?? null;
+  if (priorAt === null) return step("turn");
+  if (f.turnFirstRound && f.step.turnBoundary) return step("turn");
+  const warm = f.prior?.warmUntilMs ?? null;
+  if (f.step.whenCacheCold && warm !== null && f.now > warm) return step("cold", { coldByMs: f.now - warm });
+  if (f.step.everyRounds !== null && f.roundsSinceAt >= f.step.everyRounds) return step("every");
+  if (f.step.minFreedTokens > 0) {
+    const freed = f.freedTokens();
+    if (freed >= f.step.minFreedTokens) return step("freed", { freedTokens: freed });
+  }
+  return { at: priorAt, reason: "hold" };
+}
+
+function tokensOf(rows: Iterable<unknown>): number {
+  let chars = 0;
+  for (const row of rows)
+    chars += JSON.stringify(row, (_key, value) => (value instanceof Uint8Array ? value.length : value)).length;
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Stamp `tip.retentionClockJson` when its round opens. Call once the
+ * completion is on its turn's tape (it must be reachable from its turn).
+ */
+export function stampRetentionClock(tip: CompletionExpectation, now: number = Date.now()): RetentionClock {
+  const turn = owningTurn(tip);
+  const policy = policyOfTurn(turn);
+  const spine = tip.spine();
+  const index = spine.indexOf(tip);
+  const prior = index > 0 ? spine[index - 1]! : null;
+  const priorAt = prior === null ? null : (parseClock(prior.retentionClockJson)?.at ?? null);
+  const priorPos = priorAt === null ? -1 : spine.findIndex((c) => c.uuid === priorAt);
+  const clock = decideRetentionStep({
+    self: tip.uuid,
+    step: policy.step,
+    prior: prior === null ? null : { at: priorPos < 0 ? null : priorAt, warmUntilMs: prior.warmUntilMs },
+    turnFirstRound: prior === null || owningTurn(prior) !== turn,
+    afterCutoff: prior === null && turn !== null && latestCompactCutoff(turn) !== null,
+    roundsSinceAt: priorPos < 0 ? 0 : index - priorPos,
+    now,
+    freedTokens: () => {
+      const held = spine[priorPos];
+      if (held === undefined) return 0;
+      const before = tokensOf(projectHistory(tip, { clockAt: held }));
+      const after = tokensOf(projectHistory(tip, { clockAt: tip }));
+      return Math.max(0, before - after);
+    },
+  });
+  tip.retentionClockJson = JSON.stringify(clock);
+  return clock;
+}