@fungi.computer/braid 0.0.1 → 0.2.0

package/dist/runtime/trigger-run-reservations.js

@@ -8,22 +8,22 @@ const reservationIds = defineIdFamily({
     kinds: { reservation: { prefix: "wf_trigger_reservation" } },
 });
 const identity = z.string().min(1).max(256);
-const triggerRunScopeSchema = z.strictObject({
+const triggerRunScopeSchema = z.lazy(() => z.strictObject({
     installationId: identity,
     workflowId: workflowIdSchema,
     commit: gitSha1Schema,
     triggerId: z.string().min(1).max(80),
-});
-const reservationInputSchema = z.strictObject({
+}));
+const reservationInputSchema = z.lazy(() => z.strictObject({
     scope: triggerRunScopeSchema,
     requestId: z.string().min(1).max(1024),
-});
-const rowSchema = z.object({
+}));
+const rowSchema = z.lazy(() => z.object({
     reservation_id: identity,
     run_id: identity.nullable(),
     status: z.enum(["active", "released", "terminal"]),
-});
-const countSchema = z.object({ count: z.number().int().nonnegative() });
+}));
+const countSchema = z.lazy(() => z.object({ count: z.number().int().nonnegative() }));
 const scopeKey = (scope) => {
     const parsed = triggerRunScopeSchema.parse(scope);
     return JSON.stringify([
@@ -33,15 +33,134 @@ const scopeKey = (scope) => {
         parsed.triggerId,
     ]);
 };
+const deliveryIdentitySchema = z.strictObject({
+    host: identity,
+    tenant: identity,
+    bindingId: identity,
+    eventId: identity,
+});
+const deliveryInputSchema = z.strictObject({
+    scope: triggerRunScopeSchema,
+    delivery: deliveryIdentitySchema,
+    cargo: z.json(),
+    limits: z.strictObject({
+        hostConcurrency: z.number().int().positive().max(20),
+        bindingConcurrency: z.number().int().positive().max(20),
+    }),
+});
+const deliveryOwnerSchema = deliveryIdentitySchema.pick({
+    host: true,
+    tenant: true,
+});
+const pendingDeliverySchema = rowSchema.and(z.object({
+    scope: z.string(),
+    delivery_record: z.string().nullable(),
+}));
+const DAY = 24 * 60 * 60 * 1000;
 /** The enclosing Team owner supplies SQLite; callers never select the Team. */
 export function createTriggerRunReservations(options) {
     const { sql } = options;
+    const now = options.now ?? Date.now;
     sql.exec(`CREATE TABLE IF NOT EXISTS hub_trigger_run_reservations (
     reservation_id TEXT PRIMARY KEY, scope TEXT NOT NULL, request_id TEXT NOT NULL,
     run_id TEXT UNIQUE, status TEXT NOT NULL CHECK(status IN ('active','released','terminal')),
+    delivery_key TEXT, delivery_record TEXT, delivery_expires_at INTEGER,
+    delivery_host TEXT, delivery_tenant TEXT, delivery_binding TEXT,
+    delivery_pending INTEGER NOT NULL DEFAULT 0 CHECK(delivery_pending IN (0,1)),
     UNIQUE(scope,request_id)
   ) STRICT`);
+    sql.exec(`CREATE INDEX IF NOT EXISTS hub_trigger_delivery_identity
+    ON hub_trigger_run_reservations(delivery_key,delivery_expires_at)`);
+    sql.exec(`CREATE INDEX IF NOT EXISTS hub_trigger_delivery_expiry
+    ON hub_trigger_run_reservations(delivery_expires_at)`);
+    const expireDeliveries = () => {
+        const at = now();
+        // An expired unstarted intent cannot wake forever. A recorded active run
+        // still owns its concurrency slot even after delivery deduplication expires.
+        sql.exec("UPDATE hub_trigger_run_reservations SET status='terminal',delivery_pending=0 WHERE reservation_id IN (SELECT reservation_id FROM hub_trigger_run_reservations WHERE delivery_expires_at<=? AND run_id IS NULL LIMIT 100)", at);
+        sql.exec("DELETE FROM hub_trigger_run_reservations WHERE reservation_id IN (SELECT reservation_id FROM hub_trigger_run_reservations WHERE delivery_expires_at<=? AND status!='active' AND delivery_pending=0 LIMIT 100)", at);
+        sql.exec("UPDATE hub_trigger_run_reservations SET delivery_key=NULL,delivery_record=NULL,delivery_expires_at=NULL WHERE reservation_id IN (SELECT reservation_id FROM hub_trigger_run_reservations WHERE delivery_expires_at<=? AND run_id IS NOT NULL LIMIT 100)", at);
+        sql.exec("DELETE FROM hub_trigger_run_reservations WHERE reservation_id IN (SELECT reservation_id FROM hub_trigger_run_reservations WHERE delivery_host IS NOT NULL AND delivery_expires_at IS NULL AND status!='active' AND delivery_pending=0 LIMIT 100)");
+    };
     return {
+        /** Opaque verified cargo and delivery identity live with the run reservation. */
+        reserveWebhookDelivery(raw) {
+            const input = deliveryInputSchema.parse(raw);
+            const key = JSON.stringify(input.delivery);
+            return options.transactionSync(() => {
+                expireDeliveries();
+                const prior = sql
+                    .exec("SELECT reservation_id,run_id,status FROM hub_trigger_run_reservations WHERE delivery_key=? AND delivery_expires_at>? ORDER BY delivery_expires_at DESC LIMIT 1", key, now())
+                    .toArray()[0];
+                if (prior !== undefined) {
+                    const row = rowSchema.parse(prior);
+                    return {
+                        kind: "replay",
+                        reservationId: row.reservation_id,
+                        runId: row.run_id,
+                    };
+                }
+                const active = z
+                    .object({
+                    count: z.number(),
+                    binding_count: z.number(),
+                })
+                    .parse(sql
+                    .exec("SELECT count(*) AS count,coalesce(sum(delivery_host=? AND delivery_tenant=? AND delivery_binding=?),0) AS binding_count FROM hub_trigger_run_reservations WHERE status='active'", input.delivery.host, input.delivery.tenant, input.delivery.bindingId)
+                    .toArray()[0]);
+                if (active.count >= input.limits.hostConcurrency ||
+                    active.binding_count >= input.limits.bindingConcurrency)
+                    return { kind: "refused", reason: "limit" };
+                const reservationId = reservationIds.reservation.generate();
+                sql.exec("INSERT INTO hub_trigger_run_reservations(reservation_id,scope,request_id,run_id,status,delivery_key,delivery_record,delivery_expires_at,delivery_pending,delivery_host,delivery_tenant,delivery_binding) VALUES(?,?,?,NULL,'active',?,?,?,1,?,?,?)", reservationId, scopeKey(input.scope), reservationId, key, JSON.stringify(input), now() + DAY, input.delivery.host, input.delivery.tenant, input.delivery.bindingId);
+                return { kind: "reserved", reservationId, runId: null };
+            });
+        },
+        /** Bounded restart/lost-launch-reply recovery over the SAME reservations. */
+        pendingWebhookDeliveries(rawOwner) {
+            const owner = deliveryOwnerSchema.parse(rawOwner);
+            return options.transactionSync(() => {
+                expireDeliveries();
+                return sql
+                    .exec("SELECT reservation_id,run_id,status,scope,delivery_record FROM hub_trigger_run_reservations WHERE delivery_host=? AND delivery_tenant=? AND delivery_pending=1 ORDER BY delivery_expires_at LIMIT 32", owner.host, owner.tenant)
+                    .toArray()
+                    .map((raw) => {
+                    const row = pendingDeliverySchema.parse(raw);
+                    if (row.run_id !== null)
+                        return {
+                            kind: "launch",
+                            reservationId: row.reservation_id,
+                            runId: row.run_id,
+                        };
+                    const record = deliveryInputSchema.parse(JSON.parse(z.string().parse(row.delivery_record)));
+                    return {
+                        kind: "start",
+                        reservationId: row.reservation_id,
+                        ...record,
+                    };
+                });
+            });
+        },
+        /** Native alarms share this deadline with schedules, including idle TTL cleanup. */
+        nextWebhookWake(rawOwner) {
+            const owner = deliveryOwnerSchema.parse(rawOwner);
+            return options.transactionSync(() => {
+                expireDeliveries();
+                const row = z
+                    .object({
+                    pending: z.number(),
+                    expiry: z.number().nullable(),
+                })
+                    .parse(sql
+                    .exec("SELECT coalesce(max(delivery_pending),0) AS pending,min(delivery_expires_at) AS expiry FROM hub_trigger_run_reservations WHERE delivery_host=? AND delivery_tenant=?", owner.host, owner.tenant)
+                    .toArray()[0]);
+                return row.pending === 1 ? now() + 1000 : row.expiry;
+            });
+        },
+        completeWebhookDelivery(rawReservationId) {
+            const reservationId = identity.parse(rawReservationId);
+            sql.exec("UPDATE hub_trigger_run_reservations SET delivery_pending=0,delivery_record=NULL,status=CASE WHEN run_id IS NULL THEN 'terminal' ELSE status END WHERE reservation_id=? AND delivery_pending=1", reservationId);
+        },
         reserveTriggerRun(raw) {
             const input = reservationInputSchema.parse(raw);
             const scope = scopeKey(input.scope);

package/dist/schema.d.ts

@@ -94,6 +94,12 @@ export declare const nodeSchema: S.Union<readonly [S.Struct<{
     readonly id: S.String;
     readonly kind: S.Literal<"review">;
     readonly title: S.String;
+    /**
+     * One plain line under the title saying where the run is, such as
+     * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+     * filled from the loops around the review (see `fillReviewText`).
+     */
+    readonly detail: S.optionalKey<S.String>;
     readonly show: S.$Array<S.Struct<{
         readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
         readonly port: S.String;
@@ -102,11 +108,14 @@ export declare const nodeSchema: S.Union<readonly [S.Struct<{
     readonly timeout: S.Number;
     /**
      * Named outcomes a reviewer picks from; each is an output port carrying
-     * the shown item. Without choices the review approves or rejects.
+     * the shown item. Without choices the review approves or rejects. A
+     * choice's `description` says in plain words what picking it does, with
+     * the same placeholders as `detail`.
      */
     readonly choices: S.optionalKey<S.$Array<S.Struct<{
         readonly id: S.String;
         readonly label: S.String;
+        readonly description: S.optionalKey<S.String>;
     }>>>;
 }>, S.Struct<{
     readonly id: S.String;
@@ -199,6 +208,12 @@ export declare const graphSchema: S.Struct<{
         readonly id: S.String;
         readonly kind: S.Literal<"review">;
         readonly title: S.String;
+        /**
+         * One plain line under the title saying where the run is, such as
+         * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+         * filled from the loops around the review (see `fillReviewText`).
+         */
+        readonly detail: S.optionalKey<S.String>;
         readonly show: S.$Array<S.Struct<{
             readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
             readonly port: S.String;
@@ -207,11 +222,14 @@ export declare const graphSchema: S.Struct<{
         readonly timeout: S.Number;
         /**
          * Named outcomes a reviewer picks from; each is an output port carrying
-         * the shown item. Without choices the review approves or rejects.
+         * the shown item. Without choices the review approves or rejects. A
+         * choice's `description` says in plain words what picking it does, with
+         * the same placeholders as `detail`.
          */
         readonly choices: S.optionalKey<S.$Array<S.Struct<{
             readonly id: S.String;
             readonly label: S.String;
+            readonly description: S.optionalKey<S.String>;
         }>>>;
     }>, S.Struct<{
         readonly id: S.String;
@@ -306,6 +324,12 @@ export declare const workflowDefinitionSchema: S.Struct<{
             readonly id: S.String;
             readonly kind: S.Literal<"review">;
             readonly title: S.String;
+            /**
+             * One plain line under the title saying where the run is, such as
+             * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+             * filled from the loops around the review (see `fillReviewText`).
+             */
+            readonly detail: S.optionalKey<S.String>;
             readonly show: S.$Array<S.Struct<{
                 readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
                 readonly port: S.String;
@@ -314,11 +338,14 @@ export declare const workflowDefinitionSchema: S.Struct<{
             readonly timeout: S.Number;
             /**
              * Named outcomes a reviewer picks from; each is an output port carrying
-             * the shown item. Without choices the review approves or rejects.
+             * the shown item. Without choices the review approves or rejects. A
+             * choice's `description` says in plain words what picking it does, with
+             * the same placeholders as `detail`.
              */
             readonly choices: S.optionalKey<S.$Array<S.Struct<{
                 readonly id: S.String;
                 readonly label: S.String;
+                readonly description: S.optionalKey<S.String>;
             }>>>;
         }>, S.Struct<{
             readonly id: S.String;
@@ -434,6 +461,12 @@ export declare const workflowDefinitionSchema: S.Struct<{
         readonly id: S.String;
         readonly kind: S.Literal<"review">;
         readonly title: S.String;
+        /**
+         * One plain line under the title saying where the run is, such as
+         * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+         * filled from the loops around the review (see `fillReviewText`).
+         */
+        readonly detail: S.optionalKey<S.String>;
         readonly show: S.$Array<S.Struct<{
             readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
             readonly port: S.String;
@@ -442,11 +475,14 @@ export declare const workflowDefinitionSchema: S.Struct<{
         readonly timeout: S.Number;
         /**
          * Named outcomes a reviewer picks from; each is an output port carrying
-         * the shown item. Without choices the review approves or rejects.
+         * the shown item. Without choices the review approves or rejects. A
+         * choice's `description` says in plain words what picking it does, with
+         * the same placeholders as `detail`.
          */
         readonly choices: S.optionalKey<S.$Array<S.Struct<{
             readonly id: S.String;
             readonly label: S.String;
+            readonly description: S.optionalKey<S.String>;
         }>>>;
     }>, S.Struct<{
         readonly id: S.String;
@@ -595,6 +631,12 @@ export declare const planContentSchema: S.Struct<{
                 readonly id: S.String;
                 readonly kind: S.Literal<"review">;
                 readonly title: S.String;
+                /**
+                 * One plain line under the title saying where the run is, such as
+                 * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+                 * filled from the loops around the review (see `fillReviewText`).
+                 */
+                readonly detail: S.optionalKey<S.String>;
                 readonly show: S.$Array<S.Struct<{
                     readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
                     readonly port: S.String;
@@ -603,11 +645,14 @@ export declare const planContentSchema: S.Struct<{
                 readonly timeout: S.Number;
                 /**
                  * Named outcomes a reviewer picks from; each is an output port carrying
-                 * the shown item. Without choices the review approves or rejects.
+                 * the shown item. Without choices the review approves or rejects. A
+                 * choice's `description` says in plain words what picking it does, with
+                 * the same placeholders as `detail`.
                  */
                 readonly choices: S.optionalKey<S.$Array<S.Struct<{
                     readonly id: S.String;
                     readonly label: S.String;
+                    readonly description: S.optionalKey<S.String>;
                 }>>>;
             }>, S.Struct<{
                 readonly id: S.String;
@@ -723,6 +768,12 @@ export declare const planContentSchema: S.Struct<{
             readonly id: S.String;
             readonly kind: S.Literal<"review">;
             readonly title: S.String;
+            /**
+             * One plain line under the title saying where the run is, such as
+             * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+             * filled from the loops around the review (see `fillReviewText`).
+             */
+            readonly detail: S.optionalKey<S.String>;
             readonly show: S.$Array<S.Struct<{
                 readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
                 readonly port: S.String;
@@ -731,11 +782,14 @@ export declare const planContentSchema: S.Struct<{
             readonly timeout: S.Number;
             /**
              * Named outcomes a reviewer picks from; each is an output port carrying
-             * the shown item. Without choices the review approves or rejects.
+             * the shown item. Without choices the review approves or rejects. A
+             * choice's `description` says in plain words what picking it does, with
+             * the same placeholders as `detail`.
              */
             readonly choices: S.optionalKey<S.$Array<S.Struct<{
                 readonly id: S.String;
                 readonly label: S.String;
+                readonly description: S.optionalKey<S.String>;
             }>>>;
         }>, S.Struct<{
             readonly id: S.String;
@@ -876,6 +930,12 @@ export declare const executionPlanSchema: S.Struct<{
                 readonly id: S.String;
                 readonly kind: S.Literal<"review">;
                 readonly title: S.String;
+                /**
+                 * One plain line under the title saying where the run is, such as
+                 * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+                 * filled from the loops around the review (see `fillReviewText`).
+                 */
+                readonly detail: S.optionalKey<S.String>;
                 readonly show: S.$Array<S.Struct<{
                     readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
                     readonly port: S.String;
@@ -884,11 +944,14 @@ export declare const executionPlanSchema: S.Struct<{
                 readonly timeout: S.Number;
                 /**
                  * Named outcomes a reviewer picks from; each is an output port carrying
-                 * the shown item. Without choices the review approves or rejects.
+                 * the shown item. Without choices the review approves or rejects. A
+                 * choice's `description` says in plain words what picking it does, with
+                 * the same placeholders as `detail`.
                  */
                 readonly choices: S.optionalKey<S.$Array<S.Struct<{
                     readonly id: S.String;
                     readonly label: S.String;
+                    readonly description: S.optionalKey<S.String>;
                 }>>>;
             }>, S.Struct<{
                 readonly id: S.String;
@@ -1004,6 +1067,12 @@ export declare const executionPlanSchema: S.Struct<{
             readonly id: S.String;
             readonly kind: S.Literal<"review">;
             readonly title: S.String;
+            /**
+             * One plain line under the title saying where the run is, such as
+             * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+             * filled from the loops around the review (see `fillReviewText`).
+             */
+            readonly detail: S.optionalKey<S.String>;
             readonly show: S.$Array<S.Struct<{
                 readonly node: S.Union<readonly [S.String, S.Literals<readonly ["$input", "$item"]>]>;
                 readonly port: S.String;
@@ -1012,11 +1081,14 @@ export declare const executionPlanSchema: S.Struct<{
             readonly timeout: S.Number;
             /**
              * Named outcomes a reviewer picks from; each is an output port carrying
-             * the shown item. Without choices the review approves or rejects.
+             * the shown item. Without choices the review approves or rejects. A
+             * choice's `description` says in plain words what picking it does, with
+             * the same placeholders as `detail`.
              */
             readonly choices: S.optionalKey<S.$Array<S.Struct<{
                 readonly id: S.String;
                 readonly label: S.String;
+                readonly description: S.optionalKey<S.String>;
             }>>>;
         }>, S.Struct<{
             readonly id: S.String;

package/dist/schema.js

@@ -84,14 +84,26 @@ export const nodeSchema = S.Union([
         id: name,
         kind: S.Literal("review"),
         title: boundedString(120),
+        /**
+         * One plain line under the title saying where the run is, such as
+         * `Beat {item} of {items} · try {try} of {tries}`. The placeholders are
+         * filled from the loops around the review (see `fillReviewText`).
+         */
+        detail: S.optionalKey(boundedString(160)),
         show: array(portRefSchema, 64),
         reviewers: S.Literals(["runner", "owners"]),
         timeout: duration,
         /**
          * Named outcomes a reviewer picks from; each is an output port carrying
-         * the shown item. Without choices the review approves or rejects.
+         * the shown item. Without choices the review approves or rejects. A
+         * choice's `description` says in plain words what picking it does, with
+         * the same placeholders as `detail`.
          */
-        choices: S.optionalKey(array(S.Struct({ id: name, label: boundedString(80) }), 8)),
+        choices: S.optionalKey(array(S.Struct({
+            id: name,
+            label: boundedString(80),
+            description: S.optionalKey(boundedString(160)),
+        }), 8)),
     }),
     S.Struct({ id: name, kind: S.Literal("condition"), test: predicateSchema }),
     S.Struct({

package/dist/validate.js

@@ -2,6 +2,7 @@ import { escapePointer } from "@cfworker/json-schema";
 import * as S from "effect/Schema";
 import * as Result from "effect/Result";
 import { nextOccurrence } from "@fungi.computer/almanac";
+import { reviewTextPlaceholders, unknownReviewPlaceholders, } from "./review-text.js";
 import { workflowDefinitionSchema, catalogSchema, TRIGGER_EVENT_PORTS, } from "./schema.js";
 import { parseProjection, methodInputPorts, methodOutputPorts, portProjection, ports, accepts, assignable, } from "./ports.js";
 import { nodeRefs, mappingRefs, mappingProjection, predicateRefs, ExpressionSyntaxError, } from "./expressions.js";
@@ -363,6 +364,12 @@ export function analyze(raw, rawCatalog) {
                 case "review": {
                     const shown = node.show[0];
                     const item = shown ? (source(shown) ?? {}) : {};
+                    for (const text of [
+                        node.detail ?? "",
+                        ...(node.choices ?? []).map((choice) => choice.description ?? ""),
+                    ])
+                        for (const name of unknownReviewPlaceholders(text))
+                            issue("schema", `Unknown review placeholder {${name}}; use ${reviewTextPlaceholders.map((known) => `{${known}}`).join(", ")}`, { node: node.id });
                     if (node.choices === undefined) {
                         outs.set(node.id, {
                             approved: item,

package/dist/workflow-id.d.ts

@@ -1,3 +1,3 @@
-import { z } from "zod";
+import * as z from "zod";
 /** Identity of a versioned Workflow document, shared by hosts and the Trellis App. */
 export declare const workflowIdSchema: z.ZodString;

package/dist/workflow-id.js

@@ -1,3 +1,3 @@
-import { z } from "zod";
+import * as z from "zod";
 /** Identity of a versioned Workflow document, shared by hosts and the Trellis App. */
 export const workflowIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/braid",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "author": "Levi <levi@technomancy.dev>",
   "type": "module",
   "description": "Pure versioned Workflow graph validation and content-addressed compilation",
@@ -29,16 +29,17 @@
   ],
   "dependencies": {
     "@cfworker/json-schema": "4.1.1",
-    "@fungi.computer/almanac": "0.0.1",
-    "@fungi.computer/mycelium": "0.0.2",
+    "@fungi.computer/almanac": "0.2.0",
+    "@fungi.computer/mycelium": "0.2.0",
     "effect": "4.0.2",
     "jsonpointer": "5.0.1",
     "mustache": "4.2.0",
     "zod": "4.4.3",
-    "@fungi.computer/agar": "0.1.0",
-    "@fungi.computer/watchdog": "0.0.1",
-    "@fungi.computer/puffball": "0.0.2",
-    "@fungi.computer/cairn": "0.0.1"
+    "@fungi.computer/agar": "0.3.0",
+    "@fungi.computer/gills": "0.2.0",
+    "@fungi.computer/watchdog": "0.1.0",
+    "@fungi.computer/puffball": "0.2.0",
+    "@fungi.computer/cairn": "0.1.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "5.20260828.1",