@fungi.computer/braid 0.0.0-stage → 0.0.1

package/dist/expressions.js

@@ -0,0 +1,322 @@
+import Mustache from "mustache";
+import pointer from "jsonpointer";
+import * as S from "effect/Schema";
+import { portProjection } from "./ports.js";
+/** Expected syntax refusal only; defects in a parser or graph traversal escape. */
+export class ExpressionSyntaxError extends Error {
+}
+/** Mustache parses the representation; only its interpolation tokens belong to v1. */
+export function templateRefs(template) {
+    let tokens;
+    try {
+        tokens = Mustache.parse(template, ["{{", "}}"]);
+    }
+    catch (cause) {
+        // For a string and these fixed tags, Mustache 4's syntax refusals are plain
+        // Error. Native defects (TypeError, RangeError, etc.) are not syntax issues.
+        if (!(cause instanceof Error) || cause.constructor !== Error)
+            throw cause;
+        throw new ExpressionSyntaxError("Invalid Mustache syntax", { cause });
+    }
+    return tokens.flatMap((token) => {
+        if (token[0] === "text")
+            return [];
+        if (token[0] !== "name" ||
+            !/^([$]input|[$]item|[A-Za-z][A-Za-z0-9_-]*)[.][A-Za-z][A-Za-z0-9_-]*$/.test(token[1]))
+            throw new ExpressionSyntaxError("Only node.port interpolation is supported");
+        const [node, port] = token[1].split(".");
+        if (!node || !port)
+            throw new ExpressionSyntaxError("Invalid template reference");
+        return [{ node, port }];
+    });
+}
+export function mappingRefs(mapping) {
+    if ("from" in mapping) {
+        if (mapping.path !== undefined) {
+            try {
+                pointer.compile(mapping.path);
+            }
+            catch (cause) {
+                // jsonpointer's string compile interface reports invalid syntax as
+                // plain Error; do not turn native error subtypes into author refusals.
+                if (!(cause instanceof Error) || cause.constructor !== Error)
+                    throw cause;
+                throw new ExpressionSyntaxError("Invalid JSON pointer syntax", {
+                    cause,
+                });
+            }
+        }
+        return [mapping.from];
+    }
+    if ("template" in mapping)
+        return templateRefs(mapping.template);
+    if ("coalesce" in mapping)
+        return mapping.coalesce.flatMap(mappingRefs);
+    if ("object" in mapping)
+        return Object.values(mapping.object).flatMap(mappingRefs);
+    if ("array" in mapping)
+        return mapping.array.flatMap(mappingRefs);
+    if ("each" in mapping)
+        return [
+            ...mappingRefs(mapping.each.over),
+            ...mappingRefs(mapping.each.body).filter((ref) => {
+                if (ref.node !== "$item")
+                    return true;
+                if (ref.port !== "value" && ref.port !== "index")
+                    throw new ExpressionSyntaxError("Each exposes only $item.value and $item.index");
+                return false;
+            }),
+        ];
+    return [];
+}
+export function predicateRefs(test) {
+    if ("tests" in test)
+        return test.tests.flatMap(predicateRefs);
+    if ("test" in test)
+        return predicateRefs(test.test);
+    if ("value" in test)
+        return mappingRefs(test.value);
+    return [...mappingRefs(test.left), ...mappingRefs(test.right)];
+}
+export function nodeRefs(node) {
+    switch (node.kind) {
+        case "app":
+        case "code":
+            return Object.values(node.values).flatMap(mappingRefs);
+        case "review":
+            return node.show;
+        case "map":
+            return [node.over];
+        case "repeat":
+            return [{ node: "$input", port: "item" }];
+        case "condition":
+            return predicateRefs(node.test);
+        case "transform":
+            return Object.values(node.fields).flatMap(mappingRefs);
+        case "wait":
+            return [];
+    }
+}
+export function readPort(values, ref) {
+    if (!Object.hasOwn(values, ref.node))
+        return undefined;
+    const node = values[ref.node];
+    return node && Object.hasOwn(node, ref.port) ? node[ref.port] : undefined;
+}
+/** Infer constructed data through the same Mapping grammar used at execution. */
+export function mappingProjection(mapping, source) {
+    const mapped = (part) => mappingProjection(part, source);
+    const union = (parts) => parts.length === 0
+        ? {}
+        : parts.length === 1
+            ? (parts[0] ?? {})
+            : { anyOf: [...parts] };
+    if ("from" in mapping)
+        return source(mapping.from, mapping.path) ?? {};
+    if ("literal" in mapping) {
+        const value = mapping.literal;
+        if (S.is(S.Array(S.Json))(value))
+            return {
+                type: "array",
+                const: value,
+                items: union(value.map((item) => mapped({ literal: item }))),
+                minItems: value.length,
+                maxItems: value.length,
+            };
+        if (S.is(S.JsonObject)(value))
+            return {
+                type: "object",
+                const: value,
+                properties: Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                    key,
+                    mapped({ literal: item }),
+                ])),
+                required: Object.keys(value),
+                additionalProperties: false,
+            };
+        return {
+            type: value === null
+                ? "null"
+                : S.is(S.String)(value)
+                    ? "string"
+                    : S.is(S.Boolean)(value)
+                        ? "boolean"
+                        : Number.isInteger(value)
+                            ? "integer"
+                            : "number",
+            const: value,
+        };
+    }
+    if ("coalesce" in mapping)
+        return union(mapping.coalesce
+            .filter((part) => !("literal" in part && part.literal === null))
+            .map(mapped));
+    if ("object" in mapping)
+        return {
+            type: "object",
+            properties: Object.fromEntries(Object.entries(mapping.object).map(([key, part]) => [
+                key,
+                mapped(part),
+            ])),
+            required: Object.keys(mapping.object),
+            additionalProperties: false,
+        };
+    if ("array" in mapping)
+        return {
+            type: "array",
+            items: union(mapping.array.map(mapped)),
+            minItems: mapping.array.length,
+            maxItems: mapping.array.length,
+        };
+    if ("each" in mapping) {
+        const over = mapped(mapping.each.over);
+        const items = mappingProjection(mapping.each.body, (ref, path) => ref.node === "$item"
+            ? portProjection(ref.port === "value"
+                ? over.items
+                : ref.port === "index"
+                    ? {
+                        type: "integer",
+                        minimum: 0,
+                        maximum: mapping.each.maxItems - 1,
+                    }
+                    : undefined, path)
+            : source(ref, path));
+        return over.type === "array"
+            ? {
+                type: "array",
+                items,
+                minItems: over.minItems ?? 0,
+                maxItems: Math.min(over.maxItems ?? mapping.each.maxItems, mapping.each.maxItems),
+            }
+            : {};
+    }
+    const refs = templateRefs(mapping.template);
+    let minimum = 0;
+    let maximum = 0;
+    let cursor = 0;
+    for (const token of Mustache.parse(mapping.template, ["{{", "}}"])) {
+        if (token[0] === "text") {
+            minimum += token[1].length;
+            if (maximum !== undefined)
+                maximum += token[1].length;
+        }
+        else {
+            const ref = refs[cursor++];
+            const schema = ref ? source(ref) : undefined;
+            // Templates retain their optional-reference behavior: absence renders empty text.
+            if (schema?.maxLength === undefined)
+                maximum = undefined;
+            else if (maximum !== undefined)
+                maximum += schema.maxLength;
+        }
+    }
+    return maximum === undefined
+        ? { type: "string", minLength: minimum }
+        : { type: "string", minLength: minimum, maxLength: maximum };
+}
+export function evaluateMapping(mapping, values) {
+    // Materialization shares the engine's 64 KiB result ceiling. Count visits as
+    // well so nested each expressions cannot allocate an exponential intermediate.
+    let remaining = 64 * 1024;
+    const evaluate = (mapping, values) => {
+        if (--remaining < 0)
+            return undefined;
+        const value = evaluateValue(mapping, values);
+        return value !== undefined && JSON.stringify(value).length <= 64 * 1024
+            ? value
+            : undefined;
+    };
+    const evaluateValue = (mapping, values) => {
+        if ("literal" in mapping)
+            return mapping.literal;
+        if ("from" in mapping) {
+            const value = readPort(values, mapping.from);
+            if (mapping.path === undefined || value === undefined)
+                return value;
+            if (!S.is(S.Union([S.JsonObject, S.Array(S.Json)]))(value))
+                return undefined;
+            const selected = pointer.get(value, mapping.path);
+            return selected === undefined
+                ? undefined
+                : S.decodeUnknownSync(S.Json)(selected);
+        }
+        if ("coalesce" in mapping) {
+            for (const part of mapping.coalesce) {
+                const value = evaluate(part, values);
+                if (value !== undefined && value !== null)
+                    return value;
+            }
+            return undefined;
+        }
+        if ("object" in mapping) {
+            const entries = [];
+            for (const [key, part] of Object.entries(mapping.object)) {
+                const value = evaluate(part, values);
+                if (value === undefined)
+                    return undefined;
+                entries.push([key, value]);
+            }
+            return Object.fromEntries(entries);
+        }
+        if ("array" in mapping) {
+            const items = [];
+            for (const part of mapping.array) {
+                const value = evaluate(part, values);
+                if (value === undefined)
+                    return undefined;
+                items.push(value);
+            }
+            return items;
+        }
+        if ("each" in mapping) {
+            const over = evaluate(mapping.each.over, values);
+            if (!S.is(S.Array(S.Json))(over) || over.length > mapping.each.maxItems)
+                return undefined;
+            const items = [];
+            for (const [index, value] of over.entries()) {
+                const item = evaluate(mapping.each.body, {
+                    ...values,
+                    $item: { value, index },
+                });
+                if (item === undefined)
+                    return undefined;
+                items.push(item);
+            }
+            return items;
+        }
+        templateRefs(mapping.template);
+        return Mustache.render(mapping.template, values, undefined, {
+            escape: (value) => value,
+        });
+    };
+    return evaluate(mapping, values);
+}
+export function evaluatePredicate(test, values) {
+    switch (test.op) {
+        case "and":
+            return test.tests.every((child) => evaluatePredicate(child, values));
+        case "or":
+            return test.tests.some((child) => evaluatePredicate(child, values));
+        case "not":
+            return !evaluatePredicate(test.test, values);
+        case "exists":
+            return evaluateMapping(test.value, values) !== undefined;
+        default: {
+            const left = evaluateMapping(test.left, values);
+            const right = evaluateMapping(test.right, values);
+            switch (test.op) {
+                case "eq":
+                    return JSON.stringify(left) === JSON.stringify(right);
+                case "neq":
+                    return JSON.stringify(left) !== JSON.stringify(right);
+                case "gt":
+                    return S.is(S.Number)(left) && S.is(S.Number)(right) && left > right;
+                case "lt":
+                    return S.is(S.Number)(left) && S.is(S.Number)(right) && left < right;
+                case "in":
+                    return (Array.isArray(right) &&
+                        right.some((item) => JSON.stringify(item) === JSON.stringify(left)));
+            }
+        }
+    }
+}

