@spacefast/common 0.2.1 → 0.4.1

package/dist/contracts/{content-program.js → content-model.js}

@@ -1,14 +1,23 @@
 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
+import { grantCapabilitySchema } from "./grants-core.js";
+import { ZERO_PLATFORM_ABILITIES } from "./zero-platform-abilities.generated.js";
+export const CONTENT_MODEL_FORMAT = "spacefast.zero-wordpress";
+export const CONTENT_MODEL_VERSION = 1;
+export const contentModelSha256Schema = executionSha256Schema.brand();
+/**
+ * The one spelling of a content model identifier.
+ *
+ * Exported because every "author → content model" compiler needs to normalize
+ * someone else's identifiers against it, and a hand-copied regex that drifts
+ * from this one produces ids the release then refuses.
+ */
+export const contentStableIdSchema = z
     .string()
     .min(1)
     .max(160)
     .regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/);
+const stableIdSchema = contentStableIdSchema;
 export const contentResourceIdSchema = stableIdSchema.brand();
 export const contentFieldIdSchema = stableIdSchema.brand();
 export const contentTableIdSchema = stableIdSchema.brand();
@@ -16,6 +25,42 @@ export const contentAbilityIdSchema = stableIdSchema.brand();
 export const contentSchemaIdSchema = stableIdSchema.brand();
 export const contentComponentIdSchema = stableIdSchema.brand();
 export const contentSyncBindingIdSchema = stableIdSchema.brand();
+/**
+ * The name WordPress publishes an Ability under, derived from its content model id.
+ *
+ * Content model ids stay the vocabulary everywhere Spacefast addresses an Ability —
+ * routes, SDK descriptors, executables, decisions, receipts, invalidations.
+ * WordPress is the exception: its Abilities registry admits
+ * `^[a-z0-9-]+/[a-z0-9-]+$`, one namespace and one slug, so a dotted id
+ * flattens onto a single Zero-branded slug and `content.projects.list` is
+ * published as `zero/content-projects-list`.
+ *
+ * `spacefast_content_model_ability_name` in runtime/engine/wordpress/content-model-kernel.php
+ * is the same derivation in PHP and the two must change together. Because
+ * flattening is many-to-one (`a.b` and `a_b` collide),
+ * `contentModelReleaseV1Schema` rejects a content model whose abilities would share
+ * a name.
+ */
+export function contentAbilityWordPressName(id) {
+    return `zero/${id.replaceAll(".", "-").replaceAll("_", "-")}`;
+}
+/**
+ * The TypeScript identifier the generated content model SDK gives an Ability.
+ *
+ * This flattening is coarser than `contentAbilityWordPressName`: it drops every
+ * `.`/`_`/`-` separator and PascalCases the parts, so two ids that keep distinct
+ * WordPress names can still land on the same identifier (`posts.v2` and
+ * `posts.v.2` both become `PostsV2`, because a digit-led part has no letter to
+ * capitalize). `contentModelReleaseV1Schema` rejects that collision so the
+ * generated module never emits a duplicate `export type`.
+ */
+export function contentAbilityTypeName(id) {
+    return id
+        .split(/[^a-z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join("");
+}
 export const contentSyncSourcePathSchema = z
     .string()
     .min(1)
@@ -27,7 +72,7 @@ export const contentSyncSourcePathSchema = z
     }), "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 contentModelJsonValueSchema = z.json();
 export const contentResourceRefSchema = z
     .string()
     .regex(/^(?:content|table)\.[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/)
@@ -35,14 +80,14 @@ export const contentResourceRefSchema = z
 export const contentSchemaRefSchema = z
     .object({
     id: contentSchemaIdSchema,
-    sha256: contentProgramSha256Schema,
+    sha256: contentModelSha256Schema,
 })
     .strict();
 export const contentSchemaDefinitionSchema = z
     .object({
     id: contentSchemaIdSchema,
-    sha256: contentProgramSha256Schema,
-    schema: contentProgramJsonValueSchema,
+    sha256: contentModelSha256Schema,
+    schema: contentModelJsonValueSchema,
 })
     .strict();
 const fieldValueSchema = z.discriminatedUnion("kind", [
@@ -78,7 +123,7 @@ const fieldValueSchema = z.discriminatedUnion("kind", [
     })
         .strict(),
 ]);
-export const contentProgramFieldSchema = z
+export const contentModelFieldSchema = z
     .object({
     id: contentFieldIdSchema,
     name: stableIdSchema,
@@ -93,13 +138,13 @@ export const wordpressContentResourceSchema = z
     name: stableIdSchema,
     label: z.string().trim().min(1).max(160),
     kind: z.enum(["posts", "pages", "media", "collection"]),
-    fields: z.array(contentProgramFieldSchema).max(100),
+    fields: z.array(contentModelFieldSchema).max(100),
     publicRead: z.boolean(),
 })
     .strict();
-export const wordpressProgramIrV1Schema = z
+export const wordpressContentModelIrV1Schema = z
     .object({
-    format: z.literal("spacefast.wordpress-program"),
+    format: z.literal("spacefast.wordpress-content-model"),
     version: z.literal(1),
     resources: z.array(wordpressContentResourceSchema).min(3).max(53),
 })
@@ -134,7 +179,7 @@ export const wordpressProgramIrV1Schema = z
             context.addIssue({
                 code: "custom",
                 path: ["resources"],
-                message: `WordPress programs require exactly one native ${required} resource`,
+                message: `WordPress content models require exactly one native ${required} resource`,
             });
         }
         const native = wordpress.resources.find((resource) => resource.kind === required);
