@xandreed/plugin-render 0.8.0-next.0

package/dist/plugin.adapter.js

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+import { definePlugin } from "@xandreed/core";
+import { FeedOptions } from "./domain/feed-frame.entity.js";
+import { UiOutputAdmission } from "./ports/render-output.port.js";
+import { JournalTail, Render, RenderFeed, RenderStore } from "./ports/render.port.js";
+import { RenderFeedLive } from "./render-feed.adapter.js";
+import { RenderLive } from "./render-surface.adapter.js";
+const SurfaceConfig = Schema.Struct({ maxBytes: Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1024, maximum: 131072 }))) });
+export const renderSurfaceDefaults = { maxBytes: 32768 }, renderSurfacePlugin = definePlugin({
+  id: "@xandreed/plugin-render/surface",
+  version: "0.8.0-next.0",
+  scope: "runtime",
+  requires: [RenderStore, UiOutputAdmission],
+  provides: [Render],
+  config: SurfaceConfig,
+  defaults: renderSurfaceDefaults,
+  layer: ({ maxBytes }) => RenderLive(maxBytes)
+}), renderFeedDefaults = { pollMs: 200, maxPollMs: 1000, heartbeatMs: 15000, maxDurationMs: 240000 }, renderFeedPlugin = definePlugin({
+  id: "@xandreed/plugin-render/feed",
+  version: "0.8.0-next.0",
+  scope: "runtime",
+  requires: [JournalTail],
+  provides: [RenderFeed],
+  config: FeedOptions,
+  defaults: renderFeedDefaults,
+  layer: (options) => RenderFeedLive(options)
+});

package/dist/ports/render-output.port.d.ts

@@ -0,0 +1,40 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { uiOutputToolkit } from "../render-output.tools.js";
+import type { UiOutputError, UiOutputProposal, UiOutputReceipt, UiOutputScope } from "../domain/render-output.entity.js";
+declare const UiOutputAdmission_base: Context.ServiceClass<UiOutputAdmission, "efferent/ui/OutputAdmission", {
+    readonly validate: (scope: UiOutputScope, proposal: UiOutputProposal) => Effect.Effect<void, UiOutputError>;
+}>;
+/** Exact release lookup + prop schema + evidence/permissions. Fail closed. */
+export declare class UiOutputAdmission extends UiOutputAdmission_base {
+}
+declare const UiOutputJournal_base: Context.ServiceClass<UiOutputJournal, "efferent/ui/OutputJournal", {
+    readonly commit: (scope: UiOutputScope, proposal: UiOutputProposal) => Effect.Effect<UiOutputReceipt, UiOutputError>;
+}>;
+/** A transaction must check ownership/fence, deduplicate operationId, persist
+ * the immutable revision AND its journal/outbox event before returning.
+ * Reusing an operationId with different content must fail with conflict.
+ * Streaming hosts tail this journal; they never send speculative proposals. */
+export declare class UiOutputJournal extends UiOutputJournal_base {
+}
+declare const UiOutputContext_base: Context.ServiceClass<UiOutputContext, "efferent/ui/OutputContext", {
+    readonly threadId: string;
+    readonly runId: string;
+    readonly messageId: string;
+    readonly principalId: string;
+    readonly fence: number;
+}>;
+export declare class UiOutputContext extends UiOutputContext_base {
+}
+declare const UiOutput_base: Context.ServiceClass<UiOutput, "efferent/ui/Output", {
+    readonly emit: (proposal: UiOutputProposal) => Effect.Effect<UiOutputReceipt, UiOutputError>;
+}>;
+export declare class UiOutput extends UiOutput_base {
+}
+declare const UiOutputTools_base: Context.ServiceClass<UiOutputTools, "efferent/ui/OutputTools", {
+    readonly toolkit: typeof uiOutputToolkit;
+}>;
+/** Separate from AgentTools so a UI plugin composes with domain tool plugins. */
+export declare class UiOutputTools extends UiOutputTools_base {
+}
+export {};

package/dist/ports/render-output.port.js

@@ -0,0 +1,16 @@
+import { Context } from "effect";
+
+export class UiOutputAdmission extends Context.Service()("efferent/ui/OutputAdmission") {
+}
+
+export class UiOutputJournal extends Context.Service()("efferent/ui/OutputJournal") {
+}
+
+export class UiOutputContext extends Context.Service()("efferent/ui/OutputContext") {
+}
+
+export class UiOutput extends Context.Service()("efferent/ui/Output") {
+}
+
+export class UiOutputTools extends Context.Service()("efferent/ui/OutputTools") {
+}

package/dist/ports/render.port.d.ts

