@fungi.computer/braid 0.0.0-stage → 0.0.1

package/dist/schema.js

@@ -0,0 +1,227 @@
+import * as S from "effect/Schema";
+import { gitAccessSchema, workflowBindingSchema, } from "./git-access.js";
+const boundedString = (max) => S.String.pipe(S.check(S.isMaxLength(max)));
+const name = boundedString(80).pipe(S.check(S.isPattern(/^[A-Za-z][A-Za-z0-9_-]*$/)));
+const count = (min, max) => S.Number.pipe(S.check(S.isInt()), S.check(S.isBetween({ minimum: min, maximum: max })));
+const array = (schema, max) => S.Array(schema).pipe(S.check(S.isMaxLength(max)));
+const record = (schema) => S.Record(name, schema);
+const json = S.Json.pipe(S.check(S.makeFilter((value) => JSON.stringify(value).length <= 20_000)));
+/** Same byte/depth envelope as the App API projection. */
+export const projectionSchema = S.JsonObject.pipe(S.check(S.makeFilter((value) => {
+    const withinDepth = (item, depth) => {
+        if (depth > 16)
+            return false;
+        if (S.is(S.Array(S.Json))(item))
+            return item.every((child) => withinDepth(child, depth + 1));
+        if (S.is(S.JsonObject)(item))
+            return Object.values(item).every((child) => withinDepth(child, depth + 1));
+        return true;
+    };
+    return (new TextEncoder().encode(JSON.stringify(value)).length <= 20_000 &&
+        withinDepth(value, 0));
+})));
+export const portRefSchema = S.Struct({
+    node: S.Union([name, S.Literals(["$input", "$item"])]),
+    port: name,
+});
+const templateSchema = S.Struct({ template: boundedString(4000) });
+const literalSchema = S.Struct({ literal: json });
+export const valueSchema = S.Union([literalSchema, templateSchema]);
+const fromSchema = S.Struct({
+    from: portRefSchema,
+    path: S.optionalKey(boundedString(512)),
+});
+export const mappingSchema = S.Union([
+    fromSchema,
+    valueSchema,
+    S.Struct({ coalesce: S.suspend(() => array(mappingSchema, 16)) }),
+    S.Struct({ object: S.suspend(() => S.Record(S.String, mappingSchema)) }),
+    S.Struct({ array: S.suspend(() => array(mappingSchema, 50)) }),
+    S.Struct({
+        each: S.Struct({
+            over: S.suspend(() => mappingSchema),
+            body: S.suspend(() => mappingSchema),
+            maxItems: count(1, 50),
+        }),
+    }),
+]);
+export const predicateSchema = S.Union([
+    S.Struct({
+        op: S.Literals(["eq", "neq", "gt", "lt", "in"]),
+        left: mappingSchema,
+        right: mappingSchema,
+    }),
+    S.Struct({ op: S.Literal("exists"), value: mappingSchema }),
+    S.Struct({
+        op: S.Literals(["and", "or"]),
+        tests: S.suspend(() => array(predicateSchema, 16)),
+    }),
+    S.Struct({ op: S.Literal("not"), test: S.suspend(() => predicateSchema) }),
+]);
+const duration = count(1, 7 * 24 * 60 * 60 * 1000);
+/** JavaScript body and declared data only; the whole graph also bounds UTF-8 bytes. */
+export const codeNodeSchema = S.Struct({
+    id: name,
+    kind: S.Literal("code"),
+    source: boundedString(256_000),
+    input: projectionSchema,
+    output: projectionSchema,
+    values: record(mappingSchema),
+});
+export const nodeSchema = S.Union([
+    codeNodeSchema,
+    S.Struct({
+        id: name,
+        kind: S.Literal("app"),
+        app: name,
+        method: boundedString(80),
+        methodDigest: boundedString(128),
+        values: record(mappingSchema),
+        gitAccess: S.optionalKey(S.declare((value) => gitAccessSchema.safeParse(value).success)),
+        retry: S.optionalKey(S.Struct({ attempts: count(1, 5) })),
+    }),
+    S.Struct({
+        id: name,
+        kind: S.Literal("review"),
+        title: boundedString(120),
+        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.
+         */
+        choices: S.optionalKey(array(S.Struct({ id: name, label: boundedString(80) }), 8)),
+    }),
+    S.Struct({ id: name, kind: S.Literal("condition"), test: predicateSchema }),
+    S.Struct({
+        id: name,
+        kind: S.Literal("map"),
+        over: portRefSchema,
+        body: name,
+        concurrency: count(1, 8),
+        maxItems: count(1, 50),
+    }),
+    S.Struct({
+        id: name,
+        kind: S.Literal("repeat"),
+        body: name,
+        maxRounds: count(1, 5),
+        /** The predicate reads the completed body's output through $input. */
+        until: predicateSchema,
+    }),
+    S.Struct({ id: name, kind: S.Literal("wait"), for: duration }),
+    S.Struct({
+        id: name,
+        kind: S.Literal("transform"),
+        fields: record(mappingSchema),
+    }),
+]);
+export const edgeSchema = S.Struct({ from: portRefSchema, to: portRefSchema });
+/**
+ * Ports of the event a trigger receives. Inside a trigger, `$input` names this
+ * event, not the run input: the trigger maps it onto the run's `$input`. Every
+ * port is the same on a redelivery of the same event, so a redelivery maps to
+ * the same run input and replays instead of conflicting.
+ */
+export const TRIGGER_EVENT_PORTS = {
+    webhook: ["body", "eventId", "headers"],
+    schedule: ["scheduledAt", "eventId"],
+    event: ["payload", "eventId"],
+};
+/**
+ * An incoming webhook. The host owns the URL, the secret and the signature
+ * scheme; the definition owns only the filter and the mapping onto run input.
+ * Without `input`, the event body itself must be the run input.
+ */
+const webhookTriggerSchema = S.Struct({
+    id: name,
+    on: S.Literal("webhook"),
+    title: S.optionalKey(boundedString(120)),
+    when: S.optionalKey(predicateSchema),
+    input: S.optionalKey(record(mappingSchema)),
+});
+const scheduleTriggerSchema = S.Struct({
+    id: name,
+    on: S.Literal("schedule"),
+    title: S.optionalKey(boundedString(120)),
+    cron: S.Struct({
+        expression: boundedString(256),
+        timeZone: boundedString(128),
+    }),
+    input: S.optionalKey(record(mappingSchema)),
+});
+const appEventTriggerSchema = S.Struct({
+    id: name,
+    on: S.Literal("event"),
+    title: S.optionalKey(boundedString(120)),
+    app: name,
+    event: boundedString(128),
+    eventDigest: boundedString(128),
+    when: S.optionalKey(predicateSchema),
+    input: S.optionalKey(record(mappingSchema)),
+    /**
+     * The one repository, in the event App's own Git namespace, this event is
+     * about. A node's `gitAccess` names it as `$trigger.repository`.
+     */
+    repository: S.optionalKey(mappingSchema),
+});
+const triggerSchema = S.Union([
+    webhookTriggerSchema,
+    scheduleTriggerSchema,
+    appEventTriggerSchema,
+]);
+export const graphSchema = S.Struct({
+    input: projectionSchema,
+    nodes: array(nodeSchema, 64),
+    edges: array(edgeSchema, 256),
+    output: record(portRefSchema),
+});
+export const workflowDefinitionSchema = S.Struct({
+    ...graphSchema.fields,
+    format: S.Literal("fungi.workflow/v1"),
+    title: boundedString(120),
+    description: S.optionalKey(boundedString(1000)),
+    apps: record(S.Struct({
+        appId: boundedString(256),
+        role: S.optionalKey(boundedString(80)),
+    })),
+    subgraphs: S.optionalKey(record(graphSchema)),
+    triggers: S.optionalKey(array(triggerSchema, 8)),
+}).pipe(S.check(S.makeFilter((value) => new TextEncoder().encode(JSON.stringify(value)).length <= 256_000)));
+/** Structural App API method shape from T1; digests are supplied by its catalog owner. */
+export const methodSchema = S.Struct({
+    /** This method may yield Agar Pending before its completed output. */
+    pending: S.optionalKey(S.Literal(true)),
+    description: boundedString(1000),
+    input: projectionSchema,
+    output: projectionSchema,
+    effect: S.Literals(["read", "write", "external"]),
+    approval: S.Literals(["none", "queue", "simulate"]),
+    requires: array(boundedString(80), 64),
+});
+export const eventSchema = S.Struct({
+    description: boundedString(1000),
+    payload: projectionSchema,
+});
+export const catalogSchema = S.Record(S.String, S.Struct({
+    methods: S.Record(S.String, S.Struct({ ...methodSchema.fields, digest: boundedString(128) })),
+    events: S.optionalKey(S.Record(S.String, S.Struct({ ...eventSchema.fields, digest: boundedString(128) }))),
+}));
+export const bindingsSchema = record(S.declare((value) => workflowBindingSchema.safeParse(value).success));
+export const planContentSchema = S.Struct({
+    definition: workflowDefinitionSchema,
+    catalog: catalogSchema,
+    bindings: bindingsSchema,
+    estimatedSteps: count(0, 800),
+    requiredBindings: array(S.Struct({
+        app: name,
+        installationId: boundedString(256),
+        method: boundedString(80),
+        ...methodSchema.fields,
+    }), 64),
+});
+export const executionPlanSchema = S.Struct({
+    ...planContentSchema.fields,
+    planDigest: boundedString(128),
+});