@@ -248,9 +293,9 @@ export const contentCacheProfileV1Schema = z.discriminatedUnion("kind", [
     })
         .strict(),
 ]);
-const abilityRoutePathSchema = appRoutePathSchema({ subject: "Content program routes" });
+const abilityRoutePathSchema = appRoutePathSchema({ subject: "Content model routes" });
 export const contentAbilityRouteAdmissionV1Schema = z.enum(["authenticated", "public"]);
-export const contentProgramRouteSchema = z
+export const contentModelRouteSchema = z
     .object({
     id: stableIdSchema,
     method: httpMethodSchema,
@@ -264,7 +309,7 @@ const contentAbilityExposureSchema = z.discriminatedUnion("kind", [
         .object({
         kind: z.literal("routed"),
         named: z.literal(true),
-        route: contentProgramRouteSchema,
+        route: contentModelRouteSchema,
     })
         .strict(),
 ]);
@@ -405,7 +450,7 @@ export const contentAbilityReceiptV1Schema = z.discriminatedUnion("status", [
         abilityId: contentAbilityIdSchema,
         callId: stableIdSchema,
         status: z.literal("succeeded"),
-        output: contentProgramJsonValueSchema,
+        output: contentModelJsonValueSchema,
         invalidates: z.array(contentAbilityIdSchema).max(500),
     })
         .strict(),
@@ -435,65 +480,219 @@ export const contentExecutableRefV1Schema = z
     .object({
     id: stableIdSchema,
     runtime: z.enum(["php", "quickjs"]),
-    artifact: contentProgramSha256Schema,
+    artifact: contentModelSha256Schema,
     export: z.string().min(1).max(256),
 })
     .strict();
+/**
+ * Which serializer stands between a source file and the blocks WordPress holds.
+ *
+ * The format is a property of the binding rather than of the request, because
+ * the file's extension decides it once at compile time and every later
+ * reconciliation has to agree. A caller cannot ask for the other serializer on
+ * a file this ContentModelRelease bound to one.
+ */
+export const CONTENT_SYNC_FORMATS = ["md", "html", "tsx"];
+export const contentSyncFormatSchema = z.enum(CONTENT_SYNC_FORMATS);
+/**
+ * Formats that compile one way. No serializer reads them back out of blocks, so
+ * their bindings carry the digest of the markup they produced and drift is
+ * settled by recompiling and comparing rather than by merging.
+ */
+export const CONTENT_SYNC_COMPILE_FORMATS = new Set(["tsx"]);
+export function contentSyncFormatIsCompiled(format) {
+    return CONTENT_SYNC_COMPILE_FORMATS.has(format);
+}
+/** The source extension each serializer owns. */
+export const CONTENT_SYNC_FORMAT_EXTENSIONS = new Map([
+    [".md", "md"],
+    [".markdown", "md"],
+    [".html", "html"],
+    [".htm", "html"],
+    [".tsx", "tsx"],
+]);
+/** The binding format a source path implies, or `null` when no serializer claims it. */
+export function contentSyncFormatForSource(source) {
+    const dot = source.lastIndexOf(".");
+    if (dot === -1)
+        return null;
+    return CONTENT_SYNC_FORMAT_EXTENSIONS.get(source.slice(dot).toLowerCase()) ?? null;
+}
 export const contentSyncBindingV1Schema = z
     .object({
     id: contentSyncBindingIdSchema,
     resourceId: contentResourceIdSchema,
     fieldId: contentFieldIdSchema,
     source: contentSyncSourcePathSchema,
+    publicPath: abilityRoutePathSchema.optional(),
+    // Optional for backward compatibility: a ContentModelRelease compiled before
+    // the HTML interchange format carried no `format`. The value is fully
+    // derivable from the source extension (the check below enforces they agree
+    // when both are present), so a stored binding without one is filled from the
+    // source rather than rejected — otherwise re-parsing a pre-format release
+    // would throw on live read paths (e.g. versionDeclaredContentModel).
+    format: contentSyncFormatSchema.optional(),
+    // The digest of the block markup this source compiled to. Deterministic —
+    // same source, same compiler, same digest — which is why it may live in a
+    // content-addressed release, and why a later read can compare it against
+    // what WordPress holds to see whether the two have parted ways.
+    compiled: z.object({ sha256: contentModelSha256Schema }).strict().optional(),
+    documentSeed: z
+        .object({ text: z.string().max(1_000_000), sha256: contentModelSha256Schema })
+        .strict()
+        .optional(),
     slug: z.string().trim().min(1).max(200),
+})
+    .strict()
+    .superRefine((binding, context) => {
+    const derived = contentSyncFormatForSource(binding.source);
+    if (binding.format === undefined) {
+        if (derived === null) {
+            context.addIssue({
+                code: "custom",
+                path: ["format"],
+                message: "sync binding source extension has no known format",
+            });
+            return;
+        }
+    }
+    else if (derived !== binding.format) {
+        context.addIssue({
+            code: "custom",
+            path: ["format"],
+            message: "sync binding format must match its source file extension",
+        });
+    }
+    const format = binding.format ?? derived;
+    if (format === null)
+        return;
+    if (contentSyncFormatIsCompiled(format)) {
+        if (binding.compiled === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["compiled"],
+                message: "a one-way sync binding must carry the digest of its compiled markup",
+            });
+        }
+    }
+    else if (binding.compiled !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["compiled"],
+            message: "only one-way sync bindings carry a compiled digest",
+        });
+    }
+})
+    .transform((binding) => ({
+    ...binding,
+    // SAFETY: the superRefine above already rejected the only case where this
+    // could be null — an absent `format` whose source extension names no
+    // serializer — so by the time a value reaches the transform, an absent
+    // format means the source resolves.
+    format: binding.format ?? contentSyncFormatForSource(binding.source),
+}));
+/**
+ * Where a collection puts a document that WordPress created and no file backs
+ * yet. Deterministic — it restates the glob the capsule declared — so it may
+ * live in a content-addressed release.
+ */
+export const contentSyncMaterializationV1Schema = z
+    .object({
+    resourceId: contentResourceIdSchema,
+    fieldId: contentFieldIdSchema,
+    /** Capsule-relative directory, no trailing slash. */
+    directory: z.string().trim().min(1).max(512),
+    /** The filename suffix the glob named, e.g. ".md". */
+    suffix: z.string().trim().min(2).max(16),
+    format: contentSyncFormatSchema,
 })
     .strict();
