@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/content-program.js

@@ -0,0 +1,658 @@
+import { z } from "zod";
+import { appRoutePathSchema, executionSha256Schema, httpMethodSchema } from "./execution.js";
+import { grantCapabilitySchema } from "./grants.js";
+export const CONTENT_PROGRAM_FORMAT = "spacefast.zero-wordpress";
+export const CONTENT_PROGRAM_VERSION = 1;
+export const contentProgramSha256Schema = executionSha256Schema.brand();
+const stableIdSchema = z
+    .string()
+    .min(1)
+    .max(160)
+    .regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/);
+export const contentResourceIdSchema = stableIdSchema.brand();
+export const contentFieldIdSchema = stableIdSchema.brand();
+export const contentTableIdSchema = stableIdSchema.brand();
+export const contentAbilityIdSchema = stableIdSchema.brand();
+export const contentSchemaIdSchema = stableIdSchema.brand();
+export const contentComponentIdSchema = stableIdSchema.brand();
+export const contentSyncBindingIdSchema = stableIdSchema.brand();
+export const contentSyncSourcePathSchema = z
+    .string()
+    .min(1)
+    .max(1_000)
+    .refine((source) => !source.includes("\\") &&
+    Array.from(source).every((character) => {
+        const codePoint = character.codePointAt(0);
+        return codePoint !== undefined && codePoint >= 32 && codePoint !== 127;
+    }), "source paths cannot contain controls or backslashes")
+    .refine((source) => !source.startsWith("/") &&
+    source.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".."), "source paths must be normalized relative paths without traversal");
+export const contentProgramJsonValueSchema = z.json();
+export const contentResourceRefSchema = z
+    .string()
+    .regex(/^(?:content|table)\.[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/)
+    .brand();
+export const contentSchemaRefSchema = z
+    .object({
+    id: contentSchemaIdSchema,
+    sha256: contentProgramSha256Schema,
+})
+    .strict();
+export const contentSchemaDefinitionSchema = z
+    .object({
+    id: contentSchemaIdSchema,
+    sha256: contentProgramSha256Schema,
+    schema: contentProgramJsonValueSchema,
+})
+    .strict();
+const fieldValueSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("text"),
+        multiline: z.boolean(),
+        maxLength: z.number().int().positive().nullable(),
+    })
+        .strict(),
+    z.object({ kind: z.literal("number") }).strict(),
+    z.object({ kind: z.literal("boolean") }).strict(),
+    z.object({ kind: z.literal("datetime") }).strict(),
+    z
+        .object({
+        kind: z.literal("blocks"),
+        allowed: z.union([z.literal("any"), z.array(contentComponentIdSchema).max(100)]),
+    })
+        .strict(),
+    z.object({ kind: z.literal("media"), multiple: z.boolean() }).strict(),
+    z
+        .object({
+        kind: z.literal("reference"),
+        target: contentResourceIdSchema,
+        multiple: z.boolean(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("enum"),
+        values: z.array(z.string().min(1).max(160)).min(1).max(100),
+        multiple: z.boolean(),
+    })
+        .strict(),
+]);
+export const contentProgramFieldSchema = z
+    .object({
+    id: contentFieldIdSchema,
+    name: stableIdSchema,
+    label: z.string().trim().min(1).max(160),
+    required: z.boolean(),
+    value: fieldValueSchema,
+})
+    .strict();
+export const wordpressContentResourceSchema = z
+    .object({
+    id: contentResourceIdSchema,
+    name: stableIdSchema,
+    label: z.string().trim().min(1).max(160),
+    kind: z.enum(["posts", "pages", "media", "collection"]),
+    fields: z.array(contentProgramFieldSchema).max(100),
+    publicRead: z.boolean(),
+})
+    .strict();
+export const wordpressProgramIrV1Schema = z
+    .object({
+    format: z.literal("spacefast.wordpress-program"),
+    version: z.literal(1),
+    resources: z.array(wordpressContentResourceSchema).min(3).max(53),
+})
+    .strict()
+    .superRefine((wordpress, context) => {
+    const ids = new Set();
+    const kinds = new Map();
+    for (const [resourceIndex, resource] of wordpress.resources.entries()) {
+        if (ids.has(resource.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["resources", resourceIndex, "id"],
+                message: `duplicate content resource id ${resource.id}`,
+            });
+        }
+        ids.add(resource.id);
+        kinds.set(resource.kind, (kinds.get(resource.kind) ?? 0) + 1);
+        const fieldIds = new Set();
+        for (const [fieldIndex, field] of resource.fields.entries()) {
+            if (fieldIds.has(field.id)) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["resources", resourceIndex, "fields", fieldIndex, "id"],
+                    message: `duplicate field id ${field.id}`,
+                });
+            }
+            fieldIds.add(field.id);
+        }
+    }
+    for (const required of ["posts", "pages", "media"]) {
+        if (kinds.get(required) !== 1) {
+            context.addIssue({
+                code: "custom",
+                path: ["resources"],
+                message: `WordPress programs require exactly one native ${required} resource`,
+            });
+        }
+        const native = wordpress.resources.find((resource) => resource.kind === required);
+        if (native && (native.id !== required || native.name !== required)) {
+            context.addIssue({
+                code: "custom",
+                path: ["resources"],
+                message: `the native ${required} resource must keep id and name ${required}`,
+            });
+        }
+    }
+    for (const [resourceIndex, resource] of wordpress.resources.entries()) {
+        for (const [fieldIndex, field] of resource.fields.entries()) {
+            if (field.value.kind === "reference" && !ids.has(field.value.target)) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["resources", resourceIndex, "fields", fieldIndex, "value", "target"],
+                    message: `unknown content resource ${field.value.target}`,
+                });
+            }
+        }
+    }
+});
+const tableColumnValueSchema = z.discriminatedUnion("kind", [
+    z
+        .object({ kind: z.literal("string"), maxLength: z.number().int().positive().nullable() })
+        .strict(),
+    z.object({ kind: z.literal("number") }).strict(),
+    z.object({ kind: z.literal("boolean") }).strict(),
+    z.object({ kind: z.literal("datetime") }).strict(),
+    z.object({ kind: z.literal("json") }).strict(),
+]);
+export const contentTableColumnSchema = z
+    .object({
+    id: contentFieldIdSchema,
+    name: stableIdSchema,
+    nullable: z.boolean(),
+    value: tableColumnValueSchema,
+})
+    .strict();
+export const contentTableIrV1Schema = z
+    .object({
+    id: contentTableIdSchema,
+    name: stableIdSchema,
+    columns: z.array(contentTableColumnSchema).max(100),
+    indexes: z
+        .array(z
+        .object({
+        id: stableIdSchema,
+        fields: z.array(contentFieldIdSchema).min(1).max(16),
+        unique: z.boolean(),
+    })
+        .strict())
+        .max(32),
+})
+    .strict()
+    .superRefine((table, context) => {
+    const fieldIds = new Set(table.columns.map((column) => column.id));
+    const fieldNames = new Set();
+    for (const [columnPosition, column] of table.columns.entries()) {
+        if (fieldNames.has(column.name)) {
+            context.addIssue({
+                code: "custom",
+                path: ["columns", columnPosition, "name"],
+                message: `duplicate table column name ${column.name}`,
+            });
+        }
+        fieldNames.add(column.name);
+    }
+    if (fieldIds.size !== table.columns.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["columns"],
+            message: "table column ids must be unique",
+        });
+    }
+    const indexIds = new Set();
+    for (const [indexPosition, index] of table.indexes.entries()) {
+        if (indexIds.has(index.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["indexes", indexPosition, "id"],
+                message: `duplicate table index id ${index.id}`,
+            });
+        }
+        indexIds.add(index.id);
+        for (const [fieldPosition, field] of index.fields.entries()) {
+            if (!fieldIds.has(field)) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["indexes", indexPosition, "fields", fieldPosition],
+                    message: `table index references unknown field ${field}`,
+                });
+            }
+        }
+    }
+});
+export const contentCacheProfileV1Schema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("none") }).strict(),
+    z
+        .object({
+        kind: z.literal("private"),
+        maxAgeSeconds: z.number().int().nonnegative().max(86_400),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("public"),
+        maxAgeSeconds: z.number().int().nonnegative().max(86_400),
+        staleWhileRevalidateSeconds: z.number().int().nonnegative().max(604_800),
+    })
+        .strict(),
+]);
+const abilityRoutePathSchema = appRoutePathSchema({ subject: "Content program routes" });
+export const contentAbilityRouteAdmissionV1Schema = z.enum(["authenticated", "public"]);
+export const contentProgramRouteSchema = z
+    .object({
+    id: stableIdSchema,
+    method: httpMethodSchema,
+    path: abilityRoutePathSchema,
+    admission: contentAbilityRouteAdmissionV1Schema,
+})
+    .strict();
+const contentAbilityExposureSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("named"), named: z.literal(true) }).strict(),
+    z
+        .object({
+        kind: z.literal("routed"),
+        named: z.literal(true),
+        route: contentProgramRouteSchema,
+    })
+        .strict(),
+]);
+const abilityDescriptorFields = {
+    id: contentAbilityIdSchema,
+    input: contentSchemaRefSchema,
+    output: contentSchemaRefSchema,
+    permits: z.array(grantCapabilitySchema).max(5),
+    reads: z.array(contentResourceRefSchema).max(100),
+    writes: z.array(contentResourceRefSchema).max(100),
+    exposure: contentAbilityExposureSchema,
+    cache: contentCacheProfileV1Schema,
+};
+export const contentAbilityDescriptorV1Schema = z
+    .discriminatedUnion("kind", [
+    z
+        .object({ ...abilityDescriptorFields, kind: z.literal("query"), mode: z.literal("read") })
+        .strict(),
+    z
+        .object({ ...abilityDescriptorFields, kind: z.literal("mutation"), mode: z.literal("write") })
+        .strict(),
+    z
+        .object({
+        ...abilityDescriptorFields,
+        kind: z.literal("endpoint"),
+        mode: z.enum(["read", "write"]),
+    })
+        .strict(),
+])
+    .superRefine((ability, context) => {
+    if (new Set(ability.permits).size !== ability.permits.length) {
+        context.addIssue({ code: "custom", path: ["permits"], message: "permits must be unique" });
+    }
+    if (new Set(ability.reads).size !== ability.reads.length) {
+        context.addIssue({ code: "custom", path: ["reads"], message: "reads must be unique" });
+    }
+    if (new Set(ability.writes).size !== ability.writes.length) {
+        context.addIssue({ code: "custom", path: ["writes"], message: "writes must be unique" });
+    }
+    if (ability.mode === "read" && ability.writes.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["writes"],
+            message: "read abilities cannot declare writes",
+        });
+    }
+    if (ability.mode === "write" && ability.cache.kind !== "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["cache"],
+            message: "write abilities cannot be cached",
+        });
+    }
+    if (ability.cache.kind === "public" && ability.permits.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["cache"],
+            message: "public caches cannot vary on a caller capability",
+        });
+    }
+    if (ability.cache.kind === "public" &&
+        ability.exposure.kind === "routed" &&
+        ability.exposure.route.admission === "authenticated") {
+        context.addIssue({
+            code: "custom",
+            path: ["cache"],
+            message: "authenticated routes cannot use a public cache",
+        });
+    }
+    if (ability.exposure.kind === "routed" &&
+        ability.exposure.route.admission === "public" &&
+        ability.permits.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["exposure", "route", "admission"],
+            message: "public route admission cannot require a caller capability",
+        });
+    }
+    if (ability.kind !== "endpoint" && ability.exposure.kind === "routed") {
+        context.addIssue({
+            code: "custom",
+            path: ["exposure"],
+            message: "only endpoints can expose an HTTP route",
+        });
+    }
+    const writableStores = new Set(ability.writes.map((resource) => resource.split(".", 1)[0]));
+    if (writableStores.size > 1) {
+        context.addIssue({
+            code: "custom",
+            path: ["writes"],
+            message: "an ability can write either WordPress content or Lakebed tables, not both",
+        });
+    }
+});
+export const contentAbilityDenialV1Schema = z.discriminatedUnion("reason", [
+    z
+        .object({
+        reason: z.literal("capability-missing"),
+        missing: z.array(grantCapabilitySchema).min(1).max(5),
+    })
+        .strict(),
+    z.object({ reason: z.literal("resource-denied"), resource: contentResourceRefSchema }).strict(),
+    z.object({ reason: z.literal("target-mismatch") }).strict(),
+    z
+        .object({
+        reason: z.literal("business-rule-denied"),
+        code: stableIdSchema,
+        detail: z.string().min(1).max(2_000),
+    })
+        .strict(),
+]);
+export const contentAbilityDecisionV1Schema = z.discriminatedUnion("decision", [
+    z
+        .object({
+        format: z.literal("spacefast.ability-decision"),
+        version: z.literal(1),
+        abilityId: contentAbilityIdSchema,
+        callId: stableIdSchema,
+        decision: z.literal("allowed"),
+    })
+        .strict(),
+    z
+        .object({
+        format: z.literal("spacefast.ability-decision"),
+        version: z.literal(1),
+        abilityId: contentAbilityIdSchema,
+        callId: stableIdSchema,
+        decision: z.literal("denied"),
+        denial: contentAbilityDenialV1Schema,
+    })
+        .strict(),
+]);
+export const contentAbilityReceiptV1Schema = z.discriminatedUnion("status", [
+    z
+        .object({
+        format: z.literal("spacefast.ability-receipt"),
+        version: z.literal(1),
+        abilityId: contentAbilityIdSchema,
+        callId: stableIdSchema,
+        status: z.literal("succeeded"),
+        output: contentProgramJsonValueSchema,
+        invalidates: z.array(contentAbilityIdSchema).max(500),
+    })
+        .strict(),
+    z
+        .object({
+        format: z.literal("spacefast.ability-receipt"),
+        version: z.literal(1),
+        abilityId: contentAbilityIdSchema,
+        callId: stableIdSchema,
+        status: z.literal("denied"),
+        denial: contentAbilityDenialV1Schema,
+    })
+        .strict(),
+]);
+export const contentClientPageIrV1Schema = z
+    .object({
+    id: stableIdSchema,
+    sourceKey: z.string().min(1).max(512),
+    path: abilityRoutePathSchema,
+    title: z.string().trim().min(1).max(500),
+    blockName: z.literal("zero/component"),
+    componentId: contentComponentIdSchema,
+    props: contentSchemaRefSchema,
+})
+    .strict();
+export const contentExecutableRefV1Schema = z
+    .object({
+    id: stableIdSchema,
+    runtime: z.enum(["php", "quickjs"]),
+    artifact: contentProgramSha256Schema,
+    export: z.string().min(1).max(256),
+})
+    .strict();
+export const contentSyncBindingV1Schema = z
+    .object({
+    id: contentSyncBindingIdSchema,
+    resourceId: contentResourceIdSchema,
+    fieldId: contentFieldIdSchema,
+    source: contentSyncSourcePathSchema,
+    slug: z.string().trim().min(1).max(200),
+})
+    .strict();
+export const contentProgramReleaseV1Schema = z
+    .object({
+    format: z.literal(CONTENT_PROGRAM_FORMAT),
+    version: z.literal(CONTENT_PROGRAM_VERSION),
+    revision: contentProgramSha256Schema,
+    schemas: z.array(contentSchemaDefinitionSchema).min(1).max(500),
+    wordpress: wordpressProgramIrV1Schema,
+    tables: z.array(contentTableIrV1Schema).max(100),
+    abilities: z.array(contentAbilityDescriptorV1Schema).max(500),
+    pages: z.array(contentClientPageIrV1Schema).max(10_000),
+    hooks: z.array(contentExecutableRefV1Schema).max(500),
+    syncBindings: z.array(contentSyncBindingV1Schema).max(10_000),
+})
+    .strict()
+    .superRefine((program, context) => {
+    const schemas = new Map(program.schemas.map((schema) => [schema.id, schema.sha256]));
+    if (schemas.size !== program.schemas.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["schemas"],
+            message: "program schema ids must be unique",
+        });
+    }
+    const resources = new Map(program.wordpress.resources.map((resource) => [resource.id, resource]));
+    const tables = new Set(program.tables.map((table) => table.id));
+    const ids = [
+        ...program.wordpress.resources.map((resource) => resource.id),
+        ...program.tables.map((table) => table.id),
+        ...program.abilities.map((ability) => ability.id),
+        ...program.pages.map((page) => page.id),
+        ...program.hooks.map((hook) => hook.id),
+        ...program.syncBindings.map((binding) => binding.id),
+    ];
+    if (new Set(ids).size !== ids.length) {
+        context.addIssue({ code: "custom", message: "stable program ids must be globally unique" });
+    }
+    const verifySchemaRef = (ref, path) => {
+        if (schemas.get(ref.id) !== ref.sha256) {
+            context.addIssue({
+                code: "custom",
+                path,
+                message: `schema reference ${ref.id} does not match a program schema`,
+            });
+        }
+    };
+    for (const [index, ability] of program.abilities.entries()) {
+        verifySchemaRef(ability.input, ["abilities", index, "input"]);
+        verifySchemaRef(ability.output, ["abilities", index, "output"]);
+        for (const [resourceIndex, resource] of [...ability.reads, ...ability.writes].entries()) {
+            const separator = resource.indexOf(".");
+            const kind = resource.slice(0, separator);
+            const id = resource.slice(separator + 1);
+            if ((kind === "content" && !resources.has(id)) || (kind === "table" && !tables.has(id))) {
+                context.addIssue({
+                    code: "custom",
+                    path: ["abilities", index, "reads", resourceIndex],
+                    message: `ability references unknown resource ${resource}`,
+                });
+            }
+        }
+        if (ability.cache.kind === "public") {
+            for (const [resourceIndex, resource] of ability.reads.entries()) {
+                const separator = resource.indexOf(".");
+                const kind = resource.slice(0, separator);
+                const id = resource.slice(separator + 1);
+                if (kind !== "content" || resources.get(id)?.publicRead !== true) {
+                    context.addIssue({
+                        code: "custom",
+                        path: ["abilities", index, "reads", resourceIndex],
+                        message: "public caches can read only statically public content resources",
+                    });
+                }
+            }
+        }
+    }
+    for (const [index, page] of program.pages.entries()) {
+        verifySchemaRef(page.props, ["pages", index, "props"]);
+    }
+    for (const [index, binding] of program.syncBindings.entries()) {
+        const resource = resources.get(binding.resourceId);
+        const field = resource?.fields.find((candidate) => candidate.id === binding.fieldId);
+        if (!field) {
+            context.addIssue({
+                code: "custom",
+                path: ["syncBindings", index],
+                message: "sync binding must reference a field on its content resource",
+            });
+        }
+        else if (field.value.kind !== "blocks") {
+            context.addIssue({
+                code: "custom",
+                path: ["syncBindings", index, "fieldId"],
+                message: "Markdown sync bindings require a block field",
+            });
+        }
+    }
+});
+export const CONTENT_PROGRAM_ARTIFACT_FORMATS = {
+    program: CONTENT_PROGRAM_FORMAT,
+    executables: "spacefast.zero-executables",
+    sdk: "spacefast.sdk-descriptors",
+    routes: "spacefast.route-contributions",
+    requirements: "spacefast.program-requirements",
+};
+export function contentProgramArtifactRefSchema(format) {
+    return z
+        .object({
+        format: z.literal(format),
+        version: z.literal(1),
+        inputDigest: contentProgramSha256Schema,
+        sha256: contentProgramSha256Schema,
+        bytes: z.number().int().nonnegative(),
+        mediaType: z.literal("application/json"),
+    })
+        .strict();
+}
+export const compiledContentProgramV1Schema = z
+    .object({
+    format: z.literal("spacefast.compiled-program"),
+    version: z.literal(1),
+    program: contentProgramArtifactRefSchema(CONTENT_PROGRAM_ARTIFACT_FORMATS.program),
+    executables: contentProgramArtifactRefSchema(CONTENT_PROGRAM_ARTIFACT_FORMATS.executables),
+    sdk: contentProgramArtifactRefSchema(CONTENT_PROGRAM_ARTIFACT_FORMATS.sdk),
+    routes: contentProgramArtifactRefSchema(CONTENT_PROGRAM_ARTIFACT_FORMATS.routes),
+    requirements: contentProgramArtifactRefSchema(CONTENT_PROGRAM_ARTIFACT_FORMATS.requirements),
+})
+    .strict();
+export const contentExecutableSetV1Schema = z
+    .object({
+    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.executables),
+    version: z.literal(1),
+    inputDigest: contentProgramSha256Schema,
+    executables: z.array(contentExecutableRefV1Schema).max(500),
+})
+    .strict();
+const contentSdkOperationDescriptorV1Schema = z
+    .discriminatedUnion("kind", [
+    z
+        .object({
+        id: contentAbilityIdSchema,
+        kind: z.literal("query"),
+        mode: z.literal("read"),
+        input: contentSchemaRefSchema,
+        output: contentSchemaRefSchema,
+        cache: contentCacheProfileV1Schema,
+        invalidates: z.array(contentAbilityIdSchema),
+    })
+        .strict(),
+    z
+        .object({
+        id: contentAbilityIdSchema,
+        kind: z.literal("mutation"),
+        mode: z.literal("write"),
+        input: contentSchemaRefSchema,
+        output: contentSchemaRefSchema,
+        cache: z.object({ kind: z.literal("none") }).strict(),
+        invalidates: z.array(contentAbilityIdSchema),
+    })
+        .strict(),
+    z
+        .object({
+        id: contentAbilityIdSchema,
+        kind: z.literal("endpoint"),
+        mode: z.enum(["read", "write"]),
+        input: contentSchemaRefSchema,
+        output: contentSchemaRefSchema,
+        cache: contentCacheProfileV1Schema,
+        invalidates: z.array(contentAbilityIdSchema),
+    })
+        .strict(),
+])
+    .superRefine((operation, context) => {
+    if (operation.mode === "write" && operation.cache.kind !== "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["cache"],
+            message: "write SDK operations cannot be cached",
+        });
+    }
+});
+export const contentSdkDescriptorSetV1Schema = z
+    .object({
+    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.sdk),
+    version: z.literal(1),
+    inputDigest: contentProgramSha256Schema,
+    operations: z.array(contentSdkOperationDescriptorV1Schema),
+    sync: z.array(z
+        .object({
+        id: contentSyncBindingIdSchema,
+        resourceId: contentResourceIdSchema,
+        source: z.string().min(1).max(1_000),
+    })
+        .strict()),
+})
+    .strict();
+export const contentRouteContributionSetV1Schema = z
+    .object({
+    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.routes),
+    version: z.literal(1),
+    inputDigest: contentProgramSha256Schema,
+    routes: z.array(z
+        .object({
+        abilityId: contentAbilityIdSchema,
+        route: contentProgramRouteSchema,
+    })
+        .strict()),
+})
+    .strict();