package/dist/git-access.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/** Frozen installation identity or explicit registered Team-source namespace. */
+export declare const workflowBindingSchema: z.ZodUnion<readonly [z.ZodObject<{
+    appId: z.ZodString;
+    installationId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"team-source">;
+}, z.core.$strict>]>;
+/** Installation selections are admitted through the host's catalog before compilation. */
+export declare const bindingsSelectionSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    kind: z.ZodLiteral<"team-source">;
+}, z.core.$strict>]>>;
+export type BindingsSelection = z.output<typeof bindingsSelectionSchema>;
+/** Published node declaration: a write branch ceiling or a read-only scope. */
+export declare const gitAccessSchema: z.ZodUnion<readonly [z.ZodObject<{
+    binding: z.ZodString;
+    repository: z.ZodString;
+    branches: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    binding: z.ZodString;
+    repository: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"$trigger.repository">]>;
+    access: z.ZodLiteral<"read">;
+}, z.core.$strict>]>;
+/** Host-resolved scope carried to a process; data alone never grants this authority. */
+export declare const resolvedGitAccessSchema: z.ZodUnion<readonly [z.ZodObject<{
+    repository: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"installation">;
+        installationId: z.ZodString;
+        repository: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"team-source">;
+        repository: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    branches: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    repository: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"installation">;
+        installationId: z.ZodString;
+        repository: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"team-source">;
+        repository: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    access: z.ZodLiteral<"read">;
+}, z.core.$strict>]>;
+export type GitAccess = z.infer<typeof gitAccessSchema>;
+export type ResolvedGitAccess = z.infer<typeof resolvedGitAccessSchema>;
+/** The Git scope a pass for this resolved access admits. */
+export declare function gitAccessScope(access: GitAccess | ResolvedGitAccess): "read" | "write";
+/** Exact scope equality: same repository, same access, same ordered branches. */
+export declare function resolvedGitAccessEqual(left: ResolvedGitAccess, right: ResolvedGitAccess): boolean;
+/** One event-named repository, already decoded from the trigger's mapping. */
+export declare const triggerRepositorySchema: z.ZodString;
+/**
+ * Resolve only the selected frozen namespace; never infer the App executing
+ * the node. `$trigger.repository` resolves only with the run's trigger
+ * repository; without one it is unavailable.
+ */
+export declare function resolveGitAccess(bindings: Readonly<Record<string, z.output<typeof workflowBindingSchema>>>, authored: GitAccess, triggerRepository?: string): ResolvedGitAccess | null;

