@litterthanlit/hypher-cli 0.1.0

package/vendor/structuredHandoff.mjs

@@ -0,0 +1,796 @@
+// Generated from hypher-web/shared/structuredHandoff.ts by script/sync-hypher-shared.mjs. Do not edit.
+/**
+ * Versioned handoff proposal for an explicit agent switch.
+ * Hypher validates and stores the note. It does not transfer files.
+ */
+import { findSecretInValue } from "./secretScan.mjs";
+export const HANDOFF_PROPOSAL_SCHEMA_VERSION = 1;
+const MAX_ITEMS = 8;
+const MAX_SHORT = 280;
+const MAX_GOAL = 600;
+const MAX_KEY = 200;
+const MAX_BRANCH = 200;
+const MAX_COMMIT = 80;
+const MAX_DESTINATION = 80;
+const MAX_REASON = 500;
+const PROPOSAL_KEYS = new Set([
+    "schemaVersion",
+    "goal",
+    "constraints",
+    "decisions",
+    "completed",
+    "unverified",
+    "blockers",
+    "nextAction",
+    "sources",
+    "repo",
+]);
+export const HANDOFF_PROPOSAL_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "schemaVersion",
+        "goal",
+        "constraints",
+        "decisions",
+        "completed",
+        "unverified",
+        "blockers",
+        "nextAction",
+        "sources",
+        "repo",
+    ],
+    properties: {
+        schemaVersion: { type: "integer", const: 1 },
+        goal: { type: "string" },
+        constraints: { type: "array", items: { type: "string" } },
+        decisions: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["decision", "reason"],
+                properties: {
+                    decision: { type: "string" },
+                    reason: { type: "string" },
+                    status: { type: "string", enum: ["reported", "approved"] },
+                    sourceRefs: { type: "array", minItems: 1, items: { type: "string" } },
+                    supersedes: { type: "string" },
+                },
+            },
+        },
+        completed: { type: "array", items: { type: "string" } },
+        unverified: { type: "array", items: { type: "string" } },
+        blockers: { type: "array", items: { type: "string" } },
+        nextAction: { type: "string" },
+        sources: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["ref"],
+                properties: {
+                    ref: { type: "string" },
+                    label: { type: "string" },
+                    kind: { type: "string", enum: ["agent_report", "capture", "agent_event"] },
+                    sourceId: { type: "string" },
+                },
+            },
+        },
+        repo: {
+            type: "object",
+            additionalProperties: false,
+            required: ["branch", "commit", "dirty"],
+            properties: {
+                repository: { type: "string" },
+                branch: { type: "string" },
+                commit: { type: "string" },
+                dirty: { type: "boolean" },
+                worktreePath: { type: "string" },
+                dirtyFingerprint: { type: "string" },
+            },
+            description: "Working-tree metadata. This snapshot does not include file contents.",
+        },
+    },
+};
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function unknownKey(value, allowed) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            return key;
+    }
+    return null;
+}
+function shortText(value, field, max) {
+    if (typeof value !== "string")
+        return { ok: false, error: `${field} must be a string` };
+    const cleaned = value.trim();
+    if (!cleaned)
+        return { ok: false, error: `${field} is required` };
+    if (cleaned.length > max)
+        return { ok: false, error: `${field} is too long` };
+    return { ok: true, value: cleaned };
+}
+function stringList(value, field, min) {
+    if (!Array.isArray(value))
+        return { ok: false, error: `${field} must be an array` };
+    if (value.length > MAX_ITEMS)
+        return { ok: false, error: `${field} has too many items` };
+    if (value.length < min)
+        return { ok: false, error: `${field} is required` };
+    const items = [];
+    for (const item of value) {
+        const parsed = shortText(item, field, MAX_SHORT);
+        if (!parsed.ok)
+            return parsed;
+        items.push(parsed.value);
+    }
+    return { ok: true, value: items };
+}
+export function parseRepoSnapshot(value) {
+    if (!isObject(value))
+        return { ok: false, error: "repo must be an object" };
+    const extra = unknownKey(value, new Set(["repository", "branch", "commit", "dirty", "worktreePath", "dirtyFingerprint"]));
+    if (extra)
+        return { ok: false, error: `repo.${extra} is not allowed` };
+    const branch = shortText(value.branch, "repo.branch", MAX_BRANCH);
+    if (!branch.ok)
+        return branch;
+    const commit = shortText(value.commit, "repo.commit", MAX_COMMIT);
+    if (!commit.ok)
+        return commit;
+    if (typeof value.dirty !== "boolean")
+        return { ok: false, error: "repo.dirty must be a boolean" };
+    const result = { branch: branch.value, commit: commit.value, dirty: value.dirty };
+    for (const field of ["repository", "worktreePath", "dirtyFingerprint"]) {
+        if (value[field] === undefined)
+            continue;
+        const parsed = shortText(value[field], `repo.${field}`, field === "worktreePath" ? 1_000 : MAX_SHORT);
+        if (!parsed.ok)
+            return parsed;
+        result[field] = parsed.value;
+    }
+    return { ok: true, value: result };
+}
+const PLACEHOLDER_PREFIX = "FILL:";
+function isPlaceholder(value) {
+    return typeof value === "string" && value.trim().startsWith(PLACEHOLDER_PREFIX);
+}
+/** First field of a parsed proposal that still holds a template `FILL:` placeholder. */
+export function findHandoffPlaceholder(proposal) {
+    if (isPlaceholder(proposal.goal))
+        return "goal";
+    for (const field of ["constraints", "completed", "unverified", "blockers"]) {
+        if (proposal[field].some(isPlaceholder))
+            return field;
+    }
+    for (const item of proposal.decisions) {
+        if (isPlaceholder(item.decision))
+            return "decisions.decision";
+        if (isPlaceholder(item.reason))
+            return "decisions.reason";
+        if (isPlaceholder(item.supersedes))
+            return "decisions.supersedes";
+        if (item.sourceRefs?.some(isPlaceholder))
+            return "decisions.sourceRefs";
+    }
+    if (isPlaceholder(proposal.nextAction))
+        return "nextAction";
+    for (const item of proposal.sources) {
+        if (isPlaceholder(item.ref))
+            return "sources.ref";
+        if (isPlaceholder(item.label))
+            return "sources.label";
+        if (isPlaceholder(item.sourceId))
+            return "sources.sourceId";
+    }
+    for (const field of ["repository", "branch", "commit", "worktreePath", "dirtyFingerprint"]) {
+        if (isPlaceholder(proposal.repo[field]))
+            return `repo.${field}`;
+    }
+    return null;
+}
+/**
+ * Validate a proposal. New writes reject template `FILL:` placeholders; pass
+ * `allowPlaceholders` only to re-read rows stored before that guard existed.
+ */
+export function parseHandoffProposal(value, options = {}) {
+    if (!isObject(value))
+        return { ok: false, error: "proposal must be an object" };
+    const extra = unknownKey(value, PROPOSAL_KEYS);
+    if (extra)
+        return { ok: false, error: `proposal.${extra} is not allowed` };
+    if (value.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION) {
+        return { ok: false, error: "proposal.schemaVersion must be 1" };
+    }
+    const goal = shortText(value.goal, "goal", MAX_GOAL);
+    if (!goal.ok)
+        return goal;
+    const constraints = stringList(value.constraints, "constraints", 0);
+    if (!constraints.ok)
+        return constraints;
+    const completed = stringList(value.completed, "completed", 0);
+    if (!completed.ok)
+        return completed;
+    const unverified = stringList(value.unverified, "unverified", 0);
+    if (!unverified.ok)
+        return unverified;
+    const blockers = stringList(value.blockers, "blockers", 0);
+    if (!blockers.ok)
+        return blockers;
+    const nextAction = shortText(value.nextAction, "nextAction", MAX_SHORT);
+    if (!nextAction.ok)
+        return nextAction;
+    if (!Array.isArray(value.decisions))
+        return { ok: false, error: "decisions must be an array" };
+    if (value.decisions.length === 0)
+        return { ok: false, error: "decisions is required" };
+    if (value.decisions.length > MAX_ITEMS) {
+        return {
+            ok: false,
+            error: `A handoff keeps at most ${MAX_ITEMS} decisions; this one has ${value.decisions.length}. Replace an old one (name it in supersedes) or leave one out. The decision ledger comes in M2.`,
+        };
+    }
+    const decisions = [];
+    for (const item of value.decisions) {
+        if (!isObject(item))
+            return { ok: false, error: "decisions must be objects" };
+        const decisionExtra = unknownKey(item, new Set(["decision", "reason", "status", "sourceRefs", "supersedes"]));
+        if (decisionExtra)
+            return { ok: false, error: `decisions.${decisionExtra} is not allowed` };
+        const decision = shortText(item.decision, "decisions.decision", MAX_SHORT);
+        if (!decision.ok)
+            return decision;
+        const reason = shortText(item.reason, "decisions.reason", MAX_SHORT);
+        if (!reason.ok)
+            return reason;
+        const entry = { decision: decision.value, reason: reason.value };
+        if (item.status !== undefined) {
+            if (item.status !== "reported" && item.status !== "approved")
+                return { ok: false, error: "decisions.status is invalid" };
+            entry.status = item.status;
+        }
+        if (item.sourceRefs !== undefined) {
+            const sourceRefs = stringList(item.sourceRefs, "decisions.sourceRefs", 1);
+            if (!sourceRefs.ok)
+                return sourceRefs;
+            entry.sourceRefs = sourceRefs.value;
+        }
+        if (item.supersedes !== undefined) {
+            const supersedes = shortText(item.supersedes, "decisions.supersedes", MAX_SHORT);
+            if (!supersedes.ok)
+                return supersedes;
+            entry.supersedes = supersedes.value;
+        }
+        decisions.push(entry);
+    }
+    if (new Set(decisions.map((item) => item.decision.toLowerCase())).size !== decisions.length) {
+        return { ok: false, error: "decisions.decision must be unique" };
+    }
+    if (!Array.isArray(value.sources))
+        return { ok: false, error: "sources must be an array" };
+    if (value.sources.length === 0)
+        return { ok: false, error: "sources is required" };
+    if (value.sources.length > MAX_ITEMS)
+        return { ok: false, error: "sources has too many items" };
+    const sources = [];
+    for (const item of value.sources) {
+        if (!isObject(item))
+            return { ok: false, error: "sources must be objects" };
+        const sourceExtra = unknownKey(item, new Set(["ref", "label", "kind", "sourceId"]));
+        if (sourceExtra)
+            return { ok: false, error: `sources.${sourceExtra} is not allowed` };
+        const ref = shortText(item.ref, "sources.ref", MAX_SHORT);
+        if (!ref.ok)
+            return ref;
+        const source = { ref: ref.value };
+        if (item.label !== undefined) {
+            const label = shortText(item.label, "sources.label", MAX_SHORT);
+            if (!label.ok)
+                return label;
+            source.label = label.value;
+        }
+        if (item.kind !== undefined) {
+            if (item.kind !== "agent_report" && item.kind !== "capture" && item.kind !== "agent_event") {
+                return { ok: false, error: "sources.kind is invalid" };
+            }
+            source.kind = item.kind;
+        }
+        if (item.sourceId !== undefined) {
+            const sourceId = shortText(item.sourceId, "sources.sourceId", MAX_SHORT);
+            if (!sourceId.ok)
+                return sourceId;
+            source.sourceId = sourceId.value;
+        }
+        if ((source.kind === "capture" || source.kind === "agent_event") !== Boolean(source.sourceId)) {
+            return { ok: false, error: "Stored sources require a sourceId; agent reports cannot have one" };
+        }
+        sources.push(source);
+    }
+    const refs = new Set(sources.map((source) => source.ref));
+    if (refs.size !== sources.length)
+        return { ok: false, error: "sources.ref must be unique" };
+    for (const decision of decisions) {
+        if (decision.sourceRefs?.some((ref) => !refs.has(ref))) {
+            return { ok: false, error: "decisions.sourceRefs must refer to proposal sources" };
+        }
+    }
+    const repo = parseRepoSnapshot(value.repo);
+    if (!repo.ok)
+        return repo;
+    const proposal = {
+        schemaVersion: 1,
+        goal: goal.value,
+        constraints: constraints.value,
+        decisions,
+        completed: completed.value,
+        unverified: unverified.value,
+        blockers: blockers.value,
+        nextAction: nextAction.value,
+        sources,
+        repo: repo.value,
+    };
+    if (!options.allowPlaceholders) {
+        const placeholder = findHandoffPlaceholder(proposal);
+        if (placeholder)
+            return { ok: false, error: `${placeholder} still contains a FILL: placeholder` };
+        // Saved text reaches every later session, so a secret is refused, never stored.
+        const secret = findSecretInValue(proposal);
+        if (secret)
+            return { ok: false, error: `${secret.field} looks like ${secret.shape}. Remove it; Hypher never stores secrets.` };
+    }
+    return { ok: true, value: proposal };
+}
+export function renderHandoffPacket(proposal) {
+    const lines = [
+        `Goal: ${proposal.goal}`,
+        proposal.constraints.length ? `Constraints: ${proposal.constraints.join("; ")}` : "Constraints: none",
+        "Decisions:",
+        ...proposal.decisions.map((item) => `- ${item.status === "approved" ? "Approved" : "Agent-reported"}: ${item.decision} — ${item.reason}${item.sourceRefs?.length ? ` [${item.sourceRefs.join(", ")}]` : ""}${item.supersedes ? ` (supersedes: ${item.supersedes})` : ""}`),
+        proposal.completed.length ? `Agent-reported completed work: ${proposal.completed.join("; ")}` : "Agent-reported completed work: none",
+        proposal.unverified.length ? `Unverified: ${proposal.unverified.join("; ")}` : "Unverified: none",
+        proposal.blockers.length ? `Blockers: ${proposal.blockers.join("; ")}` : "Blockers: none",
+        `Next action: ${proposal.nextAction}`,
+        "Sources:",
+        ...proposal.sources.map((item) => `- ${item.kind === "capture" ? "Project capture" : item.kind === "agent_event" ? "Stored agent report" : "Agent-reported"}: ${item.label ? `${item.label}: ` : ""}${item.ref}`),
+        `Repo: ${proposal.repo.repository ?? "identity unavailable"}, branch ${proposal.repo.branch}, commit ${proposal.repo.commit}, dirty ${proposal.repo.dirty}`,
+        "Memory does not transfer code or uncommitted files.",
+    ];
+    return lines.join("\n");
+}
+export function compareRepoSnapshot(saved, current) {
+    const parts = [];
+    if (!saved.repository || !current.repository || saved.repository !== current.repository) {
+        parts.push(`repository is ${current.repository ?? "unknown"}; handoff recorded ${saved.repository ?? "unknown"}`);
+    }
+    if (saved.branch !== current.branch) {
+        parts.push(`branch is ${current.branch}; handoff recorded ${saved.branch}`);
+    }
+    if (saved.commit !== current.commit) {
+        parts.push(`commit is ${current.commit}; handoff recorded ${saved.commit}`);
+    }
+    if (saved.dirty !== current.dirty) {
+        parts.push(`dirty is ${String(current.dirty)}; handoff recorded ${String(saved.dirty)}`);
+    }
+    if (saved.worktreePath && current.worktreePath && saved.worktreePath !== current.worktreePath) {
+        parts.push("local worktree path differs");
+    }
+    if (saved.dirty && (!saved.dirtyFingerprint || !current.dirtyFingerprint || saved.dirtyFingerprint !== current.dirtyFingerprint)) {
+        parts.push("dirty file contents were not verified as the same");
+    }
+    if (parts.length === 0)
+        return { match: true, warning: "Supplied repository metadata matches. Inspect the local working tree before continuing; Hypher did not verify file contents." };
+    return {
+        match: false,
+        warning: `Supplied repository metadata does not establish the same working tree (${parts.join("; ")}). Memory did not transfer code or uncommitted files. Compare the tree yourself before continuing.`,
+    };
+}
+function integerRevision(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 1_000_000) {
+        return { ok: false, error: "expectedBaseRevision must be a non-negative integer" };
+    }
+    return { ok: true, value };
+}
+export function commitStructuredHandoff(input) {
+    const key = input.idempotencyKey.trim();
+    if (!key || key.length > MAX_KEY) {
+        return {
+            ok: false,
+            status: 400,
+            code: "invalid",
+            error: "idempotencyKey is required",
+            headRevision: input.headRevision,
+        };
+    }
+    if (input.existingKeyRevision !== null) {
+        return {
+            ok: false,
+            status: 409,
+            code: "duplicate",
+            error: `Duplicate handoff write. Idempotency key already stored at revision ${input.existingKeyRevision}.`,
+            headRevision: input.headRevision,
+            revision: input.existingKeyRevision,
+        };
+    }
+    if (input.expectedBaseRevision !== input.headRevision) {
+        return {
+            ok: false,
+            status: 409,
+            code: "stale-revision",
+            error: `Stale handoff revision. Expected base ${input.expectedBaseRevision}, current revision is ${input.headRevision}.`,
+            headRevision: input.headRevision,
+        };
+    }
+    const revision = input.headRevision + 1;
+    return {
+        ok: true,
+        head: {
+            projectId: input.projectId,
+            revision,
+            idempotencyKey: key,
+            proposal: input.proposal,
+            source: input.source,
+            savedAt: input.savedAt,
+        },
+    };
+}
+/** A revision is a full current snapshot; prior decisions need an explicit sourced retirement. */
+export function validateDecisionTransition(previous, next, approvedSourceRefs) {
+    const prior = new Map((previous?.decisions ?? []).map((item) => [item.decision.toLowerCase(), item]));
+    const current = new Set(next.decisions.map((item) => item.decision.toLowerCase()));
+    const superseded = new Set();
+    for (const item of next.decisions) {
+        const oldDecision = prior.get(item.decision.toLowerCase());
+        if (oldDecision?.status === "approved" && item.status !== "approved") {
+            return `Approved decision cannot be downgraded: ${item.decision}`;
+        }
+        const linkedApproval = item.sourceRefs?.some((ref) => approvedSourceRefs.has(ref)) ?? false;
+        if (item.status === "approved" && !linkedApproval) {
+            return `Approved decision requires a linked, project-owned pinned decision capture: ${item.decision}`;
+        }
+        if (!item.supersedes)
+            continue;
+        const old = item.supersedes.toLowerCase();
+        // Carried forward with the same supersession: that was checked when it was recorded.
+        if (oldDecision && oldDecision.supersedes?.toLowerCase() === old) {
+            if (current.has(old))
+                return `Invalid decision supersession: ${item.supersedes}`;
+            continue;
+        }
+        const retired = prior.get(old);
+        if (!retired || current.has(old) || superseded.has(old)) {
+            return `Invalid decision supersession: ${item.supersedes}`;
+        }
+        if (retired.status === "approved" && (item.status !== "approved" || !linkedApproval)) {
+            return `Approved decision supersession requires an approved, sourced decision: ${item.decision}`;
+        }
+        if (!item.sourceRefs?.length) {
+            return `Decision supersession requires a linked source: ${item.decision}`;
+        }
+        superseded.add(old);
+    }
+    for (const item of previous?.decisions ?? []) {
+        const key = item.decision.toLowerCase();
+        if (!current.has(key) && !superseded.has(key)) {
+            return `Decision cannot disappear without sourced supersession: ${item.decision}`;
+        }
+    }
+    return null;
+}
+export function planHandoffDelivery(input) {
+    if (input.destinationProjectId !== input.handoffProjectId) {
+        return {
+            ok: false,
+            status: 400,
+            code: "wrong-project",
+            error: "Destination project does not match the handoff project.",
+        };
+    }
+    const destination = input.destination.trim();
+    if (!destination || destination.length > MAX_DESTINATION) {
+        return { ok: false, status: 400, code: "invalid", error: "destination is required" };
+    }
+    if (!input.head) {
+        return {
+            ok: false,
+            status: 400,
+            code: "no-handoff",
+            error: "No structured handoff is stored for this project.",
+        };
+    }
+    const comparison = compareRepoSnapshot(input.head.proposal.repo, input.currentRepo);
+    const reason = input.reason?.trim();
+    if (reason && reason.length > MAX_REASON) {
+        return { ok: false, status: 400, code: "invalid", error: "reason is too long" };
+    }
+    const receipt = {
+        projectId: input.handoffProjectId,
+        revision: input.head.revision,
+        destination,
+        result: input.result,
+        reason: reason || undefined,
+        repoWarning: comparison.warning,
+        createdAt: input.createdAt,
+    };
+    if (input.result === "failed") {
+        return {
+            ok: false,
+            status: 409,
+            code: "failed-delivery",
+            error: reason || "Handoff delivery failed. The last valid handoff was preserved.",
+            preservedRevision: input.head.revision,
+            proposal: input.head.proposal,
+            repoSnapshot: input.head.proposal.repo,
+            repoMatch: comparison.match,
+            warning: comparison.warning,
+            transfersCode: false,
+            checksOut: false,
+            receipt,
+        };
+    }
+    return {
+        ok: true,
+        status: 200,
+        code: "prepared",
+        revision: input.head.revision,
+        proposal: input.head.proposal,
+        repoSnapshot: input.head.proposal.repo,
+        repoMatch: comparison.match,
+        warning: comparison.warning,
+        transfersCode: false,
+        checksOut: false,
+        receipt,
+    };
+}
+export function readHandoffCommand(value) {
+    if (!isObject(value))
+        return { ok: true, command: null };
+    const hasSave = "proposal" in value || "expectedBaseRevision" in value || "idempotencyKey" in value;
+    const hasResume = "resume" in value && value.resume !== undefined;
+    const hasAcknowledge = "acknowledge" in value && value.acknowledge !== undefined;
+    if (Number(hasSave) + Number(hasResume) + Number(hasAcknowledge) > 1) {
+        return { ok: false, error: "Send one handoff save, resume, or acknowledgment." };
+    }
+    if (!hasSave && !hasResume && !hasAcknowledge)
+        return { ok: true, command: null };
+    const projectId = typeof value.projectId === "string" && value.projectId.trim()
+        ? value.projectId.trim()
+        : undefined;
+    if (hasAcknowledge) {
+        if (!isObject(value.acknowledge))
+            return { ok: false, error: "acknowledge must be an object" };
+        const extra = unknownKey(value.acknowledge, new Set(["receiptId", "revision", "destination"]));
+        if (extra)
+            return { ok: false, error: `acknowledge.${extra} is not allowed` };
+        const receiptId = shortText(value.acknowledge.receiptId, "acknowledge.receiptId", MAX_KEY);
+        if (!receiptId.ok)
+            return receiptId;
+        const destination = shortText(value.acknowledge.destination, "acknowledge.destination", MAX_DESTINATION);
+        if (!destination.ok)
+            return destination;
+        const revision = integerRevision(value.acknowledge.revision);
+        if (!revision.ok || revision.value < 1)
+            return { ok: false, error: "acknowledge.revision must be positive" };
+        return { ok: true, command: { type: "acknowledge", projectId, receiptId: receiptId.value,
+                revision: revision.value, destination: destination.value } };
+    }
+    if (hasResume) {
+        if (!isObject(value.resume))
+            return { ok: false, error: "resume must be an object" };
+        const extra = unknownKey(value.resume, new Set(["destination", "destinationProjectId", "currentRepo", "result", "reason"]));
+        if (extra)
+            return { ok: false, error: `resume.${extra} is not allowed` };
+        const destination = shortText(value.resume.destination, "destination", MAX_DESTINATION);
+        if (!destination.ok)
+            return destination;
+        const currentRepo = parseRepoSnapshot(value.resume.currentRepo);
+        if (!currentRepo.ok)
+            return currentRepo;
+        let result = "prepared";
+        if (value.resume.result !== undefined) {
+            if (value.resume.result !== "delivered" && value.resume.result !== "prepared" && value.resume.result !== "failed") {
+                return { ok: false, error: "resume.result must be prepared or failed" };
+            }
+            result = value.resume.result === "delivered" ? "prepared" : value.resume.result;
+        }
+        let reason;
+        if (value.resume.reason !== undefined) {
+            const parsedReason = shortText(value.resume.reason, "reason", MAX_REASON);
+            if (!parsedReason.ok)
+                return parsedReason;
+            reason = parsedReason.value;
+        }
+        let destinationProjectId;
+        if (value.resume.destinationProjectId !== undefined) {
+            if (typeof value.resume.destinationProjectId !== "string" || !value.resume.destinationProjectId.trim()) {
+                return { ok: false, error: "destinationProjectId must be a string" };
+            }
+            destinationProjectId = value.resume.destinationProjectId.trim();
+        }
+        return {
+            ok: true,
+            command: {
+                type: "resume",
+                projectId,
+                destination: destination.value,
+                destinationProjectId,
+                currentRepo: currentRepo.value,
+                result,
+                reason,
+            },
+        };
+    }
+    if (!("proposal" in value)) {
+        return { ok: false, error: "Structured handoff save requires a proposal." };
+    }
+    const proposal = parseHandoffProposal(value.proposal);
+    if (!proposal.ok)
+        return proposal;
+    let expectedBaseRevision;
+    if (value.expectedBaseRevision !== undefined) {
+        const parsedBase = integerRevision(value.expectedBaseRevision);
+        if (!parsedBase.ok)
+            return parsedBase;
+        expectedBaseRevision = parsedBase.value;
+    }
+    let idempotencyKey;
+    if (value.idempotencyKey !== undefined) {
+        const parsedKey = shortText(value.idempotencyKey, "idempotencyKey", MAX_KEY);
+        if (!parsedKey.ok)
+            return parsedKey;
+        idempotencyKey = parsedKey.value;
+    }
+    if (value.kind !== undefined && value.kind !== "handoff") {
+        return { ok: false, error: "Structured handoff save requires kind handoff." };
+    }
+    return {
+        ok: true,
+        command: {
+            type: "save",
+            projectId,
+            ...(expectedBaseRevision !== undefined ? { expectedBaseRevision } : {}),
+            ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
+            proposal: proposal.value,
+            eventDefaults: {
+                kind: "handoff",
+                title: `Handoff: ${proposal.value.goal}`.slice(0, 200),
+                body: renderHandoffPacket(proposal.value).slice(0, 9_000),
+            },
+        },
+    };
+}
+export function parseResumeCall(args) {
+    const destination = shortText(args.destination, "destination", MAX_DESTINATION);
+    if (!destination.ok)
+        return destination;
+    const currentRepo = parseRepoSnapshot(args.currentRepo);
+    if (!currentRepo.ok)
+        return currentRepo;
+    let result = "prepared";
+    if (args.deliveryResult !== undefined) {
+        if (args.deliveryResult !== "delivered" && args.deliveryResult !== "prepared" && args.deliveryResult !== "failed") {
+            return { ok: false, error: "deliveryResult must be prepared or failed" };
+        }
+        result = args.deliveryResult === "delivered" ? "prepared" : args.deliveryResult;
+    }
+    let reason;
+    if (args.reason !== undefined) {
+        const parsed = shortText(args.reason, "reason", MAX_REASON);
+        if (!parsed.ok)
+            return parsed;
+        reason = parsed.value;
+    }
+    let destinationProjectId = args.projectId;
+    if (args.destinationProjectId !== undefined) {
+        if (typeof args.destinationProjectId !== "string" || !args.destinationProjectId.trim()) {
+            return { ok: false, error: "destinationProjectId must be a string" };
+        }
+        destinationProjectId = args.destinationProjectId.trim();
+    }
+    return {
+        ok: true,
+        value: {
+            projectId: args.projectId,
+            destinationProjectId,
+            destination: destination.value,
+            currentRepo: currentRepo.value,
+            result,
+            reason,
+        },
+    };
+}
+/**
+ * The base revision for a save that did not name one: the revision this
+ * caller was last handed (its latest prepared receipt), never whatever is
+ * newest now, so a stale save is still rejected. Null means resume first.
+ */
+export function baseRevisionForSave(input) {
+    if (input.expectedBaseRevision !== undefined)
+        return { ok: true, value: input.expectedBaseRevision };
+    if (input.lastHandedRevision !== null)
+        return { ok: true, value: input.lastHandedRevision };
+    if (input.headRevision === 0)
+        return { ok: true, value: 0 };
+    return {
+        ok: false,
+        error: `A handoff (revision ${input.headRevision}) exists that this session has not read. Resume first (prepare_handoff with currentRepo), then save.`,
+    };
+}
+/** Stable JSON: keys sorted, undefined dropped. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().filter((key) => record[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** SHA-256 hex in plain JavaScript, so Convex queries, mutations, and Node agree. */
+export function sha256Hex(text) {
+    const bytes = new TextEncoder().encode(text);
+    const K = new Uint32Array([
+        0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+        0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+        0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+        0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+        0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+        0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+        0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+        0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+    ]);
+    const H = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const length = bytes.length;
+    const padded = new Uint8Array(((length + 9 + 63) >> 6) << 6);
+    padded.set(bytes);
+    padded[length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(length / 0x20000000));
+    view.setUint32(padded.length - 4, (length << 3) >>> 0);
+    const W = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let t = 0; t < 16; t += 1)
+            W[t] = view.getUint32(offset + t * 4);
+        for (let t = 16; t < 64; t += 1) {
+            const s0 = rotr(W[t - 15], 7) ^ rotr(W[t - 15], 18) ^ (W[t - 15] >>> 3);
+            const s1 = rotr(W[t - 2], 17) ^ rotr(W[t - 2], 19) ^ (W[t - 2] >>> 10);
+            W[t] = (W[t - 16] + s0 + W[t - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = H;
+        for (let t = 0; t < 64; t += 1) {
+            const t1 = (h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[t] + W[t]) >>> 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        H[0] = (H[0] + a) >>> 0;
+        H[1] = (H[1] + b) >>> 0;
+        H[2] = (H[2] + c) >>> 0;
+        H[3] = (H[3] + d) >>> 0;
+        H[4] = (H[4] + e) >>> 0;
+        H[5] = (H[5] + f) >>> 0;
+        H[6] = (H[6] + g) >>> 0;
+        H[7] = (H[7] + h) >>> 0;
+    }
+    return Array.from(H, (word) => word.toString(16).padStart(8, "0")).join("");
+}
+/**
+ * The key for a save that did not name one: the base revision plus the full
+ * request. A retry dedupes; a change that returns to earlier content has a
+ * newer base, so it is not mistaken for a duplicate.
+ */
+export function defaultIdempotencyKey(baseRevision, request) {
+    return `auto-${sha256Hex(`${baseRevision}\n${canonicalJson(request)}`).slice(0, 48)}`;
+}