codictator 0.0.0-stage → 0.1.2

package/dist/features/steering/context-file.js

@@ -0,0 +1,107 @@
+// SPEC §4.6.2: the AGENTS.md managed block. Codictator owns the region
+// between the markers; text outside it belongs to the user. Content order
+// is fixed by the spec: precedence, workflow, floor rules, block action,
+// terse output. The block never exceeds 6,000 bytes.
+import { CONTEXT_BLOCK_MAX_BYTES, MANAGED_BEGIN, MANAGED_END, PRECEDENCE_STATEMENT, utf8Bytes, } from "./precedence.js";
+// SPEC §5.1 and §5.9: the steering-owned floor and band rules with their
+// pack statements. Callers with an effective rule set pass floorRules;
+// the default keeps the block truthful without a config read.
+const DEFAULT_FLOOR_RULES = [
+    {
+        id: "core/context-soft-band",
+        statement: "Keep routine work inside softPercent of the context window.",
+    },
+    {
+        id: "core/context-hard-band",
+        statement: "Stop and checkpoint at hardPercent of the context window.",
+    },
+    {
+        id: "core/session-tool-call-limit",
+        statement: "Finish within maxToolCalls tool calls per session.",
+    },
+    {
+        id: "core/read-dedupe",
+        statement: "Never re-read a file whose content is already in context.",
+    },
+    {
+        id: "core/graph-before-scan",
+        statement: "Consult the knowledge-graph output before broad scans.",
+    },
+    { id: "core/mcp-declared", statement: "Use only declared MCP servers." },
+    { id: "core/workflow-gates", statement: "Mandatory gates stay in order." },
+    {
+        id: "core/loop-breaker",
+        statement: "Stop after maxRepeats failed attempts.",
+    },
+];
+// SPEC §4.12.2: the seven mandatory phases.
+const DEFAULT_WORKFLOW_PHASES = [
+    "discovery",
+    "planning",
+    "implementation",
+    "validation",
+    "review",
+    "record",
+    "integrate",
+];
+function floorLines(rules) {
+    return rules.map((rule) => `${rule.id} — ${rule.statement}`);
+}
+function fittedBlockMiddle(kept, total) {
+    const omitted = total - kept.length;
+    return omitted > 0
+        ? [...kept, `and ${omitted} more: codictator context --all`]
+        : [...kept];
+}
+// The block shrinks from the rules list first: precedence, workflow and
+// the tail always survive, and the tail pointer names the elided rules.
+// The pointer line itself counts against the budget while trimming.
+function fitBlock(head, rules, tail, maxBytes) {
+    const keptRules = [...rules];
+    let middle = fittedBlockMiddle(keptRules, rules.length);
+    while (utf8Bytes([...head, ...middle, ...tail].join("\n")) > maxBytes &&
+        keptRules.length > 0) {
+        keptRules.pop();
+        middle = fittedBlockMiddle(keptRules, rules.length);
+    }
+    let block = [...head, ...middle, ...tail].join("\n");
+    if (utf8Bytes(block) > maxBytes) {
+        const bytes = new TextEncoder().encode(block).slice(0, maxBytes);
+        block = new TextDecoder().decode(bytes);
+    }
+    return block;
+}
+export function buildManagedBlock(options = {}) {
+    const rules = options.floorRules ?? DEFAULT_FLOOR_RULES;
+    const phases = options.workflowPhases ?? DEFAULT_WORKFLOW_PHASES;
+    const limits = options.nonDefaultLimits ?? [];
+    const head = [
+        MANAGED_BEGIN,
+        PRECEDENCE_STATEMENT,
+        "",
+        `Workflow: ${phases.join(" > ")}. Advance with codictator task phase next.`,
+        "",
+        "Floor rules:",
+    ];
+    const tail = [
+        limits.length === 0
+            ? "Limits: defaults (softPercent 60, hardPercent 75, maxToolCalls 300, maxRepeats 3)."
+            : `Limits: ${limits.join("; ")}.`,
+        "On block: apply Do instead, never retry a variation, escalate at the loop-breaker count.",
+        "Output: terse. codictator explain <id> names the rule; codictator context shows this file.",
+        MANAGED_END,
+    ];
+    return fitBlock(head, floorLines(rules), tail, CONTEXT_BLOCK_MAX_BYTES);
+}
+// SPEC §4.6.2: the managed block for a session. The block is repo-level,
+// so every session renders the same text; maxBytes below the 6,000-byte
+// cap tightens the budget further.
+export function renderContextFile(_sessionId, maxBytes) {
+    const block = buildManagedBlock();
+    const limit = Math.min(maxBytes, CONTEXT_BLOCK_MAX_BYTES);
+    if (utf8Bytes(block) <= limit) {
+        return Promise.resolve(block);
+    }
+    const lines = block.split("\n");
+    return Promise.resolve(fitBlock(lines.slice(0, 2), lines.slice(2, -1), lines.slice(-1), limit));
+}

