@fungi.computer/workflows-wire 0.0.1 → 0.2.0

package/dist/library-contracts.js

@@ -6,7 +6,8 @@ import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
 import { gitAccessSchema, bindingsSelectionSchema, } from "@fungi.computer/braid/git-access";
 import { gitSha1Schema } from "@fungi.computer/puffball/git-representation";
 import { workflowIdSchema, workflowIssueSchema as issueSchema, } from "./outcomes.js";
-export const provenanceSchema = z.union([
+/** Source Workflow and commit recorded when importing or forking a document. */
+export const provenanceSchema = z.lazy(() => z.union([
     z.strictObject({
         kind: z.literal("import"),
         workflowId: workflowIdSchema,
@@ -20,8 +21,9 @@ export const provenanceSchema = z.union([
         workflowId: workflowIdSchema,
         commit: gitSha1Schema,
     }),
-]);
+]));
 const identity = z.string().min(1).max(256);
+/** Shared run request fields: identity, bindings, JSON input and optional delivery. */
 export const runBase = z.strictObject({
     requestId: identity,
     workflowId: workflowIdSchema,
@@ -29,10 +31,12 @@ export const runBase = z.strictObject({
     input: z.record(z.string(), z.json()),
     delivery: runDeliverySchema.optional(),
 });
-export const publishedRun = z.union([
+/** Run request pinned to either a published version or an exact Git commit. */
+export const publishedRun = z.lazy(() => z.union([
     runBase.extend({ version: z.number().int().positive() }),
     runBase.extend({ commit: gitSha1Schema }),
-]);
+]));
+/** Wire document containing definition, node layout, provenance and commit. */
 export const document = z.strictObject({
     provenance: provenanceSchema.optional(),
     definition: z.record(z.string(), z.json()),
@@ -43,15 +47,19 @@ const invalid = z.strictObject({
     kind: z.literal("invalid"),
     issues: z.array(issueSchema),
 });
+/** Nonnegative revision used to fence draft replacements. */
 export const revisionSchema = z.number().int().nonnegative();
+/** Editable document with a draft revision instead of a published commit. */
 export const draftDocument = document
     .omit({ commit: true })
     .extend({ revision: revisionSchema });
+/** Published document identified by Workflow, version, commit and content digest. */
 export const publishedDocument = document.extend({
     workflowId: workflowIdSchema,
     version: z.number().int().positive(),
     digest: z.string().refine(S.is(sha256DigestSchema)),
 });
+/** Draft save result, including revision conflict or validation issues. */
 export const saveReply = z.union([
     z.strictObject({ kind: z.literal("saved"), revision: revisionSchema }),
     z.strictObject({
@@ -61,6 +69,7 @@ export const saveReply = z.union([
     invalid,
 ]);
 const reviewedNode = { graph: z.string(), node: z.string() };
+/** Share review listing Git access, write/external nodes and trigger configuration. */
 export const shareReview = z.strictObject({
     gitAccess: z.array(z.union([
         gitAccessSchema.options[0].extend(reviewedNode),
@@ -76,7 +85,8 @@ export const shareReview = z.strictObject({
     // Definition decoding owns trigger grammar; this reply transports configuration only.
     triggers: z.array(z.json()),
 });
-export const shareCopyReply = z.union([
+/** Import/fork result with the saved draft and review, or a typed refusal. */
+export const shareCopyReply = z.lazy(() => z.union([
     z.strictObject({
         kind: z.literal("saved"),
         revision: revisionSchema,
@@ -97,53 +107,63 @@ export const shareCopyReply = z.union([
             "not_found",
         ]),
     }),
-]);
-export const shareExportReply = z.union([
+]));
+/** Exported bundle bytes and digest, or a missing/oversized bundle result. */
+export const shareExportReply = z.lazy(() => z.union([
     z.strictObject({
         bytes: z.string(),
         sha256: z.string().refine(S.is(sha256DigestSchema)),
     }),
     z.strictObject({ kind: z.enum(["not_found", "too_large"]) }),
-]);
+]));
+/** Mint and validate identities for asynchronous Workflow publication attempts. */
 export const publicationIds = defineIdFamily({
     family: "workflow-publication",
     version: 1,
     kinds: { publication: { prefix: "publication" } },
 });
-export const publicationIdSchema = z
+/** Publication identity accepted by the maintained publication id family. */
+export const publicationIdSchema = z.lazy(() => z
     .string()
     .min(1)
     .max(256)
-    .refine((value) => publicationIds.publication.is(value));
+    .refine((value) => publicationIds.publication.is(value)));
+/** Publication failure categories returned by the host. */
 export const publicationFailure = z.enum([
     "git_conflict",
     "publication_failed",
     "too_large",
     "access_changed",
 ]);
-export const publicationComplete = z.strictObject({
+/** Completed publication's exact commit and assigned version. */
+export const publicationComplete = z.lazy(() => z.strictObject({
     kind: z.literal("published"),
     commit: gitSha1Schema,
     version: z.number().int().positive(),
-});
-export const publicationPending = z.strictObject({
+}));
+/** Pending publication identified for subsequent status reads. */
+export const publicationPending = z.lazy(() => z.strictObject({
     kind: z.literal("publishing"),
     publicationId: publicationIdSchema,
-});
-export const publicationFailed = z.strictObject({
+}));
+/** Failed publication and its typed failure reason. */
+export const publicationFailed = z.lazy(() => z.strictObject({
     kind: z.literal("failed"),
     reason: publicationFailure,
-});
-export const publicationStatus = z.union([
+}));
+/** Current publication outcome, including an unknown publication identity. */
+export const publicationStatus = z.lazy(() => z.union([
     publicationPending,
     publicationComplete,
     publicationFailed,
     z.strictObject({ kind: z.literal("not_found") }),
-]);
-export const publicationElsewhere = z.strictObject({
+]));
+/** Another publication attempt currently owns the publication operation. */
+export const publicationElsewhere = z.lazy(() => z.strictObject({
     kind: z.literal("publishing_elsewhere"),
-});
-export const publishReply = z.union([
+}));
+/** Publication command result, including pending work, conflict or validation issues. */
+export const publishReply = z.lazy(() => z.union([
     publicationElsewhere,
     publicationComplete,
     publicationPending,
@@ -153,15 +173,18 @@ export const publishReply = z.union([
         head: gitSha1Schema.nullable(),
     }),
     invalid,
-]);
+]));
+/** Published version with commit identity, commit time and commit message. */
 export const version = z.strictObject({
     version: z.number().int().positive(),
     commit: gitSha1Schema,
     committedAt: z.number(),
     message: z.string(),
 });
+/** Identify one Workflow within the library. */
 export const workflow = z.strictObject({ workflowId: workflowIdSchema });
-export const listings = z
+/** Bounded library rows with draft revision and optional published reference. */
+export const listings = z.lazy(() => z
     .array(z.strictObject({
     workflowId: workflowIdSchema,
     title: z.string(),
@@ -173,39 +196,38 @@ export const listings = z
     })
         .nullable(),
 }))
-    .max(100);
+    .max(100));
+/** Bounded Git history rows without a published-version number. */
 export const history = z.array(version.omit({ version: true })).max(50);
 /** A missing index is not an empty Git repository; only write paths reconstruct it. */
-export const libraryPageInput = z.strictObject({
+export const libraryPageInput = z.lazy(() => z.strictObject({
     limit: z.number().int().min(1).max(100).default(100),
     after: workflowIdSchema.optional(),
-});
-export const libraryPage = z.strictObject({
+}));
+/** One library page with an optional exclusive cursor for the next page. */
+export const libraryPage = z.lazy(() => z.strictObject({
     items: listings,
     next: workflowIdSchema.optional(),
-});
-export const libraryListing = z.union([
-    libraryPage,
-    z.strictObject({ kind: z.literal("unindexed") }),
-]);
+}));
+/** Indexed library page, or an explicit indication that its index is missing. */
+export const libraryListing = z.lazy(() => z.union([libraryPage, z.strictObject({ kind: z.literal("unindexed") })]));
 /** A missing screen copy needs an explicit foreground rebuild, never a hidden Git read. */
-export const rebuilding = z.strictObject({ kind: z.literal("rebuilding") });
-export const documentRead = z.union([
-    draftDocument,
-    document,
-    z.null(),
-    rebuilding,
-]);
-export const versionsRead = z.union([z.array(version), rebuilding]);
-export const rebuildCopiesInput = z.strictObject({
+export const rebuilding = z.lazy(() => z.strictObject({ kind: z.literal("rebuilding") }));
+/** Draft/published document read, absence, or an explicit copy-rebuild state. */
+export const documentRead = z.lazy(() => z.union([draftDocument, document, z.null(), rebuilding]));
+/** Published version rows, or an explicit copy-rebuild state. */
+export const versionsRead = z.lazy(() => z.union([z.array(version), rebuilding]));
+/** Bounded copy-rebuild continuation, optionally targeting one pinned document. */
+export const rebuildCopiesInput = z.lazy(() => z.strictObject({
     cursor: z.string().max(1024).nullable(),
     target: workflow
         .extend({
         at: z.strictObject({ commit: gitSha1Schema }),
     })
         .optional(),
-});
-export const rebuildCopiesReply = z.strictObject({
+}));
+/** Copy-rebuild progress and the cursor needed to continue unfinished work. */
+export const rebuildCopiesReply = z.lazy(() => z.strictObject({
     done: z.boolean(),
     cursor: z.string().max(1024).nullable(),
-});
+}));

package/dist/outcomes.d.ts

@@ -1,12 +1,14 @@
 import * as z from "zod";
+/** Lowercase Workflow slug used by library files and host commands. */
 export declare const workflowIdSchema: z.ZodString;
-export declare const catalogInputSchema: z.ZodObject<{
+/** Select the palette index, or one installation's complete port declarations. */
+export declare const catalogInputSchema: z.ZodLazy<z.ZodObject<{
     installationId: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** App method declarations admitted by the host for the current invocation. */
-export declare const catalogReplySchema: z.ZodUnion<readonly [z.ZodObject<{
-    apps: z.ZodArray<z.ZodObject<{
-        methods: z.ZodRecord<z.ZodString, z.ZodObject<{
+export declare const catalogReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
+    apps: z.ZodArray<z.ZodLazy<z.ZodObject<{
+        methods: z.ZodRecord<z.ZodString, z.ZodLazy<z.ZodObject<{
             pending: z.ZodOptional<z.ZodLiteral<true>>;
             description: z.ZodString;
             effect: z.ZodEnum<{
@@ -21,19 +23,21 @@ export declare const catalogReplySchema: z.ZodUnion<readonly [z.ZodObject<{
             }>;
             requires: z.ZodArray<z.ZodString>;
             digest: z.ZodString;
-        }, z.core.$strict>>;
-        events: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        }, z.core.$strict>>>;
+        events: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodLazy<z.ZodObject<{
             description: z.ZodString;
             digest: z.ZodString;
-        }, z.core.$strict>>>;
+        }, z.core.$strict>>>>;
         installationId: z.ZodString;
         appId: z.ZodString;
         displayName: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            approvals: "approvals";
             "agent.list": "agent.list";
             "agent.manage": "agent.manage";
             "agent.rename": "agent.rename";
+            "agent.avatar": "agent.avatar";
             "agent.toolPolicy": "agent.toolPolicy";
             "agent.read": "agent.read";
             "agent.send": "agent.send";
@@ -61,9 +65,9 @@ export declare const catalogReplySchema: z.ZodUnion<readonly [z.ZodObject<{
         }>>>;
         workflowPublishGranted: z.ZodOptional<z.ZodBoolean>;
         workflowRunGranted: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodObject<{
-    app: z.ZodObject<{
+    app: z.ZodLazy<z.ZodObject<{
         methods: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
         events: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
         installationId: z.ZodString;
@@ -71,9 +75,11 @@ export declare const catalogReplySchema: z.ZodUnion<readonly [z.ZodObject<{
         displayName: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            approvals: "approvals";
             "agent.list": "agent.list";
             "agent.manage": "agent.manage";
             "agent.rename": "agent.rename";
+            "agent.avatar": "agent.avatar";
             "agent.toolPolicy": "agent.toolPolicy";
             "agent.read": "agent.read";
             "agent.send": "agent.send";
@@ -101,11 +107,12 @@ export declare const catalogReplySchema: z.ZodUnion<readonly [z.ZodObject<{
         }>>>;
         workflowPublishGranted: z.ZodOptional<z.ZodBoolean>;
         workflowRunGranted: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const workflowIssueSchema: z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Validation issue with optional graph, node, trigger, port or edge location. */
+export declare const workflowIssueSchema: z.ZodLazy<z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     graph: z.ZodOptional<z.ZodString>;
@@ -113,8 +120,9 @@ export declare const workflowIssueSchema: z.ZodObject<{
     trigger: z.ZodOptional<z.ZodString>;
     port: z.ZodOptional<z.ZodString>;
     edge: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export declare const runReply: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strip>>;
+/** Run admission result, including replay/conflict, invalid input or refusal. */
+export declare const runReply: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodEnum<{
         started: "started";
         replay: "replay";
@@ -124,7 +132,7 @@ export declare const runReply: z.ZodUnion<readonly [z.ZodObject<{
     planDigest: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"invalid">;
-    issues: z.ZodArray<z.ZodObject<{
+    issues: z.ZodArray<z.ZodLazy<z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         graph: z.ZodOptional<z.ZodString>;
@@ -132,11 +140,12 @@ export declare const runReply: z.ZodUnion<readonly [z.ZodObject<{
         trigger: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodString>;
         edge: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const cancelReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Cancellation result, an already-terminal run, or an authority refusal. */
+export declare const cancelReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodEnum<{
         cancelled: "cancelled";
         terminal: "terminal";
@@ -146,13 +155,15 @@ export declare const cancelReplySchema: z.ZodUnion<readonly [z.ZodObject<{
     reason: z.ZodLiteral<"denied">;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>>;
+/** Lifecycle outcome reported for a Workflow run. */
 export declare const runOutcomeSchema: z.ZodEnum<{
     cancelled: "cancelled";
     terminal: "terminal";
     active: "active";
 }>;
-export declare const statusReply: z.ZodUnion<readonly [z.ZodObject<{
+/** Bounded run status snapshot with events, reviews, output and error. */
+export declare const statusReply: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     runId: z.ZodString;
     planDigest: z.ZodString;
     outcome: z.ZodEnum<{
@@ -168,8 +179,9 @@ export declare const statusReply: z.ZodUnion<readonly [z.ZodObject<{
     error: z.ZodJSONSchema;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const answerReviewReply: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Result of answering a waiting run review, or an invocation refusal. */
+export declare const answerReviewReply: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     result: z.ZodEnum<{
         invalid: "invalid";
         denied: "denied";
@@ -178,8 +190,9 @@ export declare const answerReviewReply: z.ZodUnion<readonly [z.ZodObject<{
     }>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const scheduleArmReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Schedule-trigger admission or its refusal details. */
+export declare const scheduleArmReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"armed">;
     scheduleId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -188,18 +201,21 @@ export declare const scheduleArmReplySchema: z.ZodUnion<readonly [z.ZodObject<{
     issues: z.ZodOptional<z.ZodArray<z.ZodJSONSchema>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const triggerDisarmReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Trigger disarm result, including an absent trigger or denied invocation. */
+export declare const triggerDisarmReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodEnum<{
         disarmed: "disarmed";
         not_found: "not_found";
     }>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const schedulesReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Visible schedule-trigger rows with their next due time and lifecycle state. */
+export declare const schedulesReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     schedules: z.ZodArray<z.ZodObject<{
         scheduleId: z.ZodString;
+        installationId: z.ZodString;
         workflowId: z.ZodString;
         triggerId: z.ZodString;
         nextDueAt: z.ZodNumber;
@@ -213,7 +229,8 @@ export declare const schedulesReplySchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>>;
+/** Origin category recorded for a run: manual, schedule, event, Agent or key. */
 export declare const workflowRunSourceSchema: z.ZodEnum<{
     manual: "manual";
     schedule: "schedule";
@@ -222,7 +239,7 @@ export declare const workflowRunSourceSchema: z.ZodEnum<{
     key: "key";
 }>;
 /** The Agent Session (`sessionId`) stays host-side; the wire names only the Agent/key and its grantor. */
-export declare const workflowRunInitiatedBySchema: z.ZodUnion<readonly [z.ZodObject<{
+export declare const workflowRunInitiatedBySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"member">;
     memberId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -233,8 +250,9 @@ export declare const workflowRunInitiatedBySchema: z.ZodUnion<readonly [z.ZodObj
     kind: z.ZodLiteral<"key">;
     keyId: z.ZodString;
     grantorMemberId: z.ZodString;
-}, z.core.$strict>]>;
-export declare const runsReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Bounded recent-run rows with their source, initiator and pinned commit. */
+export declare const runsReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     runs: z.ZodArray<z.ZodObject<{
         runId: z.ZodString;
         workflowId: z.ZodString;
@@ -247,7 +265,7 @@ export declare const runsReplySchema: z.ZodUnion<readonly [z.ZodObject<{
             key: "key";
         }>;
         triggerId: z.ZodOptional<z.ZodString>;
-        initiatedBy: z.ZodUnion<readonly [z.ZodObject<{
+        initiatedBy: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodLiteral<"member">;
             memberId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
@@ -258,13 +276,14 @@ export declare const runsReplySchema: z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodLiteral<"key">;
             keyId: z.ZodString;
             grantorMemberId: z.ZodString;
-        }, z.core.$strict>]>;
+        }, z.core.$strict>]>>;
         startedAt: z.ZodNumber;
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const eventArmReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Event-trigger admission or its refusal details. */
+export declare const eventArmReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"armed">;
     eventTriggerId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -273,8 +292,9 @@ export declare const eventArmReplySchema: z.ZodUnion<readonly [z.ZodObject<{
     issues: z.ZodOptional<z.ZodArray<z.ZodJSONSchema>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
-export declare const eventTriggersReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+}, z.core.$strict>]>>;
+/** Visible event-trigger rows with emitter, event and current state. */
+export declare const eventTriggersReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     eventTriggers: z.ZodArray<z.ZodObject<{
         eventTriggerId: z.ZodString;
         workflowId: z.ZodString;
@@ -289,4 +309,4 @@ export declare const eventTriggersReplySchema: z.ZodUnion<readonly [z.ZodObject<
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>>;