@spacefast/common 0.0.26 → 0.2.2

package/dist/contracts/content.js

@@ -0,0 +1,303 @@
+import { z } from "zod";
+export const CONTENT_SCHEMA_FORMAT = "spacefast.content.schema";
+export const CONTENT_QUERY_FORMAT = "spacefast.content.query";
+export const CONTENT_SOURCE_FORMAT = "spacefast.content.source";
+export const CONTENT_RENDER_FORMAT = "spacefast.content.render";
+export const CONTENT_API_VERSION = 1;
+// The content model is authored as files in the Space and compiled at publish.
+// `content.config.ts` at the Space root is the entry module; sibling modules it
+// imports live under `content/`. Both are read out of the version being
+// published, so the compiled model is bound to that version and rolls back with
+// it. There is no API that mutates the content model out of band.
+export const CONTENT_CONFIG_FILE = "content.config.ts";
+export const CONTENT_CONFIG_DIRECTORY = "content/";
+export const CONTENT_CAPS = {
+    batchQueries: 25,
+    collections: 50,
+    fieldsPerCollection: 100,
+    filterClauses: 24,
+    pageSize: 100,
+    selectFields: 100,
+    sourceBytes: 2 * 1024 * 1024,
+    sourceFiles: 64,
+};
+const contentIdentifierSchema = z
+    .string()
+    .min(1)
+    .max(63)
+    .regex(/^[a-z][a-z0-9_-]*$/, "must start with a letter and contain lowercase letters, digits, _ or -");
+const contentFieldIdentifierSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "must start with a letter and contain letters, digits, _ or -");
+const contentSourcePathSchema = z
+    .string()
+    .min(1)
+    .max(240)
+    .regex(/^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*\.(?:[cm]?[jt]sx?)$/, "must be a relative JavaScript or TypeScript module path");
+export const contentSourceBundleSchema = z
+    .object({
+    format: z.literal(CONTENT_SOURCE_FORMAT),
+    version: z.literal(CONTENT_API_VERSION),
+    entry: contentSourcePathSchema.default(CONTENT_CONFIG_FILE),
+    files: z
+        .record(contentSourcePathSchema, z.string().max(CONTENT_CAPS.sourceBytes))
+        .refine((files) => Object.keys(files).length <= CONTENT_CAPS.sourceFiles, {
+        message: `must contain at most ${CONTENT_CAPS.sourceFiles} files`,
+    })
+        .refine((files) => Object.entries(files).reduce((bytes, [name, source]) => bytes +
+        new TextEncoder().encode(name).byteLength +
+        new TextEncoder().encode(source).byteLength, 0) <= CONTENT_CAPS.sourceBytes, { message: `must contain at most ${CONTENT_CAPS.sourceBytes} bytes` }),
+    phpOnly: z.boolean().default(false),
+})
+    .strict()
+    .refine((bundle) => Object.hasOwn(bundle.files, bundle.entry), {
+    message: "entry must name one of files",
+    path: ["entry"],
+});
+export const contentCompileResponseSchema = z
+    .object({
+    revision: z.string().regex(/^[a-f0-9]{64}$/),
+    schemaVersion: z.number().int().positive(),
+    collections: z.number().int().nonnegative(),
+    fields: z.number().int().nonnegative(),
+    hooks: z.number().int().nonnegative(),
+    quickJsHooks: z.number().int().nonnegative(),
+})
+    .strict();
+// Activation points the Space's WordPress at an already-compiled release. A null
+// revision is the honest answer for a version that shipped no content config:
+// activating it leaves the Space with no managed content model, so rolling back
+// to a version from before the model existed restores exactly that.
+export const contentReleaseActivateResponseSchema = z
+    .object({
+    revision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .nullable(),
+})
+    .strict();
+export const contentRenderInputSchema = z
+    .object({
+    format: z.literal(CONTENT_RENDER_FORMAT),
+    version: z.literal(CONTENT_API_VERSION),
+    collection: contentIdentifierSchema.default("posts"),
+    id: z.number().int().positive().optional(),
+    slug: z.string().trim().min(1).max(200).optional(),
+    field: contentFieldIdentifierSchema.default("content"),
+    output: z.enum(["blocks", "html"]).default("html"),
+})
+    .strict()
+    .refine((input) => (input.id === undefined) !== (input.slug === undefined), {
+    message: "set exactly one of id or slug",
+    path: ["id"],
+});
+export const contentRenderResponseSchema = z
+    .object({
+    id: z.number().int().positive(),
+    content: z.string(),
+    output: z.enum(["blocks", "html"]),
+})
+    .strict();
+const contentQueryKeySchema = z
+    .string()
+    .min(1)
+    .max(63)
+    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "must be a safe query key");
+const contentLabelSchema = z.string().trim().min(1).max(120);
+const contentFieldBaseSchema = z.object({
+    label: contentLabelSchema,
+    required: z.boolean().default(false),
+    description: z.string().trim().max(500).optional(),
+});
+export const contentFieldSchema = z.discriminatedUnion("type", [
+    contentFieldBaseSchema.extend({
+        type: z.literal("text"),
+        multiline: z.boolean().default(false),
+        maxLength: z.number().int().positive().max(100_000).optional(),
+    }),
+    contentFieldBaseSchema.extend({ type: z.literal("markdown") }),
+    contentFieldBaseSchema.extend({ type: z.literal("richText") }),
+    contentFieldBaseSchema.extend({ type: z.literal("number") }),
+    contentFieldBaseSchema.extend({ type: z.literal("boolean") }),
+    contentFieldBaseSchema.extend({ type: z.literal("date") }),
+    contentFieldBaseSchema.extend({
+        type: z.literal("media"),
+        multiple: z.boolean().default(false),
+    }),
+    contentFieldBaseSchema.extend({
+        type: z.literal("relation"),
+        collection: contentIdentifierSchema,
+        multiple: z.boolean().default(false),
+    }),
+    contentFieldBaseSchema.extend({
+        type: z.literal("select"),
+        options: z.array(z.string().trim().min(1).max(120)).min(1).max(100),
+        multiple: z.boolean().default(false),
+    }),
+]);
+export const contentCollectionSchema = z
+    .object({
+    resourceId: z.string().min(8).max(96),
+    name: contentIdentifierSchema,
+    label: contentLabelSchema,
+    singularLabel: contentLabelSchema,
+    public: z.boolean().default(true),
+    fields: z
+        .record(contentFieldIdentifierSchema, contentFieldSchema)
+        .refine((fields) => Object.keys(fields).length <= CONTENT_CAPS.fieldsPerCollection, {
+        message: `must contain at most ${CONTENT_CAPS.fieldsPerCollection} fields`,
+    }),
+})
+    .strict();
+export const contentManifestSchema = z
+    .object({
+    format: z.literal(CONTENT_SCHEMA_FORMAT),
+    version: z.literal(CONTENT_API_VERSION),
+    collections: z
+        .record(contentIdentifierSchema, contentCollectionSchema)
+        .refine((collections) => Object.keys(collections).length <= CONTENT_CAPS.collections, {
+        message: `must contain at most ${CONTENT_CAPS.collections} collections`,
+    }),
+})
+    .strict()
+    .superRefine((manifest, context) => {
+    const resourceIds = new Map();
+    const collectionNames = new Set([
+        "posts",
+        "pages",
+        "media",
+        ...Object.keys(manifest.collections),
+    ]);
+    for (const [name, collection] of Object.entries(manifest.collections)) {
+        if (collection.name !== name) {
+            context.addIssue({
+                code: "custom",
+                message: `collection key "${name}" must match collection.name`,
+                path: ["collections", name, "name"],
+            });
+        }
+        if (name === "posts" || name === "pages" || name === "media") {
+            context.addIssue({
+                code: "custom",
+                message: `collection name "${name}" is reserved`,
+                path: ["collections", name],
+            });
+        }
+        const existingName = resourceIds.get(collection.resourceId);
+        if (existingName !== undefined) {
+            context.addIssue({
+                code: "custom",
+                message: `resourceId is already used by collection "${existingName}"`,
+                path: ["collections", name, "resourceId"],
+            });
+        }
+        else {
+            resourceIds.set(collection.resourceId, name);
+        }
+        for (const [fieldName, field] of Object.entries(collection.fields)) {
+            if (field.type === "relation" && !collectionNames.has(field.collection)) {
+                context.addIssue({
+                    code: "custom",
+                    message: `relation collection "${field.collection}" does not exist`,
+                    path: ["collections", name, "fields", fieldName, "collection"],
+                });
+            }
+        }
+    }
+});
+export const contentScalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const contentValueSchema = z.union([contentScalarSchema, z.array(contentScalarSchema).max(100)]);
+export const contentFilterSchema = z
+    .object({
+    field: contentFieldIdentifierSchema,
+    operator: z.enum(["eq", "neq", "in", "notIn", "gt", "gte", "lt", "lte", "contains", "exists"]),
+    value: contentValueSchema.optional(),
+})
+    .strict()
+    .superRefine((filter, context) => {
+    if (filter.operator !== "exists" && filter.value === undefined) {
+        context.addIssue({ code: "custom", message: "value is required", path: ["value"] });
+    }
+    if ((filter.operator === "in" || filter.operator === "notIn") && !Array.isArray(filter.value)) {
+        context.addIssue({ code: "custom", message: "value must be an array", path: ["value"] });
+    }
+});
+export const contentOrderSchema = z
+    .object({
+    field: contentFieldIdentifierSchema,
+    direction: z.enum(["asc", "desc"]).default("asc"),
+})
+    .strict();
+export const contentQuerySchema = z
+    .object({
+    collection: contentIdentifierSchema,
+    where: z.array(contentFilterSchema).max(CONTENT_CAPS.filterClauses).default([]),
+    orderBy: z.array(contentOrderSchema).max(1).default([]),
+    limit: z.number().int().positive().max(CONTENT_CAPS.pageSize).default(20),
+    cursor: z.string().min(1).max(512).optional(),
+    select: z.array(contentFieldIdentifierSchema).max(CONTENT_CAPS.selectFields).optional(),
+    status: z.enum(["publish", "draft", "any"]).default("publish"),
+})
+    .strict();
+export const contentBatchQueryRequestSchema = z
+    .object({
+    format: z.literal(CONTENT_QUERY_FORMAT),
+    version: z.literal(CONTENT_API_VERSION),
+    queries: z.record(contentQueryKeySchema, contentQuerySchema).refine((queries) => {
+        const length = Object.keys(queries).length;
+        return length > 0 && length <= CONTENT_CAPS.batchQueries;
+    }, { message: `must contain between 1 and ${CONTENT_CAPS.batchQueries} queries` }),
+})
+    .strict();
+export const contentItemSchema = z
+    .object({
+    id: z.number().int().positive(),
+    slug: z.string(),
+    status: z.string(),
+    title: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    fields: z.record(z.string(), z.unknown()),
+})
+    .passthrough();
+export const contentQueryResultSchema = z.object({
+    items: z.array(contentItemSchema),
+    total: z.number().int().nonnegative(),
+    nextCursor: z.string().nullable(),
+});
+export const contentBatchQueryResponseSchema = z
+    .object({
+    format: z.literal(CONTENT_QUERY_FORMAT),
+    version: z.literal(CONTENT_API_VERSION),
+    results: z.record(contentQueryKeySchema, contentQueryResultSchema),
+})
+    .strict();
+const contentDocumentFields = {
+    collection: contentIdentifierSchema,
+    slug: z.string().trim().min(1).max(200),
+    title: z.string().max(500),
+    status: z.enum(["draft", "publish"]).default("draft"),
+    fields: z.record(contentFieldIdentifierSchema, z.unknown()).default({}),
+};
+export const contentDocumentInputSchema = z.union([
+    z.object({ ...contentDocumentFields, id: z.number().int().positive() }).strict(),
+    z.object({ ...contentDocumentFields, externalId: z.string().min(1).max(255) }).strict(),
+]);
+export const contentAdminSessionSchema = z
+    .object({
+    url: z.string().url(),
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+export const contentMarkdownSyncInputSchema = z
+    .object({
+    collection: contentIdentifierSchema.default("posts"),
+    markdown: z.string().max(200_000),
+    slug: z.string().trim().min(1).max(200),
+    source: z.string().trim().min(1).max(1_000),
+    status: z.enum(["draft", "publish"]).default("draft"),
+    title: z.string().max(500),
+})
+    .strict();

package/dist/contracts/continuation.d.ts

@@ -1,26 +1,33 @@
 import { z } from "zod";
 export declare const RequiresActionTypeSchema: z.ZodEnum<{
     device_authorization: "device_authorization";
+    confirmation: "confirmation";
+    elevation: "elevation";
 }>;
 export declare const RequiresActionSchema: z.ZodObject<{
     actionType: z.ZodEnum<{
         device_authorization: "device_authorization";
+        confirmation: "confirmation";
+        elevation: "elevation";
     }>;
     instruction: z.ZodString;
     url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pollUrl: z.ZodOptional<z.ZodString>;
     continuationToken: z.ZodString;
     pollAfterSeconds: z.ZodNumber;
     expiresAt: z.ZodString;
 }, z.core.$strict>;
 export type RequiresAction = z.infer<typeof RequiresActionSchema>;
-/** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
 export declare const RequiresActionEnvelopeSchema: z.ZodObject<{
     requiresAction: z.ZodObject<{
         actionType: z.ZodEnum<{
             device_authorization: "device_authorization";
+            confirmation: "confirmation";
+            elevation: "elevation";
         }>;
         instruction: z.ZodString;
         url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pollUrl: z.ZodOptional<z.ZodString>;
         continuationToken: z.ZodString;
         pollAfterSeconds: z.ZodNumber;
         expiresAt: z.ZodString;
@@ -34,9 +41,12 @@ export declare const ActionResumeResponseSchema: z.ZodDiscriminatedUnion<[z.ZodO
     requiresAction: z.ZodObject<{
         actionType: z.ZodEnum<{
             device_authorization: "device_authorization";
+            confirmation: "confirmation";
+            elevation: "elevation";
         }>;
         instruction: z.ZodString;
         url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pollUrl: z.ZodOptional<z.ZodString>;
         continuationToken: z.ZodString;
         pollAfterSeconds: z.ZodNumber;
         expiresAt: z.ZodString;
@@ -45,18 +55,24 @@ export declare const ActionResumeResponseSchema: z.ZodDiscriminatedUnion<[z.ZodO
     status: z.ZodLiteral<"completed">;
     actionType: z.ZodEnum<{
         device_authorization: "device_authorization";
+        confirmation: "confirmation";
+        elevation: "elevation";
     }>;
     result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strict>, z.ZodObject<{
     status: z.ZodLiteral<"denied">;
     actionType: z.ZodEnum<{
         device_authorization: "device_authorization";
+        confirmation: "confirmation";
+        elevation: "elevation";
     }>;
     message: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     status: z.ZodLiteral<"expired">;
     actionType: z.ZodEnum<{
         device_authorization: "device_authorization";
+        confirmation: "confirmation";
+        elevation: "elevation";
     }>;
     message: z.ZodString;
 }, z.core.$strict>], "status">;

package/dist/contracts/continuation.js

@@ -1,53 +1,53 @@
 import { z } from "zod";
 import { AnyObjectSchema } from "./common.js";
-// Canonical `requires_action` result envelope (W5: agent dead-end fix).
-//
-// Some flows cannot finish inside a single request: they need an out-of-band
-// human step (approve a device in the browser, confirm an approval). Historically
-// those flows returned an `{ error }` an agent could not programmatically continue
-// from — it was forced into the browser and the automation died. This envelope is
-// the additive third shape alongside `{ data }` / `{ error }`: it tells the caller
-// exactly what human step is pending, where to send the human, and — crucially —
-// hands back a short-lived, single-use, principal-scoped continuation token plus a
-// poll hint so the SAME agent can drive the flow to completion through the
-// generalized resume endpoint once the human step is done.
+// Canonical `requires_action` result envelope, the third shape alongside
+// `{ data }` / `{ error }`. Some flows need an out-of-band human step (approve a
+// device in the browser). This says what step is pending and where to send the
+// human, and hands back a short-lived, single-use, principal-scoped continuation
+// token plus a poll hint, so the SAME agent can finish through resume.
+// New blocking steps are added here, so resume stays one generalized contract.
 export const RequiresActionTypeSchema = z
-    .enum(["device_authorization"])
-    .describe("Stable identifier for the out-of-band step that blocks the flow. Add new blocking steps here so resume stays one generalized contract.");
+    .enum(["device_authorization", "confirmation", "elevation"])
+    .describe("Stable identifier for the out-of-band step that blocks the flow.");
 export const RequiresActionSchema = z
     .object({
     actionType: RequiresActionTypeSchema,
-    instruction: z
-        .string()
-        .describe("Human-facing instruction describing the step a person must complete out of band."),
+    instruction: z.string().describe("The step a person must complete out of band."),
     url: z
         .string()
         .url()
         .nullable()
         .optional()
         .describe("Where to send the human to complete the step, when a destination exists."),
+    // `url` / `pollUrl` / `continuationToken` are the blocked-agent key set, and
+    // they are spelled the same way here and in the `confirmation_required`
+    // problem document. One flow that answers with two vocabularies is a flow
+    // agents have to special-case twice.
+    pollUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Where to POST the continuationToken to poll this flow: `/v1/actions/resume`."),
     continuationToken: z
         .string()
         .min(1)
-        .describe("Short-lived, principal-scoped capability for this exact flow. Present it to POST /v1/actions/resume to poll and complete the flow. The token is single-use on completion. Treat it as a secret. Never log it."),
+        .describe("Short-lived, principal-scoped capability for this flow. Present it to POST /v1/actions/resume to poll and complete. Single-use on completion. A secret: never log it."),
     pollAfterSeconds: z
         .number()
         .int()
         .positive()
-        .describe("Minimum number of seconds to wait before calling resume again (retry-after hint)."),
+        .describe("Minimum seconds to wait before calling resume again."),
     expiresAt: z
         .string()
         .datetime()
-        .describe("Instant when the human step deadline is reached for the originating flow. Resume after this returns terminal `expired`. The token survives for a short grace so resume can report `expired`, but the flow can no longer be redeemed."),
+        .describe("Deadline for the human step. Resume after this returns terminal `expired`; the token survives a short grace so resume can say so, but the flow can no longer be redeemed."),
 })
     .strict();
-/** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
 export const RequiresActionEnvelopeSchema = z
     .object({ requiresAction: RequiresActionSchema })
     .strict();
 // Generalized resume/poll contract. One endpoint (`POST /v1/actions/resume`)
-// drives every requires_action flow to completion from its continuation token, so
-// agents learn the pattern once and reuse it everywhere.
+// drives every requires_action flow to completion from its continuation token.
 export const ActionResumeRequestSchema = z
     .object({
     continuationToken: z
@@ -70,7 +70,7 @@ export const ActionResumeResponseSchema = z
         .object({
         status: z.literal("completed"),
         actionType: RequiresActionTypeSchema,
-        result: AnyObjectSchema.describe("Flow success payload, redeemed exactly once. For device_authorization, this carries the one-time `apiKey` and any `claimedSpaceId`."),
+        result: AnyObjectSchema.describe("The flow returns this result one time. Device authorization returns an API key. Confirmation returns an action receipt. Elevation returns a lease receipt."),
     })
         .strict(),
     z

package/dist/contracts/countries.js

@@ -1,8 +1,7 @@
 // ISO 3166-1 alpha-2 country codes used by Grant network constraints. The
-// runtime compares them with the edge-supplied country header.
-//
-// Officially assigned codes only (no exceptionally-reserved / user-assigned
-// ranges). Display names are a UI concern (`Intl.DisplayNames`), never stored.
+// runtime compares them with the edge-supplied country header. Officially
+// assigned codes only (no exceptionally-reserved / user-assigned ranges).
+// Display names are a UI concern (`Intl.DisplayNames`), never stored.
 export const ISO_COUNTRY_CODES = [
     "AD",
     "AE",

package/dist/contracts/crons.d.ts

@@ -2,8 +2,18 @@ import { z } from "zod";
 export declare const spaceCronFailureSchema: z.ZodObject<{
     id: z.ZodString;
     occurredAt: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type SpaceCronFailure = z.infer<typeof spaceCronFailureSchema>;
+export declare const spaceCronUnattributedFailureSchema: z.ZodObject<{
+    id: z.ZodString;
+    occurredAt: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodNullable<z.ZodString>;
+    key: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SpaceCronUnattributedFailure = z.infer<typeof spaceCronUnattributedFailureSchema>;
 export declare const spaceCronListItemSchema: z.ZodObject<{
     key: z.ZodString;
     path: z.ZodString;
@@ -11,6 +21,8 @@ export declare const spaceCronListItemSchema: z.ZodObject<{
     recentFailures: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         occurredAt: z.ZodString;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        reason: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SpaceCronListItem = z.infer<typeof spaceCronListItemSchema>;
@@ -24,11 +36,16 @@ export declare const spaceCronsResponseSchema: z.ZodObject<{
             recentFailures: z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 occurredAt: z.ZodString;
+                exitCode: z.ZodNullable<z.ZodNumber>;
+                reason: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         unattributedFailures: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             occurredAt: z.ZodString;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+            reason: z.ZodNullable<z.ZodString>;
+            key: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;

package/dist/contracts/crons.js

@@ -1,23 +1,41 @@
 import { z } from "zod";
 // Crons READ surface: what the live version declares, plus what has failed.
-//
-// There is no write side and there will not be one. `crons` is an sf.jsonc key,
-// so the config file is the only writer and a publish is the only edit — which
-// is what makes a rollback restore the previous schedules for free. This
-// projection exists so a human or an agent can ask what is actually scheduled
-// right now without re-reading the file they think they published.
-// One reported failure. Deliberately just an identity and an instant: the
-// platform's own report of a failed run carries a payload whose shape is not
-// pinned yet, and guessing fields into a public contract now would freeze the
-// wrong ones. A timestamp is what both the CLI table and "did my cron break?"
-// actually need; the space's activity feed carries the narrative.
+// There is no write side. `crons` is an sf.jsonc key, so the config file is the
+// only writer and a publish the only edit, which is what makes a rollback
+// restore the previous schedules for free.
+// One reported failure. Pinned to what the platform provably knows: the
+// identity, the instant, the run's exit status when the provider delivery
+// carried one, and what that status means on our runtime (the scheduled
+// command is ours — runtime/engine/entrypoints/cron.php defines the exit-code
+// contract). Deeper detail (run output, the handler's HTTP status, whether a
+// report is a concurrency-limit skip rather than a non-zero exit) stays out of
+// the public contract until a captured live delivery pins the provider's
+// shape. Nothing from the raw delivery is ever echoed: run output can contain
+// an author's response bodies and secrets.
 export const spaceCronFailureSchema = z.object({
-    id: z.string().describe("Identifier of this failure report."),
+    id: z.string().describe("Failure report id."),
     occurredAt: z.string().datetime().describe("Instant the failure was reported."),
+    exitCode: z
+        .number()
+        .int()
+        .nullable()
+        .describe("Exit status the platform reported for the run. Null when the failure report did not carry one."),
+    reason: z
+        .string()
+        .nullable()
+        .describe("What the exit status means on this runtime, when it maps to a known failure mode. Null when unknown."),
+});
+// An unattributed failure also carries the key the platform reported, so a
+// failure from a cron since removed from the config can still say which entry
+// it belonged to. Null when the report named no key at all.
+export const spaceCronUnattributedFailureSchema = spaceCronFailureSchema.extend({
+    key: z
+        .string()
+        .nullable()
+        .describe("Key the failure report named — an entry the live config no longer declares — or null when the report carried none."),
 });
 // One scheduled entry, exactly as the live version declared it. `key` is the
-// path's slug and is what names this entry everywhere else — the CLI argument,
-// the failure reports, the platform's own bookkeeping.
+// path's slug and names the entry in the CLI, failure reports, and bookkeeping.
 export const spaceCronListItemSchema = z.object({
     key: z.string().describe("Stable identifier for this entry, derived from its path."),
     path: z.string().describe("Path on this space that gets requested."),
@@ -36,7 +54,7 @@ export const spaceCronsResponseSchema = z.object({
             .describe("Live version these declarations come from, or null before the first publish."),
         crons: z.array(spaceCronListItemSchema),
         unattributedFailures: z
-            .array(spaceCronFailureSchema)
+            .array(spaceCronUnattributedFailureSchema)
             .describe("Failures that could not be tied to one entry, newest first. A cron removed from the config can still have failed while it was live."),
     }),
 });

package/dist/contracts/dashboard-prefs.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+/** Most keys one user's preference bag may hold. */
+export declare const DASHBOARD_PREFS_MAX_KEYS = 50;
+/** Longest single preference key, in characters. */
+export declare const DASHBOARD_PREFS_MAX_KEY_LENGTH = 64;
+/** Largest serialized preference bag, in UTF-8 bytes. */
+export declare const DASHBOARD_PREFS_MAX_BYTES: number;
+/**
+ * The stored bag. Values stay `unknown`: every reader narrows with its own
+ * schema rather than trusting a shape the server never enforced.
+ */
+export declare const dashboardPrefsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type DashboardPrefs = z.infer<typeof dashboardPrefsSchema>;
+/**
+ * One value out of the bag, as wide as JSON. This is the type every consumer
+ * narrows FROM, at the boundary.
+ */
+export type DashboardPrefValue = DashboardPrefs[string];
+/**
+ * The PATCH body: a partial bag merged key-wise into the stored one. An explicit
+ * `null` deletes its key.
+ */
+export declare const dashboardPrefsPatchSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type DashboardPrefsPatch = z.infer<typeof dashboardPrefsPatchSchema>;
+/** The dashboard appearance key. */
+export declare const DASHBOARD_PREF_APPEARANCE = "appearance";
+/** Personal space favorites: the starred space ids, across every team. */
+export declare const DASHBOARD_PREF_SPACE_FAVORITES = "spaceFavorites";
+/**
+ * Favorites value: unique space ids. Capped well under the bag's byte budget —
+ * a favorite is a shortcut, and hundreds of shortcuts stop being one. Ids the
+ * server can no longer resolve to a live space are dropped on write.
+ */
+export declare const spaceFavoritesPreferenceSchema: z.ZodArray<z.ZodString>;
+export type SpaceFavoritesPreference = z.infer<typeof spaceFavoritesPreferenceSchema>;
+/** Personal manual space ordering, keyed by team id. */
+export declare const DASHBOARD_PREF_SPACE_ORDERS = "spaceOrders";
+/**
+ * Per-team ordered space ids for the "custom order" of the spaces list. This is
+ * the only home for a manual space order: it is per-user, like every other
+ * dashboard preference. Ids the server can no longer resolve to a live space of
+ * that team are dropped on write, so a deleted space cannot squat a slot.
+ */
+export declare const spaceOrdersPreferenceSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+export type SpaceOrdersPreference = z.infer<typeof spaceOrdersPreferenceSchema>;
+/**
+ * Values the appearance preference may take. `system` follows the OS setting
+ * live; the other two pin it. Mirrors the client-side `ThemePreference` union
+ * in `@spacefast/app-shell/lib/theme`.
+ */
+export declare const appearancePreferenceSchema: z.ZodEnum<{
+    dark: "dark";
+    light: "light";
+    system: "system";
+}>;
+export type AppearancePreference = z.infer<typeof appearancePreferenceSchema>;