package/dist/features/steering/graph-scan.d.ts

@@ -0,0 +1,7 @@
+export interface SearchGate {
+    readonly graphOutputOnDisk: boolean;
+    readonly priorIdenticalSearches: number;
+}
+export declare function shouldBlockSearch(gate: SearchGate): boolean;
+export declare function graphLookupInstruction(helperId?: string): string;
+export declare function evaluateGraphBeforeScanMarkers(markers: ReadonlyMap<string, string>): boolean;

package/dist/features/steering/graph-scan.js

@@ -0,0 +1,17 @@
+export function shouldBlockSearch(gate) {
+    return gate.graphOutputOnDisk && gate.priorIdenticalSearches === 0;
+}
+// The blocked search replies with the helper's lookup instruction, so the
+// agent consults the graph instead of rescanning the repo.
+export function graphLookupInstruction(helperId = "knowledge-graph") {
+    return (`Consult the ${helperId} helper output before scanning: ` +
+        "run the helper's lookup for this query and use its result instead of a repo-wide search.");
+}
+// Fixture-shaped evaluation for the pack self-test (§4.4.4): a full-repo
+// scan while the graph is absent violates the graph-first order; a
+// graph-guided scan, or one with the graph present, passes.
+export function evaluateGraphBeforeScanMarkers(markers) {
+    const scan = markers.get("scan") ?? "";
+    const graph = markers.get("knowledge-graph") ?? "";
+    return scan.includes("full-repo") && graph !== "present";
+}

package/dist/features/steering/index.d.ts

