@gonvex/module-sdk 0.3.0

package/dist/index.js

@@ -0,0 +1,805 @@
+const freeze = (value) => Object.freeze(value);
+/** Constructors for the language-neutral schema subset. */
+export const schema = {
+    string(options = {}) {
+        return freeze({ kind: "string", ...options });
+    },
+    email() {
+        return freeze({ kind: "string", format: "email" });
+    },
+    uri() {
+        return freeze({ kind: "string", format: "uri" });
+    },
+    uuid() {
+        return freeze({ kind: "string", format: "uuid" });
+    },
+    datetime() {
+        return freeze({ kind: "string", format: "datetime" });
+    },
+    number(options = {}) {
+        return freeze({ kind: "number", ...options });
+    },
+    integer(options = {}) {
+        return freeze({ kind: "number", integer: true, ...options });
+    },
+    boolean() {
+        return freeze({ kind: "boolean" });
+    },
+    null() {
+        return freeze({ kind: "null" });
+    },
+    any() {
+        return freeze({ kind: "any" });
+    },
+    id(entity) {
+        if (!entity.trim())
+            throw new Error("schema.id requires an entity name");
+        return freeze({ kind: "id", entity });
+    },
+    literal(value) {
+        return freeze({ kind: "literal", value });
+    },
+    array(items) {
+        return freeze({ kind: "array", items });
+    },
+    object(fields, options = {}) {
+        return freeze({ kind: "object", fields: freeze({ ...fields }), ...options });
+    },
+    record(values) {
+        return freeze({ kind: "record", values });
+    },
+    optional(value) {
+        return freeze({ kind: "optional", value });
+    },
+};
+/** Declare the host-invoked internal Reducer that applies invitation payloads. */
+export function invitationAcceptance(reducerPath) {
+    const reducer = normalizePath(reducerPath);
+    return freeze({ reducer });
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const normalizePath = (path) => {
+    const normalized = path.trim();
+    if (!normalized)
+        throw new Error("module function path is required");
+    if (normalized === "control" || normalized.startsWith("control.")) {
+        throw new Error(`module function path ${JSON.stringify(normalized)} uses the host-reserved Control Plane namespace`);
+    }
+    return normalized;
+};
+const validateOfflinePolicy = (value, path) => {
+    if (!isRecord(value) || (value.mode !== "forbidden" && value.mode !== "allowed" && value.mode !== "onlineOnly")) {
+        throw new Error(`reducer ${path} must declare a valid offline policy`);
+    }
+    if (value.mode === "onlineOnly" && (typeof value.reason !== "string" || !value.reason.trim())) {
+        throw new Error(`reducer ${path} onlineOnly policy requires a reason`);
+    }
+    if (value.mode === "allowed" && value.conflict !== undefined &&
+        value.conflict !== "reject" && value.conflict !== "expectedVersion" && value.conflict !== "merge") {
+        throw new Error(`reducer ${path} has an invalid offline conflict policy`);
+    }
+};
+const validateOptimisticTransaction = (value, path) => {
+    if (!isRecord(value) || !Array.isArray(value.effects) || value.effects.length === 0) {
+        throw new Error(`reducer ${path} optimistic metadata must contain a non-empty effects array`);
+    }
+    if (value.expectedRevision !== undefined &&
+        (typeof value.expectedRevision !== "number" || !Number.isSafeInteger(value.expectedRevision) || value.expectedRevision < 0)) {
+        throw new Error(`reducer ${path} optimistic expectedRevision must be a non-negative integer`);
+    }
+    for (const effect of value.effects) {
+        if (!isRecord(effect) || (effect.operation !== "patch" && effect.operation !== "upsert" && effect.operation !== "delete")) {
+            throw new Error(`reducer ${path} has an invalid optimistic effect`);
+        }
+        if (typeof effect.entity !== "string" || !effect.entity.trim()) {
+            throw new Error(`reducer ${path} optimistic effects require an entity`);
+        }
+        if ((typeof effect.id === "string" && !effect.id.trim()) ||
+            (typeof effect.id !== "string" &&
+                (!Array.isArray(effect.id) || effect.id.length === 0 || effect.id.some((part) => typeof part !== "string" || !part.trim())))) {
+            throw new Error(`reducer ${path} optimistic effects require a string id or id references`);
+        }
+        if ((effect.operation === "patch" || effect.operation === "upsert") && !isRecord(effect.operation === "patch" ? effect.fields : effect.value)) {
+            throw new Error(`reducer ${path} optimistic ${effect.operation} effects require an object value`);
+        }
+    }
+};
+const validateReplicaCollection = (value, path) => {
+    if (!isRecord(value) || typeof value.table !== "string" || !value.table.trim() ||
+        typeof value.key !== "string" || !value.key.trim() || !Array.isArray(value.columns) ||
+        value.columns.some((column) => typeof column !== "string" || !column.trim())) {
+        throw new Error(`replica collection ${path} requires a table, key, and columns`);
+    }
+    for (const field of ["maxRows", "maxBytes", "retentionMs"]) {
+        const budget = value[field];
+        if (budget !== undefined && (typeof budget !== "number" || !Number.isSafeInteger(budget) || budget <= 0)) {
+            throw new Error(`replica collection ${path} ${field} must be a positive integer`);
+        }
+    }
+    if (value.mode !== undefined && value.mode !== "eager" && value.mode !== "progressive") {
+        throw new Error(`replica collection ${path} has an invalid completeness mode`);
+    }
+    if (value.orderDirection !== undefined && value.orderDirection !== "asc" && value.orderDirection !== "desc") {
+        throw new Error(`replica collection ${path} has an invalid order direction`);
+    }
+};
+const validateActionCapabilities = (profile, value, path) => {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        throw new Error(`action ${path} capabilities must be an object`);
+    const allowed = new Set(["networkOrigins", "secrets", "tools", "scheduler", "storage", "sandbox"]);
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field))
+            throw new Error(`action ${path} capabilities has unsupported field ${field}`);
+    }
+    if (value.networkOrigins !== undefined) {
+        if (!Array.isArray(value.networkOrigins) || value.networkOrigins.length === 0) {
+            throw new Error(`action ${path} networkOrigins must be a non-empty array`);
+        }
+        const seen = new Set();
+        for (const origin of value.networkOrigins) {
+            if (typeof origin !== "string")
+                throw new Error(`action ${path} networkOrigins must contain strings`);
+            let parsed;
+            try {
+                parsed = new URL(origin);
+            }
+            catch {
+                throw new Error(`action ${path} network origin ${JSON.stringify(origin)} is invalid`);
+            }
+            if ((parsed.protocol !== "https:" && parsed.protocol !== "http:") || parsed.origin !== origin || parsed.username || parsed.password) {
+                throw new Error(`action ${path} network origin ${JSON.stringify(origin)} must be an exact HTTP(S) origin`);
+            }
+            if (seen.has(origin))
+                throw new Error(`action ${path} declares duplicate network origin ${origin}`);
+            seen.add(origin);
+        }
+    }
+    if (value.secrets !== undefined) {
+        if (!Array.isArray(value.secrets) || value.secrets.some((name) => typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name))) {
+            throw new Error(`action ${path} secrets must be uppercase environment names`);
+        }
+    }
+    if (value.tools !== undefined) {
+        if (profile !== "agent")
+            throw new Error(`action ${path} tools require profile "agent"`);
+        if (!isRecord(value.tools) || Object.keys(value.tools).length === 0) {
+            throw new Error(`agent action ${path} tools must be a non-empty object`);
+        }
+        for (const [name, binding] of Object.entries(value.tools)) {
+            if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) || !isRecord(binding) ||
+                (binding.kind !== "query" && binding.kind !== "reducer") || typeof binding.function !== "string" || !binding.function.trim()) {
+                throw new Error(`agent action ${path} has an invalid tool binding ${JSON.stringify(name)}`);
+            }
+        }
+    }
+    if (value.scheduler !== undefined && value.scheduler !== true)
+        throw new Error(`action ${path} scheduler must be true when declared`);
+    if (value.storage !== undefined && value.storage !== true)
+        throw new Error(`action ${path} storage must be true when declared`);
+    if (value.sandbox !== undefined) {
+        if (profile !== "agent")
+            throw new Error(`action ${path} sandbox requires profile "agent"`);
+        if (!isRecord(value.sandbox))
+            throw new Error(`action ${path} sandbox must be an object`);
+        for (const field of Object.keys(value.sandbox)) {
+            if (field !== "duckdb")
+                throw new Error(`action ${path} sandbox has unsupported field ${field}`);
+        }
+        if (value.sandbox.duckdb !== undefined && value.sandbox.duckdb !== true) {
+            throw new Error(`action ${path} sandbox.duckdb must be true when declared`);
+        }
+    }
+};
+const validateStructuredQueryPlan = (value, path) => {
+    if (!isRecord(value) || typeof value.table !== "string" || !value.table.trim() ||
+        typeof value.key !== "string" || !value.key.trim() || !Array.isArray(value.columns) ||
+        value.columns.length === 0 || value.columns.some((column) => typeof column !== "string" || !column.trim())) {
+        throw new Error(`one-shot query ${path} requires a structured live query plan with a table, key, and columns`);
+    }
+    if (!value.columns.includes(value.key)) {
+        throw new Error(`one-shot query ${path} live query plan columns must include its key`);
+    }
+    if (value.filters !== undefined) {
+        if (!isRecord(value.filters) || typeof value.filters.argument !== "string" || !value.filters.argument.trim() ||
+            !Array.isArray(value.filters.allowedColumns) || value.filters.allowedColumns.length === 0 ||
+            value.filters.allowedColumns.some((column) => typeof column !== "string" || !column.trim()) ||
+            !Array.isArray(value.filters.allowedOperators) || value.filters.allowedOperators.length === 0) {
+            throw new Error(`structured query plan ${path} filters must declare an argument, allowed columns, and allowed operators`);
+        }
+        const operators = new Set(["contains", "notContains", "equals", "notEquals", "startsWith", "endsWith", "empty", "notEmpty", "oneOf", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual", "inRange"]);
+        if (value.filters.allowedOperators.some((operator) => typeof operator !== "string" || !operators.has(operator))) {
+            throw new Error(`structured query plan ${path} filters contains an unsupported operator`);
+        }
+    }
+};
+const visibilityOperators = new Set(["public", "permission", "role", "eqContext", "inSet", "and", "or", "not"]);
+const visibilityContexts = new Set(["account.id", "member.id", "tenant.id"]);
+const validateExactObject = (value, path, fields) => {
+    if (!isRecord(value))
+        throw new Error(`${path} must be an object`);
+    const allowed = new Set(fields);
+    const unexpected = Object.keys(value).find((field) => !allowed.has(field));
+    if (unexpected !== undefined)
+        throw new Error(`${path} has unsupported field ${unexpected}`);
+};
+const requireVisibilityString = (value, path) => {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${path} must be a non-empty string`);
+    return value;
+};
+const validateVisibilityContext = (value, path) => {
+    if (typeof value !== "string" || !visibilityContexts.has(value)) {
+        throw new Error(`${path} must be account.id, member.id, or tenant.id`);
+    }
+    return value;
+};
+const validateVisibilityExpression = (value, path, sets, ancestors = new Set()) => {
+    validateExactObject(value, path, ["operator", "column", "context", "set", "value", "children"]);
+    if (ancestors.has(value))
+        throw new Error(`${path} contains a cycle`);
+    const operator = value.operator;
+    if (typeof operator !== "string" || !visibilityOperators.has(operator)) {
+        throw new Error(`${path}.operator is unsupported`);
+    }
+    const nested = new Set(ancestors);
+    nested.add(value);
+    switch (operator) {
+        case "public":
+            validateExactObject(value, path, ["operator"]);
+            return;
+        case "permission":
+        case "role":
+            validateExactObject(value, path, ["operator", "value"]);
+            requireVisibilityString(value.value, `${path}.value`);
+            return;
+        case "eqContext":
+            validateExactObject(value, path, ["operator", "column", "context"]);
+            requireVisibilityString(value.column, `${path}.column`);
+            validateVisibilityContext(value.context, `${path}.context`);
+            return;
+        case "inSet": {
+            validateExactObject(value, path, ["operator", "column", "set"]);
+            requireVisibilityString(value.column, `${path}.column`);
+            const set = requireVisibilityString(value.set, `${path}.set`);
+            if (!Object.prototype.hasOwnProperty.call(sets, set))
+                throw new Error(`${path}.set references unknown visibility set ${set}`);
+            return;
+        }
+        case "and":
+        case "or":
+            validateExactObject(value, path, ["operator", "children"]);
+            if (!Array.isArray(value.children) || value.children.length === 0) {
+                throw new Error(`${path}.${operator} requires children`);
+            }
+            value.children.forEach((child, index) => validateVisibilityExpression(child, `${path}.children[${index}]`, sets, nested));
+            return;
+        case "not":
+            validateExactObject(value, path, ["operator", "children"]);
+            if (!Array.isArray(value.children) || value.children.length !== 1) {
+                throw new Error(`${path}.not requires exactly one child`);
+            }
+            validateVisibilityExpression(value.children[0], `${path}.children[0]`, sets, nested);
+            return;
+    }
+};
+const validateVisibilityPlan = (value, path) => {
+    validateExactObject(value, path, ["table", "key", "sets", "where"]);
+    requireVisibilityString(value.table, `${path}.table`);
+    requireVisibilityString(value.key, `${path}.key`);
+    if (!isRecord(value.sets))
+        throw new Error(`${path}.sets must be an object`);
+    for (const [name, candidate] of Object.entries(value.sets)) {
+        requireVisibilityString(name, `${path}.sets key`);
+        const setPath = `${path}.sets.${name}`;
+        validateExactObject(candidate, setPath, ["table", "select", "joins", "where"]);
+        requireVisibilityString(candidate.table, `${setPath}.table`);
+        requireVisibilityString(candidate.select, `${setPath}.select`);
+        if (!Array.isArray(candidate.joins))
+            throw new Error(`${setPath}.joins must be an array`);
+        candidate.joins.forEach((join, index) => {
+            const joinPath = `${setPath}.joins[${index}]`;
+            validateExactObject(join, joinPath, ["table", "leftColumn", "rightColumn"]);
+            requireVisibilityString(join.table, `${joinPath}.table`);
+            requireVisibilityString(join.leftColumn, `${joinPath}.leftColumn`);
+            requireVisibilityString(join.rightColumn, `${joinPath}.rightColumn`);
+        });
+        if (!Array.isArray(candidate.where))
+            throw new Error(`${setPath}.where must be an array`);
+        candidate.where.forEach((constraint, index) => {
+            const constraintPath = `${setPath}.where[${index}]`;
+            validateExactObject(constraint, constraintPath, ["table", "column", "context"]);
+            requireVisibilityString(constraint.table, `${constraintPath}.table`);
+            requireVisibilityString(constraint.column, `${constraintPath}.column`);
+            validateVisibilityContext(constraint.context, `${constraintPath}.context`);
+        });
+    }
+    validateVisibilityExpression(value.where, `${path}.where`, value.sets);
+};
+const freezeVisibilityExpression = (expression) => freeze({
+    ...expression,
+    children: expression.children === undefined
+        ? undefined
+        : freeze(expression.children.map(freezeVisibilityExpression)),
+});
+const freezeVisibilityPlan = (plan) => {
+    const sets = {};
+    for (const name of Object.keys(plan.sets).sort()) {
+        const set = plan.sets[name];
+        sets[name] = freeze({
+            ...set,
+            joins: freeze(set.joins.map((join) => freeze({ ...join }))),
+            where: freeze(set.where.map((constraint) => freeze({ ...constraint }))),
+        });
+    }
+    return freeze({
+        ...plan,
+        sets: freeze(sets),
+        where: freezeVisibilityExpression(plan.where),
+    });
+};
+/** Declare and validate one source table's language-neutral visibility plan. */
+export function visibility(options) {
+    validateVisibilityPlan(options, "visibility");
+    return freezeVisibilityPlan(options);
+}
+const stableValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (isRecord(value)) {
+        const sorted = {};
+        for (const key of Object.keys(value).sort())
+            sorted[key] = stableValue(value[key]);
+        return sorted;
+    }
+    return value;
+};
+/** JSON serialization with recursively sorted object keys for reproducible artifacts. */
+export const stableJsonStringify = (value, space) => JSON.stringify(stableValue(value), null, space);
+const validateCron = (options) => {
+    const name = options.name.trim();
+    const functionPath = options.function.trim();
+    if (!name)
+        throw new Error("cron name is required");
+    if (!functionPath)
+        throw new Error(`cron ${JSON.stringify(name)} requires a function path`);
+    const hasInterval = options.intervalMs !== undefined;
+    const hasExpression = options.expression !== undefined;
+    if (hasInterval === hasExpression) {
+        throw new Error(`cron ${JSON.stringify(name)} requires exactly one of intervalMs or expression`);
+    }
+    if (hasInterval && (!Number.isSafeInteger(options.intervalMs) || options.intervalMs <= 0)) {
+        throw new Error(`cron ${JSON.stringify(name)} intervalMs must be a positive safe integer`);
+    }
+    const expression = options.expression?.trim();
+    if (hasExpression && !expression)
+        throw new Error(`cron ${JSON.stringify(name)} expression must be non-empty`);
+    return freeze({
+        name,
+        function: functionPath,
+        scope: options.scope,
+        ...(options.args === undefined ? {} : { args: options.args }),
+        ...(hasInterval ? { intervalMs: options.intervalMs } : { expression: expression }),
+    });
+};
+/** Declare a project-wide recurring Reducer or Action. */
+export function cron(options) {
+    return validateCron({ ...options, scope: "project" });
+}
+/** Declare a recurring Reducer or Action once for every tenant. */
+export function tenantCron(options) {
+    return validateCron({ ...options, scope: "tenant" });
+}
+export class ModuleManifestCollector {
+    entries = new Map();
+    visibilityEntries = new Map();
+    cronEntries = new Map();
+    metadata;
+    constructor(metadata) {
+        const { visibility: initialVisibility, crons: initialCrons, ...baseMetadata } = metadata;
+        this.metadata = baseMetadata;
+        for (const sourceTable of Object.keys(initialVisibility ?? {}).sort()) {
+            const plan = initialVisibility[sourceTable];
+            if (sourceTable !== plan.table) {
+                throw new Error(`visibility map key ${sourceTable} does not match source table ${plan.table}`);
+            }
+            this.registerVisibility(plan);
+        }
+        for (const spec of initialCrons ?? [])
+            this.registerCron(spec);
+    }
+    register(path, entry) {
+        const normalized = normalizePath(path);
+        if (this.entries.has(normalized))
+            throw new Error(`duplicate module function: ${normalized}`);
+        const result = freeze({ path: normalized, ...entry });
+        this.entries.set(normalized, result);
+        return result;
+    }
+    registerVisibility(options) {
+        const plan = visibility(options);
+        if (this.visibilityEntries.has(plan.table))
+            throw new Error(`duplicate visibility plan: ${plan.table}`);
+        this.visibilityEntries.set(plan.table, plan);
+        return plan;
+    }
+    registerCron(options) {
+        const spec = validateCron(options);
+        if (this.cronEntries.has(spec.name))
+            throw new Error(`duplicate cron: ${spec.name}`);
+        this.cronEntries.set(spec.name, spec);
+        return spec;
+    }
+    manifest() {
+        const functions = {};
+        for (const path of [...this.entries.keys()].sort())
+            functions[path] = this.entries.get(path);
+        const visibilityPlans = {};
+        for (const table of [...this.visibilityEntries.keys()].sort())
+            visibilityPlans[table] = this.visibilityEntries.get(table);
+        const crons = [...this.cronEntries.values()].sort((left, right) => left.name.localeCompare(right.name));
+        for (const spec of crons) {
+            const target = this.entries.get(spec.function);
+            if (!target)
+                throw new Error(`cron ${JSON.stringify(spec.name)} targets unknown function ${JSON.stringify(spec.function)}`);
+            if (target.kind === "query")
+                throw new Error(`cron ${JSON.stringify(spec.name)} must target a reducer or action`);
+        }
+        for (const [path, definition] of this.entries) {
+            for (const [name, binding] of Object.entries(definition.actionCapabilities?.tools ?? {})) {
+                const target = this.entries.get(binding.function);
+                if (!target)
+                    throw new Error(`action ${JSON.stringify(path)} tool ${JSON.stringify(name)} targets unknown function ${JSON.stringify(binding.function)}`);
+                if (target.kind !== binding.kind)
+                    throw new Error(`action ${JSON.stringify(path)} tool ${JSON.stringify(name)} kind does not match ${JSON.stringify(binding.function)}`);
+                if (binding.kind === "query" && (!target.internal || target.delivery !== "oneShot"))
+                    throw new Error(`action ${JSON.stringify(path)} tool ${JSON.stringify(name)} must target an internal one-shot Query`);
+                if (binding.kind === "reducer" && target.internal)
+                    throw new Error(`action ${JSON.stringify(path)} tool ${JSON.stringify(name)} must target a public business-intent Reducer`);
+            }
+        }
+        return freeze({
+            ...this.metadata,
+            functions: freeze(functions),
+            crons: crons.length === 0 ? undefined : freeze(crons),
+            visibility: this.visibilityEntries.size === 0 ? undefined : freeze(visibilityPlans),
+        });
+    }
+    serialize(space) {
+        return stableJsonStringify(this.manifest(), space);
+    }
+}
+const executableOptions = (options) => freeze({ ...options });
+const queryDefinition = (options, deliveryOverride) => {
+    const liveQueryPlan = options.liveQueryPlan;
+    const replica = options.replica;
+    // `query()` is always a one-shot declaration. Live and replica delivery are
+    // selected only by the dedicated helpers below; a structured plan does not
+    // silently change the execution mode.
+    const delivery = deliveryOverride ?? options.delivery ?? "oneShot";
+    if (delivery === "live" && !liveQueryPlan)
+        throw new Error("live query requires a live query plan");
+    if (delivery === "oneShot") {
+        if (!liveQueryPlan)
+            throw new Error("one-shot query requires a structured live query plan");
+        validateStructuredQueryPlan(liveQueryPlan, "<export>");
+    }
+    if (delivery === "replica") {
+        if (!replica)
+            throw new Error("replica collection requires a replica definition");
+        validateReplicaCollection(replica, "<export>");
+    }
+    return freeze({
+        kind: "query",
+        internal: options.internal,
+        delivery,
+        liveQueryPlan,
+        replica,
+        options: executableOptions(options),
+        handler: options.run,
+    });
+};
+/** Declare an executable one-shot, live, or replica query export. */
+export function query(options = {}) {
+    return queryDefinition(options);
+}
+/** Declare a one-shot Query that is unreachable from clients and may be bound to an Action tool. */
+export function internalQuery(options = {}) {
+    return queryDefinition({ ...options, internal: true, delivery: "oneShot" });
+}
+/** Declare an executable live query export with a structured live plan. */
+export function liveQuery(options = {}) {
+    return queryDefinition({ ...options, delivery: "live" }, "live");
+}
+/** Declare an executable bounded replica collection export. */
+export function replicaCollection(options) {
+    return queryDefinition({ ...options, delivery: "replica", replica: options.replica }, "replica");
+}
+const reducerDefinition = (options, internal = false) => {
+    validateOfflinePolicy(options.offline, "<export>");
+    if (options.optimistic !== undefined)
+        validateOptimisticTransaction(options.optimistic, "<export>");
+    if (options.interactive === false && options.optimistic !== undefined) {
+        throw new Error("non-interactive reducer <export> cannot declare optimistic metadata");
+    }
+    if (options.interactive !== false && options.optimistic === undefined && !options.nonOptimisticReason?.trim()) {
+        throw new Error("interactive reducer <export> requires an optimistic transaction or nonOptimisticReason");
+    }
+    return freeze({
+        kind: "reducer",
+        internal: internal || options.internal,
+        options: executableOptions(options),
+        handler: options.run,
+    });
+};
+/** Declare an executable public reducer export. */
+export function reducer(options) {
+    return reducerDefinition(options);
+}
+/** Declare an executable non-interactive internal reducer export. */
+export function internalReducer(options) {
+    return reducerDefinition({
+        ...options,
+        offline: options.offline ?? { mode: "forbidden" },
+        interactive: false,
+        internal: true,
+    }, true);
+}
+/** Declare an executable action export. */
+export function action(options = {}) {
+    validateActionCapabilities(options.profile ?? "standard", options.capabilities, options.name?.trim() || "<export>");
+    return freeze({ kind: "action", options: executableOptions(options), handler: options.run });
+}
+export class ModuleBuilder {
+    manifestCollector;
+    runtimeEntries = new Map();
+    constructor(metadata) {
+        this.manifestCollector = new ModuleManifestCollector({
+            format: "gonvex.module.v1",
+            name: metadata.name,
+            version: metadata.version,
+            language: metadata.language ?? "typescript",
+            engine: metadata.engine ?? "v8",
+            schema: metadata.schema,
+            artifact: metadata.artifact,
+            visibility: metadata.visibility,
+            crons: metadata.crons,
+        });
+    }
+    visibility(options) {
+        return this.manifestCollector.registerVisibility(options);
+    }
+    cron(options) {
+        return this.manifestCollector.registerCron(cron(options));
+    }
+    tenantCron(options) {
+        return this.manifestCollector.registerCron(tenantCron(options));
+    }
+    query(path, options = {}) {
+        const liveQueryPlan = options.liveQueryPlan;
+        const replica = options.replica;
+        // `ModuleBuilder.query()` follows the same contract as the static artifact
+        // parser: a plan describes the SQL source, not the delivery mode.
+        const delivery = options.delivery ?? "oneShot";
+        if (delivery === "live" && !liveQueryPlan)
+            throw new Error(`live query ${normalizePath(path)} requires a live query plan`);
+        if (delivery === "oneShot") {
+            if (!liveQueryPlan)
+                throw new Error(`one-shot query ${normalizePath(path)} requires a structured live query plan`);
+            validateStructuredQueryPlan(liveQueryPlan, normalizePath(path));
+        }
+        if (delivery === "replica") {
+            if (!replica)
+                throw new Error(`replica collection ${normalizePath(path)} requires a replica definition`);
+            validateReplicaCollection(replica, normalizePath(path));
+        }
+        const definition = this.manifestCollector.register(path, {
+            kind: "query",
+            args: options.args,
+            result: options.result,
+            delivery,
+            liveQueryPlan,
+            replica,
+            internal: options.internal,
+        });
+        const registration = freeze({ path: definition.path, kind: definition.kind, definition, handler: options.run });
+        this.runtimeEntries.set(definition.path, registration);
+        return registration;
+    }
+    /** Register a Query delivered as a live, structured query stream. */
+    liveQuery(path, options = {}) {
+        return this.query(path, { ...options, delivery: "live" });
+    }
+    /** Register a Query delivered as a bounded local replica collection. */
+    replicaCollection(path, options) {
+        return this.query(path, { ...options, delivery: "replica", replica: options.replica });
+    }
+    reducer(path, options) {
+        const normalized = normalizePath(path);
+        validateOfflinePolicy(options.offline, normalized);
+        if (options.optimistic !== undefined)
+            validateOptimisticTransaction(options.optimistic, normalized);
+        if (options.interactive === false && options.optimistic !== undefined) {
+            throw new Error(`non-interactive reducer ${normalized} cannot declare optimistic metadata`);
+        }
+        if (options.interactive !== false && options.optimistic === undefined && !options.nonOptimisticReason?.trim()) {
+            throw new Error(`interactive reducer ${normalized} requires an optimistic transaction or nonOptimisticReason`);
+        }
+        const definition = this.manifestCollector.register(path, {
+            kind: "reducer",
+            args: options.args,
+            result: options.result,
+            offline: options.offline,
+            interactive: options.interactive ?? true,
+            internal: options.internal,
+            optimistic: options.optimistic,
+            nonOptimisticReason: options.nonOptimisticReason?.trim() || undefined,
+        });
+        const registration = freeze({ path: definition.path, kind: definition.kind, definition, handler: options.run });
+        this.runtimeEntries.set(definition.path, registration);
+        return registration;
+    }
+    /** Register a non-public Reducer while retaining kind `reducer` in the manifest. */
+    internalReducer(path, options) {
+        return this.reducer(path, {
+            ...options,
+            offline: options.offline ?? { mode: "forbidden" },
+            interactive: false,
+            internal: true,
+        });
+    }
+    action(path, options = {}) {
+        const profile = options.profile ?? "standard";
+        validateActionCapabilities(profile, options.capabilities, normalizePath(path));
+        const definition = this.manifestCollector.register(path, {
+            kind: "action",
+            args: options.args,
+            result: options.result,
+            actionProfile: profile,
+            actionCapabilities: options.capabilities,
+        });
+        const registration = freeze({ path: definition.path, kind: definition.kind, definition, handler: options.run });
+        this.runtimeEntries.set(definition.path, registration);
+        return registration;
+    }
+    manifest() {
+        return this.manifestCollector.manifest();
+    }
+    serialize(space) {
+        return this.manifestCollector.serialize(space);
+    }
+    /** Executable registrations sorted by path for deterministic host loading. */
+    runtimeRegistrations() {
+        return Object.freeze([...this.runtimeEntries.values()].sort((a, b) => a.path.localeCompare(b.path)));
+    }
+    runtimePayload() {
+        const registrations = this.runtimeRegistrations().map(({ path, kind, definition }) => ({ path, kind, definition }));
+        return freeze({
+            format: "gonvex.module.runtime.v1",
+            manifest: this.manifest(),
+            registrations: freeze(registrations),
+        });
+    }
+    serializeRuntimePayload(space) {
+        return stableJsonStringify(this.runtimePayload(), space);
+    }
+    createRuntimeRegistry() {
+        return new ModuleRuntimeRegistry(this);
+    }
+}
+/**
+ * Host-side executable registry. It is deliberately unaware of V8,
+ * Postgres, or network transport; an engine supplies the capability-bearing
+ * context and this registry only selects and invokes the registered handler.
+ */
+export class ModuleRuntimeRegistry {
+    entries = new Map();
+    baseManifest;
+    constructor(source) {
+        this.baseManifest = source.manifest();
+        for (const registration of source.runtimeRegistrations())
+            this.register(registration);
+    }
+    register(registration) {
+        const path = normalizePath(registration.path);
+        if (path !== registration.definition.path) {
+            throw new Error(`runtime registration path does not match its manifest: ${path}`);
+        }
+        if (registration.kind !== registration.definition.kind) {
+            throw new Error(`runtime registration kind does not match its manifest: ${path}`);
+        }
+        if (registration.kind === "reducer") {
+            validateOfflinePolicy(registration.definition.offline, path);
+            if (registration.definition.optimistic !== undefined) {
+                validateOptimisticTransaction(registration.definition.optimistic, path);
+            }
+            if (registration.definition.interactive !== false && registration.definition.optimistic === undefined && !registration.definition.nonOptimisticReason?.trim()) {
+                throw new Error(`interactive reducer ${path} requires an optimistic transaction or nonOptimisticReason`);
+            }
+        }
+        if (registration.kind === "query" && (registration.definition.delivery ?? "oneShot") === "oneShot") {
+            if (!registration.definition.liveQueryPlan)
+                throw new Error(`one-shot query ${path} requires a structured live query plan`);
+            validateStructuredQueryPlan(registration.definition.liveQueryPlan, path);
+        }
+        if (registration.definition.delivery === "replica") {
+            if (!registration.definition.replica)
+                throw new Error(`replica query ${path} requires a replica definition`);
+            validateReplicaCollection(registration.definition.replica, path);
+        }
+        if (this.entries.has(path))
+            throw new Error(`duplicate runtime registration: ${path}`);
+        this.entries.set(path, freeze({ ...registration, path }));
+    }
+    has(path, kind) {
+        const registration = this.entries.get(normalizePath(path));
+        return registration !== undefined && (kind === undefined || registration.kind === kind);
+    }
+    registration(path) {
+        return this.entries.get(normalizePath(path));
+    }
+    registrations() {
+        return Object.freeze([...this.entries.values()].sort((a, b) => a.path.localeCompare(b.path)));
+    }
+    manifest() {
+        const functions = {};
+        for (const registration of this.registrations())
+            functions[registration.path] = registration.definition;
+        return freeze({
+            format: this.baseManifest.format,
+            name: this.baseManifest.name,
+            version: this.baseManifest.version,
+            language: this.baseManifest.language,
+            engine: this.baseManifest.engine,
+            schema: this.baseManifest.schema,
+            artifact: this.baseManifest.artifact,
+            crons: this.baseManifest.crons,
+            visibility: this.baseManifest.visibility,
+            functions: freeze(functions),
+        });
+    }
+    registrationPayload() {
+        return freeze({
+            format: "gonvex.module.runtime.v1",
+            manifest: this.manifest(),
+            registrations: freeze(this.registrations().map(({ path, kind, definition }) => ({ path, kind, definition }))),
+        });
+    }
+    serializeRegistrationPayload(space) {
+        return stableJsonStringify(this.registrationPayload(), space);
+    }
+    async query(path, context, args) {
+        return this.dispatch({ path, kind: "query", context, args });
+    }
+    async reducer(path, context, args) {
+        return this.dispatch({ path, kind: "reducer", context, args });
+    }
+    async action(path, context, args) {
+        return this.dispatch({ path, kind: "action", context, args });
+    }
+    async dispatch(invocation) {
+        const path = normalizePath(invocation.path);
+        const registration = this.entries.get(path);
+        if (!registration)
+            throw new Error(`unknown module function: ${path}`);
+        if (registration.kind !== invocation.kind) {
+            throw new Error(`module function ${path} is ${registration.kind}, not ${invocation.kind}`);
+        }
+        if (!registration.handler) {
+            throw new Error(`module function ${path} has no executable handler`);
+        }
+        switch (invocation.kind) {
+            case "query":
+                return registration.handler(invocation.context, invocation.args);
+            case "reducer":
+                return registration.handler(invocation.context, invocation.args);
+            case "action":
+                return registration.handler(invocation.context, invocation.args);
+        }
+    }
+}
+export function createModule(metadata) {
+    return new ModuleBuilder(metadata);
+}
+//# sourceMappingURL=index.js.map