@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/frontend-shape.js

@@ -0,0 +1,425 @@
+/**
+ * Frontend task shape routing (M7) and shape-transition capsules.
+ *
+ * Pure and independent of the M4 risk classifier and the runtime branch
+ * control. The shape functions here are deterministic (no I/O, no model, no
+ * side effects). This module is the generation-time authority for frontend
+ * task-shape routing; `init-hybrid.ts` must consume it directly and must not
+ * import the closeout renderer.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+/** Fixture-only node counts. They are NOT the authoritative 15/13/11
+ * topology: split-required has no count. */
+export const FRONTEND_SHAPE_NODE_COUNTS = {
+    micro: 7,
+    small: 10,
+    standard: 11,
+    high: 11,
+};
+const SHAPE_ESCALATION_PATTERNS = [
+    { id: "auth-permission", re: /\bauth\b|\bpermission\b|\brbac\b|登录|权限|\bjwt\b|\bsession\b/i },
+    { id: "sensitive-action", re: /\bpayment\b|delete\s+account|支付|删除用户|\bdestructive\b/i },
+    { id: "ssr-boundary", re: /\bssr\b|\brsc\b|server\s+component|\bhydration\b|server-client/i },
+    { id: "new-route", re: /new\s+route|新增路由|createBrowserRouter|add\s+route/i },
+    { id: "shared-public-api", re: /public\s+api|shared\s+component|公共组件|破坏性|breaking\s+change/i },
+    { id: "schema-api-change", re: /\bopenapi\b|graphql\s+schema|api\s+contract|接口变更|schema\s+change/i },
+    { id: "new-dependency", re: /new\s+dependency|add\s+dependency|npm\s+install|新增依赖/i },
+    { id: "cross-domain-paths", re: /多个领域|cross-module|multiple\s+packages/i },
+];
+const SHAPE_SMALL_PATTERNS = [
+    { id: "single-component", re: /single\s+component|单一组件|局部样式|style\s+tweak|css\s+only|文案|copy\s+change/i },
+    { id: "no-remote", re: /no\s+api|无接口|本地状态|local\s+state\s+only|pure\s+ui/i },
+];
+const SHAPE_SPLIT_REQUIRED_PATTERN = /拆分|split\s+(?:requirement|task|需求)|large\s+requirement|大型需求|多步骤需求/i;
+const EXECUTABLE_SHAPE_RANK = {
+    micro: 0,
+    small: 1,
+    standard: 2,
+    high: 3,
+};
+function pathSpreadScore(paths) {
+    const tops = new Set(paths
+        .map((p) => p.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter(Boolean));
+    return tops.size;
+}
+function collectEscalationSignals(blob, supervised) {
+    const signals = [];
+    for (const pattern of SHAPE_ESCALATION_PATTERNS) {
+        if (pattern.re.test(blob))
+            signals.push(pattern.id);
+    }
+    if (supervised)
+        signals.push("supervised-profile");
+    if (SHAPE_SPLIT_REQUIRED_PATTERN.test(blob)) {
+        signals.push("large-requirement-split");
+    }
+    return [...new Set(signals)];
+}
+function resolveBaselineFrontendTaskShape(input) {
+    const blob = [
+        input.requirementMarkdown ?? "",
+        input.constraintMarkdown ?? "",
+        (input.allowedPaths ?? []).join("\n"),
+    ].join("\n");
+    const profile = (input.governanceProfile ?? "").toLowerCase();
+    const supervised = profile === "supervised" ||
+        profile.includes("supervised") ||
+        /\bsupervised\b/i.test(blob);
+    const escalationSignals = collectEscalationSignals(blob, supervised);
+    const smallHits = [];
+    for (const pattern of SHAPE_SMALL_PATTERNS) {
+        if (pattern.re.test(blob))
+            smallHits.push(pattern.id);
+    }
+    const paths = input.allowedPaths ?? [];
+    const spread = pathSpreadScore(paths);
+    const concentrated = spread <= 1 && paths.length <= 4;
+    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
+        !/\b(no\s+api|无接口|not-needed)\b/i.test(blob);
+    const complexity = (input.complexity ?? "").toLowerCase();
+    // split-required wins over everything: it is a termination/escalation
+    // signal, not an executable topology.
+    if (input.splitSignal.splitRequired) {
+        return {
+            shape: "split-required",
+            signals: [...new Set([...escalationSignals, "split-required"])],
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-split-required`),
+            reason: "split-required signal present: terminate/escalate before planning or writing",
+        };
+    }
+    if (supervised) {
+        const shape = escalationSignals.filter((s) => s !== "supervised-profile").length > 0
+            ? "high"
+            : "standard";
+        return {
+            shape,
+            signals: escalationSignals,
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-supervised`),
+            reason: shape === "high"
+                ? `high escalation under supervised: ${escalationSignals.join(", ")}`
+                : "supervised profile forces full gates (standard minimum)",
+        };
+    }
+    if (escalationSignals.length > 0) {
+        return {
+            shape: "high",
+            signals: escalationSignals,
+            rejectedSignals: smallHits.map((id) => `small:${id}:blocked-by-escalation`),
+            reason: `escalation signals present: ${escalationSignals.join(", ")}`,
+        };
+    }
+    // micro: the smallest possible change — explicit micro complexity, no API
+    // signal, no escalation, concentrated paths.
+    if ((complexity === "micro" || complexity === "trivial") &&
+        concentrated &&
+        !hasApiSignal) {
+        return {
+            shape: "micro",
+            signals: smallHits.length > 0 ? smallHits : ["micro-scope"],
+            rejectedSignals: [],
+            reason: "micro scope: trivial single-file change without remote API",
+        };
+    }
+    // small: no escalation, no supervised, small keywords, concentrated paths,
+    // no remote API signal.
+    if (smallHits.length > 0 &&
+        concentrated &&
+        !hasApiSignal &&
+        (complexity === "small" || complexity === "low")) {
+        return {
+            shape: "small",
+            signals: smallHits,
+            rejectedSignals: [],
+            reason: `small signals without escalation: ${smallHits.join(", ")}`,
+        };
+    }
+    const rejected = smallHits.map((id) => `small:${id}:blocked-by-${hasApiSignal ? "api-signal" : "path-spread"}`);
+    return {
+        shape: "standard",
+        signals: ["default-standard"],
+        rejectedSignals: rejected,
+        reason: smallHits.length > 0
+            ? hasApiSignal
+                ? "small keywords present but API/remote signals require standard topology"
+                : "small keywords present but path spread requires standard topology"
+            : "ambiguous or standard frontend work; default standard topology",
+    };
+}
+function reshapeFloorShape(capsule) {
+    if (capsule.requestedMinimumRisk === "high")
+        return "high";
+    if (capsule.requestedMinimumSize === "standard")
+        return "standard";
+    if (capsule.requestedMinimumRisk === "standard")
+        return "standard";
+    return "small";
+}
+function raiseExecutableShape(baseline, floor) {
+    if (baseline === "split-required")
+        return "split-required";
+    return EXECUTABLE_SHAPE_RANK[baseline] >= EXECUTABLE_SHAPE_RANK[floor]
+        ? baseline
+        : floor;
+}
+/**
+ * Route a frontend task into one of five shapes. Pure and independent of the
+ * M4 risk classifier and the runtime branch control. Escalation signals
+ * (high-risk keywords, supervised profile, cross-domain, large requirement
+ * split) always raise the shape above `small` or produce `split-required` —
+ * they are never silently swallowed. A verified shape-transition capsule, when
+ * present, outranks natural-language keywords and complexity but never lowers
+ * an already-higher executable baseline.
+ */
+export function resolveFrontendTaskShape(input) {
+    const capsule = input.shapeTransitionCapsule != null
+        ? parseFrontendShapeTransitionCapsule(input.shapeTransitionCapsule)
+        : undefined;
+    if (capsule) {
+        if (!input.taskId || !input.sourceDigest) {
+            throw new Error("shape transition capsule requires matching taskId and sourceDigest");
+        }
+        if (capsule.taskId !== input.taskId ||
+            capsule.sourceDigest !== input.sourceDigest) {
+            throw new Error("shape transition capsule task/source binding mismatch");
+        }
+    }
+    const baseline = resolveBaselineFrontendTaskShape(input);
+    if (!capsule)
+        return baseline;
+    if (capsule.kind === "split") {
+        return {
+            shape: "split-required",
+            signals: [...new Set([...baseline.signals, "shape-transition-split"])],
+            rejectedSignals: baseline.rejectedSignals,
+            reason: `shape transition capsule split: ${capsule.splitProposalRef}`,
+        };
+    }
+    const floor = reshapeFloorShape(capsule);
+    const shape = raiseExecutableShape(baseline.shape, floor);
+    return {
+        shape,
+        signals: [
+            ...new Set([
+                ...baseline.signals,
+                ...capsule.escalationSignals,
+                "shape-transition-reshape",
+            ]),
+        ],
+        rejectedSignals: baseline.rejectedSignals,
+        reason: shape === baseline.shape
+            ? baseline.reason
+            : `shape transition capsule reshape floor ${floor} raised ${baseline.shape}`,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Frozen topology binding and runtime escalation evaluation           *
+ * ------------------------------------------------------------------ */
+export const FRONTEND_TOPOLOGY_BINDING_SCHEMA_VERSION = 1;
+/** Freeze capability from the generated canonical task set. Node complexity
+ * is deliberately excluded: Standard and High share the same full topology. */
+export function buildFrontendTopologyBinding(taskIds) {
+    const canonicalTaskIds = [...new Set(taskIds)].sort();
+    const capability = canonicalTaskIds.includes("frontend-design-review-pi")
+        ? "full"
+        : "small";
+    const descriptor = {
+        schemaVersion: FRONTEND_TOPOLOGY_BINDING_SCHEMA_VERSION,
+        capability,
+        taskIds: canonicalTaskIds,
+    };
+    return {
+        ...descriptor,
+        canonicalDigest: sha256Utf8(JSON.stringify(sortKeysDeep(descriptor))),
+    };
+}
+export function assertFrontendTopologyBinding(binding, taskIds) {
+    if (!binding)
+        throw new Error("frontend topology binding is missing");
+    const expected = buildFrontendTopologyBinding(taskIds);
+    if (binding.schemaVersion !== expected.schemaVersion ||
+        binding.capability !== expected.capability ||
+        binding.canonicalDigest !== expected.canonicalDigest ||
+        !stringArraysEqual(binding.taskIds, expected.taskIds)) {
+        throw new Error("frontend topology binding drifted from immutable DagSpec tasks");
+    }
+    return binding;
+}
+/** Runtime-only fact derivation. This intentionally does not call the
+ * generation-time `resolveFrontendTaskShape` router. */
+export function deriveFrontendRuntimeShapeFacts(input) {
+    const blob = [
+        input.requirementMarkdown ?? "",
+        input.constraintMarkdown ?? "",
+        (input.allowedPaths ?? []).join("\n"),
+    ].join("\n");
+    const supervised = /\bsupervised\b/i.test(blob);
+    const escalationSignals = collectEscalationSignals(blob, supervised);
+    const paths = input.allowedPaths ?? [];
+    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
+        !/\b(no\s+api|无接口|not-needed)\b/i.test(blob);
+    const requiresFull = escalationSignals.length > 0 || pathSpreadScore(paths) > 1 || hasApiSignal;
+    return {
+        splitRequired: input.splitRequired,
+        escalationSignals,
+        minimumTopologyCapability: requiresFull ? "full" : "small",
+    };
+}
+/** Compare committed runtime facts with the generation-frozen topology. */
+export function evaluateFrontendShapeEscalation(input) {
+    if (input.splitRequired) {
+        return {
+            outcome: "split-required",
+            reason: "runtime facts require splitting before downstream dispatch",
+        };
+    }
+    if (input.minimumTopologyCapability === "full" &&
+        input.currentTopologyCapability === "small") {
+        return {
+            outcome: "reshape-required",
+            reason: `runtime facts require full frontend topology${input.escalationSignals.length > 0 ? `: ${input.escalationSignals.join(", ")}` : ""}`,
+        };
+    }
+    return {
+        outcome: "continue",
+        reason: input.escalationSignals.length > 0
+            ? `frozen topology already covers runtime risk signals: ${input.escalationSignals.join(", ")}`
+            : "frozen topology satisfies committed runtime facts",
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Shape transition capsule (§7.1 fields; runtime five-tier mapping)   *
+ * ------------------------------------------------------------------ */
+const hash64 = z.string().regex(/^[a-f0-9]{64}$/);
+const committedIdList = z.array(z.string().min(1)).min(1);
+const frontendShapeTransitionCapsuleBaseFields = {
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    sourceDigest: hash64,
+    fromShapeDigest: hash64,
+    shapeFactsDigest: hash64,
+    committedFactIds: committedIdList,
+    evidenceRefs: committedIdList,
+    committedAt: z.string().datetime(),
+    capsuleDigest: hash64,
+};
+export const frontendShapeTransitionReshapeCapsuleSchema = z
+    .object({
+    ...frontendShapeTransitionCapsuleBaseFields,
+    kind: z.literal("reshape"),
+    requestedMinimumSize: z.enum(["small", "standard"]),
+    requestedMinimumRisk: z.enum(["low", "standard", "high"]),
+    escalationSignals: z.array(z.string().min(1)),
+})
+    .strict();
+export const frontendShapeTransitionSplitCapsuleSchema = z
+    .object({
+    ...frontendShapeTransitionCapsuleBaseFields,
+    kind: z.literal("split"),
+    splitProposalRef: z.string().min(1),
+    splitProposalDigest: hash64,
+    requirementCoverageDigest: hash64,
+})
+    .strict();
+export const frontendShapeTransitionCapsuleSchema = z.discriminatedUnion("kind", [
+    frontendShapeTransitionReshapeCapsuleSchema,
+    frontendShapeTransitionSplitCapsuleSchema,
+]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dedupeSortStrings(values) {
+    return [...new Set(values)].sort();
+}
+function stringArraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+        const out = {};
+        for (const key of keys) {
+            out[key] = sortKeysDeep(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function sha256Utf8(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function computeCapsuleDigest(fields) {
+    const { capsuleDigest: _ignored, ...rest } = fields;
+    return sha256Utf8(JSON.stringify(sortKeysDeep(rest)));
+}
+function requireNonEmptyStringArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${field} must be a non-empty array of committed facts`);
+    }
+    if (!value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+        throw new Error(`${field} must contain only non-empty strings`);
+    }
+    return value;
+}
+function normalizeCapsuleRecord(input) {
+    const next = {
+        ...input,
+        committedFactIds: dedupeSortStrings(requireNonEmptyStringArray(input.committedFactIds, "committedFactIds")),
+        evidenceRefs: dedupeSortStrings(requireNonEmptyStringArray(input.evidenceRefs, "evidenceRefs")),
+    };
+    if (next.kind === "reshape") {
+        const signals = next.escalationSignals;
+        if (signals === undefined) {
+            next.escalationSignals = [];
+        }
+        else if (!Array.isArray(signals)) {
+            throw new Error("escalationSignals must be a string array");
+        }
+        else {
+            next.escalationSignals = dedupeSortStrings(signals.map((entry) => {
+                if (typeof entry !== "string") {
+                    throw new Error("escalationSignals must contain only strings");
+                }
+                return entry;
+            }));
+        }
+    }
+    return next;
+}
+export function computeFrontendShapeSourceDigest(input) {
+    return sha256Utf8(JSON.stringify(sortKeysDeep({
+        constraintMarkdown: input.constraintMarkdown ?? "",
+        requirementMarkdown: input.requirementMarkdown,
+    })));
+}
+export function buildFrontendShapeTransitionCapsule(input) {
+    if (!isPlainObject(input)) {
+        throw new Error("FrontendShapeTransitionCapsule input must be an object");
+    }
+    const { capsuleDigest: _ignored, ...rest } = input;
+    const normalized = normalizeCapsuleRecord(rest);
+    return frontendShapeTransitionCapsuleSchema.parse({
+        ...normalized,
+        capsuleDigest: computeCapsuleDigest(normalized),
+    });
+}
+export function parseFrontendShapeTransitionCapsule(value) {
+    const parsed = frontendShapeTransitionCapsuleSchema.parse(value);
+    const normalized = normalizeCapsuleRecord(parsed);
+    if (!stringArraysEqual(parsed.committedFactIds, normalized.committedFactIds) ||
+        !stringArraysEqual(parsed.evidenceRefs, normalized.evidenceRefs) ||
+        (parsed.kind === "reshape" &&
+            !stringArraysEqual(parsed.escalationSignals, normalized.escalationSignals))) {
+        throw new Error("FrontendShapeTransitionCapsule arrays must use canonical sorted unique representation");
+    }
+    const expected = computeCapsuleDigest(normalized);
+    if (parsed.capsuleDigest !== expected) {
+        throw new Error("capsuleDigest does not match canonical fields");
+    }
+    return parsed;
+}

package/dist/workflows/dag/frontend-split-application-service.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { assertFrontendSplitBindingConsistency, buildFrontendOperationExecution, buildFrontendSplitAggregateCloseout, completeFrontendSplitIntegration, completeFrontendSplitIntegrationInputSchema, finalizeFrontendSplitAggregate, frontendCommittedFactRefSchema, frontendOperationExecutionSchema, frontendSplitAggregateCloseoutSchema, frontendSplitCandidateBindingSchema, frontendSplitChildObservationSchema, frontendSplitIntegrationBindingSchema, frontendSplitManifestSchema, frontendSplitParentRecordSchema, isFrontendSplitChildReady, observeFrontendSplitChild, prepareFrontendSplitJoin, } from "./frontend-split-orchestrator.js";
+const idSchema = z.string().trim().min(1);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const positiveIntegerSchema = z.number().int().positive();
+export const frontendSplitProjectionSchema = z.object({
+    revision: positiveIntegerSchema,
+    execution: frontendOperationExecutionSchema,
+    manifest: frontendSplitManifestSchema,
+    parent: frontendSplitParentRecordSchema,
+    candidateBinding: frontendSplitCandidateBindingSchema.optional(),
+    integrationBinding: frontendSplitIntegrationBindingSchema.optional(),
+    aggregateCloseout: z.object({ value: frontendSplitAggregateCloseoutSchema, committedRef: frontendCommittedFactRefSchema }).strict().optional(),
+}).strict().superRefine((value, ctx) => {
+    if (value.revision !== value.parent.operationRevision || value.execution.kind !== "split-parent" || value.execution.operationId !== value.parent.operationId || value.execution.operationRevision !== value.parent.operationRevision || value.execution.parentRecordDigest !== value.parent.digest)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "revision/execution/parent projection mismatch" });
+    if (value.manifest.parentOperationId !== value.parent.operationId || value.manifest.digest !== value.parent.manifestDigest)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "manifest/parent projection mismatch" });
+    try {
+        assertFrontendSplitBindingConsistency(value);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: error instanceof Error ? error.message : "split projection binding mismatch" });
+    }
+});
+export function assertFrontendSplitProjectionSuccessor(currentValue, nextValue) {
+    const current = frontendSplitProjectionSchema.parse(currentValue);
+    const next = frontendSplitProjectionSchema.parse(nextValue);
+    if (next.revision !== current.revision + 1 || next.parent.operationRevision !== current.parent.operationRevision + 1)
+        throw new Error("split successor revision mismatch");
+    if (JSON.stringify(next.manifest) !== JSON.stringify(current.manifest) || next.parent.operationId !== current.parent.operationId || next.parent.generation !== current.parent.generation || next.parent.sourceRunId !== current.parent.sourceRunId || next.parent.sourceDigest !== current.parent.sourceDigest || next.parent.manifestDigest !== current.parent.manifestDigest)
+        throw new Error("split successor immutable binding mismatch");
+    if (next.parent.operationState === "success" || next.parent.operationTerminal === "success" || next.parent.phase === "closed") {
+        if (!next.aggregateCloseout)
+            throw new Error("split success requires committed aggregate closeout");
+        const finalized = finalizeFrontendSplitAggregate(current.parent, next.aggregateCloseout.value, next.aggregateCloseout.committedRef);
+        const expected = frontendSplitProjectionSchema.parse({ ...current, revision: current.revision + 1, parent: finalized.parent, execution: finalized.execution, aggregateCloseout: next.aggregateCloseout });
+        if (JSON.stringify(next) !== JSON.stringify(expected))
+            throw new Error("split success is not the canonical aggregate successor");
+    }
+    else if (next.aggregateCloseout)
+        throw new Error("non-success successor may not carry aggregate closeout");
+    return next;
+}
+const commandBase = { operationId: idSchema, expectedRevision: positiveIntegerSchema, expectedParentDigest: digestSchema, expectedManifestDigest: digestSchema };
+export const frontendSplitWakeupCommandSchema = z.object(commandBase).strict();
+export const frontendSplitChildCallbackCommandSchema = z.object({ ...commandBase, observation: frontendSplitChildObservationSchema }).strict();
+export const frontendSplitIntegrationCallbackCommandSchema = z.object({ ...commandBase, completion: completeFrontendSplitIntegrationInputSchema }).strict();
+export const frontendSplitFinalizeCommandSchema = z.object(commandBase).strict();
+function commandFreshnessMismatch(projection, command) {
+    if (projection.parent.operationId !== command.operationId)
+        return "operationId";
+    if (projection.revision !== command.expectedRevision)
+        return "expectedRevision";
+    if (projection.parent.digest !== command.expectedParentDigest)
+        return "expectedParentDigest";
+    if (projection.manifest.digest !== command.expectedManifestDigest)
+        return "expectedManifestDigest";
+    return undefined;
+}
+function assertCurrent(raw, command) {
+    const projection = frontendSplitProjectionSchema.parse(raw);
+    if (commandFreshnessMismatch(projection, command))
+        throw new Error("frontend split command freshness mismatch");
+    return projection;
+}
+function executionForParent(parent) {
+    return buildFrontendOperationExecution({ kind: "split-parent", operationId: parent.operationId, operationRevision: parent.operationRevision, sourceRunId: parent.sourceRunId, sourceDigest: parent.sourceDigest, generation: parent.generation, parentRecordDigest: parent.digest });
+}
+function nextProjection(current, patch) {
+    return frontendSplitProjectionSchema.parse({ ...current, ...patch, revision: current.revision + 1 });
+}
+export class FrontendSplitOrchestrator {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async loadProjection(operationId) {
+        const loaded = await this.ports.load(operationId);
+        if (!loaded)
+            throw new Error(`frontend split operation not found: ${operationId}`);
+        return frontendSplitProjectionSchema.parse(loaded);
+    }
+    async loadCurrent(command) {
+        return assertCurrent(await this.loadProjection(command.operationId), command);
+    }
+    async loadCallbackCurrent(command, fact) {
+        const projection = await this.loadProjection(command.operationId);
+        const mismatch = commandFreshnessMismatch(projection, command);
+        if (!mismatch)
+            return projection;
+        await this.ports.auditStale({
+            operationId: command.operationId,
+            reason: "frontend split command freshness mismatch",
+            fact: { mismatch, callbackFact: fact },
+        });
+        return undefined;
+    }
+    cas(current, next) {
+        return this.ports.compareAndSwap({ operationId: current.parent.operationId, expectedRevision: current.revision, expectedExecutionDigest: current.execution.digest, expectedParentDigest: current.parent.digest, next });
+    }
+    async wakeupChildren(raw) {
+        const command = frontendSplitWakeupCommandSchema.parse(raw);
+        const current = await this.loadCurrent(command);
+        const materialized = [];
+        const scheduled = [];
+        for (const childId of current.manifest.topologicalOrder) {
+            const child = current.manifest.children.find((item) => item.childId === childId);
+            const result = await this.ports.materialize({ kind: "child", parentOperationId: current.parent.operationId, manifestDigest: current.manifest.digest, generation: current.parent.generation, taskId: child.taskId, operationId: child.operationId, payloadDigest: current.manifest.digest, allowedPaths: child.allowedPaths, writeSet: child.writeSet, verifyRefs: current.manifest.verifyRefs });
+            if (result.taskId !== child.taskId || result.operationId !== child.operationId)
+                throw new Error("child materialization binding drift");
+            materialized.push(child.operationId);
+            const childControllerOwnsScheduling = current.parent.observations.some((observation) => observation.childId === childId && observation.operationId === child.operationId);
+            if (!childControllerOwnsScheduling && isFrontendSplitChildReady(current.parent, current.manifest, childId)) {
+                await this.ports.schedule({ operationId: child.operationId, generation: current.parent.generation, bindingDigest: current.parent.digest });
+                scheduled.push(child.operationId);
+            }
+        }
+        return { materialized, scheduled };
+    }
+    async childCallback(raw) {
+        const command = frontendSplitChildCallbackCommandSchema.parse(raw);
+        const current = await this.loadCallbackCurrent(command, command.observation);
+        if (!current)
+            return { outcome: "ignored-stale" };
+        const reduced = observeFrontendSplitChild(current.parent, current.manifest, command.observation);
+        if (reduced.outcome === "ignored-stale") {
+            await this.ports.auditStale({ operationId: command.operationId, reason: reduced.auditFact.reason, fact: reduced.auditFact });
+            return { outcome: "ignored-stale" };
+        }
+        return this.cas(current, nextProjection(current, { parent: reduced.parent, execution: executionForParent(reduced.parent) }));
+    }
+    async wakeupIntegration(raw) {
+        const command = frontendSplitWakeupCommandSchema.parse(raw);
+        const current = await this.loadCurrent(command);
+        const integration = current.manifest.integration;
+        const materializeAndSchedule = async (bindingDigest) => {
+            if (!integration.required || !integration.operationId)
+                return;
+            const taskId = `${current.parent.operationId}:integration`;
+            const result = await this.ports.materialize({ kind: "integration", parentOperationId: current.parent.operationId, manifestDigest: current.manifest.digest, generation: current.parent.generation, taskId, operationId: integration.operationId, payloadDigest: bindingDigest, allowedPaths: integration.allowedPaths, writeSet: integration.writeSet, verifyRefs: integration.verifyRefs });
+            if (result.taskId !== taskId || result.operationId !== integration.operationId)
+                throw new Error("integration materialization binding drift");
+            await this.ports.schedule({ operationId: integration.operationId, generation: current.parent.generation, bindingDigest });
+        };
+        if (current.parent.phase === "awaiting-integration") {
+            if (!integration.required || !current.candidateBinding)
+                return { outcome: "not-ready" };
+            await materializeAndSchedule(current.candidateBinding.digest);
+            return { outcome: "scheduled-existing" };
+        }
+        const joined = prepareFrontendSplitJoin(current.parent, current.manifest);
+        if (joined.outcome === "not-ready")
+            return { outcome: "not-ready" };
+        if (integration.required) {
+            const taskId = `${current.parent.operationId}:integration`;
+            const result = await this.ports.materialize({ kind: "integration", parentOperationId: current.parent.operationId, manifestDigest: current.manifest.digest, generation: current.parent.generation, taskId, operationId: integration.operationId, payloadDigest: joined.binding.digest, allowedPaths: integration.allowedPaths, writeSet: integration.writeSet, verifyRefs: integration.verifyRefs });
+            if (result.taskId !== taskId || result.operationId !== integration.operationId)
+                throw new Error("integration materialization binding drift");
+        }
+        const next = nextProjection(current, { parent: joined.parent, execution: executionForParent(joined.parent), candidateBinding: joined.binding });
+        const applied = await this.cas(current, next);
+        if (applied.outcome === "applied" && integration.required)
+            await this.ports.schedule({ operationId: integration.operationId, generation: current.parent.generation, bindingDigest: joined.binding.digest });
+        return applied;
+    }
+    async integrationCallback(raw) {
+        const command = frontendSplitIntegrationCallbackCommandSchema.parse(raw);
+        const current = await this.loadCallbackCurrent(command, command.completion);
+        if (!current)
+            return { outcome: "ignored-stale" };
+        if (!current.candidateBinding)
+            throw new Error("candidate binding is missing");
+        const completed = completeFrontendSplitIntegration(current.parent, current.manifest, current.candidateBinding, command.completion);
+        if (completed.outcome === "ignored-stale") {
+            await this.ports.auditStale({ operationId: command.operationId, reason: completed.reason, fact: command.completion });
+            return { outcome: "ignored-stale" };
+        }
+        return this.cas(current, nextProjection(current, { parent: completed.parent, execution: executionForParent(completed.parent), integrationBinding: completed.binding }));
+    }
+    async finalize(raw) {
+        const command = frontendSplitFinalizeCommandSchema.parse(raw);
+        const current = await this.loadCurrent(command);
+        if (!current.candidateBinding)
+            throw new Error("candidate binding is missing");
+        const childCloseoutFacts = [];
+        for (const child of current.candidateBinding.children) {
+            childCloseoutFacts.push(await this.ports.loadChildCloseoutFacts({ childId: child.childId, closeoutRef: child.closeoutRef }));
+        }
+        const aggregate = buildFrontendSplitAggregateCloseout(current.parent, current.manifest, current.candidateBinding, current.integrationBinding, childCloseoutFacts);
+        return this.ports.settleAggregate({
+            operationId: current.parent.operationId,
+            expectedRevision: current.revision,
+            expectedExecutionDigest: current.execution.digest,
+            expectedParentDigest: current.parent.digest,
+            expectedManifestDigest: current.manifest.digest,
+            expectedCandidateBindingDigest: current.candidateBinding.digest,
+            expectedIntegrationBindingDigest: current.integrationBinding?.digest,
+            childCloseoutFacts,
+            aggregate,
+        });
+    }
+}