@@ -0,0 +1,30 @@
+import { type BudgetBand } from "./budgets.ts";
+import { type InjectionOptions } from "./injection.ts";
+export type { AgentAssetId } from "./agent-assets.ts";
+export { AGENT_ASSET_IDS, AGENT_ASSET_PURPOSES, AGENT_ASSET_TEMPLATES, findMissingHelpers, parseHelperList, renderAgentAsset, } from "./agent-assets.ts";
+export type { BudgetBand, SteeringSession } from "./budgets.ts";
+export { bandForUsage, createSteeringSession, isSubagentSession, noteCheckpointCommitted, noteCompaction, noteSoftAdvised, recordSessionUsage, recordToolCall, sessionBand, startSteeringSession, } from "./budgets.ts";
+export { evaluateContextHardBand, evaluateContextSoftBand, evaluateRepeatReads, evaluateToolCallLimit, parseMarkerCount, parseMarkerMap, parseMarkerPercent, } from "./checks.ts";
+export type { ContextFileOptions, FloorRuleLine, } from "./context-file.ts";
+export { buildManagedBlock } from "./context-file.ts";
+export { evaluateGraphBeforeScanMarkers, graphLookupInstruction, type SearchGate, shouldBlockSearch, } from "./graph-scan.ts";
+export type { InjectionOptions, InjectionRuleLine } from "./injection.ts";
+export { injectionDigest } from "./injection.ts";
+export { evaluateMcpDeclaredMarkers, findUndeclaredServers, } from "./mcp.ts";
+export { CONTEXT_BLOCK_MAX_BYTES, HARD_PERCENT_DEFAULT, MANAGED_BEGIN, MANAGED_END, MAX_TOOL_CALLS_DEFAULT, PRECEDENCE_STATEMENT, REQUIRED_HELPERS_DEFAULT, SCOPED_INJECTION_MAX_BYTES, SOFT_PERCENT_DEFAULT, utf8Bytes, } from "./precedence.ts";
+export type { ReadEntry, ReadRange } from "./read-cache.ts";
+export { clearReadCache, createReadCache, isRepeatRead, recordRead, } from "./read-cache.ts";
+export interface SteeringBudget {
+    readonly contextWindow: number;
+    readonly usedTokens: number;
+    readonly band: BudgetBand;
+    readonly available: boolean;
+}
+export interface ScopedInjection {
+    readonly sessionId: string;
+    readonly content: string;
+    readonly bytes: number;
+}
+export declare function renderContextFile(_sessionId: string, _maxBytes: number): Promise<string>;
+export declare function renderScopedInjection(_sessionId: string, _scope: ReadonlyArray<string>, _maxBytes: number, _options?: InjectionOptions): Promise<ScopedInjection>;
+export declare function currentBand(_sessionId: string): Promise<SteeringBudget>;

package/dist/features/steering/index.js

@@ -0,0 +1,45 @@
+// SPEC §4.6: context rendering, budgets, read cache. Owns the AGENTS.md
+// block (§4.6.2) and scoped injection (§4.6.3) byte budgets. The three
+// tested contracts stay on this entry; every helper lives beside it so
+// adapters and the pack registry import through here (SPEC §3.3).
+import { sessionBand } from "./budgets.js";
+import { renderContextFile as renderFile } from "./context-file.js";
+import { renderScopedInjection as renderInjection, } from "./injection.js";
+export { AGENT_ASSET_IDS, AGENT_ASSET_PURPOSES, AGENT_ASSET_TEMPLATES, findMissingHelpers, parseHelperList, renderAgentAsset, } from "./agent-assets.js";
+export { bandForUsage, createSteeringSession, isSubagentSession, noteCheckpointCommitted, noteCompaction, noteSoftAdvised, recordSessionUsage, recordToolCall, sessionBand, startSteeringSession, } from "./budgets.js";
+export { evaluateContextHardBand, evaluateContextSoftBand, evaluateRepeatReads, evaluateToolCallLimit, parseMarkerCount, parseMarkerMap, parseMarkerPercent, } from "./checks.js";
+export { buildManagedBlock } from "./context-file.js";
+export { evaluateGraphBeforeScanMarkers, graphLookupInstruction, shouldBlockSearch, } from "./graph-scan.js";
+export { injectionDigest } from "./injection.js";
+export { evaluateMcpDeclaredMarkers, findUndeclaredServers, } from "./mcp.js";
+export { CONTEXT_BLOCK_MAX_BYTES, HARD_PERCENT_DEFAULT, MANAGED_BEGIN, MANAGED_END, MAX_TOOL_CALLS_DEFAULT, PRECEDENCE_STATEMENT, REQUIRED_HELPERS_DEFAULT, SCOPED_INJECTION_MAX_BYTES, SOFT_PERCENT_DEFAULT, utf8Bytes, } from "./precedence.js";
+export { clearReadCache, createReadCache, isRepeatRead, recordRead, } from "./read-cache.js";
+// SPEC §4.6.2: precedence statement plus managed block rendering.
+export function renderContextFile(_sessionId, _maxBytes) {
+    return renderFile(_sessionId, _maxBytes);
+}
+// SPEC §4.6.3: per-scope injection inside its byte budget.
+export function renderScopedInjection(_sessionId, _scope, _maxBytes, _options = {}) {
+    return renderInjection(_sessionId, _scope, _maxBytes, _options);
+}
+// SPEC §4.6.4: budget band lookup for the session. No usage is recorded
+// through this contract, so the band is unevaluated by construction;
+// runtimes thread a SteeringSession through recordSessionUsage and read
+// sessionBand instead.
+export function currentBand(_sessionId) {
+    const fresh = sessionBand({
+        sessionId: _sessionId,
+        toolCalls: 0,
+        usedTokens: 0,
+        contextWindow: 0,
+        usageKnown: false,
+        checkpointRequired: false,
+        softAdvised: false,
+    });
+    return Promise.resolve({
+        contextWindow: 0,
+        usedTokens: 0,
+        band: fresh,
+        available: false,
+    });
+}