@@ -0,0 +1,86 @@
+import { Context } from "effect";
+import type { Effect, Option, Stream } from "effect";
+import type { UiOutputProposal, UiOutputReceipt } from "../domain/render-output.entity.js";
+import type { FreezeReason, PublishResult, RenderError, RenderNode, RenderSnapshotInput, SurfaceCompleted, SurfaceFrozen, SurfacePlanned, SurfaceRecord, SurfaceScope, SurfaceState } from "../domain/render-surface.entity.js";
+import type { FeedFrame, FeedPayload, FeedScope, JournalRecord } from "../domain/feed-frame.entity.js";
+declare const RenderStore_base: Context.ServiceClass<RenderStore, "efferent/render/Store", {
+    readonly hydrate: (scope: SurfaceScope) => Effect.Effect<ReadonlyArray<SurfaceRecord>, RenderError>;
+    readonly plan: (scope: SurfaceScope, record: SurfacePlanned) => Effect.Effect<void, RenderError>;
+    readonly commit: (scope: SurfaceScope, write: {
+        readonly versionId: string;
+        readonly proposal: UiOutputProposal;
+    }) => Effect.Effect<UiOutputReceipt, RenderError>;
+    readonly complete: (scope: SurfaceScope, record: SurfaceCompleted) => Effect.Effect<void, RenderError>;
+    readonly freeze: (scope: SurfaceScope, record: SurfaceFrozen) => Effect.Effect<void, RenderError>;
+    readonly annotate: (scope: SurfaceScope, kind: string, data: Readonly<Record<string, unknown>>) => Effect.Effect<void, RenderError>;
+}>;
+/**
+ * The host's durable surface storage. Every write is fenced by the scope.
+ * - `plan` MUST fail with code `frozen` inside the same transaction when a
+ *   `SurfaceFrozen` exists for the scope's surface and message.
+ * - `commit` is idempotent by `proposal.operationId`; reusing an id with a
+ *   different proposal fails with `conflict`. It persists a `SurfaceCommitted`.
+ * - `hydrate` returns this surface's records, in write order, for every message.
+ */
+export declare class RenderStore extends RenderStore_base {
+}
+/** Everything a host does with one surface during a run. Writes are serialized. */
+export interface RenderSurface {
+    readonly scope: SurfaceScope;
+    /** The records hydrated when the surface was opened, for every message (e.g. the page being edited). */
+    readonly records: ReadonlyArray<SurfaceRecord>;
+    readonly state: Effect.Effect<SurfaceState>;
+    /** Versioned and deduplicated: identical content opens no new generation. A frozen surface records a frozen, partial completion instead of failing. */
+    readonly publish: (snapshot: RenderSnapshotInput) => Effect.Effect<PublishResult, RenderError>;
+    /** Commit a node into a declared placeholder of the current version; allowed after freezing. */
+    readonly fill: (placeholder: string, node: RenderNode) => Effect.Effect<UiOutputReceipt, RenderError>;
+    /** Run a stream of snapshots in the background through the host's `fork`, one preparation at a time. Failures are annotated `render.preparation-failed` and passed to `recover`. */
+    readonly prepare: <E>(work: Stream.Stream<RenderSnapshotInput, E>, recover: (error: E | RenderError) => Effect.Effect<void>) => Effect.Effect<void>;
+    /** Wait for every preparation started so far. */
+    readonly settled: Effect.Effect<void>;
+    readonly freeze: (reason: FreezeReason) => Effect.Effect<void, RenderError>;
+    readonly annotate: (kind: string, data: Readonly<Record<string, unknown>>) => Effect.Effect<void, RenderError>;
+}
+export interface RenderOpenOptions {
+    /** The host's background runner (e.g. its turn tasks), so preparations live and die with the host's unit of work. */
+    readonly fork: (tag: string, work: Effect.Effect<void>) => Effect.Effect<void>;
+}
+declare const Render_base: Context.ServiceClass<Render, "efferent/render/Render", {
+    readonly open: (scope: SurfaceScope, options: RenderOpenOptions) => Effect.Effect<RenderSurface, RenderError>;
+}>;
+export declare class Render extends Render_base {
+}
+declare const JournalTail_base: Context.ServiceClass<JournalTail, "efferent/render/JournalTail", {
+    readonly read: (feed: FeedScope, after: number) => Effect.Effect<ReadonlyArray<JournalRecord>, RenderError>;
+    /**
+     * Optional wake signal: each element means the feed's journal may have new
+     * records, and the feed polls at once instead of waiting out its interval.
+     * Polling stays the fallback; a failed or ended stream only stops waking.
+     */
+    readonly changes?: (feed: FeedScope) => Stream.Stream<void, RenderError>;
+}>;
+/** The host's journal, read after a cursor. The host authorizes the feed's principal. */
+export declare class JournalTail extends JournalTail_base {
+}
+/** Maps a journal record to what a client receives; `None` skips it (the cursor still advances). */
+export type FeedProjection = (record: JournalRecord) => Effect.Effect<Option.Option<FeedPayload>, RenderError>;
+declare const RenderFeed_base: Context.ServiceClass<RenderFeed, "efferent/render/Feed", {
+    readonly frames: (feed: FeedScope, after: number, project: FeedProjection) => Stream.Stream<FeedFrame, RenderError>;
+}>;
+export declare class RenderFeed extends RenderFeed_base {
+}
+/** A wire: SSE, WebSocket, or anything that can carry text frames to one peer. */
+export interface RenderTransport<Peer> {
+    readonly id: string;
+    readonly serve: (frames: Stream.Stream<FeedFrame, RenderError>, peer: Peer) => Effect.Effect<void>;
+}
+export interface SsePeer {
+    readonly write: (chunk: string) => Effect.Effect<void>;
+    /** Completes when the client disconnects. */
+    readonly closed: Effect.Effect<void>;
+}
+export interface SocketPeer {
+    readonly send: (text: string) => Effect.Effect<void>;
+    readonly closed: Effect.Effect<void>;
+}
+export {};

