@fungi.computer/workflows-wire 0.1.0 → 0.2.1

package/dist/outcomes.js

@@ -1,126 +1,226 @@
 import * as z from "zod";
 import { appCapabilityIds } from "@fungi.computer/puffball";
+/** Lowercase Workflow slug used by library files and host commands. */
 export const workflowIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
 const identity = z.string().min(1).max(256);
-const refusal = z.strictObject({ error: identity });
+const refusal = z.strictObject({
+    /** Host-authored invocation refusal. */
+    error: identity,
+});
 /** What the palette shows before a method's ports are ever fetched. */
 const methodSummarySchema = z.lazy(() => z.strictObject({
+    /** Port details have not yet been loaded. */
     pending: z.literal(true).optional(),
+    /** Human-readable method summary. */
     description: z.string().max(1000),
+    /** Declared read, write or external effect. */
     effect: z.enum(["read", "write", "external"]),
+    /** Declared approval mode. */
     approval: z.enum(["none", "queue", "simulate"]),
+    /** Capabilities required by this method. */
     requires: z.array(z.string().max(80)).max(64),
+    /** Digest identifying the declaration being summarized. */
     digest: z.string().max(128),
 }));
 const eventSummarySchema = z.lazy(() => z.strictObject({
+    /** Human-readable event summary. */
     description: z.string().max(1000),
+    /** Digest identifying the event declaration. */
     digest: z.string().max(128),
 }));
 const entryIdentity = {
+    /** Installation exposing these ports. */
     installationId: identity,
+    /** App installed at this installation. */
     appId: identity,
+    /** App display name shown in the palette. */
     displayName: z.string().max(256),
+    /** Optional declared App icon. */
     icon: z.string().min(1).max(80).optional(),
+    /** App capabilities included in the admitted catalog row. */
     capabilities: z.array(z.enum(appCapabilityIds)).optional(),
+    /** Whether Workflow publication is granted to this installation. */
     workflowPublishGranted: z.boolean().optional(),
+    /** Whether Workflow execution is granted to this installation. */
     workflowRunGranted: z.boolean().optional(),
 };
 /** `catalog({})`: a palette index over every installation, with no port schemas. */
 const catalogIndexEntrySchema = z.lazy(() => z.strictObject({
     ...entryIdentity,
+    /** Method summaries indexed by declared name. */
     methods: z.record(z.string(), methodSummarySchema),
+    /** Event summaries indexed by declared name. */
     events: z.record(z.string(), eventSummarySchema).optional(),
 }));
 /** `catalog({installationId})`: that one installation's full declared ports. */
 const catalogFullEntrySchema = z.lazy(() => z.strictObject({
     ...entryIdentity,
+    /** Complete JSON method declarations indexed by name. */
     methods: z.record(z.string(), z.json()),
+    /** Complete JSON event declarations indexed by name. */
     events: z.record(z.string(), z.json()).optional(),
 }));
+/** Select the palette index, or one installation's complete port declarations. */
 export const catalogInputSchema = z.lazy(() => z.strictObject({
+    /** Select one installation, or omit to read the palette index. */
     installationId: identity.optional(),
 }));
 /** App method declarations admitted by the host for the current invocation. */
 export const catalogReplySchema = z.lazy(() => z.union([
-    z.strictObject({ apps: z.array(catalogIndexEntrySchema).max(200) }),
-    z.strictObject({ app: catalogFullEntrySchema }),
+    z.strictObject({
+        /** Bounded palette index over admitted installations. */
+        apps: z.array(catalogIndexEntrySchema).max(200),
+    }),
+    z.strictObject({
+        /** Full port declarations for the selected installation. */
+        app: catalogFullEntrySchema,
+    }),
     refusal,
 ]));
+/** Validation issue with optional graph, node, trigger, port or edge location. */
 export const workflowIssueSchema = z.lazy(() => z.object({
+    /** Machine-readable validation issue category. */
     code: z.string(),
+    /** Human-readable validation explanation. */
     message: z.string(),
+    /** Graph containing the invalid declaration. */
     graph: z.string().optional(),
+    /** Node associated with this issue. */
     node: z.string().optional(),
+    /** Trigger associated with this issue. */
     trigger: z.string().optional(),
+    /** Port associated with this issue. */
     port: z.string().optional(),
+    /** Edge index associated with this issue. */
     edge: z.number().optional(),
 }));