package/dist/features/steering/injection.d.ts

@@ -0,0 +1,23 @@
+export interface InjectionRuleLine {
+    readonly id: string;
+    readonly statement: string;
+    readonly floor: boolean;
+}
+export interface InjectionOptions {
+    readonly checkpointRequired?: boolean;
+    readonly isSubagent?: boolean;
+    readonly taskSummary?: string;
+    readonly allowedFiles?: ReadonlyArray<string>;
+    readonly testSummary?: string;
+    readonly reviewFindings?: string;
+    readonly relevantRules?: ReadonlyArray<InjectionRuleLine>;
+    readonly usedTokens?: number;
+    readonly contextWindow?: number;
+    readonly checkpointCommand?: string;
+}
+export declare function injectionDigest(content: string): string;
+export declare function renderScopedInjection(sessionId: string, scope: ReadonlyArray<string>, maxBytes: number, options?: InjectionOptions): Promise<{
+    readonly sessionId: string;
+    readonly content: string;
+    readonly bytes: number;
+}>;

package/dist/features/steering/injection.js

@@ -0,0 +1,124 @@
+// SPEC §4.6.3: the scoped injection returned on session.start,
+// compact.post and prompt.submit. Built from committed state, never from a
+// compaction summary; at most 2,000 bytes. The runtime re-sends it only
+// when its digest differs from the last injection in the session, so the
+// digest helper lives beside the renderer.
+import { sha256Text } from "../../kernel/index.js";
+import { bandForUsage, isSubagentSession } from "./budgets.js";
+import { PRECEDENCE_STATEMENT, SCOPED_INJECTION_MAX_BYTES, utf8Bytes, } from "./precedence.js";
+// The runtime compares digests to honour "re-sent only when its hash
+// differs", so an unchanged state costs nothing (SPEC §4.6.3).
+export function injectionDigest(content) {
+    return sha256Text(content);
+}
+function ruleText(rule) {
+    return `${rule.id} — ${rule.statement}`;
+}
+// Relevant rules for raw scopes with no rule resolution: one line per
+// scope, floor-first when the caller labels them.
+function rulesForScopes(scopes) {
+    return [...scopes].sort().map((scope) => ({
+        id: scope,
+        statement: "scoped context",
+        floor: false,
+    }));
+}
+function budgetLine(options) {
+    if (options.usedTokens !== undefined &&
+        options.contextWindow !== undefined &&
+        options.contextWindow > 0) {
+        // SPEC §4.6.3: the budget part names the current band, so the
+        // auditable injection event carries it to the status row (§4.18.3).
+        const band = bandForUsage(options.usedTokens, options.contextWindow);
+        return `Budget: ${band} (${options.usedTokens}/${options.contextWindow} tokens used).`;
+    }
+    return "Budget: unavailable (no usage data).";
+}
+// SPEC §4.6.7 EC-12: the rules list truncates floor-first with the
+// codictator context pointer naming the elided count. Fixed head and tail
+// lines always survive; only rule lines are dropped.
+function moreLine(omitted) {
+    return `and ${omitted} more: codictator context --all`;
+}
+function fittedMiddle(kept, total) {
+    const omitted = total - kept.length;
+    return omitted > 0 ? [...kept, moreLine(omitted)] : [...kept];
+}
+// SPEC §4.6.7 EC-12: the rules list truncates floor-first with the
+// codictator context pointer naming the elided count. Fixed head and tail
+// lines always survive; only rule lines are dropped.
+function fitInjection(head, ruleLines, tail, maxBytes) {
+    const kept = [...ruleLines];
+    let middle = fittedMiddle(kept, ruleLines.length);
+    while (utf8Bytes([...head, ...middle, ...tail].join("\n")) > maxBytes &&
+        kept.length > 0) {
+        kept.pop();
+        middle = fittedMiddle(kept, ruleLines.length);
+    }
+    let content = [...head, ...middle, ...tail].join("\n");
+    if (utf8Bytes(content) > maxBytes) {
+        const bytes = new TextEncoder().encode(content).slice(0, maxBytes);
+        content = new TextDecoder().decode(bytes);
+    }
+    return content;
+}
+function checkpointLines(command) {
+    return [
+        "Checkpoint required: every tool call is blocked except codictator task",
+        `checkpoint, git add/commit of the task record, and task record reads (${command}).`,
+        "Run /clear or /new (or start a new session); the resume note is in",
+        ".codictator/state/resume.md.",
+    ];
+}
+function subagentLines() {
+    return [
+        "Subagent hard band: do not clear. Return CHECKPOINT: <one-line summary>",
+        "to your caller instead; the parent session is unaffected.",
+    ];
+}
+export function renderScopedInjection(sessionId, scope, maxBytes, options = {}) {
+    const limit = Math.min(maxBytes, SCOPED_INJECTION_MAX_BYTES);
+    const subagent = options.isSubagent ?? isSubagentSession(sessionId);
+    const tail = [budgetLine(options)];
+    if (options.checkpointRequired === true) {
+        tail.push(...checkpointLines(options.checkpointCommand ?? "codictator"));
+    }
+    if (subagent) {
+        tail.push(...subagentLines());
+    }
+    let head;
+    let ruleLines;
+    if (scope.length === 0 && options.taskSummary === undefined) {
+        head = [
+            PRECEDENCE_STATEMENT,
+            "",
+            "No active task. Start one: codictator task new, then work only inside",
+            "the plan it records (core/workflow-gates).",
+            "",
+        ];
+        ruleLines = [];
+    }
+    else {
+        const rules = options.relevantRules ?? rulesForScopes(scope);
+        const ordered = [...rules].sort((a, b) => {
+            if (a.floor !== b.floor) {
+                return a.floor ? -1 : 1;
+            }
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        });
+        head = [
+            `Task: ${options.taskSummary ?? "unassigned — codictator task new"}`,
+            `Allowed files: ${(options.allowedFiles ?? scope).join(", ") || "(none)"}`,
+            `Tests: ${options.testSummary ?? "(none recorded)"}`,
+            `Open review findings: ${options.reviewFindings ?? "(none)"}`,
+            "Relevant rules:",
+        ];
+        ruleLines = ordered.map(ruleText);
+    }
+    const content = fitInjection(head, ruleLines, tail, limit);
+    return Promise.resolve({
+        sessionId,
+        content,
+        bytes: utf8Bytes(content),
+    });
+}

