@zq-silk/yui 0.14.0 → 0.14.2

package/dist/execution/resourceBroker.js

@@ -1,426 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
-import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
-import { validateExecutionGroup } from "./executionGroup.js";
-export const RESOURCE_BROKER_POLICY_SCHEMA_VERSION = 1;
-/** Compatibility/display default; observed tokens never close execution spend. */
-export const DEFAULT_EXECUTION_STAGE_TOKEN_BUDGET_PER_LANE = 120_000;
-/** One shared hard-stop predicate for admission, recovery, and Leader routing. */
-export function executionStageSpendClosed(resources) {
-    return resources.deadlineReached
-        || resources.exhaustedBudgets.includes("tool-calls")
-        || resources.exhaustedBudgets.includes("wall-clock");
-}
-const DEFAULT_ACTIVE_LANES = 4;
-const DEFAULT_ACTIVE_LANES_PER_TASK = 2;
-const DEFAULT_ACTIVE_LANES_PER_WORK_ITEM = 2;
-const DEFAULT_ACTIVE_LANES_PER_GROUP = 2;
-const DEFAULT_ACTIVE_LANES_PER_PROVIDER = 4;
-const DEFAULT_ACTIVE_LANES_PER_AGENT = 2;
-const DEFAULT_ACTIVE_LANES_PER_MODEL = 2;
-const DEFAULT_QUEUED_LANES_PER_GROUP = 4;
-export function resolveResourceBrokerPolicy(configured) {
-    const value = configured ?? {};
-    return Object.freeze({
-        schemaVersion: RESOURCE_BROKER_POLICY_SCHEMA_VERSION,
-        maxActiveLanes: positive(value.maxActiveLanes, DEFAULT_ACTIVE_LANES, "maxActiveLanes"),
-        maxActiveLanesPerTask: positive(value.maxActiveLanesPerTask, DEFAULT_ACTIVE_LANES_PER_TASK, "maxActiveLanesPerTask"),
-        maxActiveLanesPerWorkItem: positive(value.maxActiveLanesPerWorkItem, DEFAULT_ACTIVE_LANES_PER_WORK_ITEM, "maxActiveLanesPerWorkItem"),
-        maxActiveLanesPerGroup: positive(value.maxActiveLanesPerGroup, DEFAULT_ACTIVE_LANES_PER_GROUP, "maxActiveLanesPerGroup"),
-        maxActiveLanesPerProvider: positive(value.maxActiveLanesPerProvider, DEFAULT_ACTIVE_LANES_PER_PROVIDER, "maxActiveLanesPerProvider"),
-        maxActiveLanesPerAgent: positive(value.maxActiveLanesPerAgent, DEFAULT_ACTIVE_LANES_PER_AGENT, "maxActiveLanesPerAgent"),
-        maxActiveLanesPerModel: positive(value.maxActiveLanesPerModel, DEFAULT_ACTIVE_LANES_PER_MODEL, "maxActiveLanesPerModel"),
-        maxQueuedLanesPerGroup: positive(value.maxQueuedLanesPerGroup, DEFAULT_QUEUED_LANES_PER_GROUP, "maxQueuedLanesPerGroup")
-    });
-}
-/**
- * Deterministic admission over the caller's stable request order. Capacity
- * pressure queues a Lane; it never terminalizes that Lane or its siblings.
- */
-export function planResourceAdmissions(input) {
-    const policy = resolveResourceBrokerPolicy(input.policy);
-    const active = input.active.map(validateLaneIdentity);
-    const queued = input.queued.map(validateLaneIdentity);
-    const decisions = [];
-    for (const raw of input.requests) {
-        const request = validateLaneIdentity(raw);
-        const directLimits = activeLimits(policy, active, request);
-        const activeLaneKeys = new Set(active.map(resourceLaneKey));
-        const queuedBefore = [
-            ...queued,
-            ...decisions.filter(({ decision }) => decision === "queued").map(({ request }) => request)
-        ].filter((candidate) => !activeLaneKeys.has(resourceLaneKey(candidate)));
-        const fairReservations = directLimits.length === 0
-            ? reservableOlderQueuedLanes(policy, active, queuedBefore, request)
-            : [];
-        const fairLimits = activeLimits(policy, [...active, ...fairReservations], request);
-        const limitedBy = fairLimits.length === 0
-            ? directLimits
-            : directLimits.length === 0 && fairReservations.length > 0
-                ? [...fairLimits, "fair-queue"]
-                : fairLimits;
-        if (limitedBy.length === 0) {
-            active.push(request);
-            decisions.push(Object.freeze({
-                request,
-                decision: "admitted",
-                limitedBy: [],
-                reason: "capacity is available at every resource scope"
-            }));
-            continue;
-        }
-        const groupQueued = queuedBefore.filter(({ taskId, executionGroupId }) => (taskId === request.taskId && executionGroupId === request.executionGroupId)).length;
-        if (groupQueued >= policy.maxQueuedLanesPerGroup) {
-            decisions.push(Object.freeze({
-                request,
-                decision: "blocked",
-                limitedBy: [...limitedBy, "group-queue"],
-                reason: `resource capacity is unavailable and the Group queue is full (${groupQueued}/${policy.maxQueuedLanesPerGroup})`
-            }));
-            continue;
-        }
-        decisions.push(Object.freeze({
-            request,
-            decision: "queued",
-            limitedBy,
-            reason: `resource backpressure: ${limitedBy.join(", ")}`
-        }));
-    }
-    return decisions;
-}
-/**
- * Reserve only older queued Lanes that could start now. This gives released
- * capacity to the oldest compatible waiter without letting a Provider- or
- * Agent-blocked head prevent independent work from using other scopes.
- */
-function reservableOlderQueuedLanes(policy, active, queued, request) {
-    const projected = [...active];
-    const reserved = [];
-    const seen = new Set();
-    for (const candidate of [...queued].sort(compareResourceQueueOrder)) {
-        const key = resourceLaneKey(candidate);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        if (sameResourceLane(candidate, request)
-            || compareResourceQueueOrder(candidate, request) >= 0
-            || activeLimits(policy, projected, candidate).length > 0)
-            continue;
-        projected.push(candidate);
-        reserved.push(candidate);
-    }
-    return reserved;
-}
-function compareResourceQueueOrder(left, right) {
-    return left.requestedAt.localeCompare(right.requestedAt)
-        || left.taskId.localeCompare(right.taskId, undefined, { numeric: true })
-        || left.executionGroupId.localeCompare(right.executionGroupId, undefined, { numeric: true })
-        || left.executionLaneId.localeCompare(right.executionLaneId, undefined, { numeric: true });
-}
-function sameResourceLane(left, right) {
-    return resourceLaneKey(left) === resourceLaneKey(right);
-}
-function resourceLaneKey(value) {
-    return `${value.taskId}\0${value.executionGroupId}\0${value.executionLaneId}`;
-}
-/** Current stage spend/completion projection used by CLI, Web, and routing. */
-export function projectExecutionStageResources(input) {
-    const group = validateExecutionGroup(input.group);
-    const stageGroups = executionStageRetryLineage(group, input.stageGroups);
-    const stage = group.stage;
-    const resources = stage?.resources;
-    const tokens = nonNegative(input.usage.tokens, "Execution token usage");
-    const toolCalls = nonNegative(input.usage.toolCalls, "Execution tool-call usage");
-    const nowMs = input.now.getTime();
-    if (!Number.isFinite(nowMs))
-        throw new Error("Execution resource projection time is invalid.");
-    const stageStartedAt = stageGroups
-        .map(({ createdAt }) => createdAt)
-        .sort()[0] ?? group.createdAt;
-    const wallClockSeconds = Math.max(0, Math.floor((nowMs - Date.parse(stageStartedAt)) / 1_000));
-    const usable = group.lanes.filter(({ status }) => isUsable(status))
-        .sort((left, right) => (left.endedAt ?? left.updatedAt).localeCompare(right.endedAt ?? right.updatedAt));
-    const activeLaneIds = group.lanes.filter(({ status }) => status === "running").map(({ id }) => id);
-    const pendingLaneIds = group.lanes.filter(({ status }) => status === "pending").map(({ id }) => id);
-    const skippedLaneIds = group.lanes.filter(({ status }) => status === "skipped").map(({ id }) => id);
-    const quorum = resources?.quorum ?? group.lanes.length;
-    const quorumMet = usable.length >= quorum;
-    const quorumReachedAt = quorumMet
-        ? (usable[quorum - 1].endedAt ?? usable[quorum - 1].updatedAt)
-        : undefined;
-    const tokensObservable = input.usage.tokensObservable ?? true;
-    const toolCallsObservable = input.usage.toolCallsObservable ?? true;
-    const exhaustedBudgets = [];
-    if (toolCallsObservable && stage?.budget.maxToolCalls !== undefined
-        && toolCalls >= stage.budget.maxToolCalls)
-        exhaustedBudgets.push("tool-calls");
-    if (stage?.budget.maxWallClockSeconds !== undefined
-        && wallClockSeconds >= stage.budget.maxWallClockSeconds)
-        exhaustedBudgets.push("wall-clock");
-    const deadlineReached = resources === undefined
-        ? false
-        : nowMs >= Date.parse(resources.deadlineAt);
-    const stragglerLaneIds = resources === undefined || quorumReachedAt === undefined
-        ? []
-        : nowMs - Date.parse(quorumReachedAt) < resources.stragglerAfterSeconds * 1_000
-            ? []
-            : [...activeLaneIds];
-    return Object.freeze({
-        tokens,
-        toolCalls,
-        wallClockSeconds,
-        ...(stage?.budget.maxTokens === undefined
-            ? {}
-            : { tokensRemaining: Math.max(0, stage.budget.maxTokens - tokens) }),
-        ...(stage?.budget.maxToolCalls === undefined
-            ? {}
-            : { toolCallsRemaining: Math.max(0, stage.budget.maxToolCalls - toolCalls) }),
-        ...(stage?.budget.maxWallClockSeconds === undefined
-            ? {}
-            : {
-                wallClockSecondsRemaining: Math.max(0, stage.budget.maxWallClockSeconds - wallClockSeconds)
-            }),
-        tokensObservable,
-        toolCallsObservable,
-        usableLaneCount: usable.length,
-        activeLaneIds,
-        pendingLaneIds,
-        skippedLaneIds,
-        quorumMet,
-        ...(quorumReachedAt === undefined ? {} : { quorumReachedAt }),
-        deadlineReached,
-        exhaustedBudgets,
-        stragglerLaneIds
-    });
-}
-/**
- * Parallel-vs-sequential decision support. Evidence sufficiency is an explicit
- * semantic input: budget pressure can block or defer work, but can never turn
- * insufficient evidence into a successful early stop.
- */
-export function routeExecutionStage(input) {
-    const group = validateExecutionGroup(input.group);
-    const stage = group.stage;
-    const policy = stage?.resources;
-    const marginal = input.marginalValuePercent === undefined
-        ? undefined
-        : percentage(input.marginalValuePercent, "Execution marginal value");
-    const budgetPressure = executionStageSpendClosed(input.resources);
-    const marginalLow = marginal !== undefined
-        && policy !== undefined
-        && marginal < policy.minimumMarginalValuePercent;
-    const earlyTerminationAllowed = input.evidenceSufficient && input.resources.quorumMet;
-    const stopSpending = earlyTerminationAllowed && (budgetPressure || marginalLow);
-    const cancelPendingLaneIds = stopSpending ? input.resources.pendingLaneIds : [];
-    const retainActiveLaneIds = stopSpending ? input.resources.activeLaneIds : [];
-    if (earlyTerminationAllowed) {
-        if (input.resources.activeLaneIds.length > 0) {
-            return Object.freeze({
-                action: "wait",
-                earlyTerminationAllowed,
-                cancelPendingLaneIds,
-                retainActiveLaneIds,
-                reason: stopSpending
-                    ? "quorum and sufficient evidence allow pending work to stop, but active stragglers are retained"
-                    : "evidence is sufficient, but active Lanes remain inside the stage policy"
-            });
-        }
-        if (!stopSpending && input.resources.pendingLaneIds.length > 0) {
-            return Object.freeze({
-                action: "wait",
-                earlyTerminationAllowed,
-                cancelPendingLaneIds: [],
-                retainActiveLaneIds: [],
-                reason: "evidence is sufficient, but pending Lanes remain inside the configured marginal-value policy"
-            });
-        }
-        return Object.freeze({
-            action: "resolve",
-            earlyTerminationAllowed,
-            cancelPendingLaneIds,
-            retainActiveLaneIds,
-            reason: stopSpending
-                ? "quorum and sufficient evidence make further pending spend uneconomic"
-                : "quorum and sufficient evidence are complete"
-        });
-    }
-    if (input.resources.activeLaneIds.length > 0) {
-        return Object.freeze({
-            action: "wait",
-            earlyTerminationAllowed: false,
-            cancelPendingLaneIds: [],
-            retainActiveLaneIds: [],
-            reason: budgetPressure
-                ? "evidence is insufficient; active work is retained despite budget pressure"
-                : "evidence is insufficient and active Lanes may still add evidence"
-        });
-    }
-    if (budgetPressure) {
-        return Object.freeze({
-            action: "blocked",
-            earlyTerminationAllowed: false,
-            cancelPendingLaneIds: [],
-            retainActiveLaneIds: [],
-            reason: "the stage budget or deadline is exhausted before evidence sufficiency"
-        });
-    }
-    if (input.resources.pendingLaneIds.length > 0) {
-        return Object.freeze({
-            action: "wait",
-            earlyTerminationAllowed: false,
-            cancelPendingLaneIds: [],
-            retainActiveLaneIds: [],
-            reason: "evidence is insufficient and scheduled Lanes are waiting for resource capacity"
-        });
-    }
-    const capacity = group.strategy.mode === "fixed" ? group.strategy.count : group.strategy.max;
-    if (group.strategy.mode === "adaptive"
-        && group.lanes.length < capacity
-        && (!input.resources.quorumMet || input.disagreement === "high")) {
-        return Object.freeze({
-            action: "expand-parallel",
-            earlyTerminationAllowed: false,
-            cancelPendingLaneIds: [],
-            retainActiveLaneIds: [],
-            reason: input.resources.quorumMet
-                ? "material disagreement and available Lane capacity favor another independent route"
-                : "stage quorum is open and available Lane capacity requires another independent route"
-        });
-    }
-    return Object.freeze({
-        action: "deepen-sequential",
-        earlyTerminationAllowed: false,
-        cancelPendingLaneIds: [],
-        retainActiveLaneIds: [],
-        reason: "available evidence favors the next bounded stage over more parallel fan-out"
-    });
-}
-/** Fold exact runtime observations into the spend dimensions Yui can prove. */
-export function observedExecutionResourceUsage(input) {
-    const group = validateExecutionGroup(input.group);
-    const stageGroups = executionStageRetryLineage(group, input.stageGroups);
-    const groupIds = new Set(stageGroups.map(({ id }) => id));
-    const turnIds = new Set([
-        ...stageGroups.flatMap((candidate) => candidate.lanes
-            .flatMap(({ turnId }) => turnId === undefined ? [] : [turnId])),
-        ...(input.turns ?? []).filter((turn) => (turn.taskId === group.taskId
-            && turn.purpose === "execution"
-            && turn.executionGroupId !== undefined
-            && groupIds.has(turn.executionGroupId))).map(({ id }) => id)
-    ]);
-    const observations = input.events.map(runtimeObservationFromTaskEvent)
-        .filter((value) => (value !== null
-        && value.fence.taskId === group.taskId
-        && value.fence.turnId !== undefined
-        && turnIds.has(value.fence.turnId)));
-    let tokens = 0;
-    let tokensObservable = true;
-    for (const turnId of turnIds) {
-        const usage = observations.filter(({ fence, payload }) => (fence.turnId === turnId && payload.usage !== undefined)).sort((left, right) => (left.receivedAt.localeCompare(right.receivedAt)
-            || (left.sequence ?? 0) - (right.sequence ?? 0)
-            || (left.ordinal ?? 0) - (right.ordinal ?? 0)));
-        if (usage.length === 0) {
-            tokensObservable = false;
-            continue;
-        }
-        const requestSnapshots = new Map(usage
-            .filter(({ payload }) => payload.usage.semantics === "request-context")
-            .map((observation) => [observation.semanticKey, observation.payload.usage]));
-        if (requestSnapshots.size > 0) {
-            tokens += [...requestSnapshots.values()]
-                .reduce((sum, value) => sum + value.inputTokens + value.outputTokens, 0);
-            continue;
-        }
-        const cumulative = usage
-            .filter(({ payload }) => payload.usage.semantics === "cumulative-session")
-            .map(({ payload }) => payload.usage.inputTokens + payload.usage.outputTokens);
-        if (cumulative.length >= 2 && cumulative[0] === 0) {
-            tokens += Math.max(...cumulative);
-            continue;
-        }
-        if (cumulative.length >= 2) {
-            tokens += Math.max(0, Math.max(...cumulative) - cumulative[0]);
-        }
-        if (cumulative.length > 0 || usage.some(({ payload }) => (payload.usage.semantics === "remaining-context")))
-            tokensObservable = false;
-    }
-    const toolOperationIds = new Set(observations.flatMap((observation) => (observation.kind === "operation.started" && observation.payload.operation === "tool"
-        ? [`${observation.fence.turnId}\0${observation.payload.operationId ?? observation.semanticKey}`]
-        : [])));
-    const toolCallsObservable = observations.some(({ kind, payload }) => (kind === "operation.started" && payload.operation === "tool"));
-    return Object.freeze({
-        tokens,
-        toolCalls: toolOperationIds.size,
-        tokensObservable,
-        toolCallsObservable
-    });
-}
-function activeLimits(policy, active, request) {
-    const checks = [
-        ["home", policy.maxActiveLanes, () => true],
-        ["task", policy.maxActiveLanesPerTask, (value) => value.taskId === request.taskId],
-        ["work-item", policy.maxActiveLanesPerWorkItem, (value) => (request.workItemId !== undefined && value.taskId === request.taskId
-                && value.workItemId === request.workItemId)],
-        ["group", policy.maxActiveLanesPerGroup, (value) => (value.taskId === request.taskId && value.executionGroupId === request.executionGroupId)],
-        ["provider", policy.maxActiveLanesPerProvider, (value) => value.providerId === request.providerId],
-        ["agent", policy.maxActiveLanesPerAgent, (value) => value.agentId === request.agentId],
-        ["model", policy.maxActiveLanesPerModel, (value) => modelKey(value) === modelKey(request)]
-    ];
-    return checks.filter(([, limit, matches]) => active.filter(matches).length >= limit)
-        .map(([scope]) => scope);
-}
-function executionStageRetryLineage(group, candidates) {
-    const stage = group.stage;
-    if (stage === undefined || candidates === undefined)
-        return [group];
-    const lineage = candidates
-        .map(validateExecutionGroup)
-        .filter((candidate) => (candidate.taskId === group.taskId
-        && candidate.purpose === "execution"
-        && candidate.stage?.mode === stage.mode
-        && candidate.stage.stage === stage.stage
-        && candidate.stage.round === stage.round
-        && candidate.stage.stageAttempt <= stage.stageAttempt
-        && isDeepStrictEqual(candidate.stage.budget, stage.budget)
-        && isDeepStrictEqual(candidate.stage.resources, stage.resources)));
-    if (!lineage.some(({ id }) => id === group.id))
-        lineage.push(group);
-    return lineage;
-}
-function validateLaneIdentity(value) {
-    requireIdentity(value.taskId, "Resource Lane Task id");
-    if (value.workItemId !== undefined)
-        requireIdentity(value.workItemId, "Resource Lane WorkItem id");
-    requireIdentity(value.executionGroupId, "Resource Lane ExecutionGroup id");
-    requireIdentity(value.executionLaneId, "Resource Lane id");
-    requireIdentity(value.providerId, "Resource Lane Provider id");
-    requireIdentity(value.agentId, "Resource Lane Agent id");
-    if (value.model !== undefined)
-        requireText(value.model, "Resource Lane model");
-    requireTimestamp(value.requestedAt, "Resource Lane request time");
-    return Object.freeze({ ...value });
-}
-function modelKey(value) {
-    return `${value.providerId}\0${value.model ?? "default"}`;
-}
-function positive(value, fallback, label) {
-    const resolved = value ?? fallback;
-    if (!Number.isSafeInteger(resolved) || resolved < 1) {
-        throw new TypeError(`${label} must be a positive integer.`);
-    }
-    return resolved;
-}
-function nonNegative(value, label) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        throw new Error(`${label} must be a non-negative integer.`);
-    return value;
-}
-function percentage(value, label) {
-    if (!Number.isSafeInteger(value) || value < 0 || value > 100) {
-        throw new Error(`${label} must be an integer from 0 to 100.`);
-    }
-    return value;
-}
-function isUsable(status) {
-    return status === "completed";
-}