-export const contentProgramReleaseV1Schema = z
+export const contentModelReleaseV1Schema = z
     .object({
-    format: z.literal(CONTENT_PROGRAM_FORMAT),
-    version: z.literal(CONTENT_PROGRAM_VERSION),
-    revision: contentProgramSha256Schema,
+    format: z.literal(CONTENT_MODEL_FORMAT),
+    version: z.literal(CONTENT_MODEL_VERSION),
+    revision: contentModelSha256Schema,
     schemas: z.array(contentSchemaDefinitionSchema).min(1).max(500),
-    wordpress: wordpressProgramIrV1Schema,
+    wordpress: wordpressContentModelIrV1Schema,
     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),
+    // A release published before materializations existed carries no such key.
+    // The strict schema is re-parsed against stored release JSON on live read
+    // paths (versionDeclaredContentModel), so this must default rather than be
+    // required — the PHP runtime already treats a missing key as "nothing
+    // materializes here".
+    materializations: z.array(contentSyncMaterializationV1Schema).max(100).default([]),
 })
     .strict()
-    .superRefine((program, context) => {
-    const schemas = new Map(program.schemas.map((schema) => [schema.id, schema.sha256]));
-    if (schemas.size !== program.schemas.length) {
+    .superRefine((contentModel, context) => {
+    const schemas = new Map(contentModel.schemas.map((schema) => [schema.id, schema.sha256]));
+    if (schemas.size !== contentModel.schemas.length) {
         context.addIssue({
             code: "custom",
             path: ["schemas"],
-            message: "program schema ids must be unique",
+            message: "content model 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 resources = new Map(contentModel.wordpress.resources.map((resource) => [resource.id, resource]));
+    const tables = new Set(contentModel.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),
+        ...contentModel.wordpress.resources.map((resource) => resource.id),
+        ...contentModel.tables.map((table) => table.id),
+        ...contentModel.abilities.map((ability) => ability.id),
+        ...contentModel.pages.map((page) => page.id),
+        ...contentModel.hooks.map((hook) => hook.id),
+        ...contentModel.syncBindings.map((binding) => binding.id),
     ];
     if (new Set(ids).size !== ids.length) {
-        context.addIssue({ code: "custom", message: "stable program ids must be globally unique" });
+        context.addIssue({
+            code: "custom",
+            message: "stable content model ids must be globally unique",
+        });
+    }
+    const abilityNames = contentModel.abilities.map(({ id }) => contentAbilityWordPressName(id));
+    if (new Set(abilityNames).size !== abilityNames.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["abilities"],
+            message: "ability WordPress names must be unique",
+        });
+    }
+    // A content Ability that flattens onto a platform Ability's WordPress name
+    // is a second row under one name: the runtime engine already publishes that
+    // set (`zero-wp-users`, `zero-storage`), and the merged catalog would carry
+    // two rows the consumer keys by the same id. Reject it here so the collision
+    // never reaches `zeroAbilityCatalog` or the types `sf zero types` generates.
+    const platformAbilityNames = new Set(ZERO_PLATFORM_ABILITIES.map((ability) => ability.name));
+    for (const [index, ability] of contentModel.abilities.entries()) {
+        if (platformAbilityNames.has(contentAbilityWordPressName(ability.id))) {
+            context.addIssue({
+                code: "custom",
+                path: ["abilities", index, "id"],
+                message: `ability ${ability.id} collides with a platform Ability the engine already publishes`,
+            });
+        }
+    }
+    const abilityTypeNames = contentModel.abilities.map(({ id }) => contentAbilityTypeName(id));
+    if (new Set(abilityTypeNames).size !== abilityTypeNames.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["abilities"],
+            message: "ability SDK type names must be 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`,
+                message: `schema reference ${ref.id} does not match a content model schema`,
             });
         }
     };
-    for (const [index, ability] of program.abilities.entries()) {
+    for (const [index, ability] of contentModel.abilities.entries()) {
         verifySchemaRef(ability.input, ["abilities", index, "input"]);
         verifySchemaRef(ability.output, ["abilities", index, "output"]);
         for (const [resourceIndex, resource] of [...ability.reads, ...ability.writes].entries()) {
@@ -523,10 +722,10 @@ export const contentProgramReleaseV1Schema = z
             }
         }
     }
-    for (const [index, page] of program.pages.entries()) {
+    for (const [index, page] of contentModel.pages.entries()) {
         verifySchemaRef(page.props, ["pages", index, "props"]);
     }
-    for (const [index, binding] of program.syncBindings.entries()) {
+    for (const [index, binding] of contentModel.syncBindings.entries()) {
         const resource = resources.get(binding.resourceId);
         const field = resource?.fields.find((candidate) => candidate.id === binding.fieldId);
         if (!field) {
@@ -540,50 +739,79 @@ export const contentProgramReleaseV1Schema = z
             context.addIssue({
                 code: "custom",
                 path: ["syncBindings", index, "fieldId"],
-                message: "Markdown sync bindings require a block field",
+                message: "source sync bindings require a block field",
+            });
+        }
+    }
+    // One field materializes into one directory. A second answer to "where does
+    // a document WordPress just created belong" is the same class of mistake as
+    // two globs binding one field, and the runtime would have to guess.
+    const materialized = new Set();
+    for (const [index, materialization] of contentModel.materializations.entries()) {
+        const target = `${materialization.resourceId}${materialization.fieldId}`;
+        if (materialized.has(target)) {
+            context.addIssue({
+                code: "custom",
+                path: ["materializations", index],
+                message: `duplicate content materialization for ${materialization.resourceId}.${materialization.fieldId}`,
             });
         }
+        materialized.add(target);
     }
 });
-export const CONTENT_PROGRAM_ARTIFACT_FORMATS = {
-    program: CONTENT_PROGRAM_FORMAT,
+export const contentModelStageReceiptV1Schema = z
+    .object({
+    revision: contentModelSha256Schema,
+    artifactDigest: contentModelSha256Schema,
+    staged: z.boolean(),
+})
+    .strict();
+export const contentModelActivationReceiptV1Schema = z
+    .object({
+    revision: contentModelSha256Schema.nullable(),
+    tables: z.number().int().nonnegative(),
+    pages: z.number().int().nonnegative(),
+})
+    .strict();
+export const CONTENT_MODEL_ARTIFACT_FORMATS = {
+    model: CONTENT_MODEL_FORMAT,
     executables: "spacefast.zero-executables",
     sdk: "spacefast.sdk-descriptors",
     routes: "spacefast.route-contributions",
-    requirements: "spacefast.program-requirements",
+    requirements: "spacefast.content-model-requirements",
 };
-export function contentProgramArtifactRefSchema(format) {
+export function contentModelArtifactRefSchema(format) {
     return z
         .object({
         format: z.literal(format),
         version: z.literal(1),
-        inputDigest: contentProgramSha256Schema,
-        sha256: contentProgramSha256Schema,
+        inputDigest: contentModelSha256Schema,
+        sha256: contentModelSha256Schema,
         bytes: z.number().int().nonnegative(),
         mediaType: z.literal("application/json"),
     })
         .strict();
 }
-export const compiledContentProgramV1Schema = z
+export const compiledContentModelV1Schema = z
     .object({
-    format: z.literal("spacefast.compiled-program"),
+    format: z.literal("spacefast.compiled-content-model"),
     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),
+    model: contentModelArtifactRefSchema(CONTENT_MODEL_ARTIFACT_FORMATS.model),
+    executables: contentModelArtifactRefSchema(CONTENT_MODEL_ARTIFACT_FORMATS.executables),
+    sdk: contentModelArtifactRefSchema(CONTENT_MODEL_ARTIFACT_FORMATS.sdk),
+    routes: contentModelArtifactRefSchema(CONTENT_MODEL_ARTIFACT_FORMATS.routes),
+    requirements: contentModelArtifactRefSchema(CONTENT_MODEL_ARTIFACT_FORMATS.requirements),
 })
     .strict();
 export const contentExecutableSetV1Schema = z
     .object({
-    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.executables),
+    format: z.literal(CONTENT_MODEL_ARTIFACT_FORMATS.executables),
     version: z.literal(1),
-    inputDigest: contentProgramSha256Schema,
+    inputDigest: contentModelSha256Schema,
     executables: z.array(contentExecutableRefV1Schema).max(500),
 })
     .strict();
-const contentSdkOperationDescriptorV1Schema = z
+export const contentSdkOperationDescriptorV1Schema = z
     .discriminatedUnion("kind", [
     z
         .object({
@@ -630,9 +858,9 @@ const contentSdkOperationDescriptorV1Schema = z
 });
 export const contentSdkDescriptorSetV1Schema = z
     .object({
-    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.sdk),
+    format: z.literal(CONTENT_MODEL_ARTIFACT_FORMATS.sdk),
     version: z.literal(1),
-    inputDigest: contentProgramSha256Schema,
+    inputDigest: contentModelSha256Schema,
     operations: z.array(contentSdkOperationDescriptorV1Schema),
     sync: z.array(z
         .object({
@@ -645,13 +873,13 @@ export const contentSdkDescriptorSetV1Schema = z
     .strict();
 export const contentRouteContributionSetV1Schema = z
     .object({
-    format: z.literal(CONTENT_PROGRAM_ARTIFACT_FORMATS.routes),
+    format: z.literal(CONTENT_MODEL_ARTIFACT_FORMATS.routes),
     version: z.literal(1),
-    inputDigest: contentProgramSha256Schema,
+    inputDigest: contentModelSha256Schema,
     routes: z.array(z
         .object({
         abilityId: contentAbilityIdSchema,
-        route: contentProgramRouteSchema,
+        route: contentModelRouteSchema,
     })
         .strict()),
 })