package/dist/git-access.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { repositoryRefSchema, repositoryRefsEqual, } from "@fungi.computer/agar/git";
+const repository = z
+    .string()
+    .regex(/^[a-zA-Z0-9._-]{1,128}$/)
+    .refine((value) => value !== "." && value !== "..");
+const bindingName = z
+    .string()
+    .min(1)
+    .max(80)
+    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/);
+const identity = z.string().min(1).max(256);
+const teamSourceBinding = z.strictObject({ kind: z.literal("team-source") });
+/** Frozen installation identity or explicit registered Team-source namespace. */
+export const workflowBindingSchema = z.union([
+    z.strictObject({ appId: identity, installationId: identity }),
+    teamSourceBinding,
+]);
+/** Installation selections are admitted through the host's catalog before compilation. */
+export const bindingsSelectionSchema = z.record(bindingName, z.union([identity, teamSourceBinding]));
+/** A literal branch scope, never a ref pattern or a revision expression. */
+const branch = z
+    .string()
+    .max(1024)
+    .regex(/^refs\/heads\/[A-Za-z0-9_/-][A-Za-z0-9._/-]*$/)
+    .refine((value) => !value.includes("..") &&
+    !value.includes("//") &&
+    !value.endsWith("/") &&
+    !value.endsWith(".") &&
+    value
+        .split("/")
+        .every((part) => !part.startsWith(".") && !part.endsWith(".lock")));
+const branches = z
+    .array(branch)
+    .min(1)
+    .max(256)
+    .refine((values) => new Set(values).size === values.length, "Branches must be unique");
+/** Write access names a fixed repository and its exact branch ceiling, admitted at arm time. */
+const writeGitAccessSchema = z.strictObject({
+    binding: bindingName,
+    repository,
+    branches,
+});
+/**
+ * Read access never pushes. `$trigger.repository` is the one repository the
+ * firing event names through its trigger's `repository` mapping; it resolves
+ * per run, inside the trigger App's own host-attested installation.
+ */
+const readGitAccessSchema = z.strictObject({
+    binding: bindingName,
+    repository: z.union([repository, z.literal("$trigger.repository")]),
+    access: z.literal("read"),
+});
+/** Published node declaration: a write branch ceiling or a read-only scope. */
+export const gitAccessSchema = z.union([
+    writeGitAccessSchema,
+    readGitAccessSchema,
+]);
+/** Host-resolved scope carried to a process; data alone never grants this authority. */
+export const resolvedGitAccessSchema = z.union([
+    z.strictObject({ repository: repositoryRefSchema, branches }),
+    z.strictObject({
+        repository: repositoryRefSchema,
+        access: z.literal("read"),
+    }),
+]);
+/** The Git scope a pass for this resolved access admits. */
+export function gitAccessScope(access) {
+    return "access" in access ? access.access : "write";
+}
+/** Exact scope equality: same repository, same access, same ordered branches. */
+export function resolvedGitAccessEqual(left, right) {
+    if (!repositoryRefsEqual(left.repository, right.repository))
+        return false;
+    if ("access" in left || "access" in right)
+        return "access" in left && "access" in right;
+    return (left.branches.length === right.branches.length &&
+        left.branches.every((branch, index) => branch === right.branches[index]));
+}
+/** One event-named repository, already decoded from the trigger's mapping. */
+export const triggerRepositorySchema = repository;
+/**
+ * Resolve only the selected frozen namespace; never infer the App executing
+ * the node. `$trigger.repository` resolves only with the run's trigger
+ * repository; without one it is unavailable.
+ */
+export function resolveGitAccess(bindings, authored, triggerRepository) {
+    const binding = bindings[authored.binding];
+    if (binding === undefined)
+        return null;
+    const name = authored.repository === "$trigger.repository"
+        ? triggerRepository
+        : authored.repository;
+    if (name === undefined)
+        return null;
+    const repositoryRef = "installationId" in binding
+        ? {
+            kind: "installation",
+            installationId: binding.installationId,
+            repository: name,
+        }
+        : { kind: "team-source", repository: name };
+    return resolvedGitAccessSchema.parse("access" in authored
+        ? { repository: repositoryRef, access: authored.access }
+        : { repository: repositoryRef, branches: authored.branches });
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./schema.js";
+export * from "./ports.js";
+export * from "./expressions.js";
+export * from "./validate.js";
+export * from "./compile.js";
+export * from "./triggers.js";
+export * from "./execution.js";
+export * from "./workflow-id.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./schema.js";
+export * from "./ports.js";
+export * from "./expressions.js";
+export * from "./validate.js";
+export * from "./compile.js";
+export * from "./triggers.js";
+export * from "./execution.js";
+export * from "./workflow-id.js";

package/dist/ports.d.ts

@@ -0,0 +1,58 @@
+import * as S from "effect/Schema";
+import type { Graph, Json, JsonSchemaProjection } from "./schema.js";
+/** Deliberately conservative v1 projection vocabulary. Unsupported assertions are refused. */
+export type PortSchema = {
+    readonly type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
+    readonly format?: string;
+    readonly description?: string;
+    readonly title?: string;
+    readonly enum?: Json[];
+    readonly const?: Json;
+    readonly default?: Json;
+    readonly pattern?: string;
+    readonly anyOf?: PortSchema[];
+    readonly oneOf?: PortSchema[];
+    readonly properties?: Readonly<Record<string, PortSchema>>;
+    readonly required?: string[];
+    readonly additionalProperties?: boolean;
+    readonly items?: PortSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly exclusiveMaximum?: number;
+};
+/** Effect owns the supported schema grammar; the Workers-safe validator owns instance validation. */
+export declare function parseProjection(value: JsonSchemaProjection): PortSchema;
+export declare function accepts(schema: PortSchema, value: Json): boolean;
+export type RunInputAdmission = {
+    readonly kind: "accepted";
+    readonly input: S.JsonObject;
+} | {
+    readonly kind: "invalid";
+    readonly issues: readonly {
+        readonly code: "invalid_input";
+        readonly path: string;
+        readonly message: string;
+    }[];
+};
+/** Every run source uses the same supported projection and instance validator. */
+export declare function admitRunInput(definition: Pick<Graph, "input">, raw: Json): RunInputAdmission;
+export declare function ports(schema: PortSchema): Readonly<Record<string, PortSchema>>;
+/** Only guaranteed object paths have a static type. The library owns Pointer spelling. */
+export declare function portProjection(schema: PortSchema | undefined, path?: string): PortSchema | undefined;
+/** A method receives its declared value; only the graph-facing view wraps scalars and unions. */
+export declare function methodInputPorts(schema: PortSchema): PortSchema;
+/** Declared error-object unions expose whole completion records on mutually exclusive outlets. */
+export declare function methodOutputPorts(schema: PortSchema): Readonly<Record<string, PortSchema>>;
+export declare function methodInputValue(schema: PortSchema, values: Readonly<Record<string, Json>>): Json | undefined;
+export declare function methodOutputValues(schema: PortSchema, value: Json): Readonly<Record<string, Json>> | undefined;
+export type PortKind = "text" | "number" | "bool" | "object" | "null" | "any" | "fungi:image" | "fungi:video" | "fungi:file" | {
+    readonly list: PortKind;
+};
+export declare function portKind(schema: PortSchema): PortKind;
+/** Sound subset check, not a claim to decide arbitrary JSON Schema implication. */
+export declare function assignable(source: PortSchema, target: PortSchema): boolean;