package/dist/ports/render.port.js

@@ -0,0 +1,13 @@
+import { Context } from "effect";
+
+export class RenderStore extends Context.Service()("efferent/render/Store") {
+}
+
+export class Render extends Context.Service()("efferent/render/Render") {
+}
+
+export class JournalTail extends Context.Service()("efferent/render/JournalTail") {
+}
+
+export class RenderFeed extends Context.Service()("efferent/render/Feed") {
+}

package/dist/render-feed.adapter.d.ts

@@ -0,0 +1,14 @@
+import { Layer, Stream } from "effect";
+import type { FeedFrame, FeedOptions, FeedScope } from "./domain/feed-frame.entity.js";
+import type { RenderError } from "./domain/render-surface.entity.js";
+import { JournalTail, RenderFeed } from "./ports/render.port.js";
+/**
+ * A journal tail as a stream of frames: records after the cursor (projected),
+ * one ready frame after the first empty poll, heartbeats while idle, idle
+ * polling backs off (a `changes` signal polls at once); the stream ends after
+ * `maxDurationMs`.
+ */
+export declare const makeRenderFeed: (tail: typeof JournalTail.Service, options: FeedOptions) => {
+    readonly frames: (feed: FeedScope, after: number, project: import("./index.js").FeedProjection) => Stream.Stream<FeedFrame, RenderError>;
+};
+export declare const RenderFeedLive: (options: FeedOptions) => Layer.Layer<RenderFeed, never, JournalTail>;

package/dist/render-feed.adapter.js

@@ -0,0 +1,40 @@
+import { Clock, Duration, Effect, Layer, Option, Queue, Scope, Stream } from "effect";
+import { FeedHeartbeat, FeedReady, FeedRecord } from "./domain/feed-frame.entity.js";
+import { nextPollMs } from "./domain/feed-frame.entity.functions.js";
+import { JournalTail, RenderFeed } from "./ports/render.port.js";
+const waitOf = (tail, feed) => Option.match(Option.fromNullishOr(tail.changes), {
+  onNone: () => Effect.succeed((delayMs) => Effect.sleep(Duration.millis(delayMs))),
+  onSome: (changes) => Effect.gen(function* () {
+    const wake = yield* Queue.sliding(1);
+    yield* changes(feed).pipe(Stream.runForEach(() => Queue.offer(wake, void 0)), Effect.ignore, Effect.forkScoped);
+    return (delayMs) => Effect.race(Effect.sleep(Duration.millis(delayMs)), Queue.take(wake));
+  })
+});
+export const makeRenderFeed = (tail, options) => RenderFeed.of({
+  frames: (feed, after, project) => Stream.unwrap(Effect.all([Clock.currentTimeMillis, waitOf(tail, feed)]).pipe(Effect.map(([now, wait]) => Stream.paginate({ after, ready: !1, delayMs: 0, quietSince: now, startedAt: now }, (cursor) => Effect.gen(function* () {
+    yield* wait(cursor.delayMs);
+    const at = yield* Clock.currentTimeMillis;
+    if (at - cursor.startedAt >= options.maxDurationMs)
+      return [[], Option.none()];
+    const fresh = (yield* tail.read(feed, cursor.after)).filter((record) => record.sequence > cursor.after);
+    if (fresh.length > 0) {
+      const frames = (yield* Effect.forEach(fresh, (record) => project(record).pipe(Effect.map(Option.map((payload) => FeedRecord.make({ sequence: record.sequence, event: payload.event, data: payload.data })))))).flatMap(Option.toArray), next = {
+        ...cursor,
+        after: fresh.reduce((last, record) => Math.max(last, record.sequence), cursor.after),
+        delayMs: nextPollMs(cursor.delayMs, options, !0),
+        quietSince: frames.length > 0 ? at : cursor.quietSince
+      };
+      return [frames, Option.some(next)];
+    }
+    const heartbeat = cursor.ready && at - cursor.quietSince >= options.heartbeatMs, frames = [
+      ...cursor.ready ? [] : [FeedReady.make({})],
+      ...heartbeat ? [FeedHeartbeat.make({})] : []
+    ], next = {
+      ...cursor,
+      ready: !0,
+      delayMs: nextPollMs(cursor.delayMs, options, !1),
+      quietSince: frames.length > 0 ? at : cursor.quietSince
+    };
+    return [frames, Option.some(next)];
+  })))))
+}), RenderFeedLive = (options) => Layer.effect(RenderFeed, JournalTail.pipe(Effect.map((tail) => makeRenderFeed(tail, options))));

