@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/source/index.d.ts

@@ -0,0 +1,10 @@
+/** App source seed receipts, seed claims and the fork algorithm, owned
+ * generically here; the Publisher supplies D1 adapters and the retained Git
+ * admission transport. The operator's Node-only template push (it runs the
+ * `git` executable) is deliberately not re-exported here, so Worker bundles
+ * never import it: use `@fungi.computer/oyster/source/template-push`. */
+export { templateRepositoryForApp } from "./template-repository.js";
+export { seedReceiptInputSchema, sameReceipt, type PublisherTemplateSeedReceipt, type PublisherTemplateSeedReceipts, } from "./seed-receipt.js";
+export { readTeamAppSeedProvenance, privateTeamBuildSource, TeamAppSourceError, } from "./team-source.js";
+export { parseTemplateSeedClaim, recordTemplateSeed, templateSeedClaimSchema, TEMPLATE_SEED_CLAIM_MAX_BYTES, type TemplateSeedClaim, } from "./template-seed.js";
+export { forkAppSource, type AppSourceForkResult } from "./fork.js";

package/dist/source/index.js

@@ -0,0 +1,10 @@
+/** App source seed receipts, seed claims and the fork algorithm, owned
+ * generically here; the Publisher supplies D1 adapters and the retained Git
+ * admission transport. The operator's Node-only template push (it runs the
+ * `git` executable) is deliberately not re-exported here, so Worker bundles
+ * never import it: use `@fungi.computer/oyster/source/template-push`. */
+export { templateRepositoryForApp } from "./template-repository.js";
+export { seedReceiptInputSchema, sameReceipt, } from "./seed-receipt.js";
+export { readTeamAppSeedProvenance, privateTeamBuildSource, TeamAppSourceError, } from "./team-source.js";
+export { parseTemplateSeedClaim, recordTemplateSeed, templateSeedClaimSchema, TEMPLATE_SEED_CLAIM_MAX_BYTES, } from "./template-seed.js";
+export { forkAppSource } from "./fork.js";

package/dist/source/seed-receipt.d.ts

@@ -0,0 +1,53 @@
+import { appIdSchema, sha256DigestSchema, sourceRevisionSchema } from "@fungi.computer/puffball/effect";
+import * as Schema from "effect/Schema";
+import { type PinnedRecipe } from "../build-contract.js";
+export declare const seedReceiptInputSchema: Schema.Struct<{
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly sourceRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
+    readonly sourceTreeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+    readonly seedRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
+    readonly recipe: Schema.Struct<{
+        readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+        readonly bundle: Schema.Literal<true>;
+        readonly entry: Schema.String;
+        readonly format: Schema.Literals<readonly ["html", "esm", "assets"]>;
+        readonly assets: Schema.optional<Schema.Struct<{
+            readonly maxManifestBytes: Schema.Number;
+            readonly maxObjects: Schema.Number;
+            readonly maxObjectBytes: Schema.Number;
+            readonly maxTotalBytes: Schema.Number;
+        }>>;
+        readonly assetBase: Schema.optionalKey<Schema.String>;
+        readonly toolchain: Schema.$Record<Schema.String, Schema.String>;
+        readonly maxOutputBytes: Schema.Number;
+        readonly platform: Schema.Literals<readonly ["browser", "neutral"]>;
+        readonly backend: Schema.Union<readonly [Schema.Null, Schema.Struct<{
+            readonly entry: Schema.optional<Schema.String>;
+            readonly runtime: Schema.Struct<{
+                readonly kind: Schema.Literal<"durable-facet">;
+                readonly stateSchema: Schema.Number;
+            }>;
+            readonly compatibilityDate: Schema.String;
+            readonly exportName: Schema.String;
+        }>]>;
+        readonly target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
+    }>;
+    readonly buildRecipeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+}>;
+export type PublisherTemplateSeedReceipt = Readonly<{
+    appId: Schema.Schema.Type<typeof appIdSchema>;
+    repository: string;
+    sourceRevision: Schema.Schema.Type<typeof sourceRevisionSchema>;
+    sourceTreeDigest: Schema.Schema.Type<typeof sha256DigestSchema>;
+    seedRevision: Schema.Schema.Type<typeof sourceRevisionSchema>;
+    recipe: PinnedRecipe;
+    buildRecipeDigest: Schema.Schema.Type<typeof sha256DigestSchema>;
+}>;
+/** Append-only proof that an exact projected template was seeded, keyed by
+ * the template's repository and recorded seed revision. The Publisher's D1
+ * adapter is the only durable implementation; this is the port it fulfills. */
+export type PublisherTemplateSeedReceipts = Readonly<{
+    read(appId: PublisherTemplateSeedReceipt["appId"], seedRevision: PublisherTemplateSeedReceipt["seedRevision"]): Promise<PublisherTemplateSeedReceipt | null>;
+    record(input: Schema.Schema.Type<typeof seedReceiptInputSchema>): Promise<PublisherTemplateSeedReceipt>;
+}>;
+export declare const sameReceipt: (left: PublisherTemplateSeedReceipt, right: PublisherTemplateSeedReceipt) => boolean;

