spawnfile 0.1.14 → 0.1.18

package/dist/compiler/training/rewind/contract.d.ts

@@ -0,0 +1,321 @@
+import { z } from "zod";
+export declare const inputIdentitySchema: z.ZodObject<{
+    section: z.ZodEnum<{
+        memory: "memory";
+        resources: "resources";
+        networks: "networks";
+    }>;
+    id: z.ZodString;
+    declaredBy: z.ZodString;
+}, z.core.$strict>;
+export declare const materializedInputSchema: z.ZodObject<{
+    section: z.ZodEnum<{
+        memory: "memory";
+        resources: "resources";
+        networks: "networks";
+    }>;
+    id: z.ZodString;
+    declaredBy: z.ZodString;
+    kind: z.ZodEnum<{
+        moltnet: "moltnet";
+        memory: "memory";
+        volume: "volume";
+        git: "git";
+        feed: "feed";
+        bundle: "bundle";
+    }>;
+    fidelity: z.ZodNullable<z.ZodEnum<{
+        exact: "exact";
+        approximate: "approximate";
+        overridden: "overridden";
+    }>>;
+    basis: z.ZodString;
+    source: z.ZodObject<{
+        commit: z.ZodOptional<z.ZodString>;
+        repository: z.ZodOptional<z.ZodString>;
+        revision: z.ZodOptional<z.ZodString>;
+        seq: z.ZodOptional<z.ZodNumber>;
+        trees: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            root: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+            exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        sha256: z.ZodOptional<z.ZodString>;
+        agentSlug: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        switchingAt: z.ZodOptional<z.ZodISODateTime>;
+        landedAt: z.ZodOptional<z.ZodISODateTime>;
+        prepared: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>;
+    path: z.ZodNullable<z.ZodString>;
+    notes: z.ZodArray<z.ZodString>;
+    refusal: z.ZodNullable<z.ZodString>;
+    build: z.ZodOptional<z.ZodLiteral<"deferred">>;
+}, z.core.$strict>;
+export type MaterializedInput = z.infer<typeof materializedInputSchema>;
+export declare const materializedMomentSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.materialized-moment.v1">;
+    status: z.ZodEnum<{
+        materialized: "materialized";
+        refused: "refused";
+    }>;
+    agent: z.ZodString;
+    example: z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            train: "train";
+            test: "test";
+            validation: "validation";
+        }>;
+        dataset: z.ZodString;
+    }, z.core.$strict>;
+    at: z.ZodISODateTime;
+    effectiveAt: z.ZodISODateTime;
+    inputs: z.ZodArray<z.ZodObject<{
+        section: z.ZodEnum<{
+            memory: "memory";
+            resources: "resources";
+            networks: "networks";
+        }>;
+        id: z.ZodString;
+        declaredBy: z.ZodString;
+        kind: z.ZodEnum<{
+            moltnet: "moltnet";
+            memory: "memory";
+            volume: "volume";
+            git: "git";
+            feed: "feed";
+            bundle: "bundle";
+        }>;
+        fidelity: z.ZodNullable<z.ZodEnum<{
+            exact: "exact";
+            approximate: "approximate";
+            overridden: "overridden";
+        }>>;
+        basis: z.ZodString;
+        source: z.ZodObject<{
+            commit: z.ZodOptional<z.ZodString>;
+            repository: z.ZodOptional<z.ZodString>;
+            revision: z.ZodOptional<z.ZodString>;
+            seq: z.ZodOptional<z.ZodNumber>;
+            trees: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                root: z.ZodString;
+                prefix: z.ZodOptional<z.ZodString>;
+                exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            sha256: z.ZodOptional<z.ZodString>;
+            agentSlug: z.ZodOptional<z.ZodString>;
+            snapshot: z.ZodOptional<z.ZodString>;
+            cursor: z.ZodOptional<z.ZodString>;
+            switchingAt: z.ZodOptional<z.ZodISODateTime>;
+            landedAt: z.ZodOptional<z.ZodISODateTime>;
+            prepared: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strict>;
+        path: z.ZodNullable<z.ZodString>;
+        notes: z.ZodArray<z.ZodString>;
+        refusal: z.ZodNullable<z.ZodString>;
+        build: z.ZodOptional<z.ZodLiteral<"deferred">>;
+    }, z.core.$strict>>;
+    record: z.ZodObject<{
+        matched: z.ZodBoolean;
+        attempts: z.ZodOptional<z.ZodNumber>;
+        selectedStartedAt: z.ZodOptional<z.ZodISODateTime>;
+        executionId: z.ZodOptional<z.ZodString>;
+        selection: z.ZodOptional<z.ZodLiteral<"earliest-startedAt">>;
+    }, z.core.$strict>;
+    leakCheck: z.ZodObject<{
+        ok: z.ZodBoolean;
+        findings: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type MaterializedMoment = z.infer<typeof materializedMomentSchema>;
+export declare const leakFindingSchema: z.ZodObject<{
+    input: z.ZodNullable<z.ZodObject<{
+        section: z.ZodEnum<{
+            memory: "memory";
+            resources: "resources";
+            networks: "networks";
+        }>;
+        id: z.ZodString;
+        declaredBy: z.ZodString;
+    }, z.core.$strict>>;
+    class: z.ZodEnum<{
+        snapshot: "snapshot";
+        "bundle-entry": "bundle-entry";
+        "file-time": "file-time";
+        "symlink-escape": "symlink-escape";
+        "git-object": "git-object";
+        "memory-event": "memory-event";
+        "moltnet-message": "moltnet-message";
+        "moltnet-event": "moltnet-event";
+        "moltnet-room": "moltnet-room";
+        "feed-identity": "feed-identity";
+        "dated-path": "dated-path";
+    }>;
+    path: z.ZodString;
+    detail: z.ZodString;
+}, z.core.$strict>;
+export declare const leakCheckSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.leak-check.v1">;
+    at: z.ZodISODateTime;
+    ok: z.ZodBoolean;
+    checked: z.ZodObject<{
+        files: z.ZodNumber;
+        gitObjects: z.ZodNumber;
+        memoryEvents: z.ZodNumber;
+        moltnetMessages: z.ZodNumber;
+        moltnetEvents: z.ZodNumber;
+        snapshots: z.ZodNumber;
+    }, z.core.$strict>;
+    findings: z.ZodArray<z.ZodObject<{
+        input: z.ZodNullable<z.ZodObject<{
+            section: z.ZodEnum<{
+                memory: "memory";
+                resources: "resources";
+                networks: "networks";
+            }>;
+            id: z.ZodString;
+            declaredBy: z.ZodString;
+        }, z.core.$strict>>;
+        class: z.ZodEnum<{
+            snapshot: "snapshot";
+            "bundle-entry": "bundle-entry";
+            "file-time": "file-time";
+            "symlink-escape": "symlink-escape";
+            "git-object": "git-object";
+            "memory-event": "memory-event";
+            "moltnet-message": "moltnet-message";
+            "moltnet-event": "moltnet-event";
+            "moltnet-room": "moltnet-room";
+            "feed-identity": "feed-identity";
+            "dated-path": "dated-path";
+        }>;
+        path: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LeakCheck = z.infer<typeof leakCheckSchema>;
+export type LeakFinding = z.infer<typeof leakFindingSchema>;
+export declare const taskClockSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.task-clock.v1">;
+    origin: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const materializedMomentJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.materialized-moment.v1">;
+    status: z.ZodEnum<{
+        materialized: "materialized";
+        refused: "refused";
+    }>;
+    agent: z.ZodString;
+    example: z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            train: "train";
+            test: "test";
+            validation: "validation";
+        }>;
+        dataset: z.ZodString;
+    }, z.core.$strict>;
+    at: z.ZodISODateTime;
+    effectiveAt: z.ZodISODateTime;
+    inputs: z.ZodArray<z.ZodObject<{
+        section: z.ZodEnum<{
+            memory: "memory";
+            resources: "resources";
+            networks: "networks";
+        }>;
+        id: z.ZodString;
+        declaredBy: z.ZodString;
+        kind: z.ZodEnum<{
+            moltnet: "moltnet";
+            memory: "memory";
+            volume: "volume";
+            git: "git";
+            feed: "feed";
+            bundle: "bundle";
+        }>;
+        fidelity: z.ZodNullable<z.ZodEnum<{
+            exact: "exact";
+            approximate: "approximate";
+            overridden: "overridden";
+        }>>;
+        basis: z.ZodString;
+        source: z.ZodObject<{
+            commit: z.ZodOptional<z.ZodString>;
+            repository: z.ZodOptional<z.ZodString>;
+            revision: z.ZodOptional<z.ZodString>;
+            seq: z.ZodOptional<z.ZodNumber>;
+            trees: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                root: z.ZodString;
+                prefix: z.ZodOptional<z.ZodString>;
+                exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            sha256: z.ZodOptional<z.ZodString>;
+            agentSlug: z.ZodOptional<z.ZodString>;
+            snapshot: z.ZodOptional<z.ZodString>;
+            cursor: z.ZodOptional<z.ZodString>;
+            switchingAt: z.ZodOptional<z.ZodISODateTime>;
+            landedAt: z.ZodOptional<z.ZodISODateTime>;
+            prepared: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strict>;
+        path: z.ZodNullable<z.ZodString>;
+        notes: z.ZodArray<z.ZodString>;
+        refusal: z.ZodNullable<z.ZodString>;
+        build: z.ZodOptional<z.ZodLiteral<"deferred">>;
+    }, z.core.$strict>>;
+    record: z.ZodObject<{
+        matched: z.ZodBoolean;
+        attempts: z.ZodOptional<z.ZodNumber>;
+        selectedStartedAt: z.ZodOptional<z.ZodISODateTime>;
+        executionId: z.ZodOptional<z.ZodString>;
+        selection: z.ZodOptional<z.ZodLiteral<"earliest-startedAt">>;
+    }, z.core.$strict>;
+    leakCheck: z.ZodObject<{
+        ok: z.ZodBoolean;
+        findings: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>>;
+export declare const leakCheckJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.leak-check.v1">;
+    at: z.ZodISODateTime;
+    ok: z.ZodBoolean;
+    checked: z.ZodObject<{
+        files: z.ZodNumber;
+        gitObjects: z.ZodNumber;
+        memoryEvents: z.ZodNumber;
+        moltnetMessages: z.ZodNumber;
+        moltnetEvents: z.ZodNumber;
+        snapshots: z.ZodNumber;
+    }, z.core.$strict>;
+    findings: z.ZodArray<z.ZodObject<{
+        input: z.ZodNullable<z.ZodObject<{
+            section: z.ZodEnum<{
+                memory: "memory";
+                resources: "resources";
+                networks: "networks";
+            }>;
+            id: z.ZodString;
+            declaredBy: z.ZodString;
+        }, z.core.$strict>>;
+        class: z.ZodEnum<{
+            snapshot: "snapshot";
+            "bundle-entry": "bundle-entry";
+            "file-time": "file-time";
+            "symlink-escape": "symlink-escape";
+            "git-object": "git-object";
+            "memory-event": "memory-event";
+            "moltnet-message": "moltnet-message";
+            "moltnet-event": "moltnet-event";
+            "moltnet-room": "moltnet-room";
+            "feed-identity": "feed-identity";
+            "dated-path": "dated-path";
+        }>;
+        path: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+export declare const taskClockJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.task-clock.v1">;
+    origin: z.ZodISODateTime;
+}, z.core.$strict>>;

package/dist/compiler/training/rewind/contract.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { recordedSha256Schema } from "../../../recording/index.js";
+import { trainingInstantSchema } from "../../../manifest/index.js";
+const text = z.string().min(1);
+const count = z.number().int().nonnegative();
+export const inputIdentitySchema = z.object({
+    section: z.enum(["resources", "memory", "networks"]), id: text, declaredBy: text
+}).strict();
+export const materializedInputSchema = inputIdentitySchema.extend({
+    kind: z.enum(["git", "bundle", "feed", "volume", "memory", "moltnet"]),
+    fidelity: z.enum(["exact", "approximate", "overridden"]).nullable(), basis: text,
+    source: z.object({ commit: text.optional(), repository: text.optional(), revision: text.optional(), seq: count.optional(),
+        trees: z.array(z.object({ root: z.string(), prefix: z.string().optional(), exclude: z.array(text).optional() }).strict()).min(1).optional(),
+        sha256: recordedSha256Schema.optional(), agentSlug: text.optional(), snapshot: text.optional(), cursor: text.optional(),
+        switchingAt: trainingInstantSchema.optional(), landedAt: trainingInstantSchema.optional(), prepared: z.literal(true).optional() }).strict(),
+    path: text.nullable(), notes: z.array(z.string()), refusal: text.nullable(), build: z.literal("deferred").optional()
+}).strict();
+export const materializedMomentSchema = z.object({
+    version: z.literal("spawnfile.materialized-moment.v1"), status: z.enum(["materialized", "refused"]),
+    agent: text, example: z.object({ id: text, role: z.enum(["train", "validation", "test"]), dataset: text }).strict(),
+    at: trainingInstantSchema, effectiveAt: trainingInstantSchema, inputs: z.array(materializedInputSchema),
+    record: z.object({ matched: z.boolean(), attempts: count.optional(), selectedStartedAt: trainingInstantSchema.optional(),
+        executionId: text.optional(), selection: z.literal("earliest-startedAt").optional() }).strict(),
+    leakCheck: z.object({ ok: z.boolean(), findings: count }).strict()
+}).strict();
+export const leakFindingSchema = z.object({
+    input: inputIdentitySchema.nullable(),
+    class: z.enum(["bundle-entry", "file-time", "symlink-escape", "git-object", "memory-event", "moltnet-message",
+        "moltnet-event", "moltnet-room", "feed-identity", "dated-path", "snapshot"]), path: text, detail: text
+}).strict();
+export const leakCheckSchema = z.object({
+    version: z.literal("spawnfile.leak-check.v1"), at: trainingInstantSchema, ok: z.boolean(),
+    checked: z.object({ files: count, gitObjects: count, memoryEvents: count, moltnetMessages: count,
+        moltnetEvents: count, snapshots: count }).strict(), findings: z.array(leakFindingSchema)
+}).strict();
+export const taskClockSchema = z.object({ version: z.literal("spawnfile.task-clock.v1"), origin: trainingInstantSchema }).strict();
+export const materializedMomentJsonSchema = z.toJSONSchema(materializedMomentSchema);
+export const leakCheckJsonSchema = z.toJSONSchema(leakCheckSchema);
+export const taskClockJsonSchema = z.toJSONSchema(taskClockSchema);

package/dist/compiler/training/rewind/deployedResource.d.ts

@@ -0,0 +1,22 @@
+import type { InputContext } from "./types.js";
+/** Deployment IDs remain evidence only: all bytes are read from the contained history mirror. */
+export declare const deployedResource: (context: InputContext) => Promise<{
+    pin: {
+        id: string;
+        kind: "git";
+        commit: string;
+        sha256: string;
+        agent_node_ids: string[];
+        url?: string | undefined;
+        declared_by?: string | undefined;
+    } | {
+        id: string;
+        kind: "bundle";
+        sha256: string;
+        agent_node_ids: string[];
+        origin?: string | undefined;
+        declared_by?: string | undefined;
+    };
+    exact: boolean;
+    notes: string[];
+} | null>;

package/dist/compiler/training/rewind/deployedResource.js

@@ -0,0 +1,19 @@
+/** Deployment IDs remain evidence only: all bytes are read from the contained history mirror. */
+export const deployedResource = async (context) => {
+    const agentId = context.agentId ?? context.record?.agent
+        ?? (context.input.declaredBy.startsWith("agent:") ? context.input.declaredBy : undefined);
+    const entry = await context.history?.deploymentResources(context.at, agentId);
+    if (!entry)
+        return null;
+    const pins = entry.resources.filter((resource) => resource.id === context.input.id
+        && (resource.declared_by === undefined || resource.declared_by === context.input.declaredBy));
+    if (pins.length > 1)
+        throw new Error(`Ambiguous deployment resource pin for ${context.input.declaredBy}/${context.input.id}`);
+    const pin = pins[0];
+    if (!pin)
+        return null;
+    const exact = entry.activation_exact && entry.exact !== false;
+    return { pin, exact, notes: exact ? [] : [entry.activation_note
+                ?? (entry.rolled_back_at ? "Trial instant falls inside an inexact deployment rollback interval."
+                    : "Deployment activation boundary is inexact; an overlapping predecessor may have served different pins.")] };
+};

package/dist/compiler/training/rewind/feed.d.ts

@@ -0,0 +1,12 @@
+import type { TeamWorkspaceResource } from "../../../manifest/index.js";
+import { type SelectedCommit } from "./gitProcess.js";
+import type { InputContext, InputResult } from "./types.js";
+type VolumeFeed = NonNullable<Extract<TeamWorkspaceResource, {
+    kind: "volume";
+}>["feed"]>;
+/** Same template/fallback ordering as chooseFeedRef, with historical eligibility replacing existence. */
+export declare const selectFeedCommit: (feed: VolumeFeed, repository: string, at: string) => Promise<SelectedCommit & {
+    ref: string;
+}>;
+export declare const materializeFeed: (context: InputContext) => Promise<InputResult>;
+export {};

package/dist/compiler/training/rewind/feed.js

@@ -0,0 +1,182 @@
+import { lstat, mkdir, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { digestDirectory, expandFeedPaths, expandFeedRefTemplate, FEED_IDENTITY_FILE, FEED_IDENTITY_VERSION, feedLandingAt, isFeedLanding } from "../../../volume/index.js";
+import { assertPreparedFeedRevision, feedGitRevision } from "./feedContent.js";
+import { resolveRecordedCommit } from "./recordedCommit.js";
+import { exportFeedGitTree } from "./gitArchive.js";
+import { safeCommittedPath } from "./gitTree.js";
+import { assertLocalGitRepository } from "./gitHistory.js";
+import { assertCommitNotFuture, commitAt } from "./gitProcess.js";
+import { historyKey } from "./history.js";
+import { compareInstants } from "./instant.js";
+const feedPaths = (paths) => paths?.length ? paths : undefined;
+const treeName = (tree) => tree.replace(/^trees\//u, "");
+/** Same template/fallback ordering as chooseFeedRef, with historical eligibility replacing existence. */
+export const selectFeedCommit = async (feed, repository, at) => {
+    if (!feed.git)
+        throw new Error("Directory feed cannot be rewound without a landing log; provide an override");
+    if (feed.freeze)
+        throw new Error("Feed freeze/waiting state cannot be reconstructed without a landing log; provide an override");
+    const rule = feed.git.ref;
+    if (typeof rule === "object" && rule.command)
+        throw new Error("Feed command refs cannot be evaluated historically without a landing log; provide an override");
+    const selectors = typeof rule === "object" ? [expandFeedRefTemplate(rule.template, new Date(at)), rule.fallback]
+        : [rule ?? "HEAD"];
+    for (const selector of selectors) {
+        if (!selector)
+            continue;
+        const selected = await commitAt(repository, selector, at);
+        if (selected)
+            return { ...selected, ref: selector };
+    }
+    throw new Error(`No feed ref has a first-parent commit at or before ${at}`);
+};
+const fileCount = async (directory) => {
+    let count = 0;
+    for (const name of await readdir(directory)) {
+        const file = path.join(directory, name), stats = await lstat(file);
+        count += stats.isDirectory() ? await fileCount(file) : 1;
+    }
+    return count;
+};
+export const materializeFeed = async (context) => {
+    const { input, history } = context;
+    if (input.section !== "resources" || input.declaration.kind !== "volume" || !input.declaration.feed)
+        throw new Error("Feed rewind requires a fed volume");
+    const resource = input.declaration, feed = resource.feed;
+    if (input.overridden) {
+        await mkdir(context.destination, { recursive: true });
+        return { fidelity: "overridden", basis: "override", source: {}, notes: ["Volume override starts empty; no feed refresh is run."], instant: context.at };
+    }
+    if (!history)
+        throw new Error(`Missing feed history for ${input.id}; --history is required`);
+    const key = `feeds/${historyKey(input)}`;
+    const log = await history.feedLandings(key, input.id);
+    let landing, repository = null, basis, ambiguous = false;
+    const openRepository = async () => {
+        repository ??= await history.repository(`${key}/repo`);
+        if (!repository)
+            throw new Error(`Missing feed source repository for ${input.id}`);
+        await assertLocalGitRepository(repository, history);
+        return repository;
+    };
+    for (const [index, entry] of (log ?? []).entries()) {
+        for (const selected of entry.paths ?? [])
+            safeCommittedPath(selected);
+        if (!entry.commit)
+            continue;
+        try {
+            await resolveRecordedCommit(await openRepository(), entry.commit);
+        }
+        catch (error) {
+            throw new Error(`Invalid history ${key}/landings.jsonl:${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    for (const candidate of context.candidateRecords ?? []) {
+        const entry = candidate.feeds.find((record) => record.id === input.id);
+        if (entry?.commit !== undefined)
+            await resolveRecordedCommit(await openRepository(), entry.commit);
+    }
+    const record = context.record?.feeds.find((entry) => entry.id === input.id);
+    const recordedCommit = record?.commit === undefined ? undefined : await resolveRecordedCommit(await openRepository(), record.commit);
+    const matching = record ? log?.findLast((entry) => entry.revision === record.revision && treeName(entry.tree) === treeName(record.tree)
+        && compareInstants(entry.landed_at, record.landedAt) === 0 && entry.commit === recordedCommit) : undefined;
+    const selected = record ? null : feedLandingAt(log, context.at);
+    if (record) {
+        // A wake pin is authoritative even if a later attempt or landing changed the currently selected log row.
+        landing = { version: "spawnfile.volume-feed-landing.v1", resource: input.id, volume: matching?.volume ?? resource.name,
+            revision: record.revision, tree: `trees/${treeName(record.tree)}`, landed_at: record.landedAt,
+            switching_at: matching?.switching_at ?? record.landedAt,
+            source: matching?.source ?? (feed.git ? { kind: "git", repo: feed.git.repo } : { kind: "directory", directory: feed.directory }),
+            ...(recordedCommit ? { commit: recordedCommit, ref: record.ref ?? recordedCommit } : {}),
+            ...(record.paths ? { paths: record.paths } : {}), ...(record.period ? { period: record.period } : {}) };
+        basis = "record";
+    }
+    else if (selected) {
+        landing = selected;
+        ambiguous = selected.ambiguous === true;
+        basis = "landing-log";
+    }
+    else {
+        if (log.length)
+            throw new Error(`Feed ${input.id} has no landed state at ${context.at}; provide an override`);
+        // Refuse unknown historical behavior before touching any declared source or executing any command.
+        if (!feed.git || feed.freeze || typeof feed.git.ref === "object" && feed.git.ref.command)
+            await selectFeedCommit(feed, "", context.at);
+        if (feed.include || feed.prepare)
+            throw new Error("Prepared/included feed requires a landing log and retained tree bytes");
+        const repo = await openRepository(), commit = await selectFeedCommit(feed, repo, context.at);
+        const paths = expandFeedPaths(feed.git.paths, new Date(context.at));
+        const revision = feedGitRevision(repo, commit.commit, commit.ref, paths);
+        landing = { version: "spawnfile.volume-feed-landing.v1", resource: input.id, volume: resource.name,
+            revision, tree: `trees/${revision}`, source: { kind: "git", repo: feed.git.repo },
+            commit: commit.commit, ref: commit.ref, ...(paths ? { paths } : {}), switching_at: commit.instant, landed_at: commit.instant };
+        basis = "feed-rule-at";
+    }
+    if (!isFeedLanding(landing))
+        throw new Error(`Invalid feed landing for ${input.id}`);
+    for (const selected of landing.paths ?? [])
+        safeCommittedPath(selected);
+    // Selection owns this check: retained/prepared bytes must obey the same cutoff as extraction.
+    if (landing.source.kind === "git" && (!landing.commit || !landing.ref))
+        throw new Error("Git feed landing must record its commit and ref");
+    if (landing.commit) {
+        landing.commit = await resolveRecordedCommit(await openRepository(), landing.commit);
+        await assertCommitNotFuture(await openRepository(), landing.commit, context.at);
+    }
+    const retainedName = treeName(landing.tree), tree = path.join(context.destination, "trees", retainedName);
+    const isPrepared = landing.source.prepared !== undefined
+        || basis === "record" && !matching && (feed.include !== undefined || feed.prepare !== undefined);
+    if (landing.source.prepared) {
+        assertPreparedFeedRevision(landing.revision, landing.source.prepared);
+        if (landing.commit && feedGitRevision(await openRepository(), landing.commit, landing.ref, landing.paths)
+            !== landing.source.prepared.source_revision)
+            throw new Error("Prepared feed source revision disagrees with selected commit and paths");
+    }
+    if (landing.source.kind === "git" && !isPrepared) {
+        const repo = await openRepository();
+        const revision = feedGitRevision(repo, landing.commit, landing.ref, landing.paths);
+        if (revision !== landing.revision)
+            throw new Error(`Feed revision mismatch: recorded ${landing.revision}, reconstructed ${revision}`);
+        await exportFeedGitTree(repo, landing.commit, tree, feedPaths(landing.paths));
+        if (await history.path(`${key}/trees/${retainedName}`)) {
+            const retained = path.join(context.destination, ".retained-check");
+            try {
+                await history.copyTree(`${key}/trees/${retainedName}`, retained);
+                if (digestDirectory(retained) !== digestDirectory(tree))
+                    throw new Error("Retained git feed bytes disagree with selected commit and paths");
+            }
+            finally {
+                await rm(retained, { recursive: true, force: true });
+            }
+        }
+    }
+    else {
+        if (!await history.path(`${key}/trees/${retainedName}`))
+            throw new Error("Directory/prepared/included feed requires retained landed tree bytes");
+        await history.copyTree(`${key}/trees/${retainedName}`, tree);
+    }
+    if (landing.source.kind === "directory" && !isPrepared) {
+        const actual = digestDirectory(tree);
+        if (actual !== landing.revision)
+            throw new Error(`Directory feed revision mismatch: recorded ${landing.revision}, retained ${actual}`);
+    }
+    const files = await fileCount(tree);
+    if (!files)
+        throw new Error("Retained feed tree is empty; a fed volume never serves nothing");
+    const prepared = landing.source.prepared ? { prepared: landing.source.prepared } : {};
+    const identity = { version: FEED_IDENTITY_VERSION, resource: input.id, volume: landing.volume, revision: landing.revision,
+        tree: `trees/${retainedName}`, files, landed_at: landing.landed_at,
+        source: landing.source.kind === "git" ? { kind: "git", commit: landing.commit, ref: landing.ref, paths: landing.paths ?? null, ...prepared }
+            : { kind: "directory", ...prepared } };
+    await symlink(identity.tree, path.join(context.destination, "current"));
+    await writeFile(path.join(context.destination, FEED_IDENTITY_FILE), `${JSON.stringify(identity, null, 2)}\n`);
+    return { fidelity: isPrepared || basis === "feed-rule-at" || ambiguous ? "approximate" : "exact", basis,
+        source: { revision: landing.revision, landedAt: landing.landed_at,
+            ...(basis === "landing-log" || matching ? { switchingAt: landing.switching_at } : {}),
+            ...(landing.commit ? { commit: landing.commit } : {}), ...(isPrepared ? { prepared: true } : {}) },
+        instant: compareInstants(landing.landed_at, context.at) > 0 ? context.at : landing.landed_at,
+        notes: [...(isPrepared ? ["prepared output not content-verifiable"] : []),
+            ...(ambiguous ? ["The trial instant falls inside an ambiguous feed transition; the incoming landing is used."]
+                : basis === "feed-rule-at" ? ["Commit dates do not establish when a ref advanced; historical freeze holds cannot be reconstructed."] : [])] };
+};

package/dist/compiler/training/rewind/feedContent.d.ts

@@ -0,0 +1,6 @@
+import { type FeedIdentity } from "../../../volume/index.js";
+export declare const feedGitRevision: (repo: string, commit: string, ref: string, paths?: string[] | null) => string;
+/** A prepared revision proves the recipe/source identity, never its output bytes. */
+export declare const assertPreparedFeedRevision: (revision: string, prepared: NonNullable<FeedIdentity["source"]["prepared"]>) => void;
+/** Acceptance re-extracts from history; it does not consume any producer-computed content digest. */
+export declare const verifyPlainFeedTree: (repo: string, identity: FeedIdentity, directory: string) => Promise<void>;

package/dist/compiler/training/rewind/feedContent.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { digestDirectory, resolveFeedSource } from "../../../volume/index.js";
+import { exportFeedGitTree } from "./gitArchive.js";
+import { rewindGitSync } from "./gitProcess.js";
+const revisionExec = (command, args) => {
+    if (command !== "git" || args[0] !== "-C" || !args[1])
+        throw new Error("Feed revision may only read a local git repository");
+    return rewindGitSync(args[1], args.slice(2));
+};
+export const feedGitRevision = (repo, commit, ref, paths) => resolveFeedSource({ kind: "git", fetch: false, repo, ref: commit, label: ref, paths: paths?.length ? paths : undefined }, { exec: revisionExec }).revision;
+/** A prepared revision proves the recipe/source identity, never its output bytes. */
+export const assertPreparedFeedRevision = (revision, prepared) => {
+    const provenance = { include: prepared.include, prepare: prepared.prepare, source_revision: prepared.source_revision };
+    const actual = createHash("sha256").update(`prepared\n${JSON.stringify(provenance)}\n`).digest("hex");
+    if (actual !== revision)
+        throw new Error("Prepared feed revision disagrees with its provenance");
+};
+/** Acceptance re-extracts from history; it does not consume any producer-computed content digest. */
+export const verifyPlainFeedTree = async (repo, identity, directory) => {
+    const source = identity.source;
+    if (source.kind !== "git")
+        throw new Error("Plain git feed verification requires git provenance");
+    if (feedGitRevision(repo, source.commit, source.ref, source.paths) !== identity.revision) {
+        throw new Error("Feed revision disagrees with selected commit and paths");
+    }
+    const scratch = await mkdtemp(path.join(os.tmpdir(), "spawnfile-feed-check-"));
+    try {
+        await exportFeedGitTree(repo, source.commit, scratch, source.paths?.length ? source.paths : undefined);
+        if (digestDirectory(directory) !== digestDirectory(scratch))
+            throw new Error("Git feed bytes disagree with selected commit and paths");
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+};

package/dist/compiler/training/rewind/git.d.ts

@@ -0,0 +1,8 @@
+import type { InputContext, InputResult } from "./types.js";
+export { commitAt, commitInstant, resolveRewindCommit, rewindGit, rewindGitEnvironment, rewindGitSync, selectCommitAt } from "./gitProcess.js";
+export { exportGitTree } from "./gitTree.js";
+export { assertLocalGitRepository } from "./gitHistory.js";
+export declare const localRepositoryPath: (location: string, base: string) => string;
+/** Import only the transitive object set of the selected commit; no source refs or config survive. */
+export declare const materializeCleanRepository: (repository: string, commit: string, destination: string) => Promise<void>;
+export declare const materializeGit: (context: InputContext) => Promise<InputResult>;