package/dist/render-output.adapter.d.ts

@@ -0,0 +1,10 @@
+import { Layer } from "effect";
+import { UiOutput, UiOutputAdmission, UiOutputContext, UiOutputJournal, UiOutputTools } from "./ports/render-output.port.js";
+export declare const UiOutputLive: (maxBytes?: number) => Layer.Layer<UiOutput, never, UiOutputAdmission | UiOutputJournal | UiOutputContext>;
+export declare const UiOutputHandlersLive: Layer.Layer<import("effect/ai/Tool").Handler<"render_component">, never, UiOutput>;
+/** Transport-independent: WebSocket/SSE hosts consume the committed journal. */
+export declare const uiOutputPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly maxBytes: number;
+}, {
+    readonly maxBytes: number;
+}, UiOutput | UiOutputTools, never, UiOutputAdmission | UiOutputJournal | UiOutputContext>;

package/dist/render-output.adapter.js

@@ -0,0 +1,28 @@
+import { Effect, Layer, Schema } from "effect";
+import { definePlugin } from "@xandreed/core";
+import { UiOutputError, UiOutputProposal } from "./domain/render-output.entity.js";
+import { UiOutput, UiOutputAdmission, UiOutputContext, UiOutputJournal, UiOutputTools } from "./ports/render-output.port.js";
+import { uiOutputToolkit } from "./render-output.tools.js";
+export const UiOutputLive = (maxBytes = 32768) => Layer.effect(UiOutput, Effect.gen(function* () {
+  const admission = yield* UiOutputAdmission, journal = yield* UiOutputJournal, scope = yield* UiOutputContext;
+  return UiOutput.of({
+    emit: (input) => Effect.gen(function* () {
+      const proposal = yield* Schema.decodeUnknownEffect(UiOutputProposal)(input, { onExcessProperty: "error" }).pipe(Effect.mapError(() => new UiOutputError({ code: "invalid", message: "Invalid component proposal" }))), json = yield* Schema.encodeEffect(Schema.fromJsonString(UiOutputProposal))(proposal).pipe(Effect.mapError(() => new UiOutputError({ code: "invalid", message: "Component must be serializable" })));
+      if (new TextEncoder().encode(json).byteLength > maxBytes)
+        return yield* Effect.fail(new UiOutputError({ code: "invalid", message: "Component exceeds the configured size limit" }));
+      yield* admission.validate(scope, proposal);
+      return yield* journal.commit(scope, proposal);
+    })
+  });
+})), UiOutputHandlersLive = uiOutputToolkit.toLayer(Effect.gen(function* () {
+  const output = yield* UiOutput;
+  return { render_component: (proposal) => output.emit(proposal).pipe(Effect.mapError((error) => ({ error: error.code, message: error.message }))) };
+})), uiOutputPlugin = definePlugin({
+  id: "@xandreed/plugin-render/output",
+  version: "0.8.0-next.0",
+  requires: [UiOutputAdmission, UiOutputJournal, UiOutputContext],
+  provides: [UiOutput, UiOutputTools],
+  config: Schema.Struct({ maxBytes: Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1024, maximum: 131072 }))) }),
+  defaults: { maxBytes: 32768 },
+  layer: ({ maxBytes }) => Layer.merge(UiOutputLive(maxBytes), Layer.succeed(UiOutputTools, { toolkit: uiOutputToolkit }))
+});

package/dist/render-output.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/render-output.tools.d.ts