package/dist/source/seed-receipt.js

@@ -0,0 +1,18 @@
+import { appIdSchema, sha256DigestSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+import * as Schema from "effect/Schema";
+import { capturedPinnedRecipeSchema, } from "../build-contract.js";
+export const seedReceiptInputSchema = Schema.Struct({
+    appId: appIdSchema,
+    sourceRevision: sourceRevisionSchema,
+    sourceTreeDigest: sha256DigestSchema,
+    seedRevision: sourceRevisionSchema,
+    recipe: capturedPinnedRecipeSchema,
+    buildRecipeDigest: sha256DigestSchema,
+});
+export const sameReceipt = (left, right) => left.appId === right.appId &&
+    left.repository === right.repository &&
+    left.sourceRevision === right.sourceRevision &&
+    left.sourceTreeDigest === right.sourceTreeDigest &&
+    left.seedRevision === right.seedRevision &&
+    JSON.stringify(left.recipe) === JSON.stringify(right.recipe) &&
+    left.buildRecipeDigest === right.buildRecipeDigest;

package/dist/source/team-source.d.ts

@@ -0,0 +1,32 @@
+import type { TeamAppPublisherRegistry } from "@fungi.computer/puffball/publisher";
+import type { PublisherTemplateSeedReceipt } from "./seed-receipt.js";
+export declare class TeamAppSourceError extends Error {
+    readonly code: "denied" | "unavailable";
+    constructor(code: "denied" | "unavailable");
+}
+export declare function readTeamAppSeedProvenance(options: {
+    appId: string;
+    teamId: string;
+    registry: TeamAppPublisherRegistry;
+    readSeedReceipt(appId: PublisherTemplateSeedReceipt["appId"], seedRevision: PublisherTemplateSeedReceipt["seedRevision"]): Promise<PublisherTemplateSeedReceipt | null>;
+}): Promise<Readonly<{
+    appId: string;
+    repository: string;
+    templateSeed: Readonly<{
+        appId: string;
+        revision: string;
+    }>;
+    recipe: PublisherTemplateSeedReceipt["recipe"];
+    buildRecipeDigest: PublisherTemplateSeedReceipt["buildRecipeDigest"];
+}>>;
+/** A fork keeps the seed's exact builder; private UI assets use Vite's relative base. */
+export declare function privateTeamBuildSource(source: Awaited<ReturnType<typeof readTeamAppSeedProvenance>>): Readonly<{
+    appId: string;
+    repository: string;
+    templateSeed: Readonly<{
+        appId: string;
+        revision: string;
+    }>;
+    recipe: PublisherTemplateSeedReceipt["recipe"];
+    buildRecipeDigest: PublisherTemplateSeedReceipt["buildRecipeDigest"];
+}>;

package/dist/source/team-source.js

@@ -0,0 +1,42 @@
+import { parseAppId } from "@fungi.computer/puffball";
+import { digestPinnedRecipe } from "../build-contract.js";
+import { templateRepositoryForApp } from "./template-repository.js";
+export class TeamAppSourceError extends Error {
+    code;
+    constructor(code) {
+        super(`Team App source ${code}`);
+        this.code = code;
+        this.name = "TeamAppSourceError";
+    }
+}
+export async function readTeamAppSeedProvenance(options) {
+    const appId = parseAppId(options.appId);
+    const authorization = await options.registry.authorize(appId, options.teamId);
+    if (authorization.kind !== "authorized")
+        throw new TeamAppSourceError("denied");
+    const registration = authorization.registration;
+    const templateSeed = registration.templateSeed;
+    if (registration.source.provider !== "artifacts" ||
+        templateSeed === undefined)
+        throw new TeamAppSourceError("unavailable");
+    const receipt = await options.readSeedReceipt(parseAppId(templateSeed.appId), templateSeed.revision);
+    if (receipt?.appId !== templateSeed.appId ||
+        receipt.seedRevision !== templateSeed.revision ||
+        receipt.repository !== templateRepositoryForApp(templateSeed.appId) ||
+        digestPinnedRecipe(receipt.recipe) !== receipt.buildRecipeDigest)
+        throw new TeamAppSourceError("unavailable");
+    return Object.freeze({
+        appId,
+        repository: registration.source.repository,
+        templateSeed,
+        recipe: receipt.recipe,
+        buildRecipeDigest: receipt.buildRecipeDigest,
+    });
+}
+/** A fork keeps the seed's exact builder; private UI assets use Vite's relative base. */
+export function privateTeamBuildSource(source) {
+    if (source.recipe.format !== "assets")
+        return source;
+    const recipe = { ...source.recipe, assetBase: "./" };
+    return { ...source, recipe, buildRecipeDigest: digestPinnedRecipe(recipe) };
+}

package/dist/source/template-push.d.ts

@@ -0,0 +1,33 @@
+import { type SourceRevision } from "@fungi.computer/puffball";
+/** One projected source tree, as `createFirstPartyAppSourceDistribution` returns it. */
+export type TemplateSourceFiles = readonly Readonly<{
+    path: string;
+    contents: Uint8Array;
+}>[];
+/** What one template push did: the template's `main` now names `seedRevision`. */
+export type TemplatePushResult = Readonly<{
+    seedRevision: SourceRevision;
+    /** False when `main` already held this exact tree (an exact retry). */
+    pushed: boolean;
+}>;
+/**
+ * Commit one projected App source tree onto its template repository's `main`
+ * with ordinary Git, and push it there over smart HTTP.
+ *
+ * The tree holds exactly the given bytes (no attributes or filters), each a
+ * regular non-executable file. The first seed is a parentless commit; a later
+ * different tree is an ordinary fast-forward on the current head; an exact
+ * retry pushes nothing and answers the current head. Nothing is forced. The
+ * `headers` authenticate every request and reach Git only through its config
+ * environment.
+ */
+export declare function pushTemplateSource(input: Readonly<{
+    appId: string;
+    /** The upstream commit the tree was projected from (`git:<sha>`). */
+    sourceRevision: string;
+    files: TemplateSourceFiles;
+    /** The template repository's smart-HTTP URL, without credentials. */
+    remote: string;
+    headers: Readonly<Record<string, string>>;
+    signal?: AbortSignal;
+}>): Promise<TemplatePushResult>;

package/dist/source/template-push.js

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseAppId, parseSourceRevision, } from "@fungi.computer/puffball";
+import { authenticatedGitEnvironment, repositoryEnvironment, } from "../build/git-environment.js";
+/** The fixed identity of every seed commit, so a retry of the same tree on
+ * the same parent is the same commit. */
+const seedIdentity = {
+    GIT_AUTHOR_NAME: "Botanical App Source",
+    GIT_AUTHOR_EMAIL: "app-source@botanical.invalid",
+    GIT_AUTHOR_DATE: "@0 +0000",
+    GIT_COMMITTER_NAME: "Botanical App Source",
+    GIT_COMMITTER_EMAIL: "app-source@botanical.invalid",
+    GIT_COMMITTER_DATE: "@0 +0000",
+};
+/** Artifacts' native fork drops delta-encoded objects, so seed packs carry
+ * whole objects only. Every local object is loose (written here, or fetched
+ * with an unpack limit no fetch reaches), so no delta exists to reuse; a zero
+ * window computes none, `--no-thin` sends none against remote objects and no
+ * pack is reused verbatim. */
+const wholeObjectPush = [
+    "-c",
+    "pack.window=0",
+    "-c",
+    "pack.depth=0",
+    "-c",
+    "pack.allowPackReuse=false",
+];
+const looseFetch = ["-c", "fetch.unpackLimit=1000000000"];
+const objectId = /^[0-9a-f]{40}$/u;
+/** One whole publication (project, fetch, push, confirm) is bounded. */
+const TEMPLATE_PUSH_TIMEOUT_MS = 10 * 60_000;
+/** The Git subcommand of `args`, past any leading `-c name=value` pairs. */
+function command(args) {
+    let at = 0;
+    while (args[at] === "-c")
+        at += 2;
+    return args[at] ?? "";
+}
+function runGit(args, environment, signal, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", [...args], {
+            env: environment,
+            shell: false,
+            signal,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let spawnError;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("error", (error) => {
+            spawnError = error;
+        });
+        child.once("close", (code) => {
+            if (code === 0 && spawnError === undefined) {
+                resolve(stdout);
+                return;
+            }
+            const detail = stderr.trim();
+            reject(spawnError ??
+                new Error(`git ${command(args)} failed${detail ? `: ${detail}` : ` (${String(code)})`}`));
+        });
+        child.stdin.end(input);
+    });
+}
+/** A template path names one regular file below the root: relative, no empty,
+ * `.`, `..` or `.git` part, and never both a file and a directory. */
+function checkTemplatePaths(files) {
+    const paths = new Set();
+    for (const { path } of files) {
+        const parts = path.split("/");
+        if (path.length > 4096 ||
+            path.includes("\\") ||
+            path.includes("\0") ||
+            parts.some((part) => part === "" ||
+                part === "." ||
+                part === ".." ||
+                part.toLowerCase() === ".git"))
+            throw new Error("Template source path is invalid");
+        if (paths.has(path))
+            throw new Error("Duplicate template source path");
+        paths.add(path);
+    }
+    for (const path of paths) {
+        const parts = path.split("/");
+        for (let end = 1; end < parts.length; end += 1)
+            if (paths.has(parts.slice(0, end).join("/")))
+                throw new Error("Template source path is both a file and a directory");
+    }
+}
+function oid(output) {
+    const value = output.trim();
+    if (!objectId.test(value))
+        throw new Error("git returned no object id");
+    return value;
+}
+function remoteMain(output) {
+    for (const line of output.split("\n")) {
+        const [hash, ref] = line.split("\t");
+        if (ref === "refs/heads/main" && hash !== undefined && objectId.test(hash))
+            return hash;
+    }
+    return null;
+}
+/**
+ * Commit one projected App source tree onto its template repository's `main`
+ * with ordinary Git, and push it there over smart HTTP.
+ *
+ * The tree holds exactly the given bytes (no attributes or filters), each a
+ * regular non-executable file. The first seed is a parentless commit; a later
+ * different tree is an ordinary fast-forward on the current head; an exact
+ * retry pushes nothing and answers the current head. Nothing is forced. The
+ * `headers` authenticate every request and reach Git only through its config
+ * environment.
+ */
+export async function pushTemplateSource(input) {
+    const appId = parseAppId(input.appId);
+    const sourceRevision = parseSourceRevision(input.sourceRevision);
+    const remote = new URL(input.remote);
+    if (remote.username || remote.password || remote.search || remote.hash)
+        throw new Error("Template remote must not carry credentials or a query");
+    if (input.files.length === 0)
+        throw new Error("Template source is empty");
+    checkTemplatePaths(input.files);
+    const deadline = AbortSignal.timeout(TEMPLATE_PUSH_TIMEOUT_MS);
+    const signal = input.signal === undefined
+        ? deadline
+        : AbortSignal.any([input.signal, deadline]);
+    const work = await mkdtemp(join(tmpdir(), "oyster-template-push-"));
+    try {
+        const gitDir = join(work, "repository.git");
+        const staging = join(work, "files");
+        const local = {
+            ...repositoryEnvironment(),
+            HOME: work,
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_CONFIG_GLOBAL: "/dev/null",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_DIR: gitDir,
+            GIT_INDEX_FILE: join(work, "index"),
+        };
+        const network = {
+            ...authenticatedGitEnvironment(input.headers),
+            HOME: work,
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_CONFIG_GLOBAL: "/dev/null",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_DIR: gitDir,
+        };
+        const git = (args, stdin) => runGit(args, local, signal, stdin);
+        const remoteGit = (args) => runGit(args, network, signal);
+        await runGit(["init", "--quiet", "--bare", "--initial-branch=main", gitDir], local, signal);
+        // Blobs: raw bytes, loose objects, no clean/smudge or eol filters.
+        await mkdir(staging);
+        const paths = [];
+        for (const [at, file] of input.files.entries()) {
+            const path = join(staging, String(at));
+            await writeFile(path, file.contents);
+            paths.push(path);
+        }
+        const blobs = (await git(["hash-object", "-w", "--no-filters", "--stdin-paths"], `${paths.join("\n")}\n`))
+            .trim()
+            .split("\n");
+        if (blobs.length !== input.files.length ||
+            !blobs.every((b) => objectId.test(b)))
+            throw new Error("git did not write every template blob");
+        const index = input.files
+            .map((file, at) => `100644 ${blobs[at] ?? ""}\t${file.path}\0`)
+            .join("");
+        await git(["update-index", "-z", "--add", "--index-info"], index);
+        const tree = oid(await git(["write-tree"]));
+        const head = remoteMain(await remoteGit(["ls-remote", input.remote, "refs/heads/main"]));
+        let parents = [];
+        if (head !== null) {
+            await remoteGit([
+                ...looseFetch,
+                "fetch",
+                "--quiet",
+                "--depth=1",
+                "--no-tags",
+                input.remote,
+                "refs/heads/main",
+            ]);
+            if (oid(await git(["rev-parse", `${head}^{tree}`])) === tree)
+                return {
+                    seedRevision: parseSourceRevision(`git:${head}`),
+                    pushed: false,
+                };
+            parents = ["-p", head];
+        }
+        const commit = oid(await runGit([
+            "commit-tree",
+            tree,
+            ...parents,
+            "-m",
+            `Seed ${appId} from ${sourceRevision}`,
+        ], { ...local, ...seedIdentity }, signal));
+        await remoteGit([
+            ...wholeObjectPush,
+            "push",
+            "--quiet",
+            "--no-thin",
+            input.remote,
+            `${commit}:refs/heads/main`,
+        ]);
+        // A successful push is not sufficient: main must now name this commit.
+        if (remoteMain(await remoteGit(["ls-remote", input.remote, "refs/heads/main"])) !== commit)
+            throw new Error("Template main moved during the push");
+        return { seedRevision: parseSourceRevision(`git:${commit}`), pushed: true };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}

package/dist/source/template-repository.d.ts

@@ -0,0 +1,4 @@
+/** Derive the private editable source repository from its validated App identity. */
+export declare function templateRepositoryForApp(appId: string): string;
+/** The App whose template `repository` is, or null when it names none. */
+export declare function appForTemplateRepository(repository: string): string | null;

package/dist/source/template-repository.js

@@ -0,0 +1,21 @@
+import { parseAppId } from "@fungi.computer/puffball";
+import { appIdSchema } from "@fungi.computer/puffball/effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+const TEMPLATE_REPOSITORY_PREFIX = "template-";
+/** Derive the private editable source repository from its validated App identity. */
+export function templateRepositoryForApp(appId) {
+    const parsed = parseAppId(appId);
+    // AppId's maximum 63-character suffix makes this repository at most 72 chars.
+    return `${TEMPLATE_REPOSITORY_PREFIX}${parsed.slice("app_".length)}`;
+}
+/** The App whose template `repository` is, or null when it names none. */
+export function appForTemplateRepository(repository) {
+    if (!repository.startsWith(TEMPLATE_REPOSITORY_PREFIX))
+        return null;
+    const appId = Schema.decodeUnknownOption(appIdSchema)(`app_${repository.slice(TEMPLATE_REPOSITORY_PREFIX.length)}`);
+    return Option.isSome(appId) &&
+        templateRepositoryForApp(appId.value) === repository
+        ? appId.value
+        : null;
+}

package/dist/source/template-seed.d.ts

@@ -0,0 +1,68 @@
+import * as Schema from "effect/Schema";
+import type { Artifacts } from "@fungi.computer/burrow";
+import type { PublisherTemplateSeedReceipts } from "./seed-receipt.js";
+/** A seed claim is a few fields and one pinned recipe; the source itself
+ * arrived by `git push`. */
+export declare const TEMPLATE_SEED_CLAIM_MAX_BYTES: number;
+/** The operator's claim after pushing a projected source commit to the App's
+ * template: that `seedRevision` is that commit, projected from
+ * `sourceRevision`, and builds with `recipe`. */
+export declare const templateSeedClaimSchema: Schema.Struct<{
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly sourceRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
+    readonly sourceTreeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+    readonly seedRevision: Schema.refine<import("@fungi.computer/puffball").SourceRevision, Schema.String>;
+    readonly recipe: Schema.Struct<{
+        readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+        readonly bundle: Schema.Literal<true>;
+        readonly entry: Schema.String;
+        readonly format: Schema.Literals<readonly ["html", "esm", "assets"]>;
+        readonly assets: Schema.optional<Schema.Struct<{
+            readonly maxManifestBytes: Schema.Number;
+            readonly maxObjects: Schema.Number;
+            readonly maxObjectBytes: Schema.Number;
+            readonly maxTotalBytes: Schema.Number;
+        }>>;
+        readonly assetBase: Schema.optionalKey<Schema.String>;
+        readonly toolchain: Schema.$Record<Schema.String, Schema.String>;
+        readonly maxOutputBytes: Schema.Number;
+        readonly platform: Schema.Literals<readonly ["browser", "neutral"]>;
+        readonly backend: Schema.Union<readonly [Schema.Null, Schema.Struct<{
+            readonly entry: Schema.optional<Schema.String>;
+            readonly runtime: Schema.Struct<{
+                readonly kind: Schema.Literal<"durable-facet">;
+                readonly stateSchema: Schema.Number;
+            }>;
+            readonly compatibilityDate: Schema.String;
+            readonly exportName: Schema.String;
+        }>]>;
+        readonly target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
+    }>;
+}>;
+export type TemplateSeedClaim = Schema.Schema.Type<typeof templateSeedClaimSchema>;
+/** Decode one claim body at its I/O boundary, strictly; null when it is not
+ * exactly a seed claim. */
+export declare function parseTemplateSeedClaim(body: string): TemplateSeedClaim | null;
+/**
+ * Record the seed receipt for a template the operator already pushed. The
+ * template's current `main` must be exactly the claimed seed commit, whose
+ * hash pins its tree and history; the recipe digest is computed here; an
+ * existing receipt for that commit must carry the same provenance.
+ */
+export declare function recordTemplateSeed(receipts: PublisherTemplateSeedReceipts, artifacts: Pick<Artifacts, "readDefaultBranchHead">, rawAppId: string, claim: TemplateSeedClaim): Promise<{
+    readonly kind: "conflict";
+    readonly receipt?: undefined;
+} | {
+    readonly kind: "recorded" | "existing";
+    readonly receipt: {
+        readonly appId: import("@fungi.computer/puffball").AppId;
+        readonly repository: string;
+        readonly sourceRevision: import("@fungi.computer/puffball").SourceRevision;
+        readonly sourceTreeDigest: import("@fungi.computer/puffball").Sha256Digest;
+        readonly seedRevision: import("@fungi.computer/puffball").SourceRevision;
+        readonly buildRecipeDigest: import("@fungi.computer/puffball").Sha256Digest;
+    };
+} | {
+    readonly kind: "unavailable";
+    readonly receipt?: undefined;
+}>;

package/dist/source/template-seed.js

@@ -0,0 +1,80 @@
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { parseAppId } from "@fungi.computer/puffball";
+import { appIdSchema, sha256DigestSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+import { capturedPinnedRecipeSchema, digestPinnedRecipe, } from "../build-contract.js";
+import { templateRepositoryForApp } from "./template-repository.js";
+/** A seed claim is a few fields and one pinned recipe; the source itself
+ * arrived by `git push`. */
+export const TEMPLATE_SEED_CLAIM_MAX_BYTES = 64 * 1024;
+/** The operator's claim after pushing a projected source commit to the App's
+ * template: that `seedRevision` is that commit, projected from
+ * `sourceRevision`, and builds with `recipe`. */
+export const templateSeedClaimSchema = Schema.Struct({
+    appId: appIdSchema,
+    sourceRevision: sourceRevisionSchema,
+    sourceTreeDigest: sha256DigestSchema,
+    seedRevision: sourceRevisionSchema,
+    recipe: capturedPinnedRecipeSchema,
+});
+/** Decode one claim body at its I/O boundary, strictly; null when it is not
+ * exactly a seed claim. */
+export function parseTemplateSeedClaim(body) {
+    const decoded = Schema.decodeUnknownOption(Schema.fromJsonString(templateSeedClaimSchema), { onExcessProperty: "error" })(body);
+    return Option.isSome(decoded) ? decoded.value : null;
+}
+function logEvent(operation, cause) {
+    console.error(JSON.stringify({
+        source: "app-source",
+        operation,
+        failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
+    }));
+}
+/**
+ * Record the seed receipt for a template the operator already pushed. The
+ * template's current `main` must be exactly the claimed seed commit, whose
+ * hash pins its tree and history; the recipe digest is computed here; an
+ * existing receipt for that commit must carry the same provenance.
+ */
+export async function recordTemplateSeed(receipts, artifacts, rawAppId, claim) {
+    try {
+        const appId = parseAppId(rawAppId);
+        if (claim.appId !== appId)
+            return { kind: "conflict" };
+        const repository = templateRepositoryForApp(appId);
+        const head = await artifacts.readDefaultBranchHead(repository);
+        if (head === null || `git:${head}` !== claim.seedRevision)
+            return { kind: "conflict" };
+        const receipt = {
+            appId,
+            sourceRevision: claim.sourceRevision,
+            sourceTreeDigest: claim.sourceTreeDigest,
+            seedRevision: claim.seedRevision,
+            recipe: claim.recipe,
+            buildRecipeDigest: digestPinnedRecipe(claim.recipe),
+        };
+        const existing = await receipts.read(appId, claim.seedRevision);
+        if (existing !== null &&
+            (existing.sourceRevision !== receipt.sourceRevision ||
+                existing.sourceTreeDigest !== receipt.sourceTreeDigest ||
+                existing.buildRecipeDigest !== receipt.buildRecipeDigest))
+            return { kind: "conflict" };
+        // The write-once, digest-checked receipt owner records it.
+        await receipts.record(receipt);
+        return {
+            kind: existing === null ? "recorded" : "existing",
+            receipt: {
+                appId,
+                repository,
+                sourceRevision: receipt.sourceRevision,
+                sourceTreeDigest: receipt.sourceTreeDigest,
+                seedRevision: receipt.seedRevision,
+                buildRecipeDigest: receipt.buildRecipeDigest,
+            },
+        };
+    }
+    catch (cause) {
+        logEvent("operator.template.record", cause);
+        return { kind: "unavailable" };
+    }
+}

package/dist/standalone/agent-directory.d.ts

@@ -0,0 +1,4 @@
+import type { TenantScope } from "../tenant.js";
+import type { StandaloneAgentsEnv } from "./agents.js";
+/** Host-only lookup from the already selected frame tenant; never derive it from an App or caller. */
+export declare function agentDirectoryForScope(env: Pick<StandaloneAgentsEnv, "AGENT_DIRECTORY">, scope: Pick<TenantScope, "durableName">): DurableObjectStub<import("./agents.js").AgentDirectory>;

package/dist/standalone/agent-directory.js

@@ -0,0 +1,4 @@
+/** Host-only lookup from the already selected frame tenant; never derive it from an App or caller. */
+export function agentDirectoryForScope(env, scope) {
+    return env.AGENT_DIRECTORY.getByName(scope.durableName("agents"));
+}