@fungi.computer/braid 0.0.0-stage → 0.0.1

package/dist/compile.d.ts

@@ -0,0 +1,41 @@
+import { type Issue } from "./validate.js";
+import { type ExecutionPlan, type Json, type Catalog, type Bindings, type WorkflowDefinition } from "./schema.js";
+/** Canonical object ordering; array order remains semantic. No execution layout is accepted. */
+export declare function canonicalJson(value: Json): string;
+export declare function contentDigest(value: Json): Promise<string>;
+export type CompileResult = {
+    readonly ok: false;
+    readonly issues: readonly Issue[];
+} | {
+    readonly ok: true;
+    readonly plan: ExecutionPlan;
+};
+export declare function compile(raw: WorkflowDefinition, rawCatalog: Catalog, rawBindings: Bindings): Promise<CompileResult>;
+/** Stored plans are parsed and their content identity verified before interpretation. */
+export declare function decodeExecutionPlan(raw: unknown): Promise<ExecutionPlan>;
+/** One App method as an App's `api` block declares it; structural, no App SDK import. */
+export type DeclaredMethod = Readonly<{
+    /** Opt in to the shared Pending control result. */
+    pending?: true | undefined;
+    /** Discovery-only metadata from the App declaration; hidden methods have no graph ports. */
+    hidden?: true | undefined;
+    description: string;
+    input: object;
+    output: object;
+    effect: "read" | "write" | "external";
+    requires: readonly string[];
+}>;
+/**
+ * The catalog entry for one App's declared methods. The digest covers what a
+ * node depends on (ports, effect, approval, requires), not the description, so
+ * rewording a method does not drift Workflows. External effects queue for
+ * approval; v1 declares no other approval policy.
+ */
+export declare function catalogMethods(methods: Readonly<Record<string, DeclaredMethod>>): Promise<Catalog[string]>;
+/** Event identity pins the whole emitted schema; descriptions do not affect compatibility. */
+export declare function catalogEvents(events: Readonly<Record<string, {
+    description: string;
+    payload: object;
+}>>): Promise<{
+    events: NonNullable<Catalog[string]["events"]>;
+}>;

package/dist/compile.js

