@juicesharp/rpiv-workflow 1.14.0

package/transcript.ts

@@ -0,0 +1,156 @@
+/**
+ * Branch-entry shape + predicates. `sessionManager.getBranch()` returns a
+ * discriminated union from pi-coding-agent whose internal variants aren't
+ * all re-exported; `readBranch(ctx)` is the single boundary that applies
+ * the `as unknown as` cast — every consumer in the workflow module goes
+ * through it.
+ *
+ * No artifact-path scanning lives here — discovery is the collector's
+ * job (see `output-spec.ts:ArtifactCollector`). Collectors that scan the
+ * transcript (`transcriptPathCollector`, `urlCollector`, `toolCallCollector`,
+ * …) walk this shape themselves; `lastMatchInBranch` is the shared
+ * "find the last regex match in assistant text" helper they reuse.
+ */
+
+/** Mirror of pi-ai's StopReason union — values pi attaches to AssistantMessage. */
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+
+/**
+ * Normalised stop signal: `StopReason` plus `"noResponse"` for branches with
+ * no assistant message at all (pi never set a reason because the model never
+ * spoke). Pre-stopReason assistant messages collapse to `"stop"`.
+ */
+export type StopSignal = StopReason | "noResponse";
+
+/** Single chokepoint that maps (hasAssistantMessage, lastAssistantStopReason) → StopSignal. */
+export function classifyStop(branch: BranchEntry[], offsetStart?: number): StopSignal {
+	if (!hasAssistantMessage(branch, offsetStart)) return "noResponse";
+	return lastAssistantStopReason(branch, offsetStart) ?? "stop";
+}
+
+/**
+ * One content part inside an assistant message. Pi's internal union
+ * carries more variants than these two; we model the ones collectors
+ * walk over and let unknown parts pass through structurally (every
+ * field besides `type` is optional).
+ *
+ *   - `text` parts carry user-visible markdown via `text`.
+ *   - `tool_use` parts carry a tool invocation: `name` + `input` (the
+ *     JSON object the agent called the tool with).
+ */
+export type BranchContentPart = {
+	type: string;
+	text?: string;
+	name?: string;
+	input?: Record<string, unknown>;
+};
+
+export type BranchEntry = {
+	type: string;
+	message?: {
+		role?: string;
+		content?: BranchContentPart[];
+		stopReason?: StopReason;
+	};
+};
+
+/**
+ * Read the current branch from `ctx.sessionManager`. SDK returns a discriminated
+ * union with private discriminators; the cast is unavoidable but must live in
+ * one place — calling `getBranch()` directly elsewhere bypasses the module's
+ * type discipline.
+ *
+ * Tracked: when `@earendil-works/pi-coding-agent` exposes a public
+ * `Branch.Entry` (or equivalent) type, switch to it and delete the local
+ * `BranchEntry` narrowing above. Until then this cast is the single
+ * documented coupling point to Pi's internal branch shape.
+ */
+export function readBranch(ctx: { sessionManager: { getBranch(): unknown } }): BranchEntry[] {
+	return ctx.sessionManager.getBranch() as unknown as BranchEntry[];
+}
+
+export function hasAssistantMessage(branch: BranchEntry[], offsetStart?: number): boolean {
+	const start = Math.max(offsetStart ?? 0, 0);
+	for (let i = start; i < branch.length; i++) {
+		const e = branch[i]!;
+		if (e.type === "message" && e.message?.role === "assistant") return true;
+	}
+	return false;
+}
+
+/** Undefined for empty branches or pre-stopReason assistant messages. */
+export function lastAssistantStopReason(branch: BranchEntry[], offsetStart?: number): StopReason | undefined {
+	const start = Math.max(offsetStart ?? 0, 0);
+	for (let i = branch.length - 1; i >= start; i--) {
+		const entry = branch[i]!;
+		if (entry.type !== "message") continue;
+		if (entry.message?.role !== "assistant") continue;
+		return entry.message.stopReason;
+	}
+	return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shared collector building blocks
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan assistant text blocks in reverse for `pattern`; return the last
+ * match. Pure — no I/O. Used by `transcriptPathCollector`, `urlCollector`,
+ * and any author building a transcript-scan collector.
+ *
+ * Reverse scan because the agent's final message is usually where the
+ * actionable path/URL lands; iterating from the tail short-circuits on
+ * the first hit. Thinking/tool_use blocks are ignored — only spoken
+ * `text` parts count.
+ *
+ * `offsetStart` — continue-policy stages pass the prior branch length
+ * so prior-stage entries don't leak into the result.
+ *
+ * The pattern's flags are caller-owned. `g` makes `String.match` return
+ * every occurrence (this helper takes the last); without `g`, only the
+ * first match in each block is considered. Both shapes work.
+ */
+export function lastMatchInBranch(branch: BranchEntry[], pattern: RegExp, offsetStart?: number): string | undefined {
+	const start = Math.max(offsetStart ?? 0, 0);
+	for (let i = branch.length - 1; i >= start; i--) {
+		const entry = branch[i]!;
+		if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+		const content = entry.message.content;
+		if (!Array.isArray(content)) continue;
+		for (let j = content.length - 1; j >= 0; j--) {
+			const part = content[j]!;
+			if (part.type === "text" && typeof part.text === "string") {
+				const matches = part.text.match(pattern);
+				if (matches && matches.length > 0) return matches[matches.length - 1];
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Yield every tool_use part the assistant emitted in branch order
+ * (forward — the typical "what did the agent do during this stage?"
+ * scan direction). Pure — no I/O. `toolCallCollector` walks this to
+ * apply the author's match/toArtifact pair.
+ *
+ * `offsetStart` — continue-policy stages pass the prior branch length.
+ */
+export function* iterToolUses(
+	branch: BranchEntry[],
+	offsetStart?: number,
+): Generator<{ name: string; input: Record<string, unknown> }> {
+	const start = Math.max(offsetStart ?? 0, 0);
+	for (let i = start; i < branch.length; i++) {
+		const entry = branch[i]!;
+		if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+		const content = entry.message.content;
+		if (!Array.isArray(content)) continue;
+		for (const part of content) {
+			if (part.type !== "tool_use") continue;
+			if (typeof part.name !== "string") continue;
+			yield { name: part.name, input: part.input ?? {} };
+		}
+	}
+}

package/triggers.ts

@@ -0,0 +1,27 @@
+/**
+ * Identifies what triggered a workflow run. Recorded in the JSONL
+ * header (`WorkflowHeader.trigger`), threaded into every lifecycle
+ * event (`LifecycleContext.trigger`), and surfaced on past-run
+ * enumeration (`RunSummary.trigger`).
+ *
+ * `/wf` sets `{ kind: "command", name: "wf" }`. Programmatic embedders
+ * default to `{ kind: "programmatic" }`. External trigger sources
+ * (webhook, cron, sibling-extension spawn) set `{ kind: "external",
+ * source, ref? }` so post-hoc readers can filter / route by origin.
+ *
+ * `meta` is an open escape hatch for trigger-specific payload (webhook
+ * headers, cron expression, ticket id). Kept untyped to avoid growing
+ * the union per consumer.
+ *
+ * Concurrency note: Pi is single-active-session. External triggers
+ * (cron, webhook, sibling-extension spawn) MUST gate their own
+ * spawning if a run is already in flight — the runtime does not
+ * enforce a process-wide mutex.
+ */
+export type RunTrigger =
+	| { kind: "command"; name: string; meta?: Record<string, unknown> }
+	| { kind: "programmatic"; source?: string; meta?: Record<string, unknown> }
+	| { kind: "external"; source: string; ref?: string; meta?: Record<string, unknown> };
+
+/** Default when `RunWorkflowOptions.trigger` is omitted. */
+export const DEFAULT_TRIGGER: RunTrigger = { kind: "programmatic" };

package/typebox-adapter.ts

@@ -0,0 +1,48 @@
+/**
+ * Bridge between the TypeBox schemas the built-in workflows author with and
+ * the Standard Schema v1 interface that `validate-output.ts` consumes.
+ *
+ * Why the bridge exists: `StageDef.outputSchema` / `inputSchema` are typed as
+ * `StandardSchemaV1` so users can author with Zod, Valibot, ArkType, or any
+ * other library that implements the `~standard` property. TypeBox v1.1.38
+ * doesn't ship with `~standard` natively (as of this commit); when a future
+ * version does, this adapter can be deleted and built-in.ts can pass
+ * `Type.Object(...)` results directly.
+ *
+ * Validation surface kept intentionally tight: only the runtime + path
+ * shape `validate-output.ts` needs. `expected`/`actual` diagnostic fields from
+ * the legacy TypeBox failure shape become best-effort placeholders, since
+ * Standard Schema's `issues` only carries `message` + `path`.
+ */
+
+import type { Static, TSchema } from "typebox";
+import { Value } from "typebox/value";
+import type { StageSchema } from "./api.js";
+
+/**
+ * Wrap a TypeBox schema to satisfy `StageSchema` (Standard Schema v1). The
+ * returned object is structurally a Standard Schema; downstream code
+ * (`validateOutputData`) consults `~standard.validate` and never sees
+ * the underlying TypeBox value.
+ *
+ * Generic over the input schema `S` so the parsed type (`Static<S>`) flows
+ * through `StageSchema<unknown, Static<S>>` and into the surrounding
+ * `StageDef<TIn, TOut>` — predicate bodies + downstream stage consumers can
+ * read `output.data` with the parsed type instead of `unknown`.
+ */
+export function typeboxSchema<S extends TSchema>(schema: S): StageSchema<unknown, Static<S>> {
+	return {
+		"~standard": {
+			version: 1,
+			vendor: "typebox",
+			validate: (value: unknown) => {
+				if (Value.Check(schema, value)) return { value };
+				const issues = [...Value.Errors(schema, value)].map((err) => ({
+					message: err.message || `${err.keyword} validation failed at ${err.instancePath || "root"}`,
+					path: err.instancePath ? err.instancePath.split("/").filter(Boolean) : undefined,
+				}));
+				return { issues };
+			},
+		},
+	};
+}

package/types.ts

@@ -0,0 +1,237 @@
+/**
+ * Runtime types. Three nouns flow through the workflow runtime:
+ *
+ *  - `RunContext` — per-run carry (cwd, runId, workflow, state, visited,
+ *    continueHost, registeredSkills, maxBackwardJumps). Read by every
+ *    layer; mutated only by the runner.
+ *  - `RunState` — mutable bookkeeping (output, counters, telemetry,
+ *    termination). Read by every layer; mutated by the runner + the audit
+ *    layer. Always read the chain's primary artifact via
+ *    `currentPrimaryArtifact(state)` (internal-utils.ts) — it prefers
+ *    `output.artifacts[0]` and falls back to `fallbackPrimaryArtifact`.
+ *  - `RunnerCtx` — Pi command ctx augmented with idle-await guarantees;
+ *    threaded from `withSession` callbacks down through stage/phase helpers.
+ *
+ * Per-stage / per-phase sessions extend a shared `SessionContext` base
+ * (cwd, runId, state, prompt, skill). The audit layer pins its dependency
+ * on this base structurally via `AuditCtx = Pick<SessionContext, ...>`.
+ *
+ * Lives apart from runner.ts / sessions.ts so both can reference the same
+ * shapes without a runtime import cycle (type-only refs back via this
+ * module are cycle-free).
+ */
+
+import type { StageDef, Workflow } from "./api.js";
+import type { Artifact } from "./handle.js";
+import type { WorkflowContext, WorkflowHost } from "./host.js";
+import type { LifecycleDispatcher } from "./lifecycle.js";
+import type { Output } from "./output.js";
+import type { RunTrigger } from "./triggers.js";
+
+/**
+ * Per-stage runtime ctx. Alias for `WorkflowContext` (the port) —
+ * kept as a domain noun ("the runner's command ctx") so consumers can
+ * read stage/phase code without learning the port name. Identical
+ * shape; rename-only.
+ */
+export type RunnerCtx = WorkflowContext;
+
+/** Mutable per-run bookkeeping threaded through the chain by reference. */
+export interface RunState {
+	// ── Identity ────────────────────────────────────────────────────────
+	/** Frozen — the user's `/wf` argument. */
+	originalInput: string;
+
+	// ── Progress (hot paths — runner reads on every stage) ─────────────
+	/**
+	 * Chain-input artifact — the rolling slot the next stage's prompt
+	 * inherits as input. Updated ONLY by produces stages whose
+	 * collector returned at least one artifact (the first becomes the new
+	 * primary). Side-effect stages (commit, side-effect) record their own
+	 * output but do not touch this slot — preserves the "commit
+	 * inherits the prior chain's artifact" semantic without forcing
+	 * side-effect collectors to re-emit the prior list.
+	 *
+	 * Reads must go through `currentPrimaryArtifact(state)`
+	 * (internal-utils.ts); a direct read here is a hint of a missed
+	 * accessor.
+	 */
+	primaryArtifact: Artifact | undefined;
+	output: Output | undefined;
+	/**
+	 * Named publish registry — `produces` stages APPEND their full `Output`
+	 * envelope onto the slot keyed by `stage.outcome?.name ??
+	 * stage.<record-key>` after each successful run. Slots are arrays so
+	 * iteration history is preserved across backward-jump loops; the
+	 * default read resolves to the most-recent entry (`array.at(-1)`).
+	 * Multiple stages MAY share a slot on purpose — their outputs interleave
+	 * in run order.
+	 *
+	 * Side-effect stages don't write to this slot. The slot is never
+	 * cleared by `terminal()` either: it's an additive history channel
+	 * orthogonal to the rolling `primaryArtifact`.
+	 */
+	named: Record<string, Output[]>;
+	/** Stages whose JSONL row landed on disk. */
+	stagesCompleted: number;
+	/** Most recently allocated stageNumber. Advances on every recordStage call. */
+	lastAllocatedStageNumber: number;
+
+	// ── Telemetry (post-hoc only; not consulted by chain advancement) ──
+	telemetry: {
+		backwardJumps: number;
+		/**
+		 * Routing rows whose JSONL append failed mid-run. The chain advanced
+		 * past them (routing rows are write-only telemetry, not
+		 * reconstruction inputs), but the final result envelope surfaces this
+		 * so post-hoc readers can distinguish "deterministic edge — no row
+		 * written by design" from "decision made — write was dropped." Empty
+		 * in the common case.
+		 */
+		droppedRoutingRows: Array<{ fromStageIndex: number; fromStage: string; decision: string }>;
+	};
+
+	// ── Termination (set once at end-of-run) ───────────────────────────
+	termination: {
+		success: boolean;
+		error: string | undefined;
+	};
+}
+
+/** Per-run context the chain carries from stage to stage. */
+export interface RunContext {
+	cwd: string;
+	runId: string;
+	workflow: Workflow;
+	/**
+	 * Upper bound for stage status display — count of stages reachable from
+	 * `workflow.start`, computed once at run start. The actual stage count
+	 * is path-dependent (a predicate edge may short-circuit), so this is
+	 * the denominator users see; the numerator is the live stage index.
+	 */
+	totalStages: number;
+	state: RunState;
+	/**
+	 * Stage names already executed in this run. The backward-jump guard
+	 * increments `state.telemetry.backwardJumps` on every re-entry; revise →
+	 * implement loops legitimately revisit stages, but unbounded loops trip
+	 * the cap.
+	 */
+	visited: Set<string>;
+	/**
+	 * Set of bare skill names registered with Pi at workflow start (e.g.
+	 * "research", "blueprint" — the `skill:` prefix is stripped). Snapshot
+	 * is taken ONCE in `runWorkflow` before any `ctx.newSession()` runs,
+	 * because Pi invalidates `WorkflowHost` handles after a session
+	 * replacement. `ensureSkillRegistered` consults this set instead of
+	 * calling `host.getCommands()` mid-run.
+	 *
+	 * Undefined when no host was passed to `runWorkflow` (programmatic
+	 * embedders that opt out of the skill-registration preflight — same
+	 * fail-soft posture as the rest of the host-optional surface).
+	 */
+	registeredSkills?: ReadonlySet<string>;
+	/**
+	 * Pi `ExtensionAPI` handle, retained as the FALLBACK send-path for
+	 * continue-policy stages — used only when the live inner ctx lacks
+	 * `sendUserMessage` (i.e. the workflow's first stage is continue and
+	 * the runtime is still on the outer command ctx). Everywhere else,
+	 * `CONTINUE_HANDLER` prefers `ctx.sendUserMessage` because Pi marks
+	 * this handle stale after the first `ctx.newSession()`. Touching it
+	 * for anything other than the fallback path will throw "extension
+	 * ctx is stale" on every workflow whose first stage is fresh.
+	 *
+	 * Read-only registry needs go through `registeredSkills` (snapshotted
+	 * at workflow start). Continue-policy presence checks
+	 * (`enforceSessionInvariants`) still gate on this field so the
+	 * fallback path has a working host when the start-stage path needs it.
+	 *
+	 * Naming: deliberately NOT called `host`. Future code-readers see the
+	 * field name and know the constraint without reading the JSDoc.
+	 */
+	continueHost?: WorkflowHost;
+	maxBackwardJumps: number;
+	/** What triggered the run; defaulted at `runWorkflow` entry. */
+	trigger: RunTrigger;
+	/** Lifecycle event dispatcher — see `lifecycle.ts`. Threaded by reference. */
+	lifecycle: LifecycleDispatcher;
+}
+
+/**
+ * Per-stage / per-unit common base. Extended by `StageSession` and
+ * `FanoutSession`; consumed in pick form by `AuditCtx` (audit.ts) so the audit
+ * layer pins its dependency on this shape structurally instead of
+ * duplicating the field list.
+ *
+ * `stageName` is the workflow stage's record key — the value that lands
+ * in `WorkflowStage.stage`. `skill` is the Pi skill body the runner
+ * dispatches (`/skill:<skill>`). They're equal in the common case but
+ * diverge for aliased stages (`stages: { "implement-after-revise":
+ * acts({ skill: "implement" }) }` → stageName="implement-after-revise",
+ * skill="implement").
+ */
+export interface SessionContext {
+	cwd: string;
+	runId: string;
+	state: RunState;
+	/** `/skill:<name> <args>`. */
+	prompt: string;
+	/** Workflow stage record key — JSONL `WorkflowStage.stage` value. */
+	stageName: string;
+	/** Pi skill body — `/skill:<skill>` dispatch + status-line label + JSONL `WorkflowStage.skill`. */
+	skill: string;
+	/** Shared lifecycle dispatcher. Threaded from `RunContext` so the audit layer can fire `onStageEnd` / `onStageError` / `onFanoutUnitEnd` without re-importing it. */
+	lifecycle: LifecycleDispatcher;
+	/**
+	 * Read-only run identity passed to lifecycle callbacks. Captured at
+	 * session construction (cwd + runId + workflow name + totalStages +
+	 * trigger). Built once per run, reused.
+	 */
+	runIdentity: {
+		workflow: string;
+		totalStages: number;
+		trigger: RunTrigger;
+	};
+}
+
+export interface StageSession extends SessionContext {
+	stage: StageDef;
+	/** 0-based stage index within this run — for status display + JSONL stage number. */
+	stageIndex: number;
+	/** Pre-stage snapshot value (undefined if the stage's `outcome` has no `snapshot`). */
+	snapshot: unknown;
+	/**
+	 * Pi `ExtensionAPI` handle reserved for the continue-policy handler
+	 * (`spawn.ts`). Required iff `stage.sessionPolicy === "continue"`.
+	 * Same constraint as `RunContext.continueHost`: stale after any prior
+	 * `ctx.newSession()`, so the runner MUST NOT read it for registry
+	 * inspection. See `RunContext.continueHost` JSDoc.
+	 */
+	continueHost?: WorkflowHost;
+	/** Only set for continue stages — branch slice offset. */
+	branchOffset?: number;
+	onFailure?: (ctx: RunnerCtx) => void;
+	onSuccess: (ctx: RunnerCtx, artifact: Artifact | undefined) => Promise<void>;
+}
+
+/**
+ * One unit of a fanout iteration. `label` is the user-supplied
+ * disambiguating tag from `FanoutUnit.label`; it's woven into the status
+ * line (`STATUS_FANOUT_UNIT`). The JSONL row's `stage` value (built by
+ * `fanoutRowStage`) prefixes the parent's `stageName` with `id ?? label`
+ * so the runner adds no implicit wording.
+ */
+export interface FanoutSession extends SessionContext {
+	/** 1-based position within the run's fanout array — for halt diagnostics. */
+	unitIndex: number;
+	/** From `FanoutUnit.label` — already disambiguating, e.g. `"phase 2/5"`. */
+	label: string;
+	/**
+	 * From `FanoutUnit.id` when set — stable audit identifier preferred
+	 * over `label` in JSONL rows. Undefined when the user supplied none.
+	 */
+	id?: string;
+	/** Parent stage's 0-based index. */
+	stageIndex: number;
+	onSuccess: (ctx: RunnerCtx) => Promise<void>;
+}

package/validate-output.ts

@@ -0,0 +1,120 @@
+/**
+ * Output-data validation against a `StageSchema` (Standard Schema v1 under
+ * the hood). The schema-library boundary is `~standard.validate`; users may
+ * bring Zod / Valibot / ArkType / TypeBox (wrapped via
+ * `typebox-adapter.ts:typeboxSchema`).
+ */
+
+import type { StageSchema } from "./api.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SchemaValidationFailure {
+	/** JSON-pointer-like path (instancePath); `"."` for root. */
+	path: string;
+	/** Schema keyword that failed. */
+	expected: string;
+	/** typeof / "array" / "null" / "undefined" of the offending value. */
+	actual: string;
+	message: string;
+}
+
+export interface ValidationResult {
+	valid: boolean;
+	failures: SchemaValidationFailure[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const MIN_VALIDATION_RETRIES = 1;
+export const MAX_VALIDATION_RETRIES = 3;
+export const DEFAULT_VALIDATION_RETRIES = 1;
+
+export const DEFAULT_VALIDATION_RETRY_TIMEOUT_MS = 5 * 60 * 1000;
+export const MAX_VALIDATION_RETRY_TIMEOUT_MS = 30 * 60 * 1000;
+export const MIN_VALIDATION_RETRY_TIMEOUT_MS = 1_000;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the schema's verdict on `data`. Standard Schema permits `validate`
+ * to return synchronously or as a Promise; this function mirrors that —
+ * callers must `await` the result. Both seams that drive validation
+ * (`retryUntilValid` in extraction.ts and `ensureInputValid` in
+ * stage-lifecycle.ts) are async, so awaiting a sync value is free (one
+ * microtask) and async schemas (I/O-backed checks, async-by-default libs
+ * like ArkType) round-trip without a sync-only escape hatch.
+ */
+export function validateOutputData(schema: StageSchema, data: unknown): ValidationResult | Promise<ValidationResult> {
+	const result = schema["~standard"].validate(data);
+	if (result instanceof Promise) {
+		return result.then((resolved) => buildResult(resolved, data));
+	}
+	return buildResult(result, data);
+}
+
+function buildResult(
+	result: {
+		readonly issues?: readonly {
+			readonly message: string;
+			readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[];
+		}[];
+	},
+	data: unknown,
+): ValidationResult {
+	if (!result.issues) {
+		return { valid: true, failures: [] };
+	}
+	const failures: SchemaValidationFailure[] = result.issues.map((issue) => {
+		const path = issue.path ? formatStandardPath(issue.path) : ".";
+		return {
+			path,
+			expected: "schema",
+			actual: describeType(resolveInstanceValue(data, path)),
+			message: issue.message,
+		};
+	});
+	return { valid: false, failures };
+}
+
+/** `["foo", 0, "bar"]` → `/foo/0/bar`; empty path → `"."`. */
+function formatStandardPath(path: readonly (PropertyKey | { readonly key: PropertyKey })[]): string {
+	if (path.length === 0) return ".";
+	const segs: string[] = [];
+	for (const seg of path) {
+		if (typeof seg === "object" && seg !== null && "key" in seg) {
+			segs.push(String(seg.key));
+		} else {
+			segs.push(String(seg));
+		}
+	}
+	return `/${segs.join("/")}`;
+}
+
+function resolveInstanceValue(data: unknown, instancePath: string): unknown {
+	if (!instancePath || instancePath === "" || instancePath === ".") return data;
+	const segments = instancePath.split("/").slice(1);
+	let cur: unknown = data;
+	for (const seg of segments) {
+		if (cur === null || cur === undefined) return cur;
+		cur = (cur as Record<string, unknown>)[seg];
+	}
+	return cur;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function describeType(value: unknown): string {
+	if (value === null) return "null";
+	if (value === undefined) return "undefined";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}