package/dist/triggers.d.ts

@@ -0,0 +1,46 @@
+import * as S from "effect/Schema";
+import type { Json, WorkflowDefinition } from "./schema.js";
+/**
+ * One verified incoming event, as the host hands it to a trigger. The host has
+ * already authenticated the sender and bounded the body. `eventId` is the
+ * host's stable, non-secret identity for the event; `headers` holds only the
+ * host's allowlisted, non-secret headers that a redelivery repeats.
+ */
+export type TriggerEvent = Readonly<{
+    body: Json;
+    eventId: string;
+    headers: Readonly<Record<string, string>>;
+}> | Readonly<{
+    scheduledAt: string;
+    eventId: string;
+}> | Readonly<{
+    payload: Json;
+    eventId: string;
+}>;
+export type TriggerOutcome = Readonly<{
+    kind: "start";
+    input: S.JsonObject;
+    repository?: string;
+}> | Readonly<{
+    kind: "ignored";
+}> | Readonly<{
+    kind: "refused";
+    code: "unknown_trigger" | "invalid_input" | "invalid_repository";
+}>;
+/**
+ * Decide what one event does to a Workflow: start a run with typed input,
+ * nothing (its filter does not select the event), or a refusal. Pure; the
+ * definition has already passed `validate`.
+ */
+export declare function triggerRun(definition: WorkflowDefinition, triggerId: string, event: TriggerEvent): TriggerOutcome;
+/**
+ * The idempotent start key for a triggered run. `scope` is the host's name for
+ * where the event arrived (for example a webhook binding); a redelivery of the
+ * same event through the same trigger yields the same key, so it starts at
+ * most one run.
+ */
+export declare function triggerRequestId(input: Readonly<{
+    scope: string;
+    triggerId: string;
+    eventId: string;
+}>): Promise<string>;

