spawnfile 0.1.17 → 0.1.19

package/dist/manifest/volumeFeedSchemas.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { argvSchema, pinnedImageSchema } from "./commandSchemas.js";
+/** `${date}` (UTC) or `${date:<IANA zone>}`: the local date (YYYY-MM-DD) at refresh time. The only placeholder a ref or path template knows. */
+export const FEED_REF_PLACEHOLDER = /\$\{date(?::([^}]*))?\}/gu;
+export const FEED_CLOCK_PATTERN = /^(?:[01]\d|2[0-3]):[0-5]\d$/u;
+export const isFeedTimeZone = (zone) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return zone.trim() !== "";
+    }
+    catch {
+        return false;
+    }
+};
+const plainRelativePath = (entry) => !entry.startsWith("/") && !entry.split("/").some((segment) => segment === ".." || segment === "." || segment === "");
+/** Issues with the placeholders in a ref or path template: only `${date}` and `${date:<IANA zone>}` exist. */
+const templateIssues = (template, what) => {
+    const issues = [];
+    for (const match of template.matchAll(FEED_REF_PLACEHOLDER)) {
+        if (match[1] !== undefined && !isFeedTimeZone(match[1]))
+            issues.push(`${what} time zone ${JSON.stringify(match[1])} is not an IANA time zone`);
+    }
+    if (template.replace(FEED_REF_PLACEHOLDER, "").includes("${"))
+        issues.push(`${what}s know only \${date} and \${date:<time zone>}`);
+    return issues;
+};
+/** A ref resolved per refresh: a template or a command printing a ref, with an optional fallback when it does not exist yet. */
+const volumeFeedRefRuleSchema = z.object({
+    command: argvSchema.optional(),
+    fallback: z.string().trim().min(1).optional(),
+    template: z.string().trim().min(1).optional()
+}).strict().superRefine((value, context) => {
+    if ((value.command === undefined) === (value.template === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "a volume feed ref rule must declare exactly one of template or command" });
+    }
+    if (value.template === undefined)
+        return;
+    for (const message of templateIssues(value.template, "volume feed ref template"))
+        context.addIssue({ code: z.ZodIssueCode.custom, message });
+});
+/**
+ * Host-fed content for a volume: a host directory or a git ref Spawnfile copies into the volume by atomic
+ * swap (`spawnfile volume refresh`), never through the image. Exactly one source per feed.
+ */
+export const volumeFeedSchema = z.object({
+    directory: z.string().trim().min(1).optional(),
+    /** Once local time passes `after`, a volume that already landed this period's ref stops advancing until the period or the ref changes. */
+    freeze: z.object({
+        after: z.string().regex(FEED_CLOCK_PATTERN, "freeze.after must be HH:MM (24-hour)"),
+        timezone: z.string().trim().min(1).refine(isFeedTimeZone, "freeze.timezone must be an IANA time zone")
+    }).strict().optional(),
+    git: z.object({
+        fetch: z.boolean().optional(),
+        /** Directories to feed instead of the whole tree; each MAY carry `${date}` placeholders, expanded with the ref. */
+        paths: z.array(z.string().trim().min(1)).min(1).optional(),
+        ref: z.union([z.string().trim().min(1), volumeFeedRefRuleSchema]).optional(),
+        repo: z.string().trim().min(1)
+    }).strict().optional(),
+    /** Host directories (files not in the source, e.g. fonts) staged into the tree before `prepare`. */
+    include: z.array(z.object({
+        from: z.string().trim().min(1),
+        to: z.string().trim().min(1)
+    }).strict()).min(1).optional(),
+    keep: z.number().int().min(1).optional(),
+    owner: z.string().regex(/^\d+:\d+$/u, "owner must be <uid>:<gid>").optional(),
+    /** A command run inside the staged tree after fetch and before validate: in a digest-pinned image, or explicitly on the host. */
+    prepare: z.object({
+        command: argvSchema,
+        host: z.literal(true).optional(),
+        image: pinnedImageSchema.optional(),
+        network: z.boolean().optional(),
+        platform: z.enum(["linux/amd64", "linux/arm64"]).optional(),
+        timeout_seconds: z.number().int().positive().max(86_400).optional()
+    }).strict().superRefine((value, context) => {
+        if ((value.image === undefined) === (value.host === undefined)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "volume feed prepare must declare exactly one of image (digest-pinned) or host: true" });
+        }
+        if (value.host && (value.platform !== undefined || value.network !== undefined)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "volume feed prepare platform and network apply only to an image" });
+        }
+    }).optional(),
+    validate: z.array(z.string().min(1)).min(1).optional()
+}).strict().superRefine((value, context) => {
+    if ((value.directory === undefined) === (value.git === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "volume feeds must declare exactly one of directory or git" });
+    }
+    for (const entry of value.git?.paths ?? []) {
+        const placeholders = templateIssues(entry, "volume feed git path template");
+        for (const message of placeholders)
+            context.addIssue({ code: z.ZodIssueCode.custom, message });
+        // A placeholder expands to YYYY-MM-DD, so the path is judged with one in its place.
+        if (placeholders.length === 0 && !plainRelativePath(entry.replace(FEED_REF_PLACEHOLDER, "0000-00-00"))) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: `volume feed git path ${entry} must be a plain repository-relative path` });
+        }
+    }
+    const targets = (value.include ?? []).map((entry) => entry.to);
+    for (const [index, to] of targets.entries()) {
+        if (!plainRelativePath(to))
+            context.addIssue({ code: z.ZodIssueCode.custom, message: `volume feed include target ${to} must be a plain tree-relative path` });
+        if (targets.some((other, at) => at !== index && (other === to || other.startsWith(`${to}/`)))) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: `volume feed include target ${to} overlaps another include` });
+        }
+    }
+});