@@ -0,0 +1,240 @@
+import * as S from "effect/Schema";
+import * as Option from "effect/Option";
+import { analyze } from "./validate.js";
+import { bindingsSchema, executionPlanSchema, methodSchema, eventSchema, projectionSchema, } from "./schema.js";
+/** Canonical object ordering; array order remains semantic. No execution layout is accepted. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return "[" + value.map(canonicalJson).join(",") + "]";
+    if (S.is(S.JsonObject)(value))
+        return ("{" +
+            Object.keys(value)
+                .sort()
+                .map((key) => JSON.stringify(key) + ":" + canonicalJson(value[key] ?? null))
+                .join(",") +
+            "}");
+    return JSON.stringify(value);
+}
+export async function contentDigest(value) {
+    const json = S.decodeUnknownSync(S.Json)(value);
+    const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(json)));
+    return ("sha256:" +
+        [...new Uint8Array(hash)]
+            .map((byte) => byte.toString(16).padStart(2, "0"))
+            .join(""));
+}
+export async function compile(raw, rawCatalog, rawBindings) {
+    const analysis = analyze(raw, rawCatalog);
+    if (analysis.issues.length || !analysis.definition || !analysis.catalog)
+        return { ok: false, issues: analysis.issues };
+    let bindings;
+    try {
+        bindings = S.decodeUnknownSync(bindingsSchema)(rawBindings, {
+            onExcessProperty: "error",
+        });
+    }
+    catch (cause) {
+        if (!S.isSchemaError(cause))
+            throw cause;
+        return {
+            ok: false,
+            issues: [{ code: "binding", message: "Invalid installation bindings" }],
+        };
+    }
+    const { definition, catalog } = analysis;
+    const requiredBindings = [];
+    const pinned = {};
+    const bound = {};
+    const issues = [];
+    const seen = new Set();
+    for (const node of Object.values(analysis.order).flat()) {
+        if (node.kind !== "app")
+            continue;
+        const app = definition.apps[node.app];
+        const binding = bindings[node.app];
+        if (!app ||
+            binding === undefined ||
+            !("installationId" in binding) ||
+            !binding.installationId ||
+            binding.appId !== app.appId) {
+            issues.push({
+                code: "binding",
+                node: node.id,
+                message: "App binding missing or targets a different App",
+            });
+            continue;
+        }
+        const method = catalog[app.appId]?.methods[node.method];
+        if (!method)
+            continue;
+        pinned[app.appId] = {
+            methods: { ...pinned[app.appId]?.methods, [node.method]: method },
+        };
+        bound[node.app] = binding;
+        if (node.gitAccess !== undefined) {
+            const target = bindings[node.gitAccess.binding];
+            if (target === undefined) {
+                issues.push({
+                    code: "binding",
+                    node: node.id,
+                    message: "Git repository binding is missing",
+                });
+                continue;
+            }
+            bound[node.gitAccess.binding] = target;
+        }
+        const key = node.app + "." + node.method;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const { description, input, output, effect, approval, requires } = method;
+        requiredBindings.push({
+            app: node.app,
+            installationId: binding.installationId,
+            method: node.method,
+            description,
+            input,
+            output,
+            effect,
+            approval,
+            requires,
+        });
+    }
+    for (const trigger of definition.triggers ?? []) {
+        if (trigger.on !== "event")
+            continue;
+        const app = definition.apps[trigger.app];
+        const binding = bindings[trigger.app];
+        if (!app ||
+            binding === undefined ||
+            !("installationId" in binding) ||
+            !binding.installationId ||
+            binding.appId !== app.appId) {
+            issues.push({
+                code: "binding",
+                trigger: trigger.id,
+                message: "Event App binding missing or targets a different App",
+            });
+            continue;
+        }
+        const event = catalog[app.appId]?.events?.[trigger.event];
+        if (!event)
+            continue;
+        const prior = pinned[app.appId];
+        pinned[app.appId] = {
+            methods: prior?.methods ?? {},
+            events: { ...prior?.events, [trigger.event]: event },
+        };
+        bound[trigger.app] = binding;
+    }
+    if (issues.length)
+        return { ok: false, issues };
+    let sortedDefinition = {
+        ...definition,
+        nodes: analysis.order.root ?? [],
+        edges: [...definition.edges].sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b))),
+    };
+    if (definition.subgraphs) {
+        sortedDefinition = {
+            ...sortedDefinition,
+            subgraphs: Object.fromEntries(Object.entries(definition.subgraphs).map(([id, graph]) => [
+                id,
+                {
+                    ...graph,
+                    nodes: analysis.order[id] ?? [],
+                    edges: [...graph.edges].sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b))),
+                },
+            ])),
+        };
+    }
+    const content = {
+        definition: sortedDefinition,
+        catalog: pinned,
+        bindings: bound,
+        estimatedSteps: analysis.estimatedSteps,
+        requiredBindings: requiredBindings.sort((a, b) => (a.app + a.method).localeCompare(b.app + b.method)),
+    };
+    return {
+        ok: true,
+        plan: { ...content, planDigest: await contentDigest(content) },
+    };
+}
+/** Stored plans are parsed and their content identity verified before interpretation. */
+export async function decodeExecutionPlan(raw) {
+    const plan = S.decodeUnknownSync(executionPlanSchema)(raw, {
+        onExcessProperty: "error",
+    });
+    const { planDigest, ...content } = plan;
+    if ((await contentDigest(content)) !== planDigest)
+        throw new Error("Workflow plan digest mismatch");
+    const rebuilt = await compile(plan.definition, plan.catalog, plan.bindings);
+    if (!rebuilt.ok || rebuilt.plan.planDigest !== planDigest)
+        throw new Error("Workflow plan is not a compiled v1 plan");
+    return plan;
+}
+// The emitted draft identifier is metadata; graph ports use the completion schema.
+function schemaView(schema) {
+    return Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$schema"));
+}
+// Agar emits exactly [declared Output, Pending]. This projects its completion
+// side only; unsupported nested unions remain unsupported graph port schemas.
+const emittedPendingUnion = S.Struct({
+    anyOf: S.Tuple([projectionSchema, projectionSchema]),
+});
+function completionView(method) {
+    const output = schemaView(method.output);
+    if (method.pending !== true)
+        return output;
+    const union = S.decodeUnknownOption(emittedPendingUnion, {
+        onExcessProperty: "error",
+    })(output);
+    return Option.isSome(union) ? schemaView(union.value.anyOf[0]) : output;
+}
+/**
+ * The catalog entry for one App's declared methods. The digest covers what a
+ * node depends on (ports, effect, approval, requires), not the description, so
+ * rewording a method does not drift Workflows. External effects queue for
+ * approval; v1 declares no other approval policy.
+ */
+export async function catalogMethods(methods) {
+    const entries = await Promise.all(Object.entries(methods)
+        .flatMap(([name, { hidden, ...declared }]) => hidden === true ? [] : [[name, declared]])
+        .map(async ([name, declared]) => {
+        const method = S.decodeUnknownSync(methodSchema)({
+            ...declared,
+            requires: [...declared.requires],
+            approval: declared.effect === "external" ? "queue" : "none",
+        }, { onExcessProperty: "error" });
+        const pinned = {
+            input: method.input,
+            output: method.output,
+            effect: method.effect,
+            approval: method.approval,
+            requires: method.requires,
+        };
+        const digestInput = method.pending === true ? { ...pinned, pending: true } : pinned;
+        return [
+            name,
+            {
+                ...method,
+                input: schemaView(method.input),
+                output: completionView(method),
+                digest: await contentDigest(digestInput),
+            },
+        ];
+    }));
+    return { methods: Object.fromEntries(entries) };
+}
+/** Event identity pins the whole emitted schema; descriptions do not affect compatibility. */
+export async function catalogEvents(events) {
+    const entries = await Promise.all(Object.entries(events).map(async ([name, raw]) => {
+        const event = S.decodeUnknownSync(eventSchema)(raw, {
+            onExcessProperty: "error",
+        });
+        return [
+            name,
+            { ...event, digest: await contentDigest({ payload: event.payload }) },
+        ];
+    }));
+    return { events: Object.fromEntries(entries) };
+}

