@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/internal/woodstock/client-projection.js

@@ -0,0 +1,512 @@
+import { readSessionAttention } from "./session-attention.js";
+import { ShiitakeError } from "../../errors.js";
+import { decodeWoodstockCursor, encodeWoodstockCursor } from "./cursor.js";
+import { operatorClientMessage, promptCommand } from "./session-entry.js";
+import { lineageEntrySequence, lineageHasSequence, lineageRowLimit, readLineageWindow, readLineageWorkFacts, readSessionEntriesForWork, readSessionLineage, readPendingSessionCommands, readSessionCommandAdmission, } from "./session-store.js";
+const maximumPagePayloadBytes = 2_097_152;
+const replayPageLimit = 200;
+const maximumRowsPerPage = lineageRowLimit;
+const encoder = new TextEncoder();
+function unavailable(message) {
+    return new ShiitakeError("store", "unavailable", message);
+}
+function commandIdsByWorkId(owner, sessionId, path) {
+    const commandIds = new Map();
+    for (const row of path) {
+        if (row.entry.kind === "command")
+            commandIds.set(row.entry.workId, row.entry.workId);
+    }
+    const unresolved = path.flatMap(({ entry }) => (entry.kind === "run_terminal" || entry.kind === "work_terminal") &&
+        !commandIds.has(entry.workId)
+        ? [entry.workId]
+        : []);
+    for (const workId of unresolved)
+        if (readSessionCommandAdmission(owner, sessionId, workId) !== undefined)
+            commandIds.set(workId, workId);
+    return commandIds;
+}
+function admissionOrigin(owner, sessionId) {
+    return (commandId) => {
+        const origin = readSessionCommandAdmission(owner, sessionId, commandId)?.origin;
+        return origin?.kind === "extension"
+            ? { extensionId: origin.extensionId, correlation: origin.correlation }
+            : undefined;
+    };
+}
+/** Facts from rows already in hand: one work's own entries. */
+function workFacts(owner, sessionId, path) {
+    return {
+        commandIds: commandIdsByWorkId(owner, sessionId, path),
+        diagnostics: diagnosticsByWorkId(path),
+        cancellations: new Map(path.flatMap(({ entry }) => entry.kind === "cancellation" && entry.meta !== undefined
+            ? [[entry.targetWorkId, entry.meta]]
+            : [])),
+        origin: admissionOrigin(owner, sessionId),
+    };
+}
+/**
+ * Facts for one bounded page: only the works its rows show, looked up across
+ * the whole lineage without decoding it (`diagnosticsByWorkId`'s rule, in SQL).
+ */
+function pageWorkFacts(owner, sessionId, lineage, rows) {
+    const shown = new Set(rows.flatMap(({ entry }) => entry.kind === "message" ||
+        entry.kind === "run_terminal" ||
+        entry.kind === "work_terminal"
+        ? [entry.workId]
+        : []));
+    const facts = readLineageWorkFacts(owner, lineage, shown);
+    const commandIds = new Map();
+    for (const workId of facts.commands)
+        commandIds.set(workId, workId);
+    for (const { entry } of rows)
+        if ((entry.kind === "run_terminal" || entry.kind === "work_terminal") &&
+            !commandIds.has(entry.workId) &&
+            readSessionCommandAdmission(owner, sessionId, entry.workId) !== undefined)
+            commandIds.set(entry.workId, entry.workId);
+    return {
+        commandIds,
+        diagnostics: facts.diagnostics,
+        cancellations: facts.cancellations,
+        origin: admissionOrigin(owner, sessionId),
+    };
+}
+function projectMessage(row, work) {
+    // A compaction request has no message; its compaction marker and its
+    // terminal are what clients see of it.
+    const prompt = promptCommand(row.entry);
+    if (prompt !== undefined) {
+        const origin = work.origin(prompt.workId);
+        const message = {
+            id: row.id,
+            sequence: row.sequence,
+            commandId: prompt.workId,
+            value: prompt.message,
+        };
+        let projected = message;
+        if (prompt.meta !== undefined)
+            projected = { ...projected, meta: prompt.meta };
+        if (origin !== undefined)
+            projected = { ...projected, origin };
+        return Object.freeze(projected);
+    }
+    if (row.entry.kind === "operator") {
+        const message = {
+            id: row.id,
+            sequence: row.sequence,
+            commandId: null,
+            value: operatorClientMessage(row.entry),
+        };
+        let projected = message;
+        if (row.entry.meta !== undefined)
+            projected = { ...projected, meta: row.entry.meta };
+        return Object.freeze(projected);
+    }
+    if (row.entry.kind === "message")
+        return Object.freeze({
+            id: row.entry.message.value,
+            sequence: row.sequence,
+            commandId: work.commandIds.get(row.entry.workId) ?? null,
+            value: row.entry.value,
+        });
+    return undefined;
+}
+/**
+ * Newest failure message each work recorded: a work-terminal diagnostic, an
+ * assistant error or a final retry error. Raw text; clients and the reply
+ * fan-out decide how to present and bound it.
+ */
+export function diagnosticsByWorkId(path) {
+    const diagnostics = new Map();
+    for (const { entry } of path) {
+        if (entry.kind === "work_terminal" && entry.diagnostic !== undefined) {
+            diagnostics.set(entry.workId, entry.diagnostic);
+        }
+        else if (entry.kind === "message" && entry.value.role === "assistant") {
+            if (entry.value.errorMessage !== undefined)
+                diagnostics.set(entry.workId, entry.value.errorMessage);
+        }
+        else if (entry.kind === "live_retry" &&
+            entry.event.type === "auto_retry_end" &&
+            entry.event.finalError !== undefined)
+            diagnostics.set(entry.workId, entry.event.finalError);
+    }
+    return diagnostics;
+}
+function projectTerminal(row, { commandIds, diagnostics, cancellations }) {
+    if (row.entry.kind !== "run_terminal" && row.entry.kind !== "work_terminal")
+        return undefined;
+    const commandId = commandIds.get(row.entry.workId);
+    if (commandId === undefined)
+        return undefined;
+    const terminal = {
+        commandId,
+        outcome: row.entry.outcome,
+        sequence: row.sequence,
+        diagnostic: diagnostics.get(row.entry.workId) ?? null,
+    };
+    const meta = row.entry.outcome === "cancelled"
+        ? cancellations.get(row.entry.workId)
+        : undefined;
+    return Object.freeze(meta === undefined ? terminal : { ...terminal, meta });
+}
+/**
+ * Full-history client projections show every durable entry, including what a
+ * compaction summarized away. Each compaction entry in `rows` contributes one
+ * minimal marker, positioned to sort immediately before the first entry its
+ * compaction kept (the same boundary `buildSessionContext` resumes from) so
+ * the client can render "the agent's memory starts below" accurately even
+ * when the kept entries are not the compaction row's immediate predecessors.
+ */
+function compactionMarkersIn(owner, lineage, rows) {
+    const markers = [];
+    for (const row of rows) {
+        const entry = row.entry;
+        if (entry.kind !== "compaction")
+            continue;
+        const kept = lineageEntrySequence(owner, lineage, entry.firstKeptEntryId);
+        if (kept === undefined)
+            throw unavailable("Session compaction horizon is unavailable");
+        markers.push(Object.freeze({
+            id: row.id,
+            sequence: kept,
+            at: row.timestamp,
+            tokensBefore: entry.tokensBefore,
+            tokensAfter: entry.tokensAfter ?? null,
+            trigger: entry.trigger ?? null,
+        }));
+    }
+    return Object.freeze(markers);
+}
+/** Each compaction that changed nothing, at its own place in the page. */
+function compactionNoticesIn(rows) {
+    return Object.freeze(rows.flatMap(({ id, sequence, timestamp, entry }) => entry.kind === "compaction_notice"
+        ? [
+            Object.freeze({
+                id,
+                sequence,
+                at: timestamp,
+                trigger: entry.trigger,
+                result: entry.result,
+                diagnostic: entry.diagnostic ?? null,
+            }),
+        ]
+        : []));
+}
+function payloadBytes(value) {
+    return encoder.encode(JSON.stringify(value)).byteLength;
+}
+function cursorFor(generation, sequence) {
+    const cursor = encodeWoodstockCursor({ generation, sequence });
+    if (cursor === undefined)
+        throw unavailable("Session cursor is unavailable");
+    return cursor;
+}
+function admitProjectedRow(state, row, maximumMessages, work, includeSandboxFailures = false) {
+    const message = projectMessage(row, work);
+    const terminal = projectTerminal(row, work);
+    const sandboxFailure = includeSandboxFailures && row.entry.kind === "sandbox_failure"
+        ? row.entry.event
+        : undefined;
+    if (message !== undefined && state.messages.length === maximumMessages)
+        return false;
+    const nextBytes = (message === undefined ? 0 : payloadBytes(message)) +
+        (terminal === undefined ? 0 : payloadBytes(terminal)) +
+        (sandboxFailure === undefined ? 0 : payloadBytes(sandboxFailure));
+    if (nextBytes > maximumPagePayloadBytes)
+        throw unavailable("Session projection entry exceeds the read bound");
+    if (state.bytes + nextBytes > maximumPagePayloadBytes)
+        return false;
+    if (message !== undefined)
+        state.messages.push(message);
+    if (terminal !== undefined)
+        state.terminals.push(terminal);
+    if (sandboxFailure !== undefined)
+        state.sandboxFailures.push(sandboxFailure);
+    state.bytes += nextBytes;
+    return true;
+}
+function readBoundedPage(rows, 
+/** Whether the lineage holds candidate rows beyond `rows`. */
+more, maximumMessages, work, direction, includeSandboxFailures = false) {
+    const state = {
+        messages: [],
+        terminals: [],
+        sandboxFailures: [],
+        bytes: 0,
+    };
+    let consumed = 0;
+    for (let offset = 0; offset < rows.length; offset += 1) {
+        if (consumed === maximumRowsPerPage)
+            break;
+        const index = direction === "forward" ? offset : rows.length - 1 - offset;
+        const row = rows[index];
+        if (row === undefined ||
+            !admitProjectedRow(state, row, maximumMessages, work, includeSandboxFailures))
+            break;
+        consumed += 1;
+    }
+    if (consumed === 0 && rows.length > 0)
+        throw unavailable("Session page cannot make bounded progress");
+    const messages = direction === "backward" ? [...state.messages].reverse() : state.messages;
+    const terminals = direction === "backward" ? [...state.terminals].reverse() : state.terminals;
+    const sandboxFailures = direction === "backward"
+        ? [...state.sandboxFailures].reverse()
+        : state.sandboxFailures;
+    return Object.freeze({
+        messages: Object.freeze(messages),
+        terminals: Object.freeze(terminals),
+        sandboxFailures: Object.freeze(sandboxFailures),
+        consumed,
+        hasMore: more || consumed < rows.length,
+    });
+}
+function isPromptParts(content) {
+    return Array.isArray(content);
+}
+function readPendingPrompts(owner, sessionId) {
+    const { commands: rows, total } = readPendingSessionCommands(owner, sessionId, maximumRowsPerPage + 1, "prompts");
+    const prompts = [];
+    let bytes = encoder.encode(JSON.stringify({ prompts: [], hasMore: false, total })).byteLength;
+    for (const row of rows) {
+        const entry = promptCommand(row.entry);
+        if (entry === undefined)
+            throw unavailable("Pending Session prompt is unavailable");
+        const content = entry.message.content;
+        const prompt = isPromptParts(content)
+            ? {
+                commandId: row.entry.workId,
+                text: content
+                    .filter((part) => part.type === "text")
+                    .map((part) => part.text)
+                    .join(""),
+                images: content.filter((part) => part.type === "image"),
+                delivery: entry.delivery ?? "followUp",
+            }
+            : {
+                commandId: row.entry.workId,
+                text: content,
+                delivery: entry.delivery ?? "followUp",
+            };
+        const withMeta = row.entry.meta === undefined
+            ? prompt
+            : { ...prompt, meta: row.entry.meta };
+        const attributed = row.origin.kind === "extension"
+            ? {
+                ...withMeta,
+                origin: {
+                    extensionId: row.origin.extensionId,
+                    correlation: row.origin.correlation,
+                },
+            }
+            : withMeta;
+        const size = encoder.encode(JSON.stringify(attributed)).byteLength +
+            (prompts.length === 0 ? 0 : 1);
+        if (prompts.length === maximumRowsPerPage ||
+            bytes + size > maximumPagePayloadBytes)
+            return { prompts, hasMore: true, total };
+        prompts.push(attributed);
+        bytes += size;
+    }
+    return { prompts, hasMore: false, total };
+}
+/**
+ * The exclusive upper sequence a baseline read pages back from: none for the
+ * latest page, or exactly the entry a `before` cursor names. Undefined means
+ * the cursor cannot be honored (another lineage, or an entry no longer on
+ * the selected path).
+ */
+function resolveHistoryAnchor(owner, lineage, before) {
+    const position = decodeWoodstockCursor(before);
+    if (position?.generation !== lineage.rootId)
+        return undefined;
+    return lineageHasSequence(owner, lineage, position.sequence)
+        ? position.sequence
+        : undefined;
+}
+/**
+ * Read one bounded public baseline from the selected Session lineage. Only
+ * the page's rows are decoded; `before` pages back through the whole saved
+ * history, including what compaction summarized away.
+ */
+export function readClientSnapshot(owner, sessionId, options, activity, projectExtensions = () => ({})) {
+    return owner.transactionSync(() => {
+        const pending = readPendingPrompts(owner, sessionId);
+        const lineage = readSessionLineage(owner, { sessionId });
+        if (lineage === undefined)
+            return Object.freeze({
+                sessionId,
+                cursor: null,
+                hasMore: false,
+                oldestCursor: null,
+                messages: Object.freeze([]),
+                terminals: Object.freeze([]),
+                compactions: Object.freeze([]),
+                compactionNotices: Object.freeze([]),
+                pending,
+                activity: activity.facts,
+                progress: activity.progress,
+                extensions: projectExtensions(),
+                attention: readSessionAttention(owner, sessionId),
+            });
+        const generation = lineage.rootId;
+        const anchor = options.before === undefined
+            ? Number.MAX_SAFE_INTEGER
+            : resolveHistoryAnchor(owner, lineage, options.before);
+        if (anchor === undefined)
+            throw unavailable("Session read cursor is unavailable");
+        const candidates = readLineageWindow(owner, lineage, {
+            before: anchor,
+            from: "newest",
+            rows: maximumRowsPerPage,
+        });
+        const page = readBoundedPage(candidates.rows, candidates.more, options.limit, pageWorkFacts(owner, sessionId, lineage, candidates.rows), "backward", options.includeSandboxFailures === true);
+        const consumedRows = candidates.rows.slice(candidates.rows.length - page.consumed);
+        const newestIncluded = candidates.rows.at(-1);
+        const oldestIncluded = consumedRows[0];
+        const snapshot = {
+            sessionId,
+            cursor: newestIncluded === undefined
+                ? null
+                : cursorFor(generation, newestIncluded.sequence),
+            hasMore: page.hasMore,
+            oldestCursor: page.hasMore && oldestIncluded !== undefined
+                ? cursorFor(generation, oldestIncluded.sequence)
+                : null,
+            messages: page.messages,
+            terminals: page.terminals,
+            compactions: compactionMarkersIn(owner, lineage, consumedRows),
+            compactionNotices: compactionNoticesIn(consumedRows),
+            pending,
+            activity: activity.facts,
+            progress: options.before === undefined ? activity.progress : null,
+            extensions: projectExtensions(),
+            attention: readSessionAttention(owner, sessionId),
+        };
+        return Object.freeze(options.includeSandboxFailures === true
+            ? { ...snapshot, sandboxFailures: page.sandboxFailures }
+            : snapshot);
+    });
+}
+const resetReplayPage = Object.freeze({ kind: "reset" });
+/** The exclusive lower sequence a replay resumes after; undefined resets. */
+function replayStart(owner, lineage, position) {
+    if (position === undefined)
+        return 0;
+    if (position.generation !== lineage.rootId)
+        return undefined;
+    return lineageHasSequence(owner, lineage, position.sequence)
+        ? position.sequence
+        : undefined;
+}
+function replayFrames(owner, lineage, start, delivery, activity, extensions, attention, pending, includeSandboxFailures) {
+    const candidates = readLineageWindow(owner, lineage, {
+        after: start,
+        from: "oldest",
+        rows: maximumRowsPerPage,
+    });
+    const page = readBoundedPage(candidates.rows, candidates.more, replayPageLimit, pageWorkFacts(owner, lineage.sessionId, lineage, candidates.rows), "forward", includeSandboxFailures);
+    const consumedRows = candidates.rows.slice(0, page.consumed);
+    const observationSequence = consumedRows.at(-1)?.sequence ?? lineage.newestSequence;
+    const frame = {
+        kind: "update",
+        delivery,
+        cursor: cursorFor(lineage.rootId, observationSequence),
+        messages: page.messages,
+        terminals: page.terminals,
+        compactions: compactionMarkersIn(owner, lineage, consumedRows),
+        compactionNotices: compactionNoticesIn(consumedRows),
+        pending,
+        activity: activity.facts,
+        extensions,
+        attention,
+    };
+    const frames = [
+        Object.freeze(includeSandboxFailures
+            ? { ...frame, sandboxFailures: page.sandboxFailures }
+            : frame),
+    ];
+    if (delivery === "live" && !page.hasMore && activity.progress !== null)
+        frames.push(Object.freeze({
+            kind: "progress",
+            progress: activity.progress,
+            activity: activity.facts,
+        }));
+    return Object.freeze({
+        kind: "page",
+        frames: Object.freeze(frames),
+        hasMore: page.hasMore,
+    });
+}
+/** Read strict-after history plus the current waiting-admission view. */
+export function readClientReplayPage(owner, sessionId, after, delivery, activity, projectExtensions = () => ({}), includeSandboxFailures = false) {
+    const position = after === undefined ? undefined : decodeWoodstockCursor(after);
+    if (after !== undefined && position === undefined)
+        return resetReplayPage;
+    return owner.transactionSync(() => {
+        const pending = readPendingPrompts(owner, sessionId);
+        const lineage = readSessionLineage(owner, { sessionId });
+        if (lineage === undefined) {
+            if (after !== undefined)
+                return resetReplayPage;
+            return {
+                kind: "page",
+                frames: [
+                    {
+                        kind: "update",
+                        delivery,
+                        cursor: null,
+                        messages: [],
+                        terminals: [],
+                        compactions: [],
+                        compactionNotices: [],
+                        activity: activity.facts,
+                        extensions: projectExtensions(),
+                        attention: readSessionAttention(owner, sessionId),
+                        pending,
+                    },
+                ],
+                hasMore: false,
+            };
+        }
+        const start = replayStart(owner, lineage, position);
+        return start === undefined
+            ? resetReplayPage
+            : replayFrames(owner, lineage, start, delivery, activity, projectExtensions(), readSessionAttention(owner, sessionId), pending, includeSandboxFailures);
+    });
+}
+/** Project one exact command's durable facts without selecting a transcript lineage. */
+export function projectCommandSettlement(owner, sessionId, commandId) {
+    const admission = readSessionCommandAdmission(owner, sessionId, commandId);
+    if (admission === undefined)
+        throw unavailable("Accepted Session command is unavailable");
+    const rows = readSessionEntriesForWork(owner, sessionId, admission.entry.workId);
+    const work = workFacts(owner, sessionId, rows);
+    const terminal = rows
+        .flatMap((row) => {
+        const value = projectTerminal(row, work);
+        return value === undefined ? [] : [value];
+    })
+        .at(-1);
+    if (terminal === undefined)
+        return undefined;
+    const answers = rows.flatMap(({ entry }) => entry.kind === "message" && entry.value.role === "assistant"
+        ? [entry.value]
+        : []);
+    const last = answers.at(-1);
+    const meta = terminal.outcome === "cancelled" ? terminal.meta : admission.entry.meta;
+    return {
+        terminal: meta === undefined ? terminal : { ...terminal, meta },
+        content: terminal.outcome === "cancelled"
+            ? ""
+            : (last?.content
+                .flatMap((part) => (part.type === "text" ? [part.text] : []))
+                .join("")
+                .trim() ?? ""),
+        usage: answers.map(({ provider, model, usage }) => ({
+            provider,
+            model,
+            usage,
+        })),
+        toolCalls: new Set(rows.flatMap(({ entry }) => entry.kind === "tool_intent" ? [entry.call.id] : [])).size,
+    };
+}