@@ -0,0 +1,59 @@
+import { Tool, Toolkit } from "effect/ai";
+export declare const RenderComponent: Tool.Tool<"render_component", {
+    readonly parameters: import("effect/Schema").Struct<{
+        readonly operationId: import("effect/Schema").Trimmed;
+        readonly nodeId: import("effect/Schema").Trimmed;
+        readonly release: import("effect/Schema").Struct<{
+            readonly component: import("effect/Schema").Trimmed;
+            readonly version: import("effect/Schema").Trimmed;
+            readonly definitionHash: import("effect/Schema").String;
+            readonly rendererRelease: import("effect/Schema").Trimmed;
+            readonly tokensHash: import("effect/Schema").String;
+            readonly layoutVersion: import("effect/Schema").Trimmed;
+        }>;
+        readonly props: import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>;
+        readonly evidence: import("effect/Schema").$Array<import("effect/Schema").Trimmed>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+        readonly threadId: import("effect/Schema").Trimmed;
+        readonly messageId: import("effect/Schema").Trimmed;
+        readonly revisionId: import("effect/Schema").Trimmed;
+        readonly sequence: import("effect/Schema").Int;
+        readonly nodeId: import("effect/Schema").Trimmed;
+    }>;
+    readonly failure: import("effect/Schema").Struct<{
+        readonly error: import("effect/Schema").String;
+        readonly message: import("effect/Schema").String;
+    }>;
+    readonly failureMode: "return";
+}, never>;
+export declare const uiOutputToolkit: Toolkit.Toolkit<{
+    readonly render_component: Tool.Tool<"render_component", {
+        readonly parameters: import("effect/Schema").Struct<{
+            readonly operationId: import("effect/Schema").Trimmed;
+            readonly nodeId: import("effect/Schema").Trimmed;
+            readonly release: import("effect/Schema").Struct<{
+                readonly component: import("effect/Schema").Trimmed;
+                readonly version: import("effect/Schema").Trimmed;
+                readonly definitionHash: import("effect/Schema").String;
+                readonly rendererRelease: import("effect/Schema").Trimmed;
+                readonly tokensHash: import("effect/Schema").String;
+                readonly layoutVersion: import("effect/Schema").Trimmed;
+            }>;
+            readonly props: import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>;
+            readonly evidence: import("effect/Schema").$Array<import("effect/Schema").Trimmed>;
+        }>;
+        readonly success: import("effect/Schema").Struct<{
+            readonly threadId: import("effect/Schema").Trimmed;
+            readonly messageId: import("effect/Schema").Trimmed;
+            readonly revisionId: import("effect/Schema").Trimmed;
+            readonly sequence: import("effect/Schema").Int;
+            readonly nodeId: import("effect/Schema").Trimmed;
+        }>;
+        readonly failure: import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").String;
+            readonly message: import("effect/Schema").String;
+        }>;
+        readonly failureMode: "return";
+    }, never>;
+}>;

package/dist/render-output.tools.js

@@ -0,0 +1,10 @@
+import { Tool, Toolkit } from "effect/ai";
+import { Failure } from "@xandreed/core";
+import { UiOutputProposal, UiOutputReceipt } from "./domain/render-output.entity.js";
+export const RenderComponent = Tool.make("render_component", {
+  description: "Publish one complete, evidence-backed component using an exact approved release. Returns its durable canvas revision and chat anchor. Use only catalog props and evidence IDs returned by domain tools. Never emit code, HTML or guessed facts. Reuse operationId only to retry the identical call. Plain answers need no component.",
+  parameters: UiOutputProposal,
+  success: UiOutputReceipt,
+  failure: Failure,
+  failureMode: "return"
+}), uiOutputToolkit = Toolkit.make(RenderComponent);

package/dist/render-store.memory.adapter.d.ts

