@inixiative/foundry-core 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/adapters/markdown-docs.ts

@@ -1,4 +1,4 @@
-import { realpathSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -33,6 +33,8 @@ export class MarkdownDocs {
   /** Scan and load all matching files. */
   async load(): Promise<Map<string, string>> {
     const results = new Map<string, string>();
+    // A docs directory that doesn't exist yet (a fresh install's home) has no docs.
+    if (!existsSync(this.dir)) return results;
     const scanner = new Bun.Glob(this.glob).scan({ cwd: this.dir, absolute: false });
 
     for await (const relPath of scanner) {
@@ -65,6 +67,7 @@ export class MarkdownDocs {
   /** List all matching files. */
   async list(): Promise<string[]> {
     const paths: string[] = [];
+    if (!existsSync(this.dir)) return paths;
     const scanner = new Bun.Glob(this.glob).scan({ cwd: this.dir, absolute: false });
     for await (const relPath of scanner) {
       paths.push(relPath);
@@ -206,6 +209,8 @@ export interface InstructionFile {
   readonly path: string;
   /** Text with block-level HTML comments removed, as Claude Code injects it. */
   readonly content: string;
+  /** The file's text as read, when stripping comments changed it (`content` is the stripped form). */
+  readonly raw?: string;
   /** Import hops from the file the chain started at (0 for that file). */
   readonly depth: number;
   /** The file whose `@path` loaded this one. */
@@ -392,8 +397,15 @@ export async function readInstructionFile(
       return;
     }
     seen.add(real);
-    const content = stripInstructionComments(await Bun.file(real).text());
-    files.push({ path: file, content, depth, ...(importedBy ? { importedBy } : {}) });
+    const raw = await Bun.file(real).text();
+    const content = stripInstructionComments(raw);
+    files.push({
+      path: file,
+      content,
+      ...(raw !== content ? { raw } : {}),
+      depth,
+      ...(importedBy ? { importedBy } : {}),
+    });
     if (depth >= maxDepth) return;
     for (const target of instructionImports(content)) {
       const next = resolveInstructionImport(target, file, options.home);

package/src/adapters/markdown-hierarchy.ts

@@ -617,7 +617,8 @@ export async function discoverHierarchy(
         continue;
       }
       if (statSync(real).size > INSTRUCTION_FILE_LIMIT) continue;
-      let content = readFileSync(unit.path, 'utf8');
+      const raw = readFileSync(unit.path, 'utf8');
+      let content = raw;
       if (unit.source.maxLines !== undefined)
         content = content.split('\n').slice(0, unit.source.maxLines).join('\n');
       if (unit.source.maxBytes !== undefined)
@@ -625,7 +626,14 @@ export async function discoverHierarchy(
       const final = tierOf(unit.path, node);
       seen.add(real);
       kept.set(real, { path: unit.path, node: final.id, index: files.length });
-      files.push({ path: unit.path, content, depth: 0, node: final.id, tier: final.tier });
+      files.push({
+        path: unit.path,
+        content,
+        ...(raw !== content ? { raw } : {}),
+        depth: 0,
+        node: final.id,
+        tier: final.tier,
+      });
       continue;
     }
     const allowed =
@@ -665,7 +673,13 @@ export async function discoverHierarchy(
       // Every file keeps the narrower tier of its node and any node owning its path, found or imported.
       const final = tierOf(file.path, node);
       kept.set(realOf(file.path), { path: file.path, node: final.id, index: files.length });
-      files.push({ ...file, content, node: final.id, tier: final.tier });
+      files.push({
+        ...file,
+        content,
+        ...(content !== file.content ? { raw: file.raw ?? file.content } : {}),
+        node: final.id,
+        tier: final.tier,
+      });
     }
   }
   return { files, duplicates, refused, probes: [...probes] };
@@ -850,7 +864,7 @@ export function dedupeHierarchy<F extends HierarchyFile>(
         continue;
       }
       const content = cut(file.content.split('\n'), dropped);
-      if (content.trim()) keep.unshift({ ...file, content });
+      if (content.trim()) keep.unshift({ ...file, content, raw: file.raw ?? file.content });
     }
     out = keep;
   }

package/src/context-layer.ts

@@ -109,8 +109,55 @@ export interface ContextSource {
    * Must be cheap: it runs before every assembly.
    */
   changed?(): boolean;
+  /**
+   * What the last load was made of, in order: glue text and attributed parts whose concatenation is
+   * exactly the loaded text. Absent when the source cannot attribute its text.
+   */
+  segments?(): readonly SourceSegment[] | undefined;
+}
+
+/**
+ * One attributed piece of composed text. `subject` names where it came from (`file:<path>`,
+ * `prompt:agent:<id>`, `source-content:<id>`). `retrieved` marks text chosen per message (it is not
+ * a slow-moving source). `raw` is the source's own text when the composed `text` is a cleaned or
+ * trimmed form of it (comments stripped, a duplicate section removed).
+ */
+export interface SourcePart {
+  readonly subject: string;
+  readonly text: string;
+  readonly retrieved?: boolean;
+  readonly raw?: string;
+  /** The ladder rung of a file part, and its corpus tier. */
+  readonly node?: string;
+  readonly tier?: string;
+}
+
+/** Glue text (headings, separators) or an attributed part. */
+export type SourceSegment = string | SourcePart;
+
+/** What a composed agent call was made of, slot by slot (in memory; persisted as version ids). */
+export interface CompositionSnapshot {
+  /** The role composed for (an agent id). */
+  readonly role?: string;
+  readonly instructions: readonly SourceSegment[];
+  readonly domainKnowledge: readonly SourceSegment[];
+  /** What the composer left out of each slot, and why (excluded by role, a duplicate, refused, over budget). */
+  readonly omitted?: {
+    readonly instructions: readonly OmittedSource[];
+    readonly domainKnowledge: readonly OmittedSource[];
+  };
 }
 
+export interface OmittedSource {
+  readonly subject: string;
+  readonly reason: string;
+  readonly duplicateOf?: string;
+}
+
+/** The text a segment list composes. */
+export const segmentsText = (segments: readonly SourceSegment[]): string =>
+  segments.map((segment) => (typeof segment === 'string' ? segment : segment.text)).join('');
+
 /** Selection provenance carried on a layer instance for inspection. */
 export interface LayerSelectionState {
   readonly focusHash?: string;
@@ -320,6 +367,8 @@ export class ContextLayer {
   readonly perTurn: boolean;
 
   private _content: string = '';
+  /** Each source's text from the last warm, in source order; undefined after a manual `set`. */
+  private _loaded: string[] | undefined;
   private _state: LayerState = 'cold';
   private _hash: string = '';
   private _lastWarmed: number | null = null;
@@ -496,6 +545,32 @@ export class ContextLayer {
     return this._content;
   }
 
+  /**
+   * What the current content is made of: each source's segments (or the source's whole text as one
+   * part, `unattributed:<source id>`, when it cannot attribute it), joined as the content was. Content written with
+   * `set` is one part, `layer-content:<id>`. Concatenated, always exactly `content`.
+   */
+  segments(): SourceSegment[] {
+    const whole = (): SourceSegment[] =>
+      this._content ? [{ subject: `layer-content:${this.id}`, text: this._content }] : [];
+    const loaded = this._loaded;
+    if (!loaded || loaded.length !== this._sources.length) return whole();
+    const out: SourceSegment[] = [];
+    loaded.forEach((text, i) => {
+      if (i > 0) out.push('\n\n');
+      const source = this._sources[i]!;
+      const own = source.segments?.();
+      if (own && segmentsText(own) === text) out.push(...own);
+      else if (text)
+        out.push({
+          subject: `unattributed:${source.id}`,
+          text,
+          ...(source.focusable ? { retrieved: true } : {}),
+        });
+    });
+    return segmentsText(out) === this._content ? out : whole();
+  }
+
   get lastAccessed(): number | null {
     return this._lastAccessed;
   }
@@ -595,6 +670,7 @@ export class ContextLayer {
         }
 
         this._content = parts.join('\n\n');
+        this._loaded = parts;
         this._hash = computeHash(this._content);
         this._version = undefined; // even identical unversioned source bytes are a new write
         this._selection = reports.length
@@ -632,6 +708,7 @@ export class ContextLayer {
   set(content: string, author: string = 'system'): void {
     const previous = this._content;
     this._content = content;
+    this._loaded = undefined;
     this._hash = computeHash(content);
     this._selection = undefined; // manual content has no selection provenance
     this._version = undefined; // a new write carries no version until its owner marks it

package/src/feedback/warden-labels.ts

@@ -0,0 +1,229 @@
+import type { WardenProbe } from './warden-probes';
+
+/** One Warden of the roster as the labeler sees it. */
+export interface WardenRosterEntry {
+  readonly id: string;
+  readonly domain: string;
+  readonly prompt: string;
+  readonly enabled: boolean;
+}
+
+/** Whether a Warden had something of its own to add at the moment, and what it should have known. */
+export interface WardenLabel {
+  readonly relevant: boolean;
+  readonly shouldKnow?: string;
+}
+
+export type WardenTriggerKind = 'user-message' | 'agent-action' | 'agent-plan';
+
+/**
+ * A labelled moment for the Warden prefilter: which Warden domains the trigger touches. Never commit
+ * fixtures: they hold session text and company code excerpts.
+ */
+export interface WardenFixture {
+  readonly id: string;
+  /** Which context's Wardens may see it (UserEvidence fixtures only ever see the UserEvidence ladder). */
+  readonly ctx: string;
+  readonly project?: string;
+  readonly source: 'git' | 'session' | 'history';
+  /** The moment before the mistake, as a Warden would see it. */
+  readonly trigger: { readonly kind: WardenTriggerKind; readonly text: string };
+  /** The thread or change up to the moment; never what happened next. */
+  readonly context: string;
+  /** What happened next (the correction, the fix, the review). The labeler sees it; Wardens never do. */
+  readonly hidden?: string;
+  /** Every Warden of the roster, keyed by agent id. */
+  readonly labels: Readonly<Record<string, WardenLabel>>;
+  /** The FEEDBACK-LOG rule numbers the moment's mistake repeats, when any. */
+  readonly feedbackRules?: readonly number[];
+  readonly provenance: Readonly<Record<string, string | number | null>>;
+  readonly labeler?: { readonly model: string; readonly run: string; readonly promptHash: string };
+}
+
+export type UnlabelledFixture = Omit<WardenFixture, 'labels' | 'labeler' | 'feedbackRules'> & {
+  /** Earlier asks or commits in the same thread, for the labeler to summarize into `context`. */
+  readonly precedingRaw?: string;
+};
+
+export const WARDEN_LABEL_PROMPT = `You label moments from AI coding sessions and code changes for a reviewer-routing experiment.
+
+A roster of Wardens advises a coding agent. Each Warden owns one narrow domain (given below with its charter). At each moment (a user's message to the agent, or an agent's action or plan), a router must decide which Wardens to wake. You produce the ground truth for that router.
+
+For each moment you get: the thread context, the trigger (the moment itself), and WHAT HAPPENED NEXT (the person's correction, a later fix, a review comment, or nothing notable). Use what happened next to understand what was wrong or what was needed, but judge each Warden by the moment: would a competent Warden of that domain, seeing the trigger and context, have had something true, specific and useful to say inside its own domain? That includes the Warden that would have prevented the mistake, and any other Warden whose domain the moment genuinely touches (for example a schema change touches Schema even when the correction was about reuse). It does NOT include a Warden that could only say something generic, or whose domain the moment merely mentions in passing.
+
+Most Wardens are irrelevant to most moments. A moment where nothing went wrong can still be relevant to a Warden (a plan heading to merge without the full check touches Ship), but plain chatter, a status question, or an answer to the agent's question usually touches none.
+
+For each relevant Warden, write shouldKnow: the specific thing it should have known or said, at most 200 characters, naming the existing primitive, file, symbol, rule or check when there is one (e.g. "Use the existing debounce wrapper in packages/shared/debounce.ts instead of a new timer"). Never quote secrets.
+
+Also write context: 1-3 sentences summarizing the thread or change UP TO the moment (what is being worked on, where), without revealing what happened next. And feedbackRules: the numbers of the recurring rules (list given) that the moment's mistake repeats, or [].
+
+Respond with JSON only:
+{ "results": { "<fixture id>": { "context": string, "relevant": { "<domain>": "<shouldKnow>" }, "feedbackRules": number[] } } }
+List only relevant domains under "relevant" (an empty object when none). Use the domain names exactly as given.`;
+
+/** The stable start of every label input: the roster and the rule list, so primed sessions reuse it. */
+export function wardenLabelPrefix(
+  roster: readonly WardenRosterEntry[],
+  rules: readonly { n: number; rule: string; count: string }[],
+): string {
+  const wardens = roster.map((w) => `- ${w.domain}: ${w.prompt.replace(/\s+/g, ' ')}`).join('\n');
+  const recurring = rules.map((r) => `${r.n}. ${r.rule} (said ${r.count}×)`).join('\n');
+  return `## Wardens\n${wardens}\n\n## Recurring rules (FEEDBACK-LOG)\n${recurring}\n\nLabel each moment below.\n\n`;
+}
+
+export function wardenLabelMessages(
+  prefix: string,
+  fixtures: readonly UnlabelledFixture[],
+  limits: { trigger?: number; context?: number; hidden?: number } = {},
+): { role: 'system' | 'user'; content: string }[] {
+  const body = fixtures
+    .map(
+      (f) =>
+        `## ${f.id} (${f.ctx}${f.project ? `/${f.project}` : ''}, ${f.source}, trigger: ${f.trigger.kind})\n### Context\n${
+          [f.context, f.precedingRaw]
+            .filter(Boolean)
+            .join('\n')
+            .slice(-(limits.context ?? 1500)) || '(none)'
+        }\n\n### Trigger\n${f.trigger.text.slice(-(limits.trigger ?? 3000))}\n\n### What happened next\n${f.hidden?.slice(0, limits.hidden ?? 1500) || '(nothing notable)'}`,
+    )
+    .join('\n\n');
+  return [
+    { role: 'system', content: WARDEN_LABEL_PROMPT },
+    { role: 'user', content: `${prefix}${body}` },
+  ];
+}
+
+export interface ParsedWardenLabels {
+  readonly context: string;
+  readonly labels: Record<string, WardenLabel>;
+  readonly feedbackRules: number[];
+}
+
+/** One answer per fixture id; undefined where the answer is missing or malformed. Unknown domains are dropped. */
+export function parseWardenLabels(
+  content: string,
+  roster: readonly WardenRosterEntry[],
+  ids: readonly string[],
+): (ParsedWardenLabels | undefined)[] {
+  const start = content.indexOf('{');
+  const end = content.lastIndexOf('}');
+  let raw: unknown;
+  try {
+    raw = JSON.parse(content.slice(start, end + 1));
+  } catch {
+    return ids.map(() => undefined);
+  }
+  const results = (raw as { results?: Record<string, unknown> } | null)?.results ?? {};
+  const byDomain = new Map(roster.map((w) => [w.domain, w.id]));
+  return ids.map((id) => {
+    const item = results[id] as
+      | { context?: unknown; relevant?: unknown; feedbackRules?: unknown }
+      | undefined;
+    if (!item || typeof item.relevant !== 'object' || item.relevant === null) return undefined;
+    const relevant = item.relevant as Record<string, unknown>;
+    const labels: Record<string, WardenLabel> = {};
+    for (const w of roster) labels[w.id] = { relevant: false };
+    for (const [domain, know] of Object.entries(relevant)) {
+      const wardenId = byDomain.get(domain);
+      if (!wardenId) continue;
+      labels[wardenId] = {
+        relevant: true,
+        ...(typeof know === 'string' && know.trim()
+          ? { shouldKnow: know.trim().slice(0, 300) }
+          : {}),
+      };
+    }
+    return {
+      context: typeof item.context === 'string' ? item.context.trim() : '',
+      labels,
+      feedbackRules: Array.isArray(item.feedbackRules)
+        ? item.feedbackRules.filter((n): n is number => Number.isInteger(n))
+        : [],
+    };
+  });
+}
+
+export interface DomainAgreement {
+  readonly wardenId: string;
+  /** Fixtures both sides labelled. */
+  readonly n: number;
+  readonly agree: number;
+  readonly positivesA: number;
+  readonly positivesB: number;
+  readonly bothPositive: number;
+  /** Cohen's kappa; null when chance agreement is total (one class on both sides). */
+  readonly kappa: number | null;
+}
+
+/** Per-Warden agreement between two labelings of the same fixtures, plus the pooled figures. */
+export function labelAgreement(
+  a: ReadonlyMap<string, Readonly<Record<string, WardenLabel>>>,
+  b: ReadonlyMap<string, Readonly<Record<string, WardenLabel>>>,
+  wardenIds: readonly string[],
+): {
+  perWarden: DomainAgreement[];
+  pooled: DomainAgreement;
+  exactFixtures: number;
+  fixtures: number;
+} {
+  const shared = [...a.keys()].filter((id) => b.has(id));
+  const tally = (wardenId: string, ids: readonly string[], wardens: readonly string[]) => {
+    let n = 0;
+    let agree = 0;
+    let positivesA = 0;
+    let positivesB = 0;
+    let bothPositive = 0;
+    for (const id of ids)
+      for (const w of wardens) {
+        const x = a.get(id)?.[w]?.relevant ?? false;
+        const y = b.get(id)?.[w]?.relevant ?? false;
+        n++;
+        if (x === y) agree++;
+        if (x) positivesA++;
+        if (y) positivesB++;
+        if (x && y) bothPositive++;
+      }
+    const observed = n ? agree / n : 0;
+    const chance = n
+      ? (positivesA / n) * (positivesB / n) + (1 - positivesA / n) * (1 - positivesB / n)
+      : 1;
+    const kappa =
+      chance >= 1 ? null : Math.round(((observed - chance) / (1 - chance)) * 1000) / 1000;
+    return { wardenId, n, agree, positivesA, positivesB, bothPositive, kappa };
+  };
+  const exactFixtures = shared.filter((id) =>
+    wardenIds.every(
+      (w) => (a.get(id)?.[w]?.relevant ?? false) === (b.get(id)?.[w]?.relevant ?? false),
+    ),
+  ).length;
+  return {
+    perWarden: wardenIds.map((w) => tally(w, shared, [w])),
+    pooled: tally('*', shared, wardenIds),
+    exactFixtures,
+    fixtures: shared.length,
+  };
+}
+
+/** The charter eval's probe shape, so `warden-charter.ts` runs on fixtures too. */
+export function fixtureProbe(
+  fixture: WardenFixture,
+  domainOf: (wardenId: string) => string,
+): WardenProbe {
+  const relevant = Object.entries(fixture.labels).filter(([, l]) => l.relevant);
+  return {
+    id: fixture.id,
+    kind: relevant.length ? 'positive' : 'negative',
+    ctx: fixture.ctx,
+    ...(fixture.project ? { project: fixture.project } : {}),
+    moment: fixture.trigger.text,
+    ...(relevant.length
+      ? {
+          gold: {
+            domains: relevant.map(([id]) => domainOf(id)),
+            statements: relevant.map(([, l]) => l.shouldKnow).filter((s): s is string => !!s),
+          },
+        }
+      : {}),
+    ...(fixture.hidden ? { hidden: fixture.hidden } : {}),
+  };
+}

package/src/feedback/warden-prefilter.ts

@@ -0,0 +1,194 @@
+// The Warden pre-filter: one cheap local yes/no per Warden before it is asked. Data and pure
+// functions only, so Oracle scores runs the same way; Foundry's provider makes the call. It fails
+// open: a Warden is skipped only on a confident no, and anything else (an unsure score, an error, no
+// answer) asks the Warden as before.
+
+import type { WardenTriggerKind } from './warden-labels';
+
+/**
+ * Where a moment arrives: before (the user's message) or after (the agent's action or plan, and its
+ * finished turn). The labelled moments are `WardenFixture`s (`warden-labels`).
+ */
+export type PrefilterTrigger = WardenTriggerKind | 'post-turn';
+
+/** One (moment, Warden) pair as a run scored it. */
+export interface PrefilterPair {
+  readonly momentId: string;
+  readonly wardenId: string;
+  /** Labelled relevance; undefined for an unlabelled pair, which still counts toward the skip rate. */
+  readonly relevant?: boolean;
+  /** P(the moment is in this Warden's domain); undefined when the call failed (the Warden is asked). */
+  readonly score?: number;
+}
+
+/** Fail open: skip only when the score is a confident no. */
+export function prefilterSkips(score: number | undefined, skipBelow: number): boolean {
+  return score !== undefined && score < skipBelow;
+}
+
+export interface PrefilterPoint {
+  readonly threshold: number;
+  /** Share of all pairs skipped: Warden calls saved. */
+  readonly skipRate: number;
+  /** Share of relevant pairs still asked. */
+  readonly recall: number | null;
+  /** Share of labelled not-relevant pairs skipped. */
+  readonly correctSkips: number | null;
+}
+
+export interface PrefilterScore {
+  readonly pairs: number;
+  readonly relevant: number;
+  readonly labelledIrrelevant: number;
+  readonly errors: number;
+  /** Ranking quality over labelled pairs (relevant against labelled not relevant). */
+  readonly auroc: number | null;
+  /** Recall when the threshold skips this share of all pairs. */
+  readonly recallAtSkip: Readonly<Record<string, number | null>>;
+  /** The share of pairs skipped while still asking this share of relevant pairs. */
+  readonly skipAtRecall: Readonly<Record<string, { threshold: number; skipRate: number } | null>>;
+  readonly sweep: readonly PrefilterPoint[];
+}
+
+const round = (n: number) => Math.round(n * 1000) / 1000;
+const ratio = (n: number, d: number) => (d ? round(n / d) : null);
+
+export const PREFILTER_SWEEP = [
+  0.01, 0.02, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9,
+] as const;
+
+/** Recall against skip rate, both ways, and the threshold sweep. */
+export function scorePrefilter(
+  pairs: readonly PrefilterPair[],
+  options: { skipRates?: readonly number[]; recalls?: readonly number[] } = {},
+): PrefilterScore {
+  const positives = pairs.filter((p) => p.relevant === true);
+  const negatives = pairs.filter((p) => p.relevant === false);
+  const at = (threshold: number): PrefilterPoint => {
+    const skip = (p: PrefilterPair) => prefilterSkips(p.score, threshold);
+    return {
+      threshold,
+      skipRate: ratio(pairs.filter(skip).length, pairs.length) ?? 0,
+      recall: ratio(positives.filter((p) => !skip(p)).length, positives.length),
+      correctSkips: ratio(negatives.filter(skip).length, negatives.length),
+    };
+  };
+  const scoreOf = (p: PrefilterPair) => p.score ?? Number.POSITIVE_INFINITY;
+  // Recall at a skip rate: the threshold is the score that skips that share of all pairs.
+  const ascending = pairs.map(scoreOf).sort((a, b) => a - b);
+  const recallAtSkip: Record<string, number | null> = {};
+  for (const rate of options.skipRates ?? [0.3, 0.5, 0.7]) {
+    const threshold =
+      ascending[Math.min(ascending.length - 1, Math.floor(rate * ascending.length))];
+    recallAtSkip[String(rate)] =
+      threshold === undefined || !Number.isFinite(threshold) ? null : at(threshold).recall;
+  }
+  // Skip rate at a recall: the highest threshold that still asks that share of relevant pairs.
+  const positiveScores = positives.map(scoreOf).sort((a, b) => a - b);
+  const skipAtRecall: Record<string, { threshold: number; skipRate: number } | null> = {};
+  for (const target of options.recalls ?? [0.8, 0.9, 0.95]) {
+    const threshold = positiveScores[Math.floor((1 - target) * positiveScores.length + 1e-9)];
+    skipAtRecall[String(target)] =
+      threshold === undefined || !Number.isFinite(threshold)
+        ? null
+        : { threshold: round(threshold), skipRate: at(threshold).skipRate };
+  }
+  return {
+    pairs: pairs.length,
+    relevant: positives.length,
+    labelledIrrelevant: negatives.length,
+    errors: pairs.filter((p) => p.score === undefined).length,
+    auroc: auroc(positives, negatives),
+    recallAtSkip,
+    skipAtRecall,
+    sweep: PREFILTER_SWEEP.map(at),
+  };
+}
+
+function auroc(positives: readonly PrefilterPair[], negatives: readonly PrefilterPair[]) {
+  const pos = positives.flatMap((p) => (p.score === undefined ? [] : [p.score]));
+  const neg = negatives.flatMap((p) => (p.score === undefined ? [] : [p.score]));
+  if (!pos.length || !neg.length) return null;
+  let wins = 0;
+  for (const a of pos) for (const b of neg) wins += a > b ? 1 : a === b ? 0.5 : 0;
+  return round(wins / (pos.length * neg.length));
+}
+
+/**
+ * The same pair scored N times: the share whose skip/ask decision never changed at the threshold,
+ * and the mean spread (max − min) of its score.
+ */
+export function prefilterConsistency(
+  repeats: ReadonlyMap<string, readonly (number | undefined)[]>,
+  skipBelow: number,
+) {
+  let same = 0,
+    spread = 0,
+    n = 0;
+  for (const scores of repeats.values()) {
+    if (!scores.length) continue;
+    n++;
+    if (new Set(scores.map((s) => prefilterSkips(s, skipBelow))).size === 1) same++;
+    const values = scores.filter((s): s is number => s !== undefined);
+    spread += values.length ? Math.max(...values) - Math.min(...values) : 1;
+  }
+  return { pairs: n, sameDecision: ratio(same, n), meanSpread: n ? round(spread / n) : null };
+}
+
+export function percentiles(values: readonly number[]) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const pick = (p: number) =>
+    sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))] ?? 0;
+  return { p50: pick(50), p95: pick(95), max: sorted.at(-1) ?? 0 };
+}
+
+/** Characters of a Warden's instructions a question carries: the decision model reads 192 tokens of it. */
+export const PREFILTER_DESCRIPTION_CHARS = 480;
+/** Characters of the moment, head and tail, and of the thread context, a state carries. */
+export const PREFILTER_MOMENT_CHARS = 1600;
+export const PREFILTER_CONTEXT_CHARS = 400;
+
+/**
+ * A Warden's domain as the question states it: its instructions without the "You are the … Warden."
+ * opener, so the question reads as a topic.
+ */
+export function prefilterDescription(instructions: string): string {
+  const text = instructions
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^You are the [^.]*\.\s*/, '');
+  return clip(text, PREFILTER_DESCRIPTION_CHARS);
+}
+
+/**
+ * The System One yes/no asked per Warden, as a topic ("Is this about …"). On a small hand-checked
+ * grid it separated in-domain moments far better than asking about "a reviewer's domain".
+ */
+export function prefilterQuestion(description: string) {
+  return { type: 'noul' as const, instructions: `Is this about ${description}` };
+}
+
+/** The System One state for a moment: a bounded view of what the thread holds, then the moment. */
+export function prefilterState(trigger: PrefilterTrigger, text: string, context?: string): string {
+  const label = {
+    'user-message': "The user's message",
+    'agent-action': "The agent's action",
+    'agent-plan': "The agent's plan",
+    'post-turn': "The agent's finished turn",
+  }[trigger];
+  const moment = window(text.trim(), PREFILTER_MOMENT_CHARS);
+  return context?.trim()
+    ? `${label}:\n${moment}\n\nThread so far: ${clip(context.trim(), PREFILTER_CONTEXT_CHARS)}`
+    : `${label}:\n${moment}`;
+}
+
+function clip(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+/** Head and tail of a long text: an agent turn states its plan first and its result last. */
+function window(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const half = Math.floor((max - 3) / 2);
+  return `${text.slice(0, half)} … ${text.slice(-half)}`;
+}

package/src/feedback/warden-probes.ts

@@ -0,0 +1,212 @@
+// Warden probes: the offline measurement of how well a Warden charter keeps the chorus quiet, in
+// scope and right. Data and pure functions only, so Oracle can score runs on a core-only dependency;
+// callers bring the probes, the Warden calls and the judge call.
+//
+// A probe is one moment of a real session. A positive probe is an agent turn that drew a sharp
+// correction of an already-recorded rule; a negative probe is an agent turn the user let pass.
+
+/** One real moment a chorus is asked about. Never commit probes: they hold session text. */
+export interface WardenProbe {
+  readonly id: string;
+  readonly kind: 'positive' | 'negative';
+  /** Which context's Wardens may see it (UserEvidence probes only ever see the UserEvidence ladder). */
+  readonly ctx: string;
+  readonly project?: string;
+  /** The moment: what the agent just did or said, as the Warden sees it. */
+  readonly moment: string;
+  /** Positive probes: the Warden domains that own the rule the user enforced next, and its one-line statements. */
+  readonly gold?: { readonly domains: readonly string[]; readonly statements: readonly string[] };
+  /** The user's actual next message. The judge sees it; Wardens never do. */
+  readonly hidden?: string;
+}
+
+/** One Warden's answer on one probe, and the judge's verdict when it spoke. */
+export interface WardenProbeAnswer {
+  readonly probeId: string;
+  readonly domain: string;
+  readonly noComment: boolean;
+  /** The protocol was broken; counted apart, never as silence or speech. */
+  readonly error?: string;
+  readonly text?: string;
+  readonly elapsedMs?: number;
+  readonly judged?: WardenJudgement;
+}
+
+/** One probe run as a turn: every Warden asked at once, as the live chorus is. */
+export interface WardenProbeTurn {
+  readonly probeId: string;
+  /** Warden calls made for this probe. */
+  readonly calls: number;
+  /** Wall clock from the first ask to the last answer. */
+  readonly wallMs: number;
+  /** Calls the decision queue never admitted. */
+  readonly notAdmitted: number;
+}
+
+export interface WardenJudgement {
+  /** The remark says what the user's next message enforced (the same rule or the same fix). */
+  readonly matches: boolean;
+  /** The remark stays inside the speaking Warden's domain. */
+  readonly inDomain: boolean;
+  readonly reason?: string;
+}
+
+export interface CharterScore {
+  readonly probes: number;
+  readonly calls: number;
+  readonly errors: number;
+  /**
+   * Of the Warden answers where nothing of theirs applied (a negative probe, or a positive one owned
+   * by another domain, without a remark matched to the real correction), the share that were
+   * NO_COMMENT. A protocol error there counts as a failed silence.
+   */
+  readonly silencePrecision: number | null;
+  /** Of the remarks made, the share that matched the user's later real correction. */
+  readonly speakPrecision: number | null;
+  /** Remarks outside the speaking Warden's domain. */
+  readonly scopeViolations: number;
+  /** Positive probes where a gold (owning) Warden named the correction before the user did. */
+  readonly recall: number | null;
+  readonly remarks: number;
+  readonly silences: number;
+  /** Remarks the judge could not grade: counted as unmatched, reported apart. */
+  readonly unjudged: number;
+  /** Per-turn load at roster scale: calls and wall clock, when the run recorded turns. */
+  readonly turns?: {
+    readonly count: number;
+    readonly callsPerTurn: number;
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+    readonly maxMs: number;
+    readonly notAdmitted: number;
+  };
+}
+
+function percentile(sorted: readonly number[], p: number): number {
+  return sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))] ?? 0;
+}
+
+const ratio = (n: number, d: number) => (d ? Math.round((n / d) * 1000) / 1000 : null);
+
+/**
+ * Score one charter run. "Nothing applied" means a negative probe, or a positive probe whose gold
+ * domains do not include this Warden; a remark there that the judge matched to the real correction
+ * is still a correct remark, not a broken silence.
+ */
+export function scoreCharterRun(
+  probes: readonly WardenProbe[],
+  answers: readonly WardenProbeAnswer[],
+  turns: readonly WardenProbeTurn[] = [],
+): CharterScore {
+  const byId = new Map(probes.map((p) => [p.id, p]));
+  let calls = 0,
+    errors = 0,
+    quietCases = 0,
+    quietRight = 0,
+    remarks = 0,
+    remarksRight = 0,
+    scope = 0,
+    silences = 0,
+    unjudged = 0;
+  const recalled = new Set<string>();
+  for (const a of answers) {
+    calls++;
+    const probe = byId.get(a.probeId);
+    if (!probe) continue;
+    const owned = probe.kind === 'positive' && (probe.gold?.domains ?? []).includes(a.domain);
+    if (a.error) {
+      // A broken answer is neither silence nor a remark; where nothing applied, it is a failed silence.
+      errors++;
+      if (!owned) quietCases++;
+      continue;
+    }
+    if (a.noComment) silences++;
+    else {
+      remarks++;
+      if (!a.judged) unjudged++;
+      if (a.judged?.matches) {
+        remarksRight++;
+        if (owned) recalled.add(probe.id);
+      }
+      if (a.judged && !a.judged.inDomain) scope++;
+    }
+    if (!owned && !(a.judged?.matches ?? false)) {
+      quietCases++;
+      if (a.noComment) quietRight++;
+    }
+  }
+  const positives = probes.filter((p) => p.kind === 'positive').length;
+  return {
+    probes: probes.length,
+    calls,
+    errors,
+    silencePrecision: ratio(quietRight, quietCases),
+    speakPrecision: ratio(remarksRight, remarks),
+    scopeViolations: scope,
+    recall: ratio(recalled.size, positives),
+    remarks,
+    silences,
+    unjudged,
+    ...(turns.length
+      ? {
+          turns: (() => {
+            const walls = turns.map((t) => t.wallMs).sort((a, b) => a - b);
+            return {
+              count: turns.length,
+              callsPerTurn:
+                Math.round((turns.reduce((n, t) => n + t.calls, 0) / turns.length) * 10) / 10,
+              p50Ms: percentile(walls, 50),
+              p95Ms: percentile(walls, 95),
+              maxMs: walls.at(-1) ?? 0,
+              notAdmitted: turns.reduce((n, t) => n + t.notAdmitted, 0),
+            };
+          })(),
+        }
+      : {}),
+  };
+}
+
+/** The judge's instructions: one remark against the user's real next message. */
+export const WARDEN_JUDGE_PROMPT = `You grade one remark a narrow expert reviewer (a "Warden") made about an AI coding agent's turn.
+You see the Warden's domain, the agent's turn, the remark, and what the user actually said next.
+Answer two questions:
+- matches: does the remark say what the user's next message enforced: the same rule, or the same fix? A remark that is merely related, or generic, does not match.
+- inDomain: does the remark stay inside the Warden's stated domain?
+Respond with JSON only: { "matches": boolean, "inDomain": boolean, "reason": string } where reason is one short sentence.`;
+
+/** The judge's input for one remark. */
+export function wardenJudgeMessage(input: {
+  domain: string;
+  domainDescription: string;
+  moment: string;
+  remark: string;
+  hidden: string;
+}): string {
+  return [
+    `## Warden domain: ${input.domain}`,
+    input.domainDescription,
+    '## Agent turn',
+    input.moment,
+    '## Remark',
+    input.remark,
+    "## The user's actual next message",
+    input.hidden || '(the user let the turn pass without correcting it)',
+  ].join('\n\n');
+}
+
+/** Parse a judge answer strictly; undefined when it is not the shape. */
+export function parseWardenJudgement(text: string): WardenJudgement | undefined {
+  const trimmed = text.trim();
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n?\s*```$/.exec(trimmed);
+  try {
+    const value = JSON.parse(fenced ? fenced[1]! : trimmed) as Record<string, unknown>;
+    if (typeof value.matches !== 'boolean' || typeof value.inDomain !== 'boolean') return undefined;
+    return {
+      matches: value.matches,
+      inDomain: value.inDomain,
+      ...(typeof value.reason === 'string' ? { reason: value.reason.slice(0, 300) } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -116,6 +116,7 @@ export {
 } from './classifier';
 // Context primitives
 export {
+  type CompositionSnapshot,
   ContextLayer,
   type ContextLayerConfig,
   type ContextSource,
@@ -131,9 +132,13 @@ export {
   type LayerState,
   type LayerVersionMark,
   type LogicalMessageIdentity,
+  type OmittedSource,
   REQUIRED_CONTEXT_BLOCKED,
   type SourceLoadHint,
+  type SourcePart,
+  type SourceSegment,
   type SourceSelectionReport,
+  segmentsText,
   type VersionEntry,
   type VersionLog,
 } from './context-layer';
@@ -184,6 +189,49 @@ export {
   scrubSecrets,
   type TranscriptTurn,
 } from './feedback/correction';
+export {
+  type DomainAgreement,
+  fixtureProbe,
+  labelAgreement,
+  type ParsedWardenLabels,
+  parseWardenLabels,
+  type UnlabelledFixture,
+  WARDEN_LABEL_PROMPT,
+  type WardenFixture,
+  type WardenLabel,
+  type WardenRosterEntry,
+  type WardenTriggerKind,
+  wardenLabelMessages,
+  wardenLabelPrefix,
+} from './feedback/warden-labels';
+export {
+  PREFILTER_CONTEXT_CHARS,
+  PREFILTER_DESCRIPTION_CHARS,
+  PREFILTER_MOMENT_CHARS,
+  PREFILTER_SWEEP,
+  type PrefilterPair,
+  type PrefilterPoint,
+  type PrefilterScore,
+  type PrefilterTrigger,
+  percentiles,
+  prefilterConsistency,
+  prefilterDescription,
+  prefilterQuestion,
+  prefilterSkips,
+  prefilterState,
+  scorePrefilter,
+} from './feedback/warden-prefilter';
+export {
+  type CharterScore,
+  parseWardenJudgement,
+  scoreCharterRun,
+  WARDEN_JUDGE_PROMPT,
+  type WardenJudgement,
+  type WardenProbe,
+  type WardenProbeAnswer,
+  type WardenProbeTurn,
+  wardenJudgeMessage,
+} from './feedback/warden-probes';
 export {
   type FlowConfig,
   type FlowStage,
@@ -297,6 +345,7 @@ export {
   type ThreadMeta,
   type ThreadName,
   type ThreadReference,
+  type ThreadSpawn,
   type ThreadStatus,
   threadTitle,
 } from './thread';

package/src/messages.ts

@@ -1,4 +1,8 @@
-import type { LayerInstanceState, LogicalMessageIdentity } from './context-layer';
+import type {
+  CompositionSnapshot,
+  LayerInstanceState,
+  LogicalMessageIdentity,
+} from './context-layer';
 import { computeHash } from './context-layer';
 import type { AssembledContext, PromptBlock } from './context-stack';
 import type { ServedModel } from './native-evidence';
@@ -27,7 +31,7 @@ export interface InjectionBlock {
 /** One decorator's recorded participation in a turn. */
 export interface DecorationParticipant {
   readonly id: string;
-  /** contribute | abstain | error | timeout | omitted */
+  /** contribute | no-comment | skipped | error | timeout | excluded | omitted */
   readonly decision: string;
   readonly reason?: string;
   /** The three named inputs the participant worked from, never inferred. */
@@ -55,6 +59,8 @@ export type ParticipantRequest =
       readonly capturedAt: number;
       /** The model and effort that answered, when the provider answered before the phase sealed. */
       readonly served?: ServedModel;
+      /** What the call's instructions and domain knowledge were composed of; the journal stores version ids for it. */
+      readonly composition?: CompositionSnapshot;
     }
   | { readonly status: 'not-sent'; readonly phase: string; readonly reason: string }
   /** A call may have been made, but its input was never observed (e.g. the caller threw first). Not "not-sent". */

package/src/native-evidence.ts

@@ -34,6 +34,26 @@ export interface OwnedAdmissionInspection {
   readonly cleanup: 'not-requested' | 'pending' | 'released' | 'unknown';
   readonly capacity: 'settled' | 'unknown';
 }
+/** A native subagent's lifecycle event (agent-session `SubagentLifecycle`, allowlisted). */
+export interface NativeSubagentLifecycle {
+  readonly phase: 'started' | 'progress' | 'updated' | 'ended';
+  readonly taskId: string;
+  readonly toolUseId?: string;
+  readonly parentTaskId?: string;
+  readonly agentType?: string;
+  readonly description?: string;
+  readonly depth?: number;
+  readonly backgrounded?: boolean;
+  readonly status?: string;
+  readonly summary?: string;
+  readonly prompt?: string;
+  readonly usage?: {
+    readonly totalTokens: number;
+    readonly toolUses?: number;
+    readonly durationMs?: number;
+  };
+}
+
 export interface NativeEvidence {
   readonly schema: 1;
   readonly executionMode?: 'controlled-fixture';
@@ -65,6 +85,10 @@ export interface NativeEvidence {
   readonly content?: string;
   readonly correlation?: string;
   readonly kind?: string;
+  /** The parent's tool call that spawned the subagent this came from (absent for the thread's own). */
+  readonly parentToolUseId?: string;
+  /** A subagent's lifecycle (kind `subagent`), as the runtime reported it. */
+  readonly subagent?: NativeSubagentLifecycle;
   readonly toolName?: string;
   readonly toolServer?: string;
   readonly toolMethod?: string;

package/src/thread.ts

@@ -44,6 +44,21 @@ export function threadTitle(
   return meta.description ? { text: meta.description, source: 'description' } : undefined;
 }
 
+/** How a subagent thread came to be: who spawned it, through what, and its native identity. */
+export interface ThreadSpawn {
+  readonly via: 'foundry' | 'native-claude' | 'native-codex' | 'host-paseo' | 'host-t3';
+  /** The parent's tool call that spawned it. */
+  readonly toolCallId?: string;
+  /** The native run's id (Claude task id, Codex child thread id). */
+  readonly nativeTaskId?: string;
+  readonly agentType?: string;
+  readonly description?: string;
+  /** The parent's `handoff` phase row for this spawn. */
+  readonly handoffId?: string;
+  /** Recorded from the native stream only: no Foundry middleware ran on it. */
+  readonly observed?: boolean;
+}
+
 export interface ThreadMeta {
   /** Living description — what this thread is doing right now. */
   description: string;
@@ -72,6 +87,15 @@ export interface ThreadMeta {
   /** Parent thread when this thread is a subagent spawned by another. */
   parentThreadId?: string;
 
+  /** The parent's turn that spawned this thread (a subagent). */
+  parentTurnId?: string;
+
+  /** How this subagent thread was spawned (docs/reference/SUBAGENTS.md §4.1). */
+  spawn?: ThreadSpawn;
+
+  /** 1 for a child of a main thread. */
+  depth?: number;
+
   /** Project that owns this thread. Scopes memory sources and tool calls. */
   projectId?: string;