@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/domains/resources/skills/lexical-match.ts

@@ -0,0 +1,136 @@
+/**
+ * Local lexical matching over skill text. No model call, no network, and no
+ * request text ever leaves the process.
+ *
+ * Two callers with two different error costs share this vocabulary.
+ * `promotion.ts` scores an *unsolicited* install offer, where a false positive
+ * costs operator trust, so it keeps its own conservative thresholds on top of
+ * these helpers. The catalog view filters a listing the model explicitly asked
+ * to narrow, where the expensive error is the opposite one: a skill the
+ * operator named that the filter silently hides. {@link lexicalMatches} is
+ * tuned for that second case and is not a promotion matcher.
+ */
+
+/**
+ * Words too common in a coding request to distinguish one skill from another.
+ * Shared so both matchers agree about what carries no signal.
+ */
+export const TOKEN_STOPWORDS = new Set([
+	"the",
+	"a",
+	"an",
+	"and",
+	"or",
+	"for",
+	"with",
+	"this",
+	"that",
+	"when",
+	"what",
+	"how",
+	"into",
+	"from",
+	"use",
+	"used",
+	"using",
+	"one",
+	"not",
+	"skill",
+	"skills",
+	"clio",
+	"please",
+	"can",
+	"you",
+	"should",
+	"would",
+	"about",
+	"need",
+	"want",
+	"help",
+	"make",
+	"file",
+	"files",
+	"code",
+]);
+
+/** Lowercase, punctuation to spaces, whitespace collapsed. */
+export function normalize(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s]/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Distinctive tokens: 4+ chars and outside the stopword set.
+ *
+ * The 4-character floor belongs to the promotion matcher, which fires an offer
+ * nobody asked for and must not do so on `tdd` appearing in a sentence. The
+ * catalog filter deliberately does not use this.
+ */
+export function distinctiveTokens(text: string): Set<string> {
+	return new Set(
+		normalize(text)
+			.split(" ")
+			.filter((token) => token.length >= 4 && !TOKEN_STOPWORDS.has(token)),
+	);
+}
+
+/** How many of a multi-word query's tokens a row has to carry. */
+export type LexicalMatchMode = "all" | "any";
+
+/** Query tokens worth matching on: 2+ chars, outside the stopword set. */
+function queryTokens(normalizedQuery: string): string[] {
+	return normalizedQuery.split(" ").filter((token) => token.length >= 2 && !TOKEN_STOPWORDS.has(token));
+}
+
+/**
+ * A token matches a word outright, or as its prefix once it is 3+ characters.
+ *
+ * Prefix matching is what makes `conflict` find `resolve-merge-conflicts` and
+ * `worktree` find `worktree-create`. It is floored at 3 characters so a
+ * two-letter token cannot match most of the catalog.
+ */
+function wordMatches(words: ReadonlySet<string>, token: string): boolean {
+	if (words.has(token)) return true;
+	if (token.length < 3) return false;
+	for (const word of words) {
+		if (word.startsWith(token)) return true;
+	}
+	return false;
+}
+
+/**
+ * Does `haystack` match `query`?
+ *
+ * An empty query matches everything, so a caller can pass the operator's
+ * argument through without branching.
+ *
+ * The whole query matching as a word sequence always wins, which is how a name
+ * shorter than the token floor (`tdd`, `prd`) stays findable by typing it. The
+ * sequence is matched with word boundaries on both ends, so `git` does not hit
+ * `digital`.
+ *
+ * Failing that, the query is tokenized and matched per token. `mode` decides
+ * whether every token must land or any one of them may: the catalog view tries
+ * `all` first and only falls back to `any` when that returned nothing, so a
+ * precise query narrows and a conversational one still finds something instead
+ * of an empty page.
+ */
+export function lexicalMatches(query: string, haystack: string, mode: LexicalMatchMode = "all"): boolean {
+	// Canonical composition on both sides, so a decomposed `café` typed by
+	// one editor matches a composed `café` written by another. Applied here
+	// rather than inside `normalize`, because `normalize` is also the promotion
+	// matcher's and changing what that fires on is a separate decision.
+	const normalizedQuery = normalize(query.normalize("NFC"));
+	if (normalizedQuery.length === 0) return true;
+	const normalizedHaystack = normalize(haystack.normalize("NFC"));
+	if (` ${normalizedHaystack} `.includes(` ${normalizedQuery} `)) return true;
+	const tokens = queryTokens(normalizedQuery);
+	if (tokens.length === 0) return false;
+	const words = new Set(normalizedHaystack.split(" ").filter((word) => word.length > 0));
+	return mode === "all"
+		? tokens.every((token) => wordMatches(words, token))
+		: tokens.some((token) => wordMatches(words, token));
+}