package/dist/triggers.js

@@ -0,0 +1,75 @@
+import * as S from "effect/Schema";
+import { contentDigest } from "./compile.js";
+import { evaluateMapping, evaluatePredicate } from "./expressions.js";
+import { admitRunInput } from "./ports.js";
+import { triggerRepositorySchema } from "./git-access.js";
+/**
+ * Decide what one event does to a Workflow: start a run with typed input,
+ * nothing (its filter does not select the event), or a refusal. Pure; the
+ * definition has already passed `validate`.
+ */
+export function triggerRun(definition, triggerId, event) {
+    const trigger = definition.triggers?.find((item) => item.id === triggerId);
+    if (trigger === undefined)
+        return { kind: "refused", code: "unknown_trigger" };
+    let eventInput;
+    let defaultInput;
+    switch (trigger.on) {
+        case "webhook":
+            if (!("body" in event))
+                return { kind: "refused", code: "invalid_input" };
+            eventInput = {
+                body: event.body,
+                eventId: event.eventId,
+                headers: { ...event.headers },
+            };
+            defaultInput = event.body;
+            break;
+        case "schedule":
+            if (!("scheduledAt" in event))
+                return { kind: "refused", code: "invalid_input" };
+            eventInput = { scheduledAt: event.scheduledAt, eventId: event.eventId };
+            defaultInput = eventInput;
+            break;
+        case "event":
+            if (!("payload" in event))
+                return { kind: "refused", code: "invalid_input" };
+            eventInput = { payload: event.payload, eventId: event.eventId };
+            defaultInput = event.payload;
+            break;
+    }
+    const values = { $input: eventInput };
+    if (trigger.on !== "schedule" &&
+        trigger.when !== undefined &&
+        !evaluatePredicate(trigger.when, values))
+        return { kind: "ignored" };
+    const input = trigger.input === undefined
+        ? defaultInput
+        : Object.fromEntries(Object.entries(trigger.input).flatMap(([key, mapping]) => {
+            const value = evaluateMapping(mapping, values);
+            return value === undefined ? [] : [[key, value]];
+        }));
+    const admitted = admitRunInput(definition, input);
+    if (admitted.kind === "invalid")
+        return { kind: "refused", code: "invalid_input" };
+    if (trigger.on !== "event" || trigger.repository === undefined)
+        return { kind: "start", input: admitted.input };
+    const repository = triggerRepositorySchema.safeParse(evaluateMapping(trigger.repository, values));
+    return repository.success
+        ? { kind: "start", input: admitted.input, repository: repository.data }
+        : { kind: "refused", code: "invalid_repository" };
+}
+/**
+ * The idempotent start key for a triggered run. `scope` is the host's name for
+ * where the event arrived (for example a webhook binding); a redelivery of the
+ * same event through the same trigger yields the same key, so it starts at
+ * most one run.
+ */
+export function triggerRequestId(input) {
+    return contentDigest([
+        "fungi.workflow/v1 trigger",
+        input.scope,
+        input.triggerId,
+        input.eventId,
+    ]);
+}