+/** Run admission result, including replay/conflict, invalid input or refusal. */
 export const runReply = z.lazy(() => z.union([
     z.strictObject({
+        /** Admission, replay or request-conflict discriminator. */
         kind: z.enum(["started", "replay", "conflict"]),
+        /** Identity of the run selected by admission. */
         runId: identity,
+        /** Digest of the admitted plan. */
         planDigest: identity,
     }),
     z.strictObject({
+        /** The run request failed validation. */
         kind: z.literal("invalid"),
+        /** Validation issues explaining the refusal. */
         issues: z.array(workflowIssueSchema),
     }),
-    z.strictObject({ error: identity }),
+    z.strictObject({
+        /** Host-authored invocation refusal. */
+        error: identity,
+    }),
 ]));
+/** Cancellation result, an already-terminal run, or an authority refusal. */
 export const cancelReplySchema = z.lazy(() => z.union([
-    z.strictObject({ kind: z.enum(["cancelled", "terminal"]) }),
-    z.strictObject({ kind: z.literal("refused"), reason: z.literal("denied") }),
-    z.strictObject({ error: z.string() }),
+    z.strictObject({
+        /** Cancellation completed, or the run was already terminal. */
+        kind: z.enum(["cancelled", "terminal"]),
+    }),
+    z.strictObject({
+        /** The cancellation was refused. */
+        kind: z.literal("refused"),
+        /** Caller lacked authority to cancel the run. */
+        reason: z.literal("denied"),
+    }),
+    z.strictObject({
+        /** Host-authored invocation error. */
+        error: z.string(),
+    }),
 ]));
+/** Lifecycle outcome reported for a Workflow run. */
 export const runOutcomeSchema = z.enum(["active", "terminal", "cancelled"]);
+/** Bounded run status snapshot with events, reviews, output and error. */
 export const statusReply = z.lazy(() => z.union([
     z.strictObject({
+        /** Identity of the inspected run. */
         runId: identity,
+        /** Digest of the run's admitted plan. */
         planDigest: identity,
+        /** Current run lifecycle outcome. */
         outcome: runOutcomeSchema,
+        /** Human-readable run title. */
         title: z.string().max(120),
+        /** Bounded run event records. */
         events: z.array(z.record(z.string(), z.json())).max(4096),
+        /** Bounded review records associated with the run. */
         reviews: z.array(z.record(z.string(), z.json())).max(256),
+        /** Run status label supplied by the host. */
         status: identity,
+        /** JSON run output. */
         output: z.json(),
+        /** JSON run error. */
         error: z.json(),
     }),
     refusal,
 ]));
+/** Result of answering a waiting run review, or an invocation refusal. */
 export const answerReviewReply = z.lazy(() => z.union([
     z.strictObject({
+        /** Acceptance, denial, absence of a waiting review or invalid answer. */
         result: z.enum(["accepted", "denied", "not_waiting", "invalid"]),
     }),
     refusal,
 ]));
 const id = z.string().min(1).max(256);
-const denied = z.strictObject({ error: id });
+const denied = z.strictObject({
+    /** Host-authored invocation refusal. */
+    error: id,
+});
+/** Schedule-trigger admission or its refusal details. */
 export const scheduleArmReplySchema = z.lazy(() => z.union([
-    z.strictObject({ kind: z.literal("armed"), scheduleId: id }),
     z.strictObject({
+        /** Schedule-trigger registration was armed. */
+        kind: z.literal("armed"),
+        /** Identity of the armed schedule registration. */
+        scheduleId: id,
+    }),
+    z.strictObject({
+        /** Schedule-trigger registration was refused. */
         kind: z.literal("refused"),
+        /** Host-authored reason for the refusal. */
         reason: z.string(),
+        /** Optional validation issues associated with the trigger. */
         issues: z.array(z.json()).optional(),
     }),
     denied,
 ]));
+/** Trigger disarm result, including an absent trigger or denied invocation. */
 export const triggerDisarmReplySchema = z.lazy(() => z.union([
-    z.strictObject({ kind: z.enum(["disarmed", "not_found"]) }),
+    z.strictObject({
+        /** Registration was disarmed or was already absent. */
+        kind: z.enum(["disarmed", "not_found"]),
+    }),
     denied,
 ]));