package/dist/internal/woodstock/compaction-activity.d.ts

@@ -0,0 +1,17 @@
+import type { SessionActivity } from "../../client.js";
+import type { SqliteOwner } from "../contracts.js";
+export type CompactionActivity = NonNullable<SessionActivity["compaction"]>;
+/**
+ * Read the current process-local compaction activity for one addressed
+ * Session; null while no compaction is running on it.
+ */
+export declare function readProcessCompaction(owner: SqliteOwner, sessionId: string): CompactionActivity | null;
+/**
+ * Mark a compaction as running now, cleared by `endCompactionActivity`.
+ *
+ * Process-local only, like `openProgress`: the running state is never
+ * durable, so a restarted process shows no running compaction.
+ */
+export declare function beginCompactionActivity(owner: SqliteOwner, sessionId: string, trigger: CompactionActivity["trigger"]): void;
+/** Clear a running compaction's activity fact, however the commit ended. */
+export declare function endCompactionActivity(owner: SqliteOwner, sessionId: string): void;

package/dist/internal/woodstock/compaction-activity.js

@@ -0,0 +1,32 @@
+import { publishOwnerObservation } from "../observation-kernel.js";
+const compactionByOwner = new WeakMap();
+function compactionFor(owner) {
+    const existing = compactionByOwner.get(owner);
+    if (existing !== undefined)
+        return existing;
+    const created = new Map();
+    compactionByOwner.set(owner, created);
+    return created;
+}
+/**
+ * Read the current process-local compaction activity for one addressed
+ * Session; null while no compaction is running on it.
+ */
+export function readProcessCompaction(owner, sessionId) {
+    return compactionFor(owner).get(sessionId) ?? null;
+}
+/**
+ * Mark a compaction as running now, cleared by `endCompactionActivity`.
+ *
+ * Process-local only, like `openProgress`: the running state is never
+ * durable, so a restarted process shows no running compaction.
+ */
+export function beginCompactionActivity(owner, sessionId, trigger) {
+    compactionFor(owner).set(sessionId, Object.freeze({ trigger }));
+    publishOwnerObservation(owner, sessionId, "progress");
+}
+/** Clear a running compaction's activity fact, however the commit ended. */
+export function endCompactionActivity(owner, sessionId) {
+    if (compactionFor(owner).delete(sessionId))
+        publishOwnerObservation(owner, sessionId, "progress");
+}