package/dist/executor/launchPlan.js

@@ -1,16 +0,0 @@
-export function withYuiTurnEnvironment(launch, yuiHome, role, turn, nativeSessionId, nativeSessionRoot) {
-    return {
-        ...launch,
-        env: {
-            ...launch.env,
-            YUI_HOME: yuiHome,
-            YUI_TASK_ID: turn.taskId,
-            YUI_ROLE: role.name,
-            YUI_AGENT_ID: role.activeAgentId ?? role.agent ?? "",
-            YUI_TURN_ID: turn.id,
-            YUI_WORKSPACE: role.workspace,
-            ...(nativeSessionRoot === undefined ? {} : { YUI_NATIVE_SESSION_ROOT: nativeSessionRoot }),
-            ...(nativeSessionId === undefined ? {} : { YUI_NATIVE_SESSION_ID: nativeSessionId })
-        }
-    };
-}

package/dist/review/reviewFinding.js

@@ -1,240 +0,0 @@
-import { createHash } from "node:crypto";
-import { requireIdentity, requireText, requireTimestamp, normalizedUniqueText } from "../domain/validation.js";
-import { validateTaskRecordReference } from "../task/taskRecordReference.js";
-/** Dispositions that still block Task completion under `enforce`. */
-export const BLOCKING_FINDING_DISPOSITIONS = [
-    "open",
-    "fixed-pending-review"
-];
-/** Dispositions a Task-control Agent may set explicitly. */
-export const TASK_CONTROL_FINDING_DISPOSITIONS = [
-    "fixed-pending-review",
-    "verified-fixed",
-    "accepted-risk",
-    "not-actionable",
-    "superseded"
-];
-/** Normalizes the severity vocabularies reviewers may use to P1/P2/P3. */
-export function normalizeReviewFindingSeverity(value) {
-    if (typeof value !== "string")
-        throw new Error("Review finding severity is required.");
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "p1" || normalized === "critical" || normalized === "blocker")
-        return "p1";
-    if (normalized === "p2" || normalized === "high" || normalized === "major")
-        return "p2";
-    if (normalized === "p3"
-        || normalized === "medium"
-        || normalized === "moderate"
-        || normalized === "low"
-        || normalized === "minor"
-        || normalized === "nit"
-        || normalized === "info"
-        || normalized === "style") {
-        return "p3";
-    }
-    throw new Error(`Review finding severity is invalid: ${String(value)}.`);
-}
-/**
- * Derives the stable ledger key for one reported finding.  The key is
- * deterministic for the same invariant/path/symbol so a repeated finding in a
- * later Round updates the existing record instead of creating a duplicate.
- */
-export function reviewFindingStableKey(input) {
-    const invariant = input.invariant.trim().toLowerCase();
-    const primaryPath = (input.primaryPath ?? "").trim().toLowerCase();
-    const primarySymbol = (input.primarySymbol ?? "").trim().toLowerCase();
-    const basis = [
-        invariant,
-        primaryPath,
-        primarySymbol
-    ].join("|");
-    // Reports without path/symbol provenance cannot safely collapse different
-    // titles under one invariant. Use the title as the fallback identity instead
-    // of merging every such finding into a single ledger record.
-    const material = primaryPath.length === 0 && primarySymbol.length === 0
-        ? `${invariant}|${input.title.trim().toLowerCase()}`
-        : basis;
-    return `rf-${createHash("sha256").update(material).digest("hex").slice(0, 16)}`;
-}
-export function createReviewFinding(id, taskId, input, now) {
-    const timestamp = now.toISOString();
-    return validateReviewFinding({
-        schemaVersion: 1,
-        id: requireIdentity(id, "ReviewFinding id"),
-        taskId: requireIdentity(taskId, "Task id"),
-        ...(input.sourceId === undefined ? {} : { sourceId: requireIdentity(input.sourceId, "ReviewFinding source id") }),
-        stableKey: requireIdentity(input.stableKey, "ReviewFinding stable key"),
-        severity: input.severity,
-        invariant: requireText(input.invariant, "ReviewFinding invariant"),
-        title: requireText(input.title, "ReviewFinding title"),
-        affectedPaths: normalizedUniqueText(input.affectedPaths ?? [], "ReviewFinding affected path"),
-        affectedSymbols: normalizedUniqueText(input.affectedSymbols ?? [], "ReviewFinding affected symbol"),
-        evidence: normalizedUniqueText(input.evidence ?? [], "ReviewFinding evidence"),
-        firstReviewRoundId: requireIdentity(input.reviewRoundId, "ReviewFinding first ReviewRound"),
-        lastReviewRoundId: requireIdentity(input.reviewRoundId, "ReviewFinding last ReviewRound"),
-        disposition: "open",
-        createdAt: timestamp,
-        updatedAt: timestamp
-    });
-}
-/**
- * Applies one Leader disposition.  Terminal dispositions
- * (verified-fixed/accepted-risk/not-actionable/superseded) are explicit Leader
- * decisions and stay terminal; `fixed-pending-review` may still regress to
- * `open` when a later Round reproduces the finding.
- */
-export function disposeReviewFinding(finding, input) {
-    validateReviewFinding(finding);
-    if (!TASK_CONTROL_FINDING_DISPOSITIONS.includes(input.disposition)) {
-        throw new Error(`ReviewFinding disposition is not a Leader decision: ${input.disposition}.`);
-    }
-    if (finding.disposition !== "open" && finding.disposition !== "fixed-pending-review") {
-        throw new Error(`ReviewFinding ${finding.id} is already terminal: ${finding.disposition}.`);
-    }
-    if (input.disposition === "superseded" && input.supersededBy === undefined) {
-        throw new Error(`ReviewFinding ${finding.id} supersession requires a successor stable key.`);
-    }
-    const repair = input.repair === undefined
-        ? finding.repair
-        : validateReviewFindingRepair(input.repair);
-    return validateReviewFinding({
-        ...finding,
-        disposition: input.disposition,
-        ...(repair === undefined ? {} : { repair }),
-        dispositionBy: requireIdentity(input.by, "ReviewFinding disposition actor"),
-        ...(input.note === undefined ? {} : { dispositionNote: requireText(input.note, "ReviewFinding disposition note") }),
-        ...(input.supersededBy === undefined ? {} : { supersededBy: requireIdentity(input.supersededBy, "ReviewFinding successor stable key") }),
-        mergeRequired: false,
-        updatedAt: input.now.toISOString()
-    });
-}
-/**
- * Reconciles a re-detection of this finding in a later Round.  A regression
- * reopens a `fixed-pending-review` finding; a `verified-fixed` finding that
- * reproduces also reopens (the fix did not hold).  Explicit Leader decisions
- * (accepted-risk/not-actionable/superseded) stay terminal but still get their
- * evidence and last-Round pointer refreshed.
- */
-export function redetectReviewFinding(finding, input) {
-    validateReviewFinding(finding);
-    const evidence = normalizedUniqueText([...finding.evidence, ...(input.evidence ?? [])], "ReviewFinding evidence");
-    const reopen = finding.disposition === "fixed-pending-review"
-        || finding.disposition === "verified-fixed";
-    return validateReviewFinding({
-        ...finding,
-        lastReviewRoundId: requireIdentity(input.reviewRoundId, "ReviewFinding last ReviewRound"),
-        evidence,
-        ...(reopen ? { disposition: "open", repair: undefined } : {}),
-        ...(reopen ? { mergeRequired: finding.mergeRequired } : {}),
-        updatedAt: input.now.toISOString()
-    });
-}
-/** Refreshes last-Round/evidence for a terminal finding without reopening it. */
-export function touchReviewFinding(finding, input) {
-    validateReviewFinding(finding);
-    const evidence = normalizedUniqueText([...finding.evidence, ...(input.evidence ?? [])], "ReviewFinding evidence");
-    if (finding.lastReviewRoundId === input.reviewRoundId
-        && evidence.length === finding.evidence.length) {
-        return finding;
-    }
-    return validateReviewFinding({
-        ...finding,
-        lastReviewRoundId: requireIdentity(input.reviewRoundId, "ReviewFinding last ReviewRound"),
-        evidence,
-        updatedAt: input.now.toISOString()
-    });
-}
-/**
- * Issue 06: a Reviewer reports a previously-open finding as resolved in a
- * later semantic Round.  The claim is only accepted when the ledger already
- * has repair refs; otherwise the old finding remains open (a changed candidate
- * without repair evidence must not advance disposition).  With repair refs,
- * this transitions `open` to `fixed-pending-review` (the fix claim is recorded
- * but the Leader still owns the final disposition) and refreshes
- * evidence/last-Round for `fixed-pending-review`.  Explicit Leader decisions
- * (accepted-risk/not-actionable/superseded) and `verified-fixed` are untouched.
- */
-export function resolveReviewFinding(finding, input) {
-    validateReviewFinding(finding);
-    const evidence = normalizedUniqueText([...finding.evidence, ...(input.evidence ?? [])], "ReviewFinding evidence");
-    const transition = finding.disposition === "open" && finding.repair !== undefined;
-    if (!transition
-        && finding.lastReviewRoundId === input.reviewRoundId
-        && evidence.length === finding.evidence.length) {
-        return finding;
-    }
-    return validateReviewFinding({
-        ...finding,
-        lastReviewRoundId: requireIdentity(input.reviewRoundId, "ReviewFinding last ReviewRound"),
-        evidence,
-        ...(transition ? { disposition: "fixed-pending-review" } : {}),
-        updatedAt: input.now.toISOString()
-    });
-}
-export function isReviewFindingBlocking(finding) {
-    return BLOCKING_FINDING_DISPOSITIONS.includes(finding.disposition)
-        && (finding.severity === "p1" || finding.severity === "p2");
-}
-export function validateReviewFinding(finding) {
-    if (finding.schemaVersion !== 1) {
-        throw new Error("ReviewFinding must use schemaVersion 1.");
-    }
-    validateTaskRecordReference({ taskId: finding.taskId, localId: finding.id }, "reviewFinding");
-    requireIdentity(finding.stableKey, "ReviewFinding stable key");
-    if (finding.severity !== "p1" && finding.severity !== "p2" && finding.severity !== "p3") {
-        throw new Error(`ReviewFinding severity is invalid: ${String(finding.severity)}.`);
-    }
-    requireText(finding.invariant, "ReviewFinding invariant");
-    requireText(finding.title, "ReviewFinding title");
-    normalizedUniqueText(finding.affectedPaths, "ReviewFinding affected path");
-    normalizedUniqueText(finding.affectedSymbols, "ReviewFinding affected symbol");
-    normalizedUniqueText(finding.evidence, "ReviewFinding evidence");
-    validateTaskRecordReference({ taskId: finding.taskId, localId: finding.firstReviewRoundId }, "reviewRound");
-    validateTaskRecordReference({ taskId: finding.taskId, localId: finding.lastReviewRoundId }, "reviewRound");
-    if (![
-        "open",
-        "fixed-pending-review",
-        "verified-fixed",
-        "accepted-risk",
-        "not-actionable",
-        "superseded"
-    ].includes(finding.disposition)) {
-        throw new Error(`ReviewFinding disposition is invalid: ${String(finding.disposition)}.`);
-    }
-    if (finding.repair !== undefined)
-        validateReviewFindingRepair(finding.repair);
-    if (finding.dispositionBy !== undefined) {
-        requireIdentity(finding.dispositionBy, "ReviewFinding disposition actor");
-    }
-    if (finding.dispositionNote !== undefined) {
-        requireText(finding.dispositionNote, "ReviewFinding disposition note");
-    }
-    if (finding.supersededBy !== undefined) {
-        requireIdentity(finding.supersededBy, "ReviewFinding successor stable key");
-        if (finding.disposition !== "superseded") {
-            throw new Error(`ReviewFinding ${finding.id} carries a successor but is not superseded.`);
-        }
-    }
-    if (finding.disposition === "superseded" && finding.supersededBy === undefined) {
-        throw new Error(`ReviewFinding ${finding.id} is superseded without a successor.`);
-    }
-    requireTimestamp(finding.createdAt, "ReviewFinding createdAt");
-    requireTimestamp(finding.updatedAt, "ReviewFinding updatedAt");
-    return finding;
-}
-function validateReviewFindingRepair(repair) {
-    if (repair.workItemId !== undefined) {
-        requireIdentity(repair.workItemId, "ReviewFinding repair WorkItem");
-    }
-    if (repair.commit !== undefined) {
-        const commit = requireText(repair.commit, "ReviewFinding repair commit").toLowerCase();
-        if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(commit)) {
-            throw new Error("ReviewFinding repair commit is invalid.");
-        }
-    }
-    if (repair.verification !== undefined) {
-        requireText(repair.verification, "ReviewFinding repair verification");
-    }
-    return repair;
-}