+/** Visible schedule-trigger rows with their next due time and lifecycle state. */
 export const schedulesReplySchema = z.lazy(() => z.union([
     z.strictObject({
+        /** Schedule-trigger registrations visible to this invocation. */
         schedules: z.array(z.strictObject({
+            /** Identity of the schedule registration. */
             scheduleId: id,
+            /** Installation owning the Workflow schedule and its control door. */
+            installationId: id,
+            /** Workflow whose published trigger was armed. */
             workflowId: workflowIdSchema,
+            /** Trigger identity within the published definition. */
             triggerId: id,
+            /** Next occurrence time in epoch milliseconds. */
             nextDueAt: z.number().int(),
+            /** Current schedule lifecycle state. */
             state: z.enum(["active", "paused", "cancelled", "finished"]),
+            /** Latest scheduling failure, or null when absent. */
             lastError: z.string().nullable(),
         })),
     }),
     denied,
 ]));
+/** Origin category recorded for a run: manual, schedule, event, Agent or key. */
 export const workflowRunSourceSchema = z.enum([
     "manual",
     "schedule",
@@ -130,52 +230,90 @@ export const workflowRunSourceSchema = z.enum([
 ]);
 /** The Agent Session (`sessionId`) stays host-side; the wire names only the Agent/key and its grantor. */
 export const workflowRunInitiatedBySchema = z.lazy(() => z.union([
-    z.strictObject({ kind: z.literal("member"), memberId: id }),
     z.strictObject({
+        /** Run initiated directly by a member. */
+        kind: z.literal("member"),
+        /** Identity of the initiating member. */
+        memberId: id,
+    }),
+    z.strictObject({
+        /** Run initiated by an Agent. */
         kind: z.literal("agent"),
+        /** Identity of the initiating Agent. */
         agentId: id,
+        /** Member whose grant authorizes the invocation. */
         grantorMemberId: id,
     }),
     z.strictObject({
+        /** Run initiated by a named key. */
         kind: z.literal("key"),
+        /** Identity of the initiating key. */
         keyId: id,
+        /** Member whose grant authorizes the invocation. */
         grantorMemberId: id,
     }),
 ]));
+/** Bounded recent-run rows with their source, initiator and pinned commit. */
 export const runsReplySchema = z.lazy(() => z.union([
     z.strictObject({
+        /** Bounded recent runs visible to this invocation. */
         runs: z
             .array(z.strictObject({
+            /** Identity of the recorded run. */
             runId: id,
+            /** Workflow selected by the run. */
             workflowId: workflowIdSchema,
+            /** Exact published commit used by the run. */
             commit: z.string(),
+            /** Origin category recorded at admission. */
             source: workflowRunSourceSchema,
+            /** Published trigger that initiated the run, when applicable. */
             triggerId: id.optional(),
+            /** Host-admitted initiating principal and grantor. */
             initiatedBy: workflowRunInitiatedBySchema,
+            /** Run start timestamp. */
             startedAt: z.number(),
         }))
             .max(50),
     }),
     denied,
 ]));
+/** Event-trigger admission or its refusal details. */
 export const eventArmReplySchema = z.lazy(() => z.union([
-    z.strictObject({ kind: z.literal("armed"), eventTriggerId: id }),
     z.strictObject({
+        /** Event-trigger registration was armed. */
+        kind: z.literal("armed"),
+        /** Identity of the armed event registration. */
+        eventTriggerId: id,
+    }),
+    z.strictObject({
+        /** Event-trigger registration was refused. */
         kind: z.literal("refused"),
+        /** Host-authored reason for the refusal. */
         reason: z.string(),
+        /** Optional validation issues associated with the trigger. */
         issues: z.array(z.json()).optional(),
     }),
     denied,
 ]));
+/** Visible event-trigger rows with emitter, event and current state. */
 export const eventTriggersReplySchema = z.lazy(() => z.union([
     z.strictObject({
+        /** Event-trigger registrations visible to this invocation. */
         eventTriggers: z.array(z.strictObject({
+            /** Identity of the event registration. */
             eventTriggerId: id,
+            /** Workflow whose published trigger was armed. */
             workflowId: workflowIdSchema,
+            /** Trigger identity within the published definition. */
             triggerId: id,
+            /** Installation supplying the subscribed event. */
             emitterInstallationId: id,
+            /** Declared event name. */
             event: id,
+            /** Current event registration state. */
             state: z.enum(["active", "paused"]),
+            /** Latest event-trigger failure, or null when absent. */
             lastError: z.string().nullable(),
         })),
     }),

package/dist/published-definition.d.ts

@@ -1,6 +1,6 @@
 import { type WorkflowDefinition } from "@fungi.computer/braid";
 import type { PublishedDefinitionPort, WorkflowPublicationContext } from "@fungi.computer/braid/runtime";
-/** The slice of {@link WorkflowPublicationContext} this port actually reads. */
+/** The installation identity and Git access read from the Workflow publication context. */
 export type WorkflowPublishedDefinitionContext = Pick<WorkflowPublicationContext, "installationId" | "git">;
 /**
  * How a host reads one published Workflow definition back out of Git. The
@@ -8,6 +8,7 @@ export type WorkflowPublishedDefinitionContext = Pick<WorkflowPublicationContext
  * port only wraps that read into the braid-shaped `PublishedDefinition`.
  */
 export type WorkflowPublishedReader = Readonly<{
+    /** Read an exact published version or commit, or null when absent. */
     published(workflowId: string, at: {
         version: number;
     } | {

package/dist/repository-app-source.d.ts

@@ -0,0 +1,11 @@
+import * as S from "effect/Schema";
+/** A registered repository App as the host reports it to the calling installation:
+ * read-only identity from the source owner and the live caller. Hosts and Apps
+ * share this wire; an App never imports the host package for it.
+ * Reading it neither registers a repository nor selects or runs a Computer. */
+export declare const repositoryWorkflowSourceSchema: S.Struct<{
+    readonly appId: S.refine<import("@fungi.computer/puffball").AppId, S.String>;
+    readonly installationId: S.String;
+    readonly callerAppId: S.refine<import("@fungi.computer/puffball").AppId, S.String>;
+    readonly callerSourceRevision: S.refine<import("@fungi.computer/puffball").SourceRevision, S.String>;
+}>;

package/dist/repository-app-source.js

@@ -0,0 +1,12 @@
+import * as S from "effect/Schema";
+import { appIdSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+/** A registered repository App as the host reports it to the calling installation:
+ * read-only identity from the source owner and the live caller. Hosts and Apps
+ * share this wire; an App never imports the host package for it.
+ * Reading it neither registers a repository nor selects or runs a Computer. */
+export const repositoryWorkflowSourceSchema = S.Struct({
+    appId: appIdSchema,
+    installationId: S.String.check(S.isMinLength(1), S.isMaxLength(256)),
+    callerAppId: appIdSchema,
+    callerSourceRevision: sourceRevisionSchema,
+});

package/dist/run-contracts.d.ts

@@ -35,6 +35,7 @@ export declare const runListItemSchema: z.ZodLazy<z.ZodObject<{
         grantorMemberId: z.ZodString;
     }, z.core.$strict>]>>;
 }, z.core.$strict>>;
+/** Decoded run row with its pinned publication and display metadata. */
 export type WorkflowRunListItem = z.output<typeof runListItemSchema>;
 /**
  * The calling member's own id, so the Runs UI can tell its own runs from a
@@ -46,4 +47,5 @@ export declare const viewerReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObje
 }, z.core.$strict>, z.ZodObject<{
     error: z.ZodString;
 }, z.core.$strict>]>>;
+/** Calling member identity, or a refusal returned by the viewer read. */
 export type ViewerReply = z.output<typeof viewerReplySchema>;

package/dist/trigger-contracts.d.ts

@@ -4,6 +4,7 @@ export declare const runDeliverySchema: z.ZodObject<{
     agentId: z.ZodString;
     sessionId: z.ZodString;
 }, z.core.$strict>;
+/** Agent and Session selected to receive run endings. */
 export type RunDelivery = z.output<typeof runDeliverySchema>;
 /** One chat the member may choose for run reports: an existing Agent Session. */
 export declare const chatsReplySchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
@@ -28,13 +29,17 @@ export declare const triggerTargetSchema: z.ZodLazy<z.ZodObject<{
         sessionId: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>>;
+/** Identify the schedule-trigger registration to disarm. */
 export declare const scheduleDisarmInputSchema: z.ZodObject<{
     scheduleId: z.ZodString;
 }, z.core.$strict>;
+/** Identify the event-trigger registration to disarm. */
 export declare const eventDisarmInputSchema: z.ZodObject<{
     eventTriggerId: z.ZodString;
 }, z.core.$strict>;
+/** Trigger listing takes no caller-supplied filters. */
 export declare const triggerListInputSchema: z.ZodObject<{}, z.core.$strict>;
+/** Published trigger, pinned commit, selected bindings and optional run delivery. */
 export type WorkflowTriggerTarget = z.output<typeof triggerTargetSchema>;
 /** Host binding input carries the App-owned immutable row digest, never caller input. */
 export type WorkflowTriggerArmTarget = WorkflowTriggerTarget & Readonly<{

package/dist/trigger-contracts.js

@@ -22,6 +22,9 @@ export const triggerTargetSchema = z.lazy(() => z.strictObject({
     bindings: bindingsSelectionSchema,
     delivery: runDeliverySchema.optional(),
 }));
+/** Identify the schedule-trigger registration to disarm. */
 export const scheduleDisarmInputSchema = z.strictObject({ scheduleId: id });
+/** Identify the event-trigger registration to disarm. */
 export const eventDisarmInputSchema = z.strictObject({ eventTriggerId: id });
+/** Trigger listing takes no caller-supplied filters. */
 export const triggerListInputSchema = z.strictObject({});

package/dist/workflow-repository.d.ts

@@ -4,13 +4,14 @@ import * as S from "effect/Schema";
 /**
  * The read side of a Workflows library's Git layout, shared by the Workflows
  * App and the hosts that read its published definitions: one repository,
- * `workflows`, one `workflows/<id>.json` file per Workflow (its definition
+ * `trellis`, one `workflows/<id>.json` file per Workflow (its definition
  * plus `layout` and optional `provenance`), and one `<id>@v<n>` tag per
  * published version on `main`'s ancestry.
  */
 export declare const workflowLibraryRepository = "trellis";
 /** Where one Workflow's file lives in its library repository. */
 export declare const workflowFilePath: (id: string) => string;
+/** Decode stored definition, node layout and optional import/fork provenance. */
 export declare const workflowDraftSchema: S.Struct<{
     readonly definition: S.Struct<{
         readonly format: S.Literal<"fungi.workflow/v1">;
@@ -273,8 +274,10 @@ export declare const workflowDraftSchema: S.Struct<{
 export type WorkflowDraft = typeof workflowDraftSchema.Type;
 /** A Workflow file's content at the commit it was read from. */
 export type WorkflowDocument = WorkflowDraft & {
+    /** Exact Git commit from which the document was read. */
     readonly commit: string;
 };
+/** Read-only Git operations needed to traverse and decode library files. */
 export type WorkflowReadGit = Pick<GitBinding, "readCommit" | "readTree" | "readBlob">;
 /** Read the immediate Workflow directory without following symlinks or submodules. */
 export declare function workflowFiles(git: WorkflowReadGit, commit: string | null): Promise<Readonly<{

package/dist/workflow-repository.js

@@ -6,7 +6,7 @@ import { provenanceSchema } from "./library-contracts.js";
 /**
  * The read side of a Workflows library's Git layout, shared by the Workflows
  * App and the hosts that read its published definitions: one repository,
- * `workflows`, one `workflows/<id>.json` file per Workflow (its definition
+ * `trellis`, one `workflows/<id>.json` file per Workflow (its definition
  * plus `layout` and optional `provenance`), and one `<id>@v<n>` tag per
  * published version on `main`'s ancestry.
  */
@@ -16,6 +16,7 @@ const emptyTree = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 /** Where one Workflow's file lives in its library repository. */
 export const workflowFilePath = (id) => `workflows/${workflowIdSchema.parse(id)}.json`;
 const layoutSchema = S.Record(S.String, S.Struct({ x: S.Finite, y: S.Finite }));
+/** Decode stored definition, node layout and optional import/fork provenance. */
 export const workflowDraftSchema = S.Struct({
     definition: workflowDefinitionSchema,
     layout: layoutSchema,