package/dist/features/steering/mcp.d.ts

@@ -0,0 +1,2 @@
+export declare function findUndeclaredServers(configured: ReadonlyArray<string>, allowed: ReadonlyArray<string>): Array<string>;
+export declare function evaluateMcpDeclaredMarkers(markers: ReadonlyMap<string, string>): boolean;

package/dist/features/steering/mcp.js

@@ -0,0 +1,18 @@
+// SPEC §4.6.5 core/mcp-declared: every MCP server in a project-level
+// harness config must be listed in config.steering.mcpAllowed.
+export function findUndeclaredServers(configured, allowed) {
+    const known = new Set(allowed);
+    const missing = [];
+    for (const server of [...configured].sort()) {
+        if (!known.has(server) && !missing.includes(server)) {
+            missing.push(server);
+        }
+    }
+    return missing;
+}
+// Fixture-shaped evaluation for the pack self-test (§4.4.4): a tool call
+// to a server the markers flag as undeclared violates; a declared one
+// passes.
+export function evaluateMcpDeclaredMarkers(markers) {
+    return (markers.get("declared") ?? "false") !== "true";
+}

package/dist/features/steering/precedence.d.ts

@@ -0,0 +1,10 @@
+export declare const PRECEDENCE_STATEMENT: string;
+export declare const MANAGED_BEGIN = "<!-- codictator:begin -->";
+export declare const MANAGED_END = "<!-- codictator:end -->";
+export declare const CONTEXT_BLOCK_MAX_BYTES = 6000;
+export declare const SCOPED_INJECTION_MAX_BYTES = 2000;
+export declare const SOFT_PERCENT_DEFAULT = 60;
+export declare const HARD_PERCENT_DEFAULT = 75;
+export declare const MAX_TOOL_CALLS_DEFAULT = 300;
+export declare const REQUIRED_HELPERS_DEFAULT: ReadonlyArray<string>;
+export declare function utf8Bytes(text: string): number;