package/dist/validate.d.ts

@@ -0,0 +1,25 @@
+import { type Catalog, type Graph, type WorkflowDefinition, type Node, type PortRef } from "./schema.js";
+export type IssueCode = "schema" | "unknown_app" | "unknown_method" | "unknown_event" | "digest_drift" | "unknown_port" | "unassignable_edge" | "required_port" | "cycle" | "unreachable" | "step_budget" | "template" | "duplicate" | "subgraph" | "binding" | "literal" | "trigger";
+export type Issue = {
+    readonly code: IssueCode;
+    readonly message: string;
+    readonly graph?: string;
+    readonly node?: string;
+    readonly trigger?: string;
+    readonly port?: string;
+    readonly edge?: number;
+};
+export type Analysis = {
+    readonly issues: readonly Issue[];
+    readonly definition?: WorkflowDefinition;
+    readonly catalog?: Catalog;
+    readonly estimatedSteps: number;
+    readonly order: Readonly<Record<string, readonly Node[]>>;
+};
+/** CF permits 1024 durable steps; this private ceiling leaves execution headroom. */
+export declare const STEP_BUDGET = 800;
+export declare function dependencies(graph: Graph, node: Node): readonly PortRef[];
+export declare function topological(graph: Graph): readonly Node[];
+/** Decode JSON boundaries once, then collect domain issues for the editor. */
+export declare function analyze(raw: WorkflowDefinition, rawCatalog: Catalog): Analysis;
+export declare function validate(definition: unknown, catalog: unknown): readonly Issue[];