package/dist/execution.d.ts

@@ -0,0 +1,113 @@
+import * as S from "effect/Schema";
+import type { ExecutionPlan, Json, Method } from "./schema.js";
+export declare const graphParamsSchema: S.Union<readonly [S.Struct<{
+    readonly kind: S.Literal<"run">;
+    readonly teamId: S.String;
+    readonly runId: S.String;
+    readonly planDigest: S.String;
+}>, S.Struct<{
+    readonly kind: S.Literal<"map-item">;
+    readonly teamId: S.String;
+    readonly runId: S.String;
+    readonly planDigest: S.String;
+    readonly body: S.String;
+    readonly iteration: S.String;
+    readonly parentInstanceId: S.String;
+    readonly completionEvent: S.String;
+    readonly input: S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>;
+}>]>;
+export type GraphParams = typeof graphParamsSchema.Type;
+export declare const nodeEventSchema: S.Struct<{
+    readonly runId: S.String;
+    readonly graphId: S.optionalKey<S.String>;
+    readonly nodeId: S.String;
+    readonly iteration: S.String;
+    readonly poll: S.optionalKey<S.Number>;
+    readonly state: S.Literals<readonly ["queued", "running", "waiting", "complete", "failed", "skipped"]>;
+    readonly attempt: S.Number;
+    /** Time the host durably recorded this lifecycle fact. */
+    readonly recordedAt: S.optionalKey<S.Number>;
+    readonly durationMs: S.optionalKey<S.Number>;
+    readonly costMilliunits: S.optionalKey<S.Number>;
+    readonly outputDigest: S.optionalKey<S.String>;
+    readonly output: S.optionalKey<S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>>;
+    readonly errorMessage: S.optionalKey<S.String>;
+    readonly refusal: S.optionalKey<S.String>;
+}>;
+export type NodeEvent = typeof nodeEventSchema.Type;
+export declare const graphReviewSchema: S.Struct<{
+    readonly runId: S.String;
+    readonly nodeId: S.String;
+    readonly iteration: S.String;
+    readonly instanceId: S.String;
+    readonly eventType: S.String;
+    readonly title: S.String;
+    readonly reviewers: S.Literals<readonly ["runner", "owners"]>;
+    readonly timeout: S.Number;
+    readonly show: S.$Array<S.Codec<S.Json, S.Json, never, never>>;
+    /** The review's named choices; absent for an approve/reject review. */
+    readonly choices: S.optionalKey<S.$Array<S.String>>;
+}>;
+export type GraphReview = typeof graphReviewSchema.Type;
+/** Approve or reject a plain review, or pick one of a review's named choices. */
+export declare const reviewAnswerSchema: S.Union<readonly [S.Struct<{
+    readonly approved: S.Boolean;
+}>, S.Struct<{
+    readonly choice: S.String;
+    readonly note: S.optionalKey<S.String>;
+}>]>;
+/** Project one decoded review answer into the review node's output ports. */
+export declare function reviewAnswerOutput(answer: typeof reviewAnswerSchema.Type, item: Json): {
+    [x: string]: S.Json;
+    choice: string;
+    note: string;
+};
+export declare const dispatchResultSchema: S.Union<readonly [S.Struct<{
+    readonly kind: S.Literal<"complete">;
+    readonly output: S.Codec<S.Json, S.Json, never, never>;
+    readonly costMilliunits: S.Number;
+}>, S.Struct<{
+    readonly kind: S.Literal<"refused">;
+    readonly code: S.Literals<readonly ["not_granted", "invalid_input", "invalid_output", "revoked", "member_revoked", "workflow_run_revoked", "computer_revoked", "budget_exhausted", "unknown_method"]>;
+}>, S.Struct<{
+    readonly kind: S.Literal<"pending_approval">;
+    readonly actionId: S.String;
+}>, S.Struct<{
+    readonly kind: S.Literal<"pending">;
+    readonly retryAfterMs: S.Number;
+}>]>;
+export type DispatchResult = typeof dispatchResultSchema.Type;
+/** Live admission before any node kind; refusals use the engine's sole vocabulary. */
+export declare const nodeAdmissionResultSchema: S.Union<readonly [S.Struct<{
+    readonly kind: S.Literal<"admitted">;
+}>, S.Struct<{
+    readonly kind: S.Literal<"refused">;
+    readonly code: S.Literals<readonly ["not_granted", "invalid_input", "invalid_output", "revoked", "member_revoked", "workflow_run_revoked", "computer_revoked", "budget_exhausted", "unknown_method"]>;
+}>]>;
+export type NodeAdmissionResult = typeof nodeAdmissionResultSchema.Type;
+export type NodeCall = {
+    readonly teamId: string;
+    readonly runId: string;
+    readonly graphId?: string;
+    readonly nodeId: string;
+    readonly iteration: string;
+    readonly poll?: number;
+    readonly installationId: string;
+    readonly method: string;
+    readonly methodSpec: Method;
+    readonly input: Json;
+    readonly idempotencyKey: string;
+};
+/** Host ports: load an admitted plan, invoke Apps, and persist execution facts. */
+export type NodeDispatcher = {
+    loadRun(teamId: string, runId: string): Promise<{
+        readonly plan: ExecutionPlan;
+        readonly input: Readonly<Record<string, Json>>;
+    }>;
+    /** Recheck the run's member and live library grant before the node executes. */
+    beforeNode(event: NodeEvent): Promise<NodeAdmissionResult>;
+    dispatch(call: NodeCall): Promise<DispatchResult>;
+    recordEvent(event: NodeEvent): Promise<void>;
+    /** Persist once and return the owner-held expiration, unchanged on replay. */
+    openReview(review: GraphReview): Promise<number>;
+};