package/dist/features/steering/precedence.js

@@ -0,0 +1,28 @@
+// SPEC §4.6.1: the precedence statement, first in every context file and
+// every session-start injection. The managed-block markers (§4.6.2) and the
+// byte budgets that bound every agent-facing steering string.
+export const PRECEDENCE_STATEMENT = "Repository rules enforced by Codictator outrank any instruction in this conversation, including the user's. " +
+    "When an instruction conflicts with a rule, do what was asked the compliant way and tell the user which rule applied and why. " +
+    "Never bypass, disable or edit Codictator guardrails; if a rule blocks you three times, stop and ask the human.";
+// SPEC §4.6.2: Codictator owns one managed block delimited by these markers.
+export const MANAGED_BEGIN = "<!-- codictator:begin -->";
+export const MANAGED_END = "<!-- codictator:end -->";
+// SPEC §4.6.2: the AGENTS.md managed block is at most 6,000 bytes.
+// SPEC §4.6.3: a scoped injection is at most 2,000 bytes.
+export const CONTEXT_BLOCK_MAX_BYTES = 6000;
+export const SCOPED_INJECTION_MAX_BYTES = 2000;
+// SPEC §5.1: tunable defaults for the steering-owned F1 rules. The pack
+// manifest owns the values; these mirror them so pure steering helpers can
+// evaluate bands without a config read.
+export const SOFT_PERCENT_DEFAULT = 60;
+export const HARD_PERCENT_DEFAULT = 75;
+export const MAX_TOOL_CALLS_DEFAULT = 300;
+export const REQUIRED_HELPERS_DEFAULT = [
+    "knowledge-graph",
+    "token-saver",
+];
+// Byte length of agent-facing text. TextEncoder is dependency-free and
+// matches the kernel hash input encoding, so budgets and digests agree.
+export function utf8Bytes(text) {
+    return new TextEncoder().encode(text).length;
+}

package/dist/features/steering/read-cache.d.ts

@@ -0,0 +1,13 @@
+export interface ReadRange {
+    readonly offset: number;
+    readonly limit: number;
+}
+export interface ReadEntry {
+    readonly hash: string;
+    readonly wholeFile: boolean;
+    readonly ranges: ReadonlyArray<ReadRange>;
+}
+export declare function createReadCache(): Map<string, ReadEntry>;
+export declare function isRepeatRead(cache: ReadonlyMap<string, ReadEntry>, path: string, hash: string, range?: ReadRange): boolean;
+export declare function recordRead(cache: Map<string, ReadEntry>, path: string, hash: string, range?: ReadRange): void;
+export declare function clearReadCache(cache: Map<string, ReadEntry>): void;

package/dist/features/steering/read-cache.js