@@ -0,0 +1,69 @@
+import { Effect, Layer } from "effect";
+import type { UiOutputReceipt } from "./domain/render-output.entity.js";
+import { RenderError, SurfaceFrozen } from "./domain/render-surface.entity.js";
+import type { SurfaceRecord } from "./domain/render-surface.entity.js";
+import { RenderStore } from "./ports/render.port.js";
+export interface MemoryAnnotation {
+    readonly surfaceId: string;
+    readonly kind: string;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** A complete in-process RenderStore, for tests, examples and single-process hosts. */
+export declare const makeMemoryRenderStore: Effect.Effect<{
+    store: {
+        readonly hydrate: (scope: import("./index.js").SurfaceScope) => Effect.Effect<ReadonlyArray<SurfaceRecord>, RenderError>;
+        readonly plan: (scope: import("./index.js").SurfaceScope, record: import("./index.js").SurfacePlanned) => Effect.Effect<void, RenderError>;
+        readonly commit: (scope: import("./index.js").SurfaceScope, write: {
+            readonly versionId: string;
+            readonly proposal: import("@xandreed/ui-agent").UiOutputProposal;
+        }) => Effect.Effect<UiOutputReceipt, RenderError>;
+        readonly complete: (scope: import("./index.js").SurfaceScope, record: import("./index.js").SurfaceCompleted) => Effect.Effect<void, RenderError>;
+        readonly freeze: (scope: import("./index.js").SurfaceScope, record: SurfaceFrozen) => Effect.Effect<void, RenderError>;
+        readonly annotate: (scope: import("./index.js").SurfaceScope, kind: string, data: Readonly<Record<string, unknown>>) => Effect.Effect<void, RenderError>;
+    };
+    records: Effect.Effect<readonly ({
+        readonly _tag: "SurfacePlanned";
+        readonly surfaceId: string;
+        readonly messageId: string;
+        readonly versionId: string;
+        readonly generation: number;
+        readonly baseVersionId: import("effect/Option").Option<string>;
+        readonly phase: "partial" | "complete";
+        readonly spec: {
+            readonly [x: string]: unknown;
+        };
+        readonly nodes: readonly string[];
+        readonly placeholders: readonly string[];
+        readonly signature: string;
+    } | {
+        readonly _tag: "SurfaceCommitted";
+        readonly surfaceId: string;
+        readonly messageId: string;
+        readonly versionId: string;
+        readonly nodeId: string;
+        readonly component: string;
+        readonly receipt: {
+            readonly threadId: string;
+            readonly messageId: string;
+            readonly revisionId: string;
+            readonly sequence: number;
+            readonly nodeId: string;
+        };
+    } | {
+        readonly _tag: "SurfaceCompleted";
+        readonly surfaceId: string;
+        readonly messageId: string;
+        readonly versionId: string;
+        readonly generation: number;
+        readonly phase: "partial" | "complete";
+        readonly frozen: boolean;
+    } | {
+        readonly _tag: "SurfaceFrozen";
+        readonly surfaceId: string;
+        readonly messageId: string;
+        readonly versionId: string;
+        readonly reason: "completion" | "interaction";
+    })[], never, never>;
+    annotations: Effect.Effect<readonly MemoryAnnotation[], never, never>;
+}, never, never>;
+export declare const MemoryRenderStoreLive: Layer.Layer<RenderStore, never, never>;

package/dist/render-store.memory.adapter.js

@@ -0,0 +1,47 @@
+import { Effect, Result, Layer, Ref, Schema } from "effect";
+import { canonicalJson } from "@xandreed/core";
+import { RenderError, SurfaceCommitted, SurfaceFrozen } from "./domain/render-surface.entity.js";
+import { RenderStore } from "./ports/render.port.js";
+const isFrozen = Schema.is(SurfaceFrozen);
+export const makeMemoryRenderStore = Effect.gen(function* () {
+  const stored = yield* Ref.make({ records: [], receipts: new Map, annotations: [], sequence: 0 }), append = (record) => Ref.update(stored, (state) => ({ ...state, records: [...state.records, record] }));
+  return {
+    store: RenderStore.of({
+      hydrate: (scope) => Ref.get(stored).pipe(Effect.map((state) => state.records.filter((record) => record.surfaceId === scope.surfaceId))),
+      plan: (_scope, record) => Ref.modify(stored, (state) => state.records.some((existing) => isFrozen(existing) && existing.surfaceId === record.surfaceId && existing.messageId === record.messageId) ? [!1, state] : [!0, { ...state, records: [...state.records, record] }]).pipe(Effect.flatMap((accepted) => accepted ? Effect.void : Effect.fail(new RenderError({ code: "frozen", message: "The surface is frozen for this message" })))),
+      commit: (scope, { versionId, proposal }) => Ref.modify(stored, (state) => {
+        const content = canonicalJson(proposal), existing = state.receipts.get(proposal.operationId);
+        if (existing !== void 0)
+          return existing.proposal === content ? [Result.succeed(existing.receipt), state] : [Result.fail(new RenderError({ code: "conflict", message: `Operation ${proposal.operationId} was already committed with other content` })), state];
+        const sequence = state.sequence + 1, receipt = {
+          threadId: scope.threadId,
+          messageId: scope.messageId,
+          revisionId: `${proposal.operationId}:r${sequence}`,
+          sequence,
+          nodeId: proposal.nodeId
+        }, committed = SurfaceCommitted.make({
+          surfaceId: scope.surfaceId,
+          messageId: scope.messageId,
+          versionId,
+          nodeId: proposal.nodeId,
+          component: proposal.release.component,
+          receipt
+        });
+        return [Result.succeed(receipt), {
+          ...state,
+          sequence,
+          receipts: new Map([...state.receipts, [proposal.operationId, { proposal: content, receipt }]]),
+          records: [...state.records, committed]
+        }];
+      }).pipe(Effect.flatMap(Result.match({ onFailure: Effect.fail, onSuccess: Effect.succeed }))),
+      complete: (_scope, record) => append(record),
+      freeze: (_scope, record) => Ref.update(stored, (state) => state.records.some((existing) => isFrozen(existing) && existing.versionId === record.versionId) ? state : { ...state, records: [...state.records, record] }),
+      annotate: (scope, kind, data) => Ref.update(stored, (state) => ({
+        ...state,
+        annotations: [...state.annotations, { surfaceId: scope.surfaceId, kind, data }]
+      }))
+    }),
+    records: Ref.get(stored).pipe(Effect.map((state) => state.records)),
+    annotations: Ref.get(stored).pipe(Effect.map((state) => state.annotations))
+  };
+}), MemoryRenderStoreLive = Layer.effect(RenderStore, makeMemoryRenderStore.pipe(Effect.map(({ store }) => store)));

package/dist/render-surface.adapter.d.ts

@@ -0,0 +1,14 @@
+import { Effect, Layer } from "effect";
+import { RenderError } from "./domain/render-surface.entity.js";
+import type { SurfaceScope } from "./domain/render-surface.entity.js";
+import { UiOutputAdmission } from "./ports/render-output.port.js";
+import { Render, RenderStore } from "./ports/render.port.js";
+import type { RenderOpenOptions, RenderSurface } from "./ports/render.port.js";
+/**
+ * One surface for one message: versions (`<messageId>:v<generation>`),
+ * signature dedupe, one idempotent commit per node, completion, freeze and
+ * background preparation. Writes are serialized; preparations run one at a
+ * time through the host's `fork`.
+ */
+export declare const openSurface: (store: typeof RenderStore.Service, admission: typeof UiOutputAdmission.Service, maxBytes: number) => (scope: SurfaceScope, options: RenderOpenOptions) => Effect.Effect<RenderSurface, RenderError>;
+export declare const RenderLive: (maxBytes?: number) => Layer.Layer<Render, never, UiOutputAdmission | RenderStore>;

package/dist/render-surface.adapter.js

@@ -0,0 +1,128 @@
+import { Deferred, Effect, Layer, Option, Ref, Schema, Stream, Semaphore } from "effect";
+import { UiOutputProposal } from "./domain/render-output.entity.js";
+import { RenderError, RenderNode, RenderSnapshot, SurfaceCompleted, SurfaceFrozen, SurfacePlanned } from "./domain/render-surface.entity.js";
+import {
+  describeError,
+  fillOperationIdOf,
+  fromOutputError,
+  operationIdOf,
+  outputScopeOf,
+  progressOf,
+  proposalOf,
+  signatureOf,
+  versionIdOf
+} from "./domain/render-surface.entity.functions.js";
+import { UiOutputAdmission } from "./ports/render-output.port.js";
+import { Render, RenderStore } from "./ports/render.port.js";
+const invalid = (message) => new RenderError({ code: "invalid", message }), unique = (values) => [...new Set(values)];
+export const openSurface = (store, admission, maxBytes) => (scope, options) => Effect.gen(function* () {
+  const records = yield* store.hydrate(scope), progress = yield* Ref.make(progressOf(scope.surfaceId, scope.messageId, records)), writer = yield* Semaphore.make(1), preparer = yield* Semaphore.make(1), preparations = yield* Ref.make([]), output = outputScopeOf(scope), identity = { surfaceId: scope.surfaceId, messageId: scope.messageId }, updateState = (change) => Ref.update(progress, (current) => ({ ...current, state: change(current.state) })), commitNode = (versionId, operationId, node) => Effect.gen(function* () {
+    const proposal = proposalOf(operationId, node), json = yield* Schema.encodeEffect(Schema.fromJsonString(UiOutputProposal))(proposal).pipe(Effect.mapError(() => invalid("A component must be serializable")));
+    if (new TextEncoder().encode(json).byteLength > maxBytes)
+      return yield* Effect.fail(invalid("A component exceeds the configured size limit"));
+    yield* admission.validate(output, proposal).pipe(Effect.mapError(fromOutputError));
+    return yield* store.commit(scope, { versionId, proposal });
+  }), snapshotResult = (frozen) => Ref.get(progress).pipe(Effect.map((current) => ({
+    version: current.state.version,
+    generation: current.state.generation,
+    changed: !1,
+    frozen
+  }))), recordFrozenCompletion = Effect.gen(function* () {
+    const current = yield* Ref.get(progress);
+    if (current.frozenRecorded)
+      return;
+    yield* Option.match(current.state.version, {
+      onNone: () => Effect.void,
+      onSome: (versionId) => store.complete(scope, SurfaceCompleted.make({
+        ...identity,
+        versionId,
+        generation: current.state.generation,
+        phase: "partial",
+        frozen: !0
+      }))
+    });
+    yield* Ref.update(progress, (value) => ({ ...value, frozenRecorded: !0, state: { ...value.state, frozen: !0 } }));
+  }), markComplete = (versionId, generation) => store.complete(scope, SurfaceCompleted.make({
+    ...identity,
+    versionId,
+    generation,
+    phase: "complete",
+    frozen: !1
+  })).pipe(Effect.andThen(updateState((state) => ({ ...state, completed: !0 })))), publishNow = (input) => Effect.gen(function* () {
+    const snapshot = yield* Schema.decodeUnknownEffect(RenderSnapshot)(input, { onExcessProperty: "error", reportInput: !0 }).pipe(Effect.mapError((error) => invalid(`Invalid snapshot: ${error.message}`))), current = yield* Ref.get(progress);
+    if (current.state.frozen)
+      return yield* recordFrozenCompletion.pipe(Effect.andThen(snapshotResult(!0)));
+    const signature = signatureOf(snapshot);
+    if (Option.contains(current.signature, signature)) {
+      if (snapshot.phase === "complete" && !current.state.completed)
+        yield* Option.match(current.state.version, { onNone: () => Effect.void, onSome: (versionId) => markComplete(versionId, current.state.generation) });
+      return yield* snapshotResult(!1);
+    }
+    const generation = current.state.generation + 1, versionId = versionIdOf(scope.messageId, generation);
+    if (!(yield* store.plan(scope, SurfacePlanned.make({
+      ...identity,
+      versionId,
+      generation,
+      baseVersionId: Option.orElse(scope.baseVersion, () => current.state.version),
+      phase: snapshot.phase,
+      spec: snapshot.spec,
+      nodes: snapshot.nodes.map((node) => node.nodeId),
+      placeholders: snapshot.placeholders,
+      signature
+    })).pipe(Effect.as(!0), Effect.catchIf((error) => error.code === "frozen", () => Effect.succeed(!1))))) {
+      yield* updateState((state) => ({ ...state, frozen: !0 }));
+      return yield* recordFrozenCompletion.pipe(Effect.andThen(snapshotResult(!0)));
+    }
+    yield* Ref.update(progress, (value) => ({
+      ...value,
+      signature: Option.some(signature),
+      state: { ...value.state, version: Option.some(versionId), generation, completed: !1, components: [], placeholders: snapshot.placeholders }
+    }));
+    yield* Effect.forEach(snapshot.nodes, (node) => commitNode(versionId, operationIdOf(scope.runId, generation, node.nodeId), node), { discard: !0 });
+    yield* updateState((state) => ({ ...state, components: unique(snapshot.nodes.map((node) => node.release.component)) }));
+    if (snapshot.phase === "complete")
+      yield* markComplete(versionId, generation);
+    return { version: Option.some(versionId), generation, changed: !0, frozen: !1 };
+  }), publish = (input) => writer.withPermits(1)(publishNow(input)), fill = (placeholder, input) => writer.withPermits(1)(Effect.gen(function* () {
+    const node = yield* Schema.decodeUnknownEffect(RenderNode)(input, { onExcessProperty: "error", reportInput: !0 }).pipe(Effect.mapError((error) => invalid(`Invalid node: ${error.message}`))), current = yield* Ref.get(progress), versionId = yield* Option.match(current.state.version, {
+      onNone: () => Effect.fail(invalid("Nothing has been published on this surface")),
+      onSome: Effect.succeed
+    });
+    if (!current.state.placeholders.includes(placeholder))
+      return yield* Effect.fail(invalid(`The current version declares no placeholder ${placeholder}`));
+    if (node.nodeId !== placeholder)
+      return yield* Effect.fail(invalid("A fill must use its placeholder as node id"));
+    const receipt = yield* commitNode(versionId, fillOperationIdOf(scope.runId, placeholder), node);
+    yield* store.annotate(scope, "render.filled", { versionId, placeholder });
+    yield* updateState((state) => ({ ...state, components: unique([...state.components, node.release.component]) }));
+    return receipt;
+  })), prepare = (work, recover) => Effect.gen(function* () {
+    const done = yield* Deferred.make();
+    yield* Ref.update(preparations, (all) => [...all, done]);
+    const run = preparer.withPermits(1)(Stream.runForEach(work, publish)).pipe(Effect.catch((error) => store.annotate(scope, "render.preparation-failed", { message: describeError(error) }).pipe(Effect.ignore, Effect.andThen(recover(error)))), Effect.ensuring(Deferred.succeed(done, void 0)));
+    yield* options.fork(`render:${scope.surfaceId}`, run);
+  }), settled = Ref.get(preparations).pipe(Effect.flatMap((all) => Effect.forEach(all, Deferred.await, { discard: !0 }))), state = Effect.gen(function* () {
+    const current = yield* Ref.get(progress), finished = yield* Effect.forEach(yield* Ref.get(preparations), Deferred.isDone);
+    return { ...current.state, pending: finished.some((done) => !done) };
+  });
+  return {
+    scope,
+    records,
+    state,
+    publish,
+    fill,
+    prepare,
+    settled,
+    freeze: (reason) => writer.withPermits(1)(Effect.gen(function* () {
+      const current = yield* Ref.get(progress);
+      yield* Option.match(current.state.version, {
+        onNone: () => Effect.void,
+        onSome: (versionId) => store.freeze(scope, SurfaceFrozen.make({ ...identity, versionId, reason })).pipe(Effect.andThen(updateState((value) => ({ ...value, frozen: !0 }))))
+      });
+    })),
+    annotate: (kind, data) => store.annotate(scope, kind, data)
+  };
+}), RenderLive = (maxBytes = 32768) => Layer.effect(Render, Effect.gen(function* () {
+  const store = yield* RenderStore, admission = yield* UiOutputAdmission;
+  return Render.of({ open: openSurface(store, admission, maxBytes) });
+}));