package/dist/internal/woodstock/cursor.d.ts

@@ -0,0 +1,9 @@
+/** Private durable position carried opaquely by the public cursor. */
+export type WoodstockCursorPosition = Readonly<{
+    generation: string;
+    sequence: number;
+}>;
+/** Encode one validated durable position in the canonical public wire form. */
+export declare function encodeWoodstockCursor(position: WoodstockCursorPosition): string | undefined;
+/** Decode only the strict canonical cursor spelling emitted by Woodstock. */
+export declare function decodeWoodstockCursor(encoded: string): WoodstockCursorPosition | undefined;

package/dist/internal/woodstock/cursor.js

@@ -0,0 +1,44 @@
+import * as Base64Url from "effect/encoding/Base64Url";
+import * as Schema from "effect/Schema";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const canonicalBase64Url = /^[A-Za-z0-9_-]+$/u;
+const CursorValueSchema = Schema.Struct({
+    v: Schema.Literal(1),
+    generation: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128)), Schema.check(Schema.makeFilter((value) => encoder.encode(value).byteLength <= 128))),
+    sequence: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)), Schema.check(Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER))),
+});
+const closed = { onExcessProperty: "error" };
+const decodeCursorValue = Schema.decodeUnknownResult(CursorValueSchema, closed);
+const decodeCursorJson = Schema.decodeUnknownResult(Schema.fromJsonString(CursorValueSchema), closed);
+/** Encode one validated durable position in the canonical public wire form. */
+export function encodeWoodstockCursor(position) {
+    const decoded = decodeCursorValue({ v: 1, ...position });
+    if (decoded._tag === "Failure")
+        return undefined;
+    const json = JSON.stringify(decoded.success);
+    if (encoder.encode(json).byteLength > 384)
+        return undefined;
+    const encoded = Base64Url.encode(json);
+    return encoder.encode(encoded).byteLength <= 512 ? encoded : undefined;
+}
+/** Decode only the strict canonical cursor spelling emitted by Woodstock. */
+export function decodeWoodstockCursor(encoded) {
+    if (encoder.encode(encoded).byteLength > 512 ||
+        !canonicalBase64Url.test(encoded))
+        return undefined;
+    const bytes = Base64Url.decode(encoded);
+    if (bytes._tag === "Failure" || bytes.success.byteLength > 384)
+        return undefined;
+    const json = decoder.decode(bytes.success);
+    const decoded = decodeCursorJson(json);
+    if (decoded._tag === "Failure")
+        return undefined;
+    const canonical = JSON.stringify(decoded.success);
+    if (canonical !== json || Base64Url.encode(canonical) !== encoded)
+        return undefined;
+    return Object.freeze({
+        generation: decoded.success.generation,
+        sequence: decoded.success.sequence,
+    });
+}