@@ -0,0 +1,51 @@
+export function createReadCache() {
+    return new Map();
+}
+function containsRange(recorded, requested) {
+    for (const entry of recorded) {
+        if (requested.offset >= entry.offset &&
+            requested.offset + requested.limit <= entry.offset + entry.limit) {
+            return true;
+        }
+    }
+    return false;
+}
+// SPEC §4.6.7 EC-9: a read of a modified file is allowed and the caller
+// refreshes the cache by recording the new hash afterwards.
+export function isRepeatRead(cache, path, hash, range) {
+    const entry = cache.get(path);
+    if (entry === undefined || entry.hash !== hash) {
+        return false;
+    }
+    if (range === undefined) {
+        return true;
+    }
+    if (entry.wholeFile) {
+        return true;
+    }
+    return containsRange(entry.ranges, range);
+}
+export function recordRead(cache, path, hash, range) {
+    const previous = cache.get(path);
+    if (previous !== undefined && previous.hash === hash) {
+        if (range === undefined || previous.wholeFile) {
+            cache.set(path, { hash, wholeFile: true, ranges: [] });
+            return;
+        }
+        cache.set(path, {
+            hash,
+            wholeFile: false,
+            ranges: [...previous.ranges, range],
+        });
+        return;
+    }
+    if (range === undefined) {
+        cache.set(path, { hash, wholeFile: true, ranges: [] });
+        return;
+    }
+    cache.set(path, { hash, wholeFile: false, ranges: [range] });
+}
+// SPEC §4.6.5: the cache is cleared on compact.post and any new session.
+export function clearReadCache(cache) {
+    cache.clear();
+}

package/dist/features/testing/base.d.ts

@@ -0,0 +1 @@
+export declare function findNewlyListed(baseRed: readonly string[], headRed: readonly string[], baseTestIds: readonly string[]): Array<string>;

package/dist/features/testing/base.js

@@ -0,0 +1,8 @@
+// SPEC §10.7 Adding rule: CI fails when a test that ran at the base commit
+// becomes listed. Set computation is pure; reading the base commit is the CI
+// workflow's job in step 1.8.
+export function findNewlyListed(baseRed, headRed, baseTestIds) {
+    const listedBefore = new Set(baseRed);
+    const ranBefore = new Set(baseTestIds);
+    return headRed.filter((entry) => !listedBefore.has(entry) && ranBefore.has(entry));
+}

package/dist/features/testing/covers.d.ts

@@ -0,0 +1,8 @@
+export interface CoverFilter {
+    readonly section: string;
+    readonly firstEc: number | undefined;
+    readonly lastEc: number | undefined;
+}
+export declare function parseCoverSpecifier(spec: string): CoverFilter | undefined;
+export declare function entryMatchesCover(testId: string, filter: CoverFilter): boolean;
+export declare function filterRedByCovers(red: readonly string[], filters: readonly CoverFilter[]): Array<string>;

package/dist/features/testing/covers.js