package/dist/execution.js

@@ -0,0 +1,108 @@
+import * as S from "effect/Schema";
+const id = S.String.pipe(S.check(S.isMinLength(1)), S.check(S.isMaxLength(256)));
+const natural = S.Number.pipe(S.check(S.isInt()), S.check(S.isGreaterThanOrEqualTo(0)));
+export const graphParamsSchema = S.Union([
+    S.Struct({ kind: S.Literal("run"), teamId: id, runId: id, planDigest: id }),
+    S.Struct({
+        kind: S.Literal("map-item"),
+        teamId: id,
+        runId: id,
+        planDigest: id,
+        body: id,
+        iteration: id,
+        parentInstanceId: id,
+        completionEvent: id,
+        input: S.JsonObject,
+    }),
+]);
+export const nodeEventSchema = S.Struct({
+    runId: id,
+    graphId: S.optionalKey(id),
+    nodeId: id,
+    iteration: id,
+    poll: S.optionalKey(natural),
+    state: S.Literals([
+        "queued",
+        "running",
+        "waiting",
+        "complete",
+        "failed",
+        "skipped",
+    ]),
+    attempt: natural,
+    /** Time the host durably recorded this lifecycle fact. */
+    recordedAt: S.optionalKey(natural),
+    durationMs: S.optionalKey(natural),
+    costMilliunits: S.optionalKey(natural),
+    outputDigest: S.optionalKey(id),
+    output: S.optionalKey(S.JsonObject),
+    errorMessage: S.optionalKey(S.String.check(S.isMaxLength(1024))),
+    refusal: S.optionalKey(id),
+});
+export const graphReviewSchema = S.Struct({
+    runId: id,
+    nodeId: id,
+    iteration: id,
+    instanceId: id,
+    eventType: id,
+    title: S.String,
+    reviewers: S.Literals(["runner", "owners"]),
+    timeout: natural,
+    show: S.Array(S.Json),
+    /** The review's named choices; absent for an approve/reject review. */
+    choices: S.optionalKey(S.Array(id)),
+});
+/** Approve or reject a plain review, or pick one of a review's named choices. */
+export const reviewAnswerSchema = S.Union([
+    S.Struct({ approved: S.Boolean }),
+    S.Struct({
+        choice: id,
+        note: S.optionalKey(S.String.check(S.isMaxLength(1000))),
+    }),
+]);
+/** Project one decoded review answer into the review node's output ports. */
+export function reviewAnswerOutput(answer, item) {
+    const choice = "choice" in answer
+        ? answer.choice
+        : answer.approved
+            ? "approved"
+            : "rejected";
+    return {
+        [choice]: item,
+        choice,
+        note: "choice" in answer ? (answer.note ?? "") : "",
+    };
+}
+const refusalCodes = [
+    "not_granted",
+    "invalid_input",
+    "invalid_output",
+    "revoked",
+    "member_revoked",
+    "workflow_run_revoked",
+    "computer_revoked",
+    "budget_exhausted",
+    "unknown_method",
+];
+export const dispatchResultSchema = S.Union([
+    S.Struct({
+        kind: S.Literal("complete"),
+        output: S.Json,
+        costMilliunits: natural,
+    }),
+    S.Struct({ kind: S.Literal("refused"), code: S.Literals(refusalCodes) }),
+    S.Struct({ kind: S.Literal("pending_approval"), actionId: id }),
+    /**
+     * The App accepted the work and it is still running. The engine calls the
+     * same method again with the same idempotency key after `retryAfterMs`.
+     */
+    S.Struct({
+        kind: S.Literal("pending"),
+        retryAfterMs: S.Number.pipe(S.check(S.isInt()), S.check(S.isBetween({ minimum: 1_000, maximum: 60_000 }))),
+    }),
+]);
+/** Live admission before any node kind; refusals use the engine's sole vocabulary. */
+export const nodeAdmissionResultSchema = S.Union([
+    S.Struct({ kind: S.Literal("admitted") }),
+    S.Struct({ kind: S.Literal("refused"), code: S.Literals(refusalCodes) }),
+]);

package/dist/expressions.d.ts

@@ -0,0 +1,16 @@
+import type { Mapping, Node, Predicate, PortRef, Json } from "./schema.js";
+import { type PortSchema } from "./ports.js";
+export type Values = Readonly<Record<string, Readonly<Record<string, Json>>>>;
+/** Expected syntax refusal only; defects in a parser or graph traversal escape. */
+export declare class ExpressionSyntaxError extends Error {
+}
+/** Mustache parses the representation; only its interpolation tokens belong to v1. */
+export declare function templateRefs(template: string): readonly PortRef[];
+export declare function mappingRefs(mapping: Mapping): readonly PortRef[];
+export declare function predicateRefs(test: Predicate): readonly PortRef[];
+export declare function nodeRefs(node: Node): readonly PortRef[];
+export declare function readPort(values: Values, ref: PortRef): Json | undefined;
+/** Infer constructed data through the same Mapping grammar used at execution. */
+export declare function mappingProjection(mapping: Mapping, source: (ref: PortRef, path?: string) => PortSchema | undefined): PortSchema;
+export declare function evaluateMapping(mapping: Mapping, values: Values): Json | undefined;
+export declare function evaluatePredicate(test: Predicate, values: Values): boolean;