package/src/domains/resources/skills/loader.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { type Dirent, existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { CLIO_SELF_DEVELOPMENT_SKILLS, detectClioCoderRepo } from "../../../core/clio-repo.js";
 import { warnLegacyNaming } from "../../../core/naming-compat.js";
 import type { PendingSkillRequest } from "../../../core/skill-activation.js";
 import { type ToolName, ToolNames } from "../../../core/tool-names.js";
@@ -145,6 +146,8 @@ export interface SkillRoot {
 	 * package roots use the package directory as their containment boundary.
 	 */
 	containment?: string;
+	/** Repository-provided roots cannot relocate their containment through a symlink. */
+	strictContainment?: boolean;
 }
 
 export interface SkillList {
@@ -242,6 +245,40 @@ export function defaultSkillRoots(input: LoadSkillsInput = {}): SkillRoot[] {
 	const trustProject = projectCompatTrusted(input.trustProjectCompatRoots);
 	const roots: SkillRoot[] = [];
 
+	// Source-checkout guidance is a narrow native discovery tier, not a package
+	// installation. An installed package owns its name even when disabled,
+	// damaged, or awaiting reload; never resurrect it through a source fallback.
+	const selfRepo = detectClioCoderRepo(cwd).repoRoot;
+	if (selfRepo) {
+		const ownedNames = installedSkillNames([], cwd);
+		if (path.resolve(cwd) !== selfRepo) {
+			for (const name of installedSkillNames([], selfRepo)) ownedNames.add(name);
+			// Native skills can be flat Markdown files or directories whose
+			// frontmatter name differs from the path. Use the loader's names so
+			// a descendant launch cannot resurrect a hidden root override.
+			const rootOverrides = loadSkillRoot(
+				{ path: path.join(selfRepo, ".clio-coder", "skills"), scope: "project", containment: selfRepo },
+				[],
+			);
+			for (const candidate of rootOverrides) ownedNames.add(candidate.skill.name);
+		}
+		for (const name of CLIO_SELF_DEVELOPMENT_SKILLS) {
+			if (ownedNames.has(name)) continue;
+			const skillPath = path.join(selfRepo, "library", "skills", "meta", name);
+			if (!existsSync(path.join(skillPath, "SKILL.md"))) continue;
+			roots.push({
+				path: skillPath,
+				scope: "project",
+				source: "clio-coder",
+				origin: "self-development",
+				precedence: SKILL_PRECEDENCE.package - 1,
+				trusted: true,
+				containment: selfRepo,
+				strictContainment: true,
+			});
+		}
+	}
+
 	for (const root of enabledPluginResourceRoots("skills", cwd)) {
 		roots.push({
 			path: root.path,
@@ -560,6 +597,7 @@ function pathIsInside(candidate: string, anchor: string): boolean {
 function containmentAnchor(root: SkillRoot): string | null {
 	if (root.containment === undefined) return null;
 	const anchor = canonicalizePath(root.containment);
+	if (root.strictContainment) return anchor;
 	const rootReal = canonicalizePath(root.path);
 	return pathIsInside(rootReal, anchor) ? anchor : rootReal;
 }

package/src/domains/resources/skills/promotion.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { safeResourceWrite } from "../../../core/safe-resource-write.js";
 import { clioConfigDir } from "../../../core/xdg.js";
+import { distinctiveTokens, normalize } from "./lexical-match.js";
 import type { MarketplaceSkill } from "./marketplace.js";
 
 /**
@@ -26,61 +27,6 @@ export interface PromotionMatch {
 	matchedTrigger?: string;
 }
 
-const TOKEN_STOPWORDS = new Set([
-	"the",
-	"a",
-	"an",
-	"and",
-	"or",
-	"for",
-	"with",
-	"this",
-	"that",
-	"when",
-	"what",
-	"how",
-	"into",
-	"from",
-	"use",
-	"used",
-	"using",
-	"one",
-	"not",
-	"skill",
-	"skills",
-	"clio",
-	"please",
-	"can",
-	"you",
-	"should",
-	"would",
-	"about",
-	"need",
-	"want",
-	"help",
-	"make",
-	"file",
-	"files",
-	"code",
-]);
-
-function normalize(text: string): string {
-	return text
-		.toLowerCase()
-		.replace(/[^\p{L}\p{N}\s]/gu, " ")
-		.replace(/\s+/g, " ")
-		.trim();
-}
-
-/** Distinctive tokens: 4+ chars and outside the stopword set. */
-function distinctiveTokens(text: string): Set<string> {
-	return new Set(
-		normalize(text)
-			.split(" ")
-			.filter((token) => token.length >= 4 && !TOKEN_STOPWORDS.has(token)),
-	);
-}
-
 const TRIGGER_SCORE = 4;
 /** Distinct description/name token overlaps required to fire without a trigger. */
 const TOKEN_FIRE_THRESHOLD = 3;

package/src/domains/resources/skills/provenance-pin.ts

@@ -101,28 +101,58 @@ export interface SkillDriftReport {
  * means nothing recorded a hash for this skill; drift evidence is opt-in and
  * never a gate, and skills still pass the normal tool safety gates either way.
  */
-export function checkSkillDrift(
-	skill: { name: string; normalizedHash: string; provenance?: { installedHash?: string } },
+export function checkSkillDrift(skill: SkillDriftSubject, cwd: string): SkillDriftReport | null {
+	return checkSkillDriftBatch([skill], cwd).get(skill.name) ?? null;
+}
+
+/** The fields a drift comparison reads. Structural, so any loaded skill satisfies it. */
+export interface SkillDriftSubject {
+	name: string;
+	normalizedHash: string;
+	provenance?: { installedHash?: string };
+}
+
+/**
+ * The same comparison for many skills, resolving and parsing the pin manifest
+ * once.
+ *
+ * Activation checks one skill and can afford to re-read the manifest each time.
+ * A listing checks every row, and doing that through the single-skill entry
+ * point would re-stat up to four candidate paths and re-parse the YAML once per
+ * skill. {@link checkSkillDrift} is the single-skill case of this function
+ * rather than a parallel implementation, so the listing and the activation can
+ * never disagree about a verdict.
+ *
+ * Skills with nothing recorded for them are absent from the map rather than
+ * present with a null: an entry means a comparison happened.
+ */
+export function checkSkillDriftBatch(
+	skills: ReadonlyArray<SkillDriftSubject>,
 	cwd: string,
-): SkillDriftReport | null {
-	const actual = skill.normalizedHash.toLowerCase();
+): Map<string, SkillDriftReport> {
+	const reports = new Map<string, SkillDriftReport>();
+	if (skills.length === 0) return reports;
 	const manifestPath = resolveSkillPinManifestPath(cwd);
 	const manifest = manifestPath === null ? null : loadSkillPinManifest(manifestPath);
-	const pinned = manifest?.get(skill.name);
-	if (pinned !== undefined) {
-		return {
-			verdict: pinned.sha256 === actual ? "match" : "mismatch",
-			authority: "pinned-manifest",
-			expected: pinned.sha256,
-		};
+	for (const skill of skills) {
+		const actual = skill.normalizedHash.toLowerCase();
+		const pinned = manifest?.get(skill.name);
+		if (pinned !== undefined) {
+			reports.set(skill.name, {
+				verdict: pinned.sha256 === actual ? "match" : "mismatch",
+				authority: "pinned-manifest",
+				expected: pinned.sha256,
+			});
+			continue;
+		}
+		const recorded = skill.provenance?.installedHash?.trim().toLowerCase();
+		if (recorded !== undefined && /^[0-9a-f]{64}$/.test(recorded)) {
+			reports.set(skill.name, {
+				verdict: recorded === actual ? "match" : "mismatch",
+				authority: "install-record",
+				expected: recorded,
+			});
+		}
 	}
-	const recorded = skill.provenance?.installedHash?.trim().toLowerCase();
-	if (recorded !== undefined && /^[0-9a-f]{64}$/.test(recorded)) {
-		return {
-			verdict: recorded === actual ? "match" : "mismatch",
-			authority: "install-record",
-			expected: recorded,
-		};
-	}
-	return null;
+	return reports;
 }

package/src/domains/safety/action-classifier.ts

@@ -98,6 +98,7 @@ function baseClassify(tool: string): ActionClass | null {
 		case ToolNames.WebFetch:
 		case ToolNames.Git:
 		case ToolNames.CodeNav:
+		case ToolNames.SelfCompact:
 		case ToolNames.Context:
 		// clio_docs and clio_library read Clio's bundled documentation and the
 		// recipe catalog; data streams structured files. None writes.

package/src/domains/session/compaction/branch-summary.ts

@@ -185,7 +185,10 @@ export function serializeConversation(entries: ReadonlyArray<SessionEntry>): str
 		}
 		// custom, modelChange, thinkingLevelChange, fileEntry, sessionInfo,
 		// protectedArtifact, taskLedger, decisionLedger, and workerRun do not
-		// project into the serialized conversation.
+		// project into the serialized conversation. Neither do handoffTransaction
+		// and continuityCommit: this is an allowlist, so transaction JSON can
+		// never reach the summarization prompt as if it were conversation, and
+		// the accepted note is never regenerated from summarizer prose.
 	}
 	return parts.join("\n\n");
 }

package/src/domains/session/compaction/compact.ts

@@ -1,3 +1,4 @@
+import type { ContinuityCheckpointPayload } from "../continuity/contract.js";
 /**
  * Compaction orchestration.
  *
@@ -30,7 +31,7 @@ import {
 import { serializeConversation } from "./branch-summary.js";
 import { findCutPoint } from "./cut-point.js";
 import { DEFAULT_KEEP_RECENT_TOKENS, DEFAULT_RESERVE_TOKENS } from "./defaults.js";
-import { calculateContextTokens, getLastAssistantUsage } from "./tokens.js";
+import { type ContinuityNoteCost, calculateContextTokens, getLastAssistantUsage } from "./tokens.js";
 
 interface FileOperations {
 	read: Set<string>;
@@ -144,6 +145,11 @@ export interface CompactionCallObservation {
 }
 
 export interface CompactInput {
+	/** Synchronous admission after exact request-fit, before each provider call. */
+	beforeSummaryCall?: (() => void) | undefined;
+	checkpointForSummary?:
+		| ((summaryRef: string, tokensBefore: number, tokensAfter: number) => ContinuityCheckpointPayload)
+		| undefined;
 	/** Ordered active-path session entries to compact; returned cut indexes address this same array. */
 	entries: ReadonlyArray<SessionEntry>;
 	/** Authoritative main-agent selection; omitted for unknown legacy state. */
@@ -175,6 +181,15 @@ export interface CompactInput {
 	preserveUserTurnId?: string;
 	/** Accounting observer; called once per invoked stream, including failures. */
 	onCall?: (call: CompactionCallObservation) => void;
+	/**
+	 * The continuity note replay projects, from `continuityProjectionTokens` and
+	 * the projection's `noteAnchorTurnId`. The note survives the reduction, so it
+	 * is on both sides of the before/after comparison; counting it needs the
+	 * session and fork facts the caller has and this module does not, and the
+	 * anchor id is what keeps it from being counted twice once a provider usage
+	 * anchor already includes it.
+	 */
+	continuityNote?: ContinuityNoteCost;
 }
 
 export interface CompactResult {
@@ -675,6 +690,7 @@ async function runSummaryStream(
 	}
 
 	input.signal?.throwIfAborted();
+	input.beforeSummaryCall?.();
 	const timestamp = new Date().toISOString();
 	const started = performance.now();
 	let usage: unknown;
@@ -804,7 +820,7 @@ export async function compact(input: CompactInput): Promise<CompactResult> {
 	const usageStart = prevCompactionIndex >= 0 ? prevCompactionIndex : 0;
 	const usageEntries = entries.slice(usageStart);
 	const lastUsage = getLastAssistantUsage(usageEntries);
-	const tokensBefore = calculateContextTokens(usageEntries, lastUsage);
+	const tokensBefore = calculateContextTokens(usageEntries, lastUsage, input.continuityNote);
 	const rawCut = findCutPoint(entries, keepRecentTokens, { startIndex: boundaryStart });
 	const cut =
 		protectedStart !== null && rawCut.firstKeptEntryIndex > protectedStart

package/src/domains/session/compaction/cut-point.ts

@@ -74,6 +74,12 @@ function isValidCutPoint(entry: SessionEntry): boolean {
 		case "workerRun":
 		case "contextEviction":
 		case "contextRecall":
+		// Transaction bookkeeping is not a place the conversation can be sliced.
+		// A cut landing on a handoff record would put the summary boundary in the
+		// middle of a durable transaction, and the records carry no conversation
+		// text for the retained suffix to be about.
+		case "handoffTransaction":
+		case "continuityCommit":
 			return false;
 	}
 }
@@ -193,7 +199,20 @@ export function findCutPoint(
 			prev.kind === "bashExecution" ||
 			prev.kind === "custom" ||
 			prev.kind === "skillActivation" ||
-			prev.kind === "branchSummary"
+			prev.kind === "branchSummary" ||
+			// Stop before a continuity record rather than widening onto it. The
+			// widening exists so bookkeeping rides with the retained suffix, but
+			// the cut index also names `firstKeptTurnId`, which becomes the new
+			// summary's structural parent. Parking that on a transaction record
+			// would anchor the summary to a non-message, and `entryBelongsToPath`
+			// resolves a summary through its anchor: on a branched session the
+			// summary would then be filtered off its own active path. Continuity
+			// records ahead of the cut lose nothing by being on the summarized
+			// side, because `serializeConversation` never projects them into the
+			// prompt and the fold reads the full pre-cut ledger rather than the
+			// replay slice.
+			prev.kind === "handoffTransaction" ||
+			prev.kind === "continuityCommit"
 		) {
 			break;
 		}

package/src/domains/session/compaction/tokens.ts

@@ -13,6 +13,7 @@
 
 import type { Usage } from "../../../engine/types.js";
 import { ceilChars, contentChars, estimateAgentMessageTokens } from "../context-accounting.js";
+import { HANDOFF_RECOVERY_REQUEST_CUSTOM_TYPE } from "../continuity/operator-request.js";
 import type {
 	BashExecutionEntry,
 	BranchSummaryEntry,
@@ -53,6 +54,11 @@ function estimateBashExecution(entry: BashExecutionEntry): number {
 
 function estimateCustom(entry: CustomEntry): number {
 	if (entry.data === undefined) return 0;
+	// The reserved operator recovery request is a control record, not model text.
+	// Model replay skips it by design (it is never turned into a user turn), so
+	// charging its data to the context budget would claim the model can see a
+	// record it is never shown.
+	if (entry.customType === HANDOFF_RECOVERY_REQUEST_CUSTOM_TYPE) return 0;
 	return ceilChars(contentChars(entry.data));
 }
 
@@ -100,6 +106,14 @@ export function estimateTokens(entry: SessionEntry): number {
 		// projection accounts for marker cost on the projected messages.
 		case "contextEviction":
 		case "contextRecall":
+		// Continuity bookkeeping. The transaction chain and the commit payload
+		// are never model text, and a carried payload is a copy of facts the
+		// projection already holds: charging every copy would price one accepted
+		// note three times over three summary cycles. The single rendered note
+		// the projection does emit is priced once, by the caller that resolved
+		// it, through `continuityNoteTokens` on `calculateContextTokens`.
+		case "handoffTransaction":
+		case "continuityCommit":
 			return 0;
 	}
 }
@@ -152,8 +166,27 @@ function findLastAssistantUsageIndex(entries: ReadonlyArray<SessionEntry>): numb
  * accurate for sessions whose most recent assistant turn carried real
  * provider usage data.
  */
-export function calculateContextTokens(entries: ReadonlyArray<SessionEntry>, lastUsage?: Usage): number {
+/**
+ * The continuity note a replay projects, for callers pricing a whole prompt.
+ *
+ * `tokens` comes from `continuityProjectionTokens`, and `anchorTurnId` is the
+ * ledger record that introduced the transaction. Selecting which note gets
+ * projected needs session and fork facts a token estimator does not have, so
+ * the caller resolves it; a second selection rule here would be free to drift
+ * from the fold's.
+ */
+export interface ContinuityNoteCost {
+	tokens: number;
+	anchorTurnId: string | null;
+}
+
+export function calculateContextTokens(
+	entries: ReadonlyArray<SessionEntry>,
+	lastUsage?: Usage,
+	continuityNote?: ContinuityNoteCost,
+): number {
 	const usage = lastUsage ?? getLastAssistantUsage(entries);
+	const noteTokens = continuityNote?.tokens ?? 0;
 	if (usage) {
 		const anchorTokens = usageTotalTokens(usage);
 		const anchorIndex = findLastAssistantUsageIndex(entries);
@@ -162,9 +195,21 @@ export function calculateContextTokens(entries: ReadonlyArray<SessionEntry>, las
 			const entry = entries[i];
 			if (entry) trailing += estimateTokens(entry);
 		}
-		return anchorTokens + trailing;
+		// The anchor is a real provider prompt count. Once a continuation has run
+		// with the note in front of it, that measurement already contains the note,
+		// and adding it again would inflate `tokensBefore` a little more on every
+		// compaction cycle. Only a note introduced *after* the anchored call is new
+		// material. An unlocatable anchor record is treated as new, which
+		// over-counts by one note rather than hiding it.
+		const introducedAt =
+			continuityNote?.anchorTurnId == null
+				? -1
+				: entries.findIndex((entry) => entry.turnId === continuityNote.anchorTurnId);
+		const alreadyMeasured = introducedAt >= 0 && introducedAt <= anchorIndex;
+		return anchorTokens + trailing + (alreadyMeasured ? 0 : noteTokens);
 	}
-	let total = 0;
+	// With no anchor everything is estimated, so the note is always new material.
+	let total = noteTokens;
 	for (const entry of entries) total += estimateTokens(entry);
 	return total;
 }

package/src/domains/session/context-accounting.ts

@@ -14,6 +14,7 @@ export interface AgentContextEstimateInput {
 	messages: ReadonlyArray<AgentMessage>;
 	systemPrompt?: string;
 	pendingUserText?: string;
+	pendingUserImages?: ReadonlyArray<unknown>;
 	tools?: ReadonlyArray<unknown>;
 }
 
@@ -253,7 +254,13 @@ export function estimateAgentContextBreakdown(input: AgentContextEstimateInput):
 			(sum, message) => sum + (message.role === "system" ? 0 : estimateAgentMessageTokens(message)),
 			0,
 		),
-		pendingUserTokens: input.pendingUserText ? ceilChars(input.pendingUserText.length) : 0,
+		pendingUserTokens:
+			input.pendingUserText !== undefined
+				? estimateAgentMessageTokens({
+						role: "user",
+						content: [{ type: "text", text: input.pendingUserText }, ...(input.pendingUserImages ?? [])],
+					})
+				: 0,
 		toolSchemaTokens: (input.tools ?? []).reduce<number>((sum, tool) => sum + ceilChars(toolSchemaChars(tool)), 0),
 	};
 }

package/src/domains/session/continuity/carry.ts

@@ -0,0 +1,59 @@
+/**
+ * Summary carry and missing-commit reconstruction (CONTRACTS.md §3.5, §6).
+ *
+ * A later summary embeds the current validated folded payload: the same
+ * identity, the same agent-authored note, the original policy, the original
+ * commit envelope/outcome/refs and spent attempts, with `state` advanced to the
+ * latest delivery, acknowledgement, pause or explicit resume. It never
+ * manufactures a commit and never turns an eviction-only outcome into a
+ * summarized one.
+ *
+ * Both functions are projections of a validated fold. Neither reads a clock,
+ * mints an id, or writes anything.
+ */
+
+import type { ContinuityCheckpointPayload, ContinuityFoldResult, MissingCommitReconstruction } from "./contract.js";
+import { HANDOFF_SCHEMA_VERSION } from "./contract.js";
+import { isContinuityCheckpointPayload } from "./validate.js";
+
+/**
+ * The payload a summary written now should carry, or null when this fold has
+ * nothing durable to carry.
+ *
+ * A carry requires a commit: before one exists there is no checkpoint to
+ * project, only an in-flight transaction whose own records are the evidence.
+ * The result is validated before being returned, so a fold that produced a
+ * shape this core would refuse to read back cannot be written out.
+ */
+export function continuityPayloadFromFold(fold: ContinuityFoldResult): ContinuityCheckpointPayload | null {
+	// Only a validated fold may be published. This is not the same as execution
+	// authority: a paused or inherited historical transaction is recall-only and
+	// still carries perfectly well, while a chain with conflicting copies or a
+	// malformed record has nothing trustworthy to write forward.
+	if (!fold.validated) return null;
+	if (!fold.identity || !fold.accepted || !fold.policy || !fold.commit || !fold.state) return null;
+	const payload: ContinuityCheckpointPayload = {
+		schemaVersion: HANDOFF_SCHEMA_VERSION,
+		identity: fold.identity,
+		accepted: fold.accepted,
+		policy: fold.policy,
+		commit: fold.commit,
+		state: fold.state,
+	};
+	return isContinuityCheckpointPayload(payload) ? payload : null;
+}
+
+/**
+ * The commit a validated carry proves existed, when this projection does not
+ * contain it.
+ *
+ * The fold has already refused to conclude absence while unreadable records
+ * could hide the commit, so this is a projection of that decision rather than a
+ * second search. The reconstruction reuses the reserved entry id, parent and
+ * timestamp, which is what keeps recovery from minting a second commit
+ * identity, and returns the later carried head separately so restoring it after
+ * the append cannot regress an acknowledgement or a pause to `ready`.
+ */
+export function missingCommitFromCarry(fold: ContinuityFoldResult): MissingCommitReconstruction | null {
+	return fold.validated ? fold.missingCommit : null;
+}