package/dist/manifest/workspaceSchemas.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { volumeFeedSchema } from "./volumeFeedSchemas.js";
 export declare const teamWorkspaceDocsSchema: z.ZodObject<{
     extras: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     heartbeat: z.ZodOptional<z.ZodString>;
@@ -7,8 +8,49 @@ export declare const teamWorkspaceDocsSchema: z.ZodObject<{
     soul: z.ZodOptional<z.ZodString>;
     system: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-declare const teamWorkspaceResourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+/**
+ * Declared inputs Spawnfile builds into the bundle archive. Exactly one input kind per bundle:
+ * `files` (git-tracked files), `dependencies` (lockfile installed for the target platform in a
+ * pinned image) or `generated` (a declared command writing an output directory from declared inputs).
+ */
+declare const workspaceBundleBuildSchema: z.ZodObject<{
+    dependencies: z.ZodOptional<z.ZodObject<{
+        check: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dev: z.ZodOptional<z.ZodBoolean>;
+        directory: z.ZodString;
+        image: z.ZodString;
+        manager: z.ZodOptional<z.ZodLiteral<"npm">>;
+        scripts: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    files: z.ZodOptional<z.ZodObject<{
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ref: z.ZodOptional<z.ZodString>;
+        root: z.ZodString;
+    }, z.core.$strict>>;
+    generated: z.ZodOptional<z.ZodObject<{
+        command: z.ZodArray<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        inputs: z.ZodArray<z.ZodObject<{
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ref: z.ZodOptional<z.ZodString>;
+            root: z.ZodString;
+        }, z.core.$strict>>;
+        timeout_seconds: z.ZodOptional<z.ZodNumber>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const teamWorkspaceResourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    auth: z.ZodOptional<z.ZodObject<{
+        ssh_key: z.ZodOptional<z.ZodString>;
+        ssh_key_env: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     branch: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fetch: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        build: "build";
+    }>>;
     id: z.ZodString;
     kind: z.ZodLiteral<"git">;
     mount: z.ZodString;
@@ -24,14 +66,76 @@ declare const teamWorkspaceResourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     tag: z.ZodOptional<z.ZodString>;
     url: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
+    build: z.ZodOptional<z.ZodObject<{
+        dependencies: z.ZodOptional<z.ZodObject<{
+            check: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            dev: z.ZodOptional<z.ZodBoolean>;
+            directory: z.ZodString;
+            image: z.ZodString;
+            manager: z.ZodOptional<z.ZodLiteral<"npm">>;
+            scripts: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        files: z.ZodOptional<z.ZodObject<{
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ref: z.ZodOptional<z.ZodString>;
+            root: z.ZodString;
+        }, z.core.$strict>>;
+        generated: z.ZodOptional<z.ZodObject<{
+            command: z.ZodArray<z.ZodString>;
+            cwd: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodString>;
+            inputs: z.ZodArray<z.ZodObject<{
+                exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                ref: z.ZodOptional<z.ZodString>;
+                root: z.ZodString;
+            }, z.core.$strict>>;
+            timeout_seconds: z.ZodOptional<z.ZodNumber>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     kind: z.ZodLiteral<"bundle">;
     mount: z.ZodString;
     mode: z.ZodLiteral<"readonly">;
-    sha256: z.ZodString;
+    sha256: z.ZodOptional<z.ZodString>;
     sharing: z.ZodOptional<z.ZodLiteral<"per_agent">>;
-    source: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
+    feed: z.ZodOptional<z.ZodObject<{
+        directory: z.ZodOptional<z.ZodString>;
+        freeze: z.ZodOptional<z.ZodObject<{
+            after: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strict>>;
+        git: z.ZodOptional<z.ZodObject<{
+            fetch: z.ZodOptional<z.ZodBoolean>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ref: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                fallback: z.ZodOptional<z.ZodString>;
+                template: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>;
+            repo: z.ZodString;
+        }, z.core.$strict>>;
+        include: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, z.core.$strict>>>;
+        keep: z.ZodOptional<z.ZodNumber>;
+        owner: z.ZodOptional<z.ZodString>;
+        prepare: z.ZodOptional<z.ZodObject<{
+            command: z.ZodArray<z.ZodString>;
+            host: z.ZodOptional<z.ZodLiteral<true>>;
+            image: z.ZodOptional<z.ZodString>;
+            network: z.ZodOptional<z.ZodBoolean>;
+            platform: z.ZodOptional<z.ZodEnum<{
+                "linux/amd64": "linux/amd64";
+                "linux/arm64": "linux/arm64";
+            }>>;
+            timeout_seconds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        validate: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     kind: z.ZodLiteral<"volume">;
     mount: z.ZodString;
@@ -61,7 +165,16 @@ export declare const teamWorkspaceSchema: z.ZodObject<{
         system: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     resources: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        auth: z.ZodOptional<z.ZodObject<{
+            ssh_key: z.ZodOptional<z.ZodString>;
+            ssh_key_env: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         branch: z.ZodOptional<z.ZodString>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fetch: z.ZodOptional<z.ZodEnum<{
+            start: "start";
+            build: "build";
+        }>>;
         id: z.ZodString;
         kind: z.ZodLiteral<"git">;
         mount: z.ZodString;
@@ -77,14 +190,76 @@ export declare const teamWorkspaceSchema: z.ZodObject<{
         tag: z.ZodOptional<z.ZodString>;
         url: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
+        build: z.ZodOptional<z.ZodObject<{
+            dependencies: z.ZodOptional<z.ZodObject<{
+                check: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                dev: z.ZodOptional<z.ZodBoolean>;
+                directory: z.ZodString;
+                image: z.ZodString;
+                manager: z.ZodOptional<z.ZodLiteral<"npm">>;
+                scripts: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            files: z.ZodOptional<z.ZodObject<{
+                exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                ref: z.ZodOptional<z.ZodString>;
+                root: z.ZodString;
+            }, z.core.$strict>>;
+            generated: z.ZodOptional<z.ZodObject<{
+                command: z.ZodArray<z.ZodString>;
+                cwd: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                inputs: z.ZodArray<z.ZodObject<{
+                    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    ref: z.ZodOptional<z.ZodString>;
+                    root: z.ZodString;
+                }, z.core.$strict>>;
+                timeout_seconds: z.ZodOptional<z.ZodNumber>;
+                tools: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         kind: z.ZodLiteral<"bundle">;
         mount: z.ZodString;
         mode: z.ZodLiteral<"readonly">;
-        sha256: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
         sharing: z.ZodOptional<z.ZodLiteral<"per_agent">>;
-        source: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
+        feed: z.ZodOptional<z.ZodObject<{
+            directory: z.ZodOptional<z.ZodString>;
+            freeze: z.ZodOptional<z.ZodObject<{
+                after: z.ZodString;
+                timezone: z.ZodString;
+            }, z.core.$strict>>;
+            git: z.ZodOptional<z.ZodObject<{
+                fetch: z.ZodOptional<z.ZodBoolean>;
+                paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                ref: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    fallback: z.ZodOptional<z.ZodString>;
+                    template: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>>;
+                repo: z.ZodString;
+            }, z.core.$strict>>;
+            include: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                from: z.ZodString;
+                to: z.ZodString;
+            }, z.core.$strict>>>;
+            keep: z.ZodOptional<z.ZodNumber>;
+            owner: z.ZodOptional<z.ZodString>;
+            prepare: z.ZodOptional<z.ZodObject<{
+                command: z.ZodArray<z.ZodString>;
+                host: z.ZodOptional<z.ZodLiteral<true>>;
+                image: z.ZodOptional<z.ZodString>;
+                network: z.ZodOptional<z.ZodBoolean>;
+                platform: z.ZodOptional<z.ZodEnum<{
+                    "linux/amd64": "linux/amd64";
+                    "linux/arm64": "linux/arm64";
+                }>>;
+                timeout_seconds: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            validate: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         kind: z.ZodLiteral<"volume">;
         mount: z.ZodString;
@@ -108,5 +283,7 @@ export declare const teamWorkspaceSchema: z.ZodObject<{
 export type TeamWorkspace = z.infer<typeof teamWorkspaceSchema>;
 export type TeamWorkspaceDocs = z.infer<typeof teamWorkspaceDocsSchema>;
 export type TeamWorkspaceResource = z.infer<typeof teamWorkspaceResourceSchema>;
+export type WorkspaceBundleBuild = z.infer<typeof workspaceBundleBuildSchema>;
+export type VolumeFeed = z.infer<typeof volumeFeedSchema>;
 export type TeamWorkspaceSkill = z.infer<typeof workspaceSkillReferenceSchema>;
 export {};

package/dist/manifest/workspaceSchemas.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { argvSchema, pinnedImageSchema } from "./commandSchemas.js";
+import { volumeFeedSchema } from "./volumeFeedSchemas.js";
 const workspaceResourceModeSchema = z.enum(["mutable", "readonly"]);
 const workspaceResourceSharingSchema = z.enum(["per_agent", "team"]);
 export const teamWorkspaceDocsSchema = z
@@ -51,9 +53,36 @@ const resourceMountSchema = z
         });
     }
 });
+/** Host-side credentials for a `fetch: build` git resource: a key file path, or an env var holding the key. */
+const gitResourceAuthSchema = z
+    .object({
+    ssh_key: z.string().trim().min(1).optional(),
+    ssh_key_env: z.string().trim().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u, "ssh_key_env must be an environment variable name").optional()
+})
+    .strict()
+    .refine((value) => (value.ssh_key === undefined) !== (value.ssh_key_env === undefined), {
+    message: "git resource auth must declare exactly one of ssh_key or ssh_key_env"
+});
+/**
+ * True when a URL may carry a credential: any password, any userinfo on a
+ * non-SSH URL (a token is often sent as the user name), or a query string.
+ * An SSH user name (`git@host:...`, `ssh://git@host/...`) is not a secret.
+ */
+const urlEmbedsCredential = (url) => {
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)/iu.exec(url);
+    if (!scheme)
+        return url.includes("?");
+    const authority = scheme[2], userinfo = authority.includes("@") ? authority.slice(0, authority.lastIndexOf("@")) : undefined;
+    if (url.includes("?") || userinfo?.includes(":"))
+        return true;
+    return userinfo !== undefined && !/^(ssh|git\+ssh|ssh\+git)$/iu.test(scheme[1]);
+};
 const teamWorkspaceResourceGitSchema = z
     .object({
+    auth: gitResourceAuthSchema.optional(),
     branch: z.string().trim().optional(),
+    exclude: z.array(z.string().trim().min(1)).optional(),
+    fetch: z.enum(["start", "build"]).optional(),
     id: z.string().trim().min(1),
     kind: z.literal("git"),
     mount: resourceMountSchema,
@@ -72,6 +101,25 @@ const teamWorkspaceResourceGitSchema = z
             message: "git resources may declare at most one of branch, tag, or ref"
         });
     }
+    if (value.fetch === "build") {
+        if ([value.branch, value.tag, value.ref].some((selector) => selector !== undefined && selector === "")) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource branch, tag, or ref must not be empty with fetch: build" });
+        }
+        if (value.mode !== "readonly") {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resources with fetch: build are pinned image content and must be mode: readonly" });
+        }
+        if (urlEmbedsCredential(value.url)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource url must not embed a credential; declare auth instead" });
+        }
+    }
+    else {
+        if (value.auth !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource auth requires fetch: build; a container-start clone never receives host credentials" });
+        }
+        if (value.exclude !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource exclude requires fetch: build" });
+        }
+    }
     if (value.sharing === "team") {
         context.addIssue({
             code: z.ZodIssueCode.custom,
@@ -81,6 +129,7 @@ const teamWorkspaceResourceGitSchema = z
 });
 const teamWorkspaceResourceVolumeSchema = z
     .object({
+    feed: volumeFeedSchema.optional(),
     id: z.string().trim().min(1),
     kind: z.literal("volume"),
     mount: resourceMountSchema,
@@ -88,13 +137,64 @@ const teamWorkspaceResourceVolumeSchema = z
     name: z.string().trim().optional(),
     sharing: workspaceResourceSharingSchema.optional()
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    if (!value.feed)
+        return;
+    // The host job addresses the volume by its exact host name, so a derived, unpublished name cannot be fed.
+    if (!value.name)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "fed volumes must declare name" });
+    // A readonly volume is made read-only by the container rewriting the whole volume on every start;
+    // a fed volume is instead frozen tree by tree on the host, so it stays mutable at the mount.
+    if (value.mode !== "mutable")
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "fed volumes must declare mode: mutable; the host freezes every landed tree" });
+});
+/** Declared inputs Spawnfile builds into the bundle archive. Exactly one input kind per bundle. */
+const workspaceBundleFilesSchema = z.object({
+    exclude: z.array(z.string().trim().min(1)).optional(),
+    /** Archive the tree of this commit (any git revision) instead of the work tree; needs no clean checkout. */
+    ref: z.string().trim().min(1).optional(),
+    root: z.string().trim().min(1)
+}).strict();
+/**
+ * Declared inputs Spawnfile builds into the bundle archive. Exactly one input kind per bundle:
+ * `files` (git-tracked files), `dependencies` (lockfile installed for the target platform in a
+ * pinned image) or `generated` (a declared command writing an output directory from declared inputs).
+ */
+const workspaceBundleBuildSchema = z.object({
+    dependencies: z.object({
+        check: argvSchema.optional(),
+        dev: z.boolean().optional(),
+        directory: z.string().trim().min(1),
+        image: pinnedImageSchema,
+        manager: z.literal("npm").optional(),
+        scripts: z.boolean().optional()
+    }).strict().optional(),
+    files: workspaceBundleFilesSchema.optional(),
+    generated: z.object({
+        command: argvSchema,
+        cwd: z.string().trim().min(1).optional(),
+        image: pinnedImageSchema.optional(),
+        inputs: z.array(workspaceBundleFilesSchema).min(1),
+        timeout_seconds: z.number().int().positive().max(86_400).optional(),
+        tools: z.array(argvSchema).optional()
+    }).strict().optional()
+}).strict().superRefine((value, context) => {
+    if ([value.files, value.dependencies, value.generated].filter((kind) => kind !== undefined).length !== 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "bundle build must declare exactly one of files, dependencies or generated" });
+    }
+});
 const teamWorkspaceResourceBundleSchema = z.object({
+    build: workspaceBundleBuildSchema.optional(),
     id: z.string().trim().min(1), kind: z.literal("bundle"), mount: resourceMountSchema,
-    mode: z.literal("readonly"), sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
-    sharing: z.literal("per_agent").optional(), source: z.string().trim().min(1)
-}).strict();
-const teamWorkspaceResourceSchema = z.discriminatedUnion("kind", [
+    mode: z.literal("readonly"), sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u).optional(),
+    sharing: z.literal("per_agent").optional(), source: z.string().trim().min(1).optional()
+}).strict().superRefine((value, context) => {
+    if ((value.source === undefined) === (value.build === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "bundle resources must declare exactly one of source or build" });
+    }
+});
+export const teamWorkspaceResourceSchema = z.discriminatedUnion("kind", [
     teamWorkspaceResourceGitSchema,
     teamWorkspaceResourceBundleSchema,
     teamWorkspaceResourceVolumeSchema
@@ -125,7 +225,10 @@ export const teamWorkspaceSchema = z
     const normalizeResourceIdentity = (resource) => {
         if (resource.kind === "git") {
             return JSON.stringify({
+                auth: resource.auth ?? null,
                 branch: resource.branch?.trim() ?? "",
+                exclude: resource.exclude ?? null,
+                fetch: resource.fetch ?? "start",
                 kind: "git",
                 mode: resource.mode,
                 mount: normalizeMount(resource.mount),
@@ -137,10 +240,11 @@ export const teamWorkspaceSchema = z
         }
         if (resource.kind === "bundle")
             return JSON.stringify({
-                kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount),
-                sha256: resource.sha256, sharing: resource.sharing ?? "per_agent", source: resource.source
+                build: resource.build ?? null, kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount),
+                sha256: resource.sha256 ?? null, sharing: resource.sharing ?? "per_agent", source: resource.source ?? null
             });
         return JSON.stringify({
+            ...(resource.feed ? { feed: resource.feed } : {}),
             kind: "volume",
             mode: resource.mode,
             mount: normalizeMount(resource.mount),

package/dist/recording/compose.d.ts

@@ -0,0 +1,3 @@
+import { type ComposeMomentRecordInput, type MomentRecord } from "./types.js";
+/** Compose only supplied evidence at the turn boundary; this function reads no files or clock. */
+export declare const composeMomentRecord: (input: ComposeMomentRecordInput) => MomentRecord;

package/dist/recording/compose.js

@@ -0,0 +1,93 @@
+import { feedLandingAt } from "../volume/index.js";
+import { recordingHistoryAt } from "./history.js";
+import { MOMENT_RECORD_VERSION } from "./types.js";
+const orderedUnique = (values) => [...new Set(values)].sort();
+/** Compose only supplied evidence at the turn boundary; this function reads no files or clock. */
+export const composeMomentRecord = (input) => {
+    const { row, agentNodeId } = input;
+    const errors = [...(input.errors ?? [])];
+    if (row.agent_id !== agentNodeId)
+        errors.push(`Wake agent ${row.agent_id} does not match compiled agent ${agentNodeId}`);
+    if (row.error !== undefined)
+        errors.push(`Wake recording: ${row.error}`);
+    if (!row.deliveries.length)
+        throw new Error("A wake moment requires at least one delivery");
+    const startedAt = row.started_at, started = Date.parse(startedAt);
+    if (!Number.isFinite(started))
+        throw new Error("A wake moment requires a valid started_at");
+    const resources = [];
+    const history = recordingHistoryAt(input.deployResources, input.deploymentRecordPath, startedAt, agentNodeId);
+    const { deployment, agent } = history;
+    errors.push(...history.errors);
+    if (deployment && (!deployment.activation_exact || deployment.exact === false)) {
+        errors.push(`Deployment activation is non-exact${deployment.activation_note ? `: ${deployment.activation_note}` : ""}`);
+    }
+    for (const resource of [...(agent?.resources ?? [])].sort((a, b) => a.id.localeCompare(b.id) || a.kind.localeCompare(b.kind))) {
+        const matches = deployment?.resources.filter((entry) => entry.id === resource.id && entry.kind === resource.kind) ?? [];
+        const pin = matches[0];
+        if (matches.length !== 1 || !pin) {
+            errors.push(`${matches.length ? "Ambiguous" : "Missing"} deployment history for ${resource.kind} resource ${resource.id} at ${startedAt}`);
+            continue;
+        }
+        resources.push(pin.kind === "git"
+            ? { id: pin.id, kind: pin.kind, commit: pin.commit, sha256: pin.sha256 }
+            : { id: pin.id, kind: pin.kind, sha256: pin.sha256 });
+    }
+    const feeds = [];
+    for (const { id, volume_name } of agent?.feeds ?? []) {
+        const history = Object.hasOwn(input.feedLandings, id) ? input.feedLandings[id] : [];
+        const landing = feedLandingAt(history.filter((entry) => entry.resource === id && entry.volume === volume_name), startedAt);
+        if (!landing) {
+            errors.push(`Missing feed history for ${id} at ${startedAt}`);
+            continue;
+        }
+        if (landing.ambiguous)
+            errors.push(`Feed ${id} transition is ambiguous at ${startedAt} (${landing.switching_at} through ${landing.landed_at})`);
+        feeds.push({ id, revision: landing.revision, tree: landing.tree, landedAt: landing.landed_at,
+            ...(landing.commit === undefined ? {} : { commit: landing.commit }),
+            ...(landing.ref === undefined ? {} : { ref: landing.ref }),
+            ...(landing.paths === undefined ? {} : { paths: [...landing.paths] }),
+            ...(landing.period === undefined ? {} : { period: landing.period }) });
+    }
+    const memory = [];
+    for (const bank of [...(agent?.memory ?? [])].sort((a, b) => a.id.localeCompare(b.id) || a.declared_by.localeCompare(b.declared_by))) {
+        const ledger = bank.ledger_path === null ? undefined : input.memoryLedgers[bank.ledger_path];
+        if (!ledger || ledger.errors?.length) {
+            const reasons = ledger?.errors?.length ? ledger.errors : ["ledger could not be read"];
+            errors.push(...reasons.map((reason) => `Memory bank ${bank.id} (${bank.declared_by}): ${reason}`));
+            continue;
+        }
+        const seq = ledger.entries.reduce((highest, entry) => Date.parse(entry.createdAt) <= started ? Math.max(highest, entry.seq) : highest, 0);
+        memory.push({ id: bank.id, declaredBy: bank.declared_by, seq });
+    }
+    const snapshotIds = orderedUnique(agent?.snapshots ?? []);
+    for (const id of snapshotIds) {
+        if (!row.snapshots.some((entry) => entry.id === id))
+            errors.push(`Missing pre-turn snapshot for ${id}`);
+    }
+    const volumes = [];
+    for (const { id, snapshot } of [...row.snapshots].sort((a, b) => a.id.localeCompare(b.id))) {
+        if (!snapshotIds.includes(id)) {
+            errors.push(`Unexpected pre-turn snapshot for ${id}: not an effective recording root for ${agentNodeId}`);
+            continue;
+        }
+        volumes.push({ id, snapshot });
+    }
+    const messageIds = row.deliveries.flatMap(({ delivery_id }) => {
+        const match = /^moltnet:(.+)$/u.exec(delivery_id);
+        return match ? [match[1]] : [];
+    });
+    return {
+        version: MOMENT_RECORD_VERSION, agent: agentNodeId,
+        wake: {
+            at: row.deliveries[0].occurred_at, startedAt, executionId: row.execution_id,
+            deliveries: row.deliveries.map(({ delivery_id, kind, occurred_at }) => ({ deliveryId: delivery_id, kind, occurredAt: occurred_at })),
+            ...(messageIds.length ? { surface: "moltnet", messageId: messageIds[0] } : {})
+        },
+        recordedAt: input.recordedAt, exact: errors.length === 0, resources, feeds, memory,
+        moltnet: orderedUnique(agent?.networks ?? []).map((network) => ({ network, cursor: startedAt,
+            ...(messageIds.length ? { messageIds: [...messageIds] } : {}) })),
+        volumes,
+        ...(errors.length ? { errors } : {})
+    };
+};

package/dist/recording/deployment.d.ts

@@ -0,0 +1,15 @@
+import { createDockerProbeGateway, inspectDockerDeployment, type DeploymentRecord } from "../deployment/index.js";
+import { type SyncMomentRecordsOptions, type SyncMomentRecordsResult } from "./sync.js";
+export interface RecordingDeploymentHandlers {
+    createDockerProbeGateway?: typeof createDockerProbeGateway;
+    inspectDockerDeployment?: typeof inspectDockerDeployment;
+    readFeedHistory?: SyncMomentRecordsOptions["readFeedHistory"];
+    now?: () => Date;
+}
+export interface RecordingDeploymentOptions {
+    record: DeploymentRecord;
+    recordPath: string;
+    dockerCommand?: string;
+    timeoutMs?: number;
+}
+export declare const syncDeploymentMoments: (options: RecordingDeploymentOptions, handlers?: RecordingDeploymentHandlers) => Promise<SyncMomentRecordsResult>;