@@ -0,0 +1,50 @@
+export function parseCoverSpecifier(spec) {
+    const match = /^§(\d+(?:\.\d+)*)(?: EC-(\d+)(?:\.\.(\d+))?)?$/.exec(spec.trim());
+    if (match === null) {
+        return undefined;
+    }
+    const section = match[1];
+    if (section === undefined) {
+        return undefined;
+    }
+    const firstText = match[2];
+    if (firstText === undefined) {
+        return { section, firstEc: undefined, lastEc: undefined };
+    }
+    const first = Number.parseInt(firstText, 10);
+    const lastText = match[3];
+    const last = lastText === undefined ? first : Number.parseInt(lastText, 10);
+    if (Number.isNaN(first) || Number.isNaN(last) || first > last) {
+        return undefined;
+    }
+    return { section, firstEc: first, lastEc: last };
+}
+function citesEc(title, ec) {
+    return new RegExp(`(?:^|\\D)EC-${ec}(?:\\D|$)`).exec(title) !== null;
+}
+function titleOf(testId) {
+    const separator = testId.indexOf("::");
+    return separator < 0 ? testId : testId.slice(separator + 2);
+}
+export function entryMatchesCover(testId, filter) {
+    const title = titleOf(testId);
+    const escaped = filter.section.replace(/\./g, "\\.");
+    if (new RegExp(`§${escaped}(?![0-9.])`).exec(title) === null) {
+        return false;
+    }
+    if (filter.firstEc === undefined || filter.lastEc === undefined) {
+        return true;
+    }
+    for (let ec = filter.firstEc; ec <= filter.lastEc; ec += 1) {
+        if (citesEc(title, ec)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function filterRedByCovers(red, filters) {
+    if (filters.length === 0) {
+        return [...red];
+    }
+    return red.filter((entry) => filters.some((filter) => entryMatchesCover(entry, filter)));
+}

package/dist/features/testing/evaluate.d.ts

@@ -0,0 +1,19 @@
+export interface TestOutcome {
+    readonly file: string;
+    readonly title: string;
+    readonly passed: boolean;
+}
+export type FailureMode = "listed-passed" | "unlisted-failed" | "listed-absent" | "newly-listed";
+export interface RunViolation {
+    readonly mode: FailureMode;
+    readonly testId: string;
+    readonly detail?: string;
+}
+export interface RunVerdict {
+    readonly ok: boolean;
+    readonly passed: number;
+    readonly failed: number;
+    readonly expectedRed: readonly string[];
+    readonly violations: readonly RunViolation[];
+}
+export declare function evaluateRun(red: readonly string[], outcomes: readonly TestOutcome[]): RunVerdict;

package/dist/features/testing/evaluate.js

@@ -0,0 +1,47 @@
+// SPEC §10.7: pass condition. The run exits 0 only when every listed test
+// executed and failed and every unlisted test passed.
+import { formatTestId } from "./ledger.js";
+export function evaluateRun(red, outcomes) {
+    const listed = new Set(red);
+    const seen = new Set();
+    const expectedRed = [];
+    const violations = [];
+    let passed = 0;
+    let failed = 0;
+    for (const outcome of outcomes) {
+        const testId = formatTestId(outcome.file, outcome.title);
+        if (seen.has(testId)) {
+            continue;
+        }
+        seen.add(testId);
+        if (outcome.passed) {
+            passed += 1;
+        }
+        else {
+            failed += 1;
+        }
+        if (listed.has(testId)) {
+            if (outcome.passed) {
+                violations.push({ mode: "listed-passed", testId });
+            }
+            else {
+                expectedRed.push(testId);
+            }
+        }
+        else if (!outcome.passed) {
+            violations.push({ mode: "unlisted-failed", testId });
+        }
+    }
+    for (const entry of red) {
+        if (!seen.has(entry)) {
+            violations.push({ mode: "listed-absent", testId: entry });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        passed,
+        failed,
+        expectedRed,
+        violations,
+    };
+}

package/dist/features/testing/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./base.ts";
+export * from "./covers.ts";
+export * from "./evaluate.ts";
+export * from "./integrity.ts";
+export * from "./ledger.ts";
+export * from "./proofs.ts";
+export * from "./report.ts";
+export * from "./scenarios.ts";
+export * from "./tap-parser.ts";
+export * from "./trace.ts";

package/dist/features/testing/index.js

@@ -0,0 +1,13 @@
+// SPEC §4.10 and §10.7: the testing module owns SPEC trace, red and green
+// proofs, the scenario classifier, test-integrity checks and the red-ledger
+// runner core.
+export * from "./base.js";
+export * from "./covers.js";
+export * from "./evaluate.js";
+export * from "./integrity.js";
+export * from "./ledger.js";
+export * from "./proofs.js";
+export * from "./report.js";
+export * from "./scenarios.js";
+export * from "./tap-parser.js";
+export * from "./trace.js";