@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.0

package/dist/execution/projection.js

@@ -0,0 +1,327 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context";
+import { ScopeContext } from "@ericsanchezok/synergy-harness/scope/context";
+import { Scope } from "@ericsanchezok/synergy-harness/scope";
+import { Session } from "@ericsanchezok/synergy-harness/session";
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage";
+import { applyProjectionPatch, projectionPatch } from "@ericsanchezok/synergy-util/projection-patch";
+import { ExecutionService } from "./service.js";
+import { ExecutionSchema } from "./schema.js";
+import { z } from "zod";
+export var ExecutionProjection;
+(function (ExecutionProjection) {
+    const checkpoints = RuntimeContext.state(() => new Map());
+    function checkpoint(sessionID, token) {
+        const value = checkpoints().get(token);
+        if (!value ||
+            !("summary" in value) ||
+            value.sessionID !== sessionID ||
+            value.scopeID !== ScopeContext.current.scope.id)
+            throw new Storage.NotFoundError({ message: "Execution checkpoint expired" });
+        return value.summary;
+    }
+    ExecutionProjection.checkpoint = checkpoint;
+    function projectionCheckpoint(sessionID, token) {
+        const value = checkpoints().get(token);
+        if (!value ||
+            !("projection" in value) ||
+            value.sessionID !== sessionID ||
+            value.scopeID !== ScopeContext.current.scope.id)
+            throw new Storage.NotFoundError({ message: "Execution checkpoint expired" });
+        return structuredClone(value.projection);
+    }
+    ExecutionProjection.projectionCheckpoint = projectionCheckpoint;
+    const Demand = z.enum(["root", "summary", "trajectory"]);
+    async function openDemand(...[interest, send, signal]) {
+        const demands = z.array(Demand).min(1).parse(interest.demands);
+        const scope = await Scope.resolve({ scopeID: interest.scopeID });
+        const session = await Session.get(interest.sessionID);
+        if (session.scope.id !== scope.id)
+            throw new Storage.NotFoundError({ message: "Execution belongs to another Scope" });
+        const controller = new AbortController();
+        const abort = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        abort.throwIfAborted();
+        const trajectory = demands.includes("trajectory");
+        const summary = trajectory || demands.includes("summary");
+        const releases = [];
+        if (summary)
+            releases.push(ExecutionService.subscribe(session.id, { trajectory }));
+        let disposed = false;
+        let frameRevision = 0;
+        let token;
+        let previous;
+        let current = {
+            state: "root",
+            sessionID: session.id,
+            revision: 0,
+            previousRevision: 0,
+            contexts: [],
+            contextTotal: 0,
+        };
+        const store = checkpoints();
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            abort.removeEventListener("abort", dispose);
+            controller.abort();
+            for (const release of releases.splice(0))
+                release();
+            if (token)
+                store.delete(token);
+            previous = undefined;
+        };
+        abort.addEventListener("abort", dispose, { once: true });
+        const publish = (value) => {
+            if (disposed)
+                return;
+            value = ExecutionSchema.Projection.parse(value);
+            current = value;
+            const patches = projectionPatch(previous, value);
+            if (!patches.length)
+                return;
+            const properties = {
+                kind: "execution",
+                sessionID: session.id,
+                generation: interest.generation,
+                revision: frameRevision + 1,
+                previousRevision: frameRevision,
+                patches,
+                snapshot: undefined,
+            };
+            const frame = { scopeID: scope.id, payload: { type: "server.view.patch", properties } };
+            if (Buffer.byteLength(JSON.stringify(frame)) > 64 * 1024) {
+                if (token)
+                    store.delete(token);
+                token = crypto.randomUUID();
+                store.set(token, { scopeID: scope.id, sessionID: session.id, projection: structuredClone(value) });
+                properties.patches = [];
+                properties.snapshot = token;
+            }
+            previous = structuredClone(value);
+            frameRevision++;
+            send(frame);
+        };
+        const scoped = (fn) => ScopeContext.provide({ scope, fn });
+        try {
+            const release = await scoped(() => ExecutionService.observeRoot(session.id, (root) => {
+                const selected = root.contexts.filter((context) => !interest.runID || context.runID === interest.runID);
+                const visible = new Set(interest.nodeIDs);
+                const contexts = selected.filter((context, index) => index < 30 || visible.has(context.nodeID));
+                publish({
+                    ...current,
+                    revision: root.revision,
+                    previousRevision: current.revision,
+                    contexts,
+                    contextTotal: selected.length,
+                });
+            }, abort));
+            if (disposed)
+                release();
+            else
+                releases.push(release);
+            if (summary && !disposed) {
+                const releaseProgress = await scoped(() => ExecutionService.observePreparation(session.id, (progress) => {
+                    if (current.state === "preparing")
+                        publish({ ...current, progress });
+                }));
+                if (disposed) {
+                    releaseProgress();
+                    return { project() { }, dispose };
+                }
+                releases.push(releaseProgress);
+                publish({ ...current, state: "preparing", progress: { stage: "metadata", prepared: 0 } });
+                void scoped(async () => {
+                    const value = await ExecutionService.summary(session.id, undefined, abort);
+                    const rounds = interest.runID ? [await ExecutionService.summary(session.id, interest.runID, abort)] : [];
+                    if (current.state === "ready" && current.summary.revision > value.revision)
+                        return;
+                    publish({
+                        ...current,
+                        state: "ready",
+                        summary: value,
+                        detailPreviousRevision: value.revision,
+                        roundSummaries: rounds,
+                        upserts: [],
+                        processUpserts: [],
+                        processRemoved: [],
+                        removed: [],
+                    });
+                    await ExecutionService.verifyJournal(session.id, abort);
+                    abort.throwIfAborted();
+                    const verified = await ExecutionService.summary(session.id, undefined, abort);
+                    const verifiedRounds = interest.runID
+                        ? [await ExecutionService.summary(session.id, interest.runID, abort)]
+                        : [];
+                    if (current.state === "ready" && current.summary.revision > verified.revision)
+                        return;
+                    publish({
+                        ...current,
+                        state: "ready",
+                        summary: verified,
+                        roundSummaries: verifiedRounds,
+                        detailPreviousRevision: current.state === "ready" ? current.summary.revision : verified.revision,
+                        upserts: [],
+                        processUpserts: [],
+                        processRemoved: [],
+                        removed: [],
+                    });
+                }).catch((error) => {
+                    if (!disposed)
+                        publish({
+                            ...current,
+                            state: "failed",
+                            error: {
+                                kind: error instanceof Error ? error.name : "Error",
+                                message: "Unable to prepare execution summary",
+                                retryable: true,
+                            },
+                        });
+                });
+            }
+        }
+        catch (error) {
+            dispose();
+            throw error;
+        }
+        return {
+            project(event) {
+                if (event.scopeID !== scope.id)
+                    return;
+                if (event.payload.type === "session.deleted" &&
+                    event.payload.properties.info?.id === session.id) {
+                    dispose();
+                    return;
+                }
+                if (!summary || event.payload.type !== "execution.updated" || event.payload.properties.sessionID !== session.id)
+                    return;
+                const value = ExecutionSchema.Updated.properties.parse(event.payload.properties);
+                if (current.state === "ready" && value.summary.revision <= current.summary.revision)
+                    return;
+                const visible = interest.nodeIDs && new Set(interest.nodeIDs);
+                publish({
+                    ...current,
+                    state: "ready",
+                    summary: value.summary,
+                    detailPreviousRevision: value.previousRevision ?? value.summary.revision,
+                    roundSummaries: value.roundSummaries.filter((round) => !interest.runID || round.runID === interest.runID),
+                    upserts: trajectory ? value.upserts.filter((node) => !visible || visible.has(node.id)) : [],
+                    processUpserts: trajectory ? (value.processUpserts ?? []) : [],
+                    processRemoved: trajectory ? (value.processRemoved ?? []) : [],
+                    removed: trajectory ? value.removed : [],
+                });
+            },
+            dispose,
+        };
+    }
+    function baseline(summary) {
+        return {
+            sessionID: summary.sessionID,
+            revision: summary.revision,
+            summary,
+            roundSummaries: [],
+            contextUpserts: [],
+            upserts: [],
+            processUpserts: [],
+            processRemoved: [],
+            removed: [],
+            previousRevision: summary.revision,
+        };
+    }
+    ExecutionProjection.baseline = baseline;
+    function contribution() {
+        return {
+            kind: "execution",
+            eventType: "execution.updated",
+            legacy: ExecutionService.legacyClient,
+            async open(interest, send, signal) {
+                if (interest.demands)
+                    return openDemand(interest, send, signal);
+                signal?.throwIfAborted();
+                const scope = await Scope.resolve({ scopeID: interest.scopeID });
+                const session = await Session.get(interest.sessionID);
+                if (session.scope.id !== scope.id)
+                    throw new Storage.NotFoundError({ message: "Execution belongs to another Scope" });
+                signal?.throwIfAborted();
+                const release = ExecutionService.subscribe(session.id);
+                let previous, revision = 0, token, disposed = false;
+                const store = checkpoints();
+                const dispose = () => {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    signal?.removeEventListener("abort", dispose);
+                    release();
+                    if (token)
+                        store.delete(token);
+                    previous = undefined;
+                };
+                signal?.addEventListener("abort", dispose, { once: true });
+                const publish = (value) => {
+                    if (disposed)
+                        return;
+                    const patches = projectionPatch(previous, value);
+                    if (!patches.length)
+                        return;
+                    const properties = {
+                        kind: "execution",
+                        sessionID: session.id,
+                        generation: interest.generation,
+                        revision: revision + 1,
+                        previousRevision: revision,
+                        patches,
+                        snapshot: undefined,
+                    };
+                    const frame = { scopeID: scope.id, payload: { type: "server.view.patch", properties } };
+                    if (Buffer.byteLength(JSON.stringify(frame)) > 64 * 1024) {
+                        const summary = value.summary;
+                        if (token)
+                            store.delete(token);
+                        token = crypto.randomUUID();
+                        const snapshot = structuredClone(summary);
+                        store.set(token, { scopeID: scope.id, sessionID: session.id, summary: snapshot });
+                        previous = baseline(snapshot);
+                        properties.patches = [];
+                        properties.snapshot = token;
+                    }
+                    else
+                        previous = applyProjectionPatch(previous, patches);
+                    revision++;
+                    send(frame);
+                };
+                try {
+                    const summary = await ScopeContext.provide({
+                        scope,
+                        fn: () => ExecutionService.summary(session.id, undefined, signal),
+                    });
+                    publish(baseline(summary));
+                }
+                catch (error) {
+                    dispose();
+                    throw error;
+                }
+                return {
+                    project(event) {
+                        if (event.scopeID !== scope.id ||
+                            event.payload.type !== "execution.updated" ||
+                            event.payload.properties.sessionID !== session.id)
+                            return;
+                        const value = event.payload.properties;
+                        const priorRevision = previous?.revision ?? -1;
+                        if (Number(value.revision) <= priorRevision)
+                            return;
+                        const visible = interest.nodeIDs && new Set(interest.nodeIDs);
+                        const selected = {
+                            ...value,
+                            roundSummaries: value.roundSummaries.filter((summary) => !interest.runID || summary.runID === interest.runID),
+                            contextUpserts: (value.contextUpserts ?? []).filter((context) => !visible || visible.has(context.nodeID)),
+                            upserts: value.upserts.filter((node) => !visible || visible.has(node.id)),
+                        };
+                        publish(selected);
+                    },
+                    dispose,
+                };
+            },
+        };
+    }
+    ExecutionProjection.contribution = contribution;
+})(ExecutionProjection || (ExecutionProjection = {}));

package/dist/execution/query.js

@@ -0,0 +1,18 @@
+export class ExecutionQueryError extends RangeError {
+}
+export function queryValue(schema, value) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new ExecutionQueryError("Invalid execution query");
+    return parsed.data;
+}
+export function queryCursor(schema, cursor) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(cursor, "base64url").toString());
+    }
+    catch {
+        throw new ExecutionQueryError("Invalid execution cursor");
+    }
+    return queryValue(schema, value);
+}

package/dist/execution/routes.js

@@ -0,0 +1,189 @@
+import { RolloutEvidence } from "@ericsanchezok/synergy-harness/rollout";
+import { Log } from "@ericsanchezok/synergy-harness/util/log";
+import { ExecutionQueryError } from "./query.js";
+import { Hono } from "hono";
+import { describeRoute, resolver, validator } from "hono-openapi";
+import { z } from "zod";
+import { Identifier } from "@ericsanchezok/synergy-harness/id/id";
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage";
+import { ExecutionSchema } from "./schema.js";
+import { ExecutionService } from "./service.js";
+import { ExecutionProjection } from "./projection.js";
+import { ExecutionContent } from "./content.js";
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context";
+import { ScopeContext } from "@ericsanchezok/synergy-harness/scope/context";
+import { Scope } from "@ericsanchezok/synergy-harness/scope";
+const Params = z.object({ sessionID: Identifier.schema("session") });
+const ContextParams = Params.extend({ callID: z.string().min(1).max(4096) });
+const NodeParams = Params.extend({ nodeID: z.string().min(1).max(4096) });
+const ContentQuery = ExecutionContent.Query.extend({
+    offset: z.coerce.number().int().nonnegative().safe().default(0),
+    limit: z.coerce.number().int().min(1).max(65_536).default(65_536),
+});
+async function download(source, field, signal) {
+    const runtime = RuntimeContext.current();
+    const scope = ScopeContext.current.scope;
+    const workspace = ScopeContext.current.workspace;
+    const iterator = source.stream()[Symbol.asyncIterator]();
+    const release = Scope.registerArchiveGuard((id) => {
+        if (id === scope.id)
+            throw new Error("Execution content is being read");
+    });
+    const bind = (fn) => runtime.bind(() => ScopeContext.provide({ scope, workspace, fn }));
+    let closed = false;
+    let controller;
+    const finish = () => {
+        if (closed)
+            return;
+        closed = true;
+        release();
+        signal.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+        if (closed)
+            return;
+        controller?.error(signal.reason);
+        finish();
+        void bind(() => iterator.return?.())().catch(() => { });
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    const body = new ReadableStream({
+        start(value) {
+            controller = value;
+            if (signal.aborted)
+                abort();
+        },
+        pull: bind(async () => {
+            if (closed)
+                return;
+            try {
+                const item = await iterator.next();
+                if (closed)
+                    return;
+                if (item.done) {
+                    finish();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(item.value);
+            }
+            catch (error) {
+                finish();
+                controller.error(error);
+            }
+        }),
+        cancel: bind(async () => {
+            finish();
+            await iterator.return?.();
+        }),
+    });
+    return new Response(body, {
+        headers: {
+            "Content-Type": "application/octet-stream",
+            "Content-Disposition": `attachment; filename="execution-${field.replace(/[^a-zA-Z0-9_-]/g, "_")}.${source.mediaType.includes("json") ? "json" : "txt"}"`,
+            "Content-Length": String(source.bytes),
+            "Cache-Control": "no-store",
+            "X-Execution-Content-Version": source.contentVersion,
+            "X-Execution-Content-Status": source.status,
+            ...(source.sha256 ? { "X-Execution-Content-Sha256": source.sha256 } : {}),
+        },
+    });
+}
+const metadata = (operationId, summary, schema) => describeRoute({
+    operationId,
+    summary,
+    responses: {
+        200: { description: summary, content: { "application/json": { schema: resolver(schema) } } },
+        400: { description: "Invalid execution query" },
+        500: { description: "Execution computation failed" },
+        404: { description: "Execution evidence was not found in the selected Scope and session" },
+    },
+});
+async function result(body) {
+    try {
+        return { status: 200, value: await body() };
+    }
+    catch (error) {
+        if (error instanceof Storage.NotFoundError)
+            return { status: 404, value: { message: error.message } };
+        if (error instanceof ExecutionQueryError || error instanceof RolloutEvidence.QueryError)
+            return { status: 400, value: { message: "Invalid execution query" } };
+        if (!(error instanceof Error && error.name === "AbortError"))
+            Log.create({ service: "execution" }).error("execution read failed", {
+                kind: error instanceof Error ? error.name : "unknown",
+                issues: error instanceof z.ZodError
+                    ? error.issues.map((issue) => ({ code: issue.code, path: issue.path }))
+                    : undefined,
+            });
+        throw error;
+    }
+}
+export const ExecutionRoute = () => new Hono()
+    .get("/:sessionID/execution/projection", metadata("session.executionProjection", "Read a captured execution projection", ExecutionSchema.Projection), validator("param", Params), validator("query", z.object({ token: z.string().uuid() })), async (c) => {
+    const response = await result(() => Promise.resolve(ExecutionProjection.projectionCheckpoint(c.req.valid("param").sessionID, c.req.valid("query").token)));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/summary", metadata("session.executionSummary", "Read a compact session execution summary", ExecutionSchema.Summary), validator("param", Params), validator("query", ExecutionSchema.Query.pick({ runID: true }).extend({ projection: z.string().uuid().optional() })), async (c) => {
+    const response = await result(() => c.req.valid("query").projection
+        ? Promise.resolve(ExecutionProjection.checkpoint(c.req.valid("param").sessionID, c.req.valid("query").projection))
+        : ExecutionService.summary(c.req.valid("param").sessionID, c.req.valid("query").runID, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/context/history", metadata("session.executionContextHistory", "Read context request history", ExecutionSchema.ContextHistory), validator("param", Params), validator("query", ExecutionSchema.ContextQuery), async (c) => {
+    const response = await result(() => ExecutionService.contextHistory(c.req.valid("param").sessionID, c.req.valid("query"), c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/context/snapshots/:callID", metadata("session.executionContextSnapshot", "Read one context request snapshot", ExecutionSchema.ContextSnapshot), validator("param", ContextParams), validator("query", ExecutionSchema.ContextQuery.pick({ runID: true })), async (c) => {
+    const { sessionID, callID } = c.req.valid("param");
+    const response = await result(() => ExecutionService.contextSnapshot(sessionID, callID, c.req.valid("query").runID, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/context/snapshots/:callID/items", metadata("session.executionContextItems", "Read a bounded context source index", ExecutionSchema.ContextItems), validator("param", ContextParams), validator("query", ExecutionSchema.ContextItemsQuery), async (c) => {
+    const { sessionID, callID } = c.req.valid("param");
+    const response = await result(() => ExecutionService.contextItems(sessionID, callID, c.req.valid("query"), c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/trajectory", metadata("session.executionTrajectory", "Page through session execution records", ExecutionSchema.Page), validator("param", Params), validator("query", ExecutionSchema.Query), async (c) => {
+    const response = await result(() => ExecutionService.trajectory(c.req.valid("param").sessionID, c.req.valid("query"), c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/nodes/:nodeID", metadata("session.executionNode", "Inspect one session execution record", ExecutionSchema.Detail), validator("param", NodeParams), validator("query", ExecutionSchema.Query.pick({ runID: true })), async (c) => {
+    const { sessionID, nodeID } = c.req.valid("param");
+    const response = await result(() => ExecutionService.node(sessionID, nodeID, c.req.valid("query").runID, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/nodes/:nodeID/content", metadata("session.executionContent", "Read a bounded execution content page", ExecutionSchema.Content), validator("param", NodeParams), validator("query", ContentQuery), async (c) => {
+    const { sessionID, nodeID } = c.req.valid("param");
+    const { field, offset, limit, runID, version } = c.req.valid("query");
+    const response = await result(() => ExecutionService.content(sessionID, nodeID, field, offset, limit, runID, version, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/nodes/:nodeID/content/sections", metadata("session.executionContentSections", "Read structured execution content sections", ExecutionContent.Sections), validator("param", NodeParams), validator("query", ExecutionContent.PageQuery), async (c) => {
+    const { sessionID, nodeID } = c.req.valid("param");
+    const input = c.req.valid("query");
+    const response = await result(async () => ExecutionContent.sections(await ExecutionService.contentSource(sessionID, nodeID, input.field, input.runID, input.version, c.req.raw.signal), input, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/nodes/:nodeID/content/search", metadata("session.executionContentSearch", "Search an entire version of execution content", ExecutionContent.Search), validator("param", NodeParams), validator("query", ExecutionContent.SearchQuery), async (c) => {
+    const { sessionID, nodeID } = c.req.valid("param");
+    const input = c.req.valid("query");
+    const response = await result(async () => ExecutionContent.search(await ExecutionService.contentSource(sessionID, nodeID, input.field, input.runID, input.version, c.req.raw.signal), input, c.req.raw.signal));
+    return c.json(response.value, response.status);
+})
+    .get("/:sessionID/execution/nodes/:nodeID/content/download", describeRoute({
+    operationId: "session.executionContentDownload",
+    summary: "Download complete execution content at a fixed version",
+    responses: {
+        200: {
+            description: "Verified execution content",
+            content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } },
+        },
+        400: { description: "Invalid execution content query or version" },
+        404: { description: "Execution content was not found" },
+    },
+}), validator("param", NodeParams), validator("query", ExecutionContent.Query), async (c) => {
+    const { sessionID, nodeID } = c.req.valid("param");
+    const input = c.req.valid("query");
+    const response = await result(async () => download(await ExecutionService.contentSource(sessionID, nodeID, input.field, input.runID, input.version, c.req.raw.signal), input.field, c.req.raw.signal));
+    return response.status === 200 ? response.value : c.json(response.value, response.status);
+});