@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/build/submission-contract.js

@@ -0,0 +1,180 @@
+import { assetBaseSchema, assetPathSchema, } from "@fungi.computer/puffball/assets";
+import { appIdSchema, releaseIdSchema, sha256DigestSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
+import { appDeclarationSchema } from "@fungi.computer/puffball/app";
+import { backendJsonSchema } from "@fungi.computer/puffball/backend";
+import * as Schema from "effect/Schema";
+import { isSigilName } from "@fungi.computer/sigils";
+/**
+ * The largest candidate manifest request body, in bytes. A manifest names
+ * objects; their bytes are uploaded one at a time, never inside it.
+ */
+export const TEAM_APP_CANDIDATE_MANIFEST_MAX_BYTES = 1024 * 1024;
+const byteLengthSchema = Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0)), Schema.check(Schema.makeFilter(Number.isSafeInteger)));
+/** One content-addressed object a build uploaded before its manifest. */
+export const candidateObjectSchema = Schema.Struct({
+    digest: sha256DigestSchema,
+    byteLength: byteLengthSchema,
+});
+const uiManifestSchema = Schema.Union([
+    Schema.Struct({
+        mediaType: Schema.Literal("text/html; charset=utf-8"),
+        content: Schema.Struct({
+            kind: Schema.Literal("html"),
+            ...candidateObjectSchema.fields,
+        }),
+    }),
+    Schema.Struct({
+        mediaType: Schema.Literal("application/vnd.fungi.app-assets+json"),
+        content: Schema.Struct({
+            kind: Schema.Literal("assets"),
+            base: assetBaseSchema,
+            assets: Schema.Array(Schema.Struct({
+                path: assetPathSchema,
+                ...candidateObjectSchema.fields,
+            })),
+        }),
+    }),
+]);
+/** A request only; the Team's installation grants remain the authority. */
+const declaration = {
+    declaration: Schema.optionalKey(appDeclarationSchema.check(Schema.makeFilter((declaration) => declaration.icon === undefined || isSigilName(declaration.icon), { message: "App icon must name a registered Sigil" }))),
+};
+/** A build's output by reference: the same surfaces as its bytes, sized. */
+export const candidateOutputManifestSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("ui"),
+        ui: uiManifestSchema,
+        ...declaration,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("backend"),
+        backend: candidateObjectSchema,
+        ...declaration,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("app"),
+        ui: uiManifestSchema,
+        backend: candidateObjectSchema,
+        ...declaration,
+    }),
+]);
+const provenanceSchema = Schema.Struct({
+    sourceRevision: sourceRevisionSchema,
+    sourceTreeDigest: sha256DigestSchema,
+    buildRecipeDigest: sha256DigestSchema,
+});
+const manifestFields = {
+    appId: appIdSchema,
+    output: candidateOutputManifestSchema,
+    provenance: provenanceSchema,
+};
+/**
+ * A submitted Team App candidate: its output's objects by digest and size,
+ * and its provenance, before the Team assigns a stable Release ID.
+ */
+export const teamAppCandidateManifestSchema = Schema.Struct(manifestFields);
+/** Publisher persistence input after TeamDO reserves retry-stable identities. */
+export const preparedCandidateManifestSchema = Schema.Struct({
+    ...manifestFields,
+    releaseId: releaseIdSchema,
+});
+/** One operator-published byte string; its request has a separate total bound. */
+const bytesSchema = Schema.Uint8ArrayFromBase64.pipe(Schema.check(Schema.makeFilter((bytes) => bytes.byteLength <= 16 * 1024 * 1024)));
+const backendBytesSchema = bytesSchema.pipe(Schema.check(Schema.makeFilter((bytes) => Schema.decodeUnknownResult(backendJsonSchema)(new TextDecoder().decode(bytes), { onExcessProperty: "error" })._tag === "Success")));
+const uiBytesSchema = Schema.Union([
+    Schema.Struct({
+        mediaType: Schema.Literal("text/html; charset=utf-8"),
+        content: Schema.Struct({
+            kind: Schema.Literal("html"),
+            bytes: bytesSchema,
+        }),
+    }),
+    Schema.Struct({
+        mediaType: Schema.Literal("application/vnd.fungi.app-assets+json"),
+        content: Schema.Struct({
+            kind: Schema.Literal("assets"),
+            base: assetBaseSchema,
+            assets: Schema.Array(Schema.Struct({ path: assetPathSchema, bytes: bytesSchema })),
+        }),
+    }),
+]);
+/**
+ * A platform App candidate the trusted operator built and packed itself,
+ * with its bytes inline: the operator's platform publication request only.
+ * A Team candidate never carries bytes; it is a manifest.
+ */
+export const preparedCandidateSchema = Schema.Struct({
+    appId: appIdSchema,
+    releaseId: releaseIdSchema,
+    output: Schema.Union([
+        Schema.Struct({
+            kind: Schema.Literal("ui"),
+            ui: uiBytesSchema,
+            ...declaration,
+        }),
+        Schema.Struct({
+            kind: Schema.Literal("backend"),
+            backend: backendBytesSchema,
+            ...declaration,
+        }),
+        Schema.Struct({
+            kind: Schema.Literal("app"),
+            ui: uiBytesSchema,
+            backend: backendBytesSchema,
+            ...declaration,
+        }),
+    ]),
+    provenance: provenanceSchema,
+});
+/** Canonical manifest bytes, so a digest is independent of JSON spacing. */
+export function encodeTeamAppCandidateManifest(manifest) {
+    return JSON.stringify(Schema.encodeUnknownSync(teamAppCandidateManifestSchema)(manifest));
+}
+/** The hex SHA-256 of a manifest's canonical bytes: its App root's name. */
+export async function digestTeamAppCandidateManifest(manifest) {
+    return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(encodeTeamAppCandidateManifest(manifest)))), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * The media type an uploaded object is stored with. A store that reads an
+ * HTML document or backend descriptor by its stored type (the Publisher's)
+ * needs it; an asset's type is its manifest's, so it is an octet stream.
+ */
+export const candidateObjectMediaTypes = [
+    "text/html; charset=utf-8",
+    "application/vnd.fungi.app-backend+json",
+    "application/octet-stream",
+];
+/** The stored media type a request names, if it is one an object may carry. */
+export function candidateObjectMediaType(value) {
+    return candidateObjectMediaTypes.find((type) => type === value) ?? null;
+}
+/** Every distinct object a manifest names, each once, in manifest order. */
+export function candidateManifestObjects(output) {
+    const objects = [];
+    const add = (object, mediaType) => {
+        const seen = objects.find(({ digest }) => digest === object.digest);
+        if (seen === undefined)
+            objects.push({
+                digest: object.digest,
+                byteLength: object.byteLength,
+                mediaType,
+            });
+        else if (seen.byteLength !== object.byteLength)
+            throw new Error("One object digest names two sizes");
+    };
+    if (output.kind !== "backend") {
+        const { content } = output.ui;
+        if (content.kind === "html")
+            add(content, "text/html; charset=utf-8");
+        else
+            for (const asset of content.assets)
+                add(asset, "application/octet-stream");
+    }
+    if (output.kind !== "ui")
+        add(output.backend, "application/vnd.fungi.app-backend+json");
+    return objects;
+}
+/** Decode a stored backend descriptor; a manifest's backend must be one. */
+export function decodeCandidateBackend(bytes) {
+    return Schema.decodeUnknownSync(backendJsonSchema)(new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes), { onExcessProperty: "error" });
+}

package/dist/build/workspace-build.d.ts

@@ -0,0 +1,55 @@
+import * as Schema from "effect/Schema";
+import type { WorkspaceBuildStep } from "./build-step.js";
+/**
+ * `package.json#fungi.build`. An App manifest (the manifest nearest the
+ * entry) declares how its page builds: `react`, `shellEntry`, the workspace
+ * packages whose declared stylesheets compile first (`packageStylesheets`)
+ * and its own `stylesheets`, compiled in place, in order. A workspace
+ * package declares its build products: extra TypeScript configs compiled
+ * after its `tsconfig.build.json`, and its stylesheet input and output; or,
+ * instead of TypeScript configs, the one `package.json` script that builds
+ * it (`script`), which only an admitted Computer build runs. Every path is
+ * relative to the manifest that declares it. Unknown build fields are
+ * refused, so a builder never silently ignores a policy it does not know.
+ */
+export declare const workspaceBuildPolicySchema: Schema.Struct<{
+    readonly react: Schema.optional<Schema.Boolean>;
+    readonly shellEntry: Schema.optional<Schema.String>;
+    readonly packageStylesheets: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly stylesheets: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly typescript: Schema.optional<Schema.$Array<Schema.String>>;
+    /** A script name in this manifest's own `scripts`. */
+    readonly script: Schema.optional<Schema.NonEmptyString>;
+    readonly stylesheet: Schema.optional<Schema.Struct<{
+        readonly input: Schema.String;
+        readonly output: Schema.String;
+    }>>;
+}>;
+/** The build policy one manifest declares. */
+export type WorkspaceBuildPolicy = Schema.Schema.Type<typeof workspaceBuildPolicySchema>;
+/** The pnpm arguments that list a source tree's workspace projects. */
+export declare const workspaceProjectsArguments: readonly string[];
+/** One App page build derived from its manifests and package graph. */
+export type WorkspaceBuild = Readonly<{
+    /** The pnpm workspace that owns the entry, relative to the source root. */
+    directory: string;
+    packageName: string;
+    react: boolean;
+    /** A shell module entry, relative to `directory`. */
+    shellEntry?: string;
+    /** The workspace's runtime workspace dependencies, dependencies first. */
+    dependencies: readonly string[];
+    steps: readonly WorkspaceBuildStep[];
+}>;
+/**
+ * Derive one App's page build from the captured source alone: the manifest
+ * nearest `entry` declares the App policy, the owning pnpm workspace's
+ * runtime `workspace:` dependencies give the compile order, and each
+ * dependency's manifest declares its own extra build products.
+ */
+export declare function resolveWorkspaceBuild(options: {
+    readonly root: string;
+    readonly entry: string;
+    /** `pnpm ls -r --depth -1 --json` output for the same source tree. */
+    readonly projects: string;
+}): Promise<WorkspaceBuild>;

package/dist/build/workspace-build.js

@@ -0,0 +1,200 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import * as Schema from "effect/Schema";
+const manifestPathSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((path) => path.length > 0 &&
+    !path.startsWith("/") &&
+    !path.includes("\\") &&
+    path
+        .split("/")
+        .every((part) => part !== "" && part !== "." && part !== ".."))));
+/**
+ * `package.json#fungi.build`. An App manifest (the manifest nearest the
+ * entry) declares how its page builds: `react`, `shellEntry`, the workspace
+ * packages whose declared stylesheets compile first (`packageStylesheets`)
+ * and its own `stylesheets`, compiled in place, in order. A workspace
+ * package declares its build products: extra TypeScript configs compiled
+ * after its `tsconfig.build.json`, and its stylesheet input and output; or,
+ * instead of TypeScript configs, the one `package.json` script that builds
+ * it (`script`), which only an admitted Computer build runs. Every path is
+ * relative to the manifest that declares it. Unknown build fields are
+ * refused, so a builder never silently ignores a policy it does not know.
+ */
+export const workspaceBuildPolicySchema = Schema.Struct({
+    react: Schema.optional(Schema.Boolean),
+    shellEntry: Schema.optional(manifestPathSchema),
+    packageStylesheets: Schema.optional(Schema.Array(Schema.String)),
+    stylesheets: Schema.optional(Schema.Array(manifestPathSchema)),
+    typescript: Schema.optional(Schema.Array(manifestPathSchema)),
+    /** A script name in this manifest's own `scripts`. */
+    script: Schema.optional(Schema.NonEmptyString),
+    stylesheet: Schema.optional(Schema.Struct({ input: manifestPathSchema, output: manifestPathSchema })),
+});
+const manifestSchema = Schema.fromJsonString(Schema.Struct({
+    name: Schema.optional(Schema.String),
+    dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    scripts: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    fungi: Schema.optional(Schema.Struct({ build: Schema.optional(Schema.Unknown) })),
+}));
+/** A manifest's build policy; only `fungi.build` itself is held strict. */
+function policyOf(manifest) {
+    const build = manifest.fungi?.build;
+    return build === undefined
+        ? {}
+        : Schema.decodeUnknownSync(workspaceBuildPolicySchema, {
+            onExcessProperty: "error",
+        })(build);
+}
+/** One pnpm workspace project, as `pnpm ls -r --depth -1 --json` lists it. */
+const workspaceProjectsSchema = Schema.fromJsonString(Schema.Array(Schema.Struct({
+    name: Schema.String.pipe(Schema.check(Schema.isMinLength(1))),
+    path: Schema.String.pipe(Schema.check(Schema.isMinLength(1))),
+})));
+/** The pnpm arguments that list a source tree's workspace projects. */
+export const workspaceProjectsArguments = Object.freeze([
+    "ls",
+    "--recursive",
+    "--depth",
+    "-1",
+    "--json",
+]);
+function within(root, path) {
+    const relativePath = relative(root, resolve(root, path));
+    if (relativePath === ".." ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath))
+        throw new Error(`Build input escapes the captured source: ${path}`);
+    return relativePath.split(sep).join("/");
+}
+async function exists(path) {
+    return access(path).then(() => true, () => false);
+}
+/**
+ * Derive one App's page build from the captured source alone: the manifest
+ * nearest `entry` declares the App policy, the owning pnpm workspace's
+ * runtime `workspace:` dependencies give the compile order, and each
+ * dependency's manifest declares its own extra build products.
+ */
+export async function resolveWorkspaceBuild(options) {
+    const root = resolve(options.root);
+    const entry = within(root, options.entry);
+    const manifests = new Map();
+    const manifest = async (directory) => {
+        const known = manifests.get(directory);
+        if (known)
+            return known;
+        const decoded = Schema.decodeUnknownSync(manifestSchema)(await readFile(join(root, directory, "package.json"), "utf8"));
+        manifests.set(directory, decoded);
+        return decoded;
+    };
+    const projects = new Map();
+    let rootProject = null;
+    for (const project of Schema.decodeUnknownSync(workspaceProjectsSchema)(options.projects)) {
+        const directory = within(root, project.path);
+        if (directory === "") {
+            rootProject = project.name;
+            continue;
+        }
+        if (projects.has(project.name))
+            throw new Error(`Workspace package name repeats: ${project.name}`);
+        projects.set(project.name, directory);
+    }
+    const owners = [...projects]
+        .filter(([, directory]) => entry.startsWith(`${directory}/`))
+        .sort(([, left], [, right]) => right.length - left.length);
+    // A workspace member owns its entry; with none, an App's own repository
+    // (one package, the App itself at the root) owns it.
+    const owner = owners[0] ??
+        (projects.size === 0 && rootProject !== null
+            ? [rootProject, ""]
+            : undefined);
+    if (!owner)
+        throw new Error(`No workspace package owns ${entry}`);
+    const [packageName, directory] = owner;
+    const parent = (path) => {
+        const up = dirname(path);
+        return up === "." ? "" : up;
+    };
+    let appDirectory = parent(entry);
+    while (appDirectory !== directory &&
+        !(await exists(join(root, appDirectory, "package.json"))))
+        appDirectory = parent(appDirectory);
+    const policy = policyOf(await manifest(appDirectory));
+    if (policy.script !== undefined)
+        throw new Error(`${appDirectory} is the App; its page builds with the recipe, not a script`);
+    const dependencies = [];
+    const visiting = new Set([directory]);
+    const visit = async (from) => {
+        for (const [name, range] of Object.entries((await manifest(from)).dependencies ?? {})) {
+            if (!range.startsWith("workspace:"))
+                continue;
+            const dependency = projects.get(name);
+            if (dependency === undefined)
+                throw new Error(`${from} depends on an unlisted workspace ${name}`);
+            if (dependencies.includes(dependency))
+                continue;
+            if (visiting.has(dependency))
+                throw new Error(`Workspace dependency cycle through ${name}`);
+            visiting.add(dependency);
+            await visit(dependency);
+            visiting.delete(dependency);
+            dependencies.push(dependency);
+        }
+    };
+    await visit(directory);
+    const steps = [];
+    for (const dependency of dependencies) {
+        const declared = await manifest(dependency);
+        const own = policyOf(declared);
+        if (own.script !== undefined) {
+            if (own.typescript !== undefined)
+                throw new Error(`${dependency} declares both a build script and TypeScript configs`);
+            if (declared.scripts === undefined ||
+                !Object.hasOwn(declared.scripts, own.script))
+                throw new Error(`${dependency} has no script named ${own.script}`);
+            steps.push({ kind: "script", directory: dependency, script: own.script });
+            continue;
+        }
+        if (await exists(join(root, dependency, "tsconfig.build.json")))
+            steps.push({
+                kind: "typescript",
+                config: `${dependency}/tsconfig.build.json`,
+            });
+        for (const config of own.typescript ?? [])
+            steps.push({ kind: "typescript", config: `${dependency}/${config}` });
+    }
+    const appManifest = await manifest(appDirectory);
+    for (const name of policy.packageStylesheets ?? []) {
+        const owner = projects.get(name);
+        // A package installed from a registry ships its built stylesheet; only a
+        // workspace package's stylesheet compiles here.
+        if (owner === undefined && appManifest.dependencies?.[name] !== undefined)
+            continue;
+        if (owner === undefined || !dependencies.includes(owner))
+            throw new Error(`Stylesheet package ${name} is not a workspace dependency`);
+        const declared = policyOf(await manifest(owner)).stylesheet;
+        if (!declared)
+            throw new Error(`${name} declares no stylesheet`);
+        steps.push({
+            kind: "tailwind",
+            input: `${owner}/${declared.input}`,
+            output: `${owner}/${declared.output}`,
+        });
+    }
+    for (const stylesheet of policy.stylesheets ?? []) {
+        const path = within(root, join(appDirectory, stylesheet));
+        steps.push({ kind: "tailwind", input: path, output: path });
+    }
+    const build = {
+        directory,
+        packageName,
+        react: policy.react === true,
+        dependencies: Object.freeze(dependencies),
+        steps: Object.freeze(steps),
+    };
+    if (policy.shellEntry === undefined)
+        return Object.freeze(build);
+    const shellEntry = relative(join(root, directory), join(root, appDirectory, policy.shellEntry))
+        .split(sep)
+        .join("/");
+    return Object.freeze({ ...build, shellEntry });
+}

package/dist/build-contract.d.ts

@@ -0,0 +1,7 @@
+/** Provider-neutral App build recipes and candidate orchestration. */
+export * from "./build/effect.js";
+/** Team App candidate wire contract: submission schema and codec. */
+export * from "./build/submission-contract.js";
+export { workspaceBuildPolicy } from "./build/build-policy.js";
+/** A build's uploaded objects in an R2-shaped, content-addressed store. */
+export * from "./build/content-objects.js";

package/dist/build-contract.js

@@ -0,0 +1,7 @@
+/** Provider-neutral App build recipes and candidate orchestration. */
+export * from "./build/effect.js";
+/** Team App candidate wire contract: submission schema and codec. */
+export * from "./build/submission-contract.js";
+export { workspaceBuildPolicy } from "./build/build-policy.js";
+/** A build's uploaded objects in an R2-shaped, content-addressed store. */
+export * from "./build/content-objects.js";

package/dist/build-egress.d.ts

@@ -0,0 +1,62 @@
+import { type CandidateObject, type CandidateObjectMediaType, type TeamAppCandidateManifest } from "./build-contract.js";
+/** The two facts a build job reports; a host's Team Git event is a superset
+ * that also carries pushes, so a host's own record callback is always
+ * assignable here. */
+export type BuildGitEvent = Readonly<{
+    kind: "build-artifact";
+    jobId: string;
+    credentialId: string;
+    digest: string;
+    bytes: number;
+}> | Readonly<{
+    kind: "build-status";
+    jobId: string;
+    credentialId: string;
+    status: "succeeded" | "failed";
+    detail: string | null;
+}>;
+/** A Git principal admitted to read exactly one live build job's one
+ * repository: the job-scoped read clone. It never pushes, and its reads are
+ * never recorded as Team Git push events. */
+export type BuildGitPrincipal = Readonly<{
+    kind: "build";
+    jobId: string;
+    credentialId: string;
+}>;
+/** True when an admitted Git principal is a build job's job-scoped read
+ * credential rather than an Agent or a Workflow Git pass. A host's Git
+ * egress uses this to admit the job-scoped read clone while refusing any
+ * write and skipping push-event recording for it. Generic so a host's own
+ * wider principal union still narrows away the "build" member afterward,
+ * exactly as the literal `principal.kind === "build"` comparison it
+ * replaces did. */
+export declare function isBuildGitPrincipal<P extends Readonly<{
+    kind: string;
+}>>(principal: P): principal is Extract<P, Readonly<{
+    kind: "build";
+}>>;
+/**
+ * The build-report handler for `/jobs/:id/(candidate|artifact|status)` and
+ * `PUT /jobs/:id/objects/sha256-<hex>`. `admitBuild` is the host's own
+ * live-job lookup; `admitObject` admits one object upload for a live job's
+ * grant and answers its size bound; `storeObject` streams an admitted object
+ * into the host's content-addressed store, which verifies its digest;
+ * `submitCandidate` hands an admitted manifest to the host's Publisher
+ * custody; `record` delivers a reported fact to the host's own projection.
+ * `report` observes a body or JSON decode failure without changing its 400
+ * outcome; a host may wire its own structured logger or omit it.
+ */
+export declare function createBuildEgress(options: Readonly<{
+    admitBuild: (jobId: string) => Promise<Readonly<{
+        credentialId: string;
+    }> | null>;
+    admitObject: (jobId: string, grant: string) => Promise<Readonly<{
+        maxObjectBytes: number;
+    }> | null>;
+    storeObject: (object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType) => Promise<"stored" | "refused">;
+    submitCandidate: (jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string) => Promise<Response>;
+    record: (event: BuildGitEvent) => Promise<void>;
+    report?: (operation: string, cause: unknown) => void;
+}>): Readonly<{
+    fetch(request: Request, url: URL): Promise<Response>;
+}>;

package/dist/build-egress.js

@@ -0,0 +1,148 @@
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+import { teamAppCandidateManifestSchema, TEAM_APP_CANDIDATE_MANIFEST_MAX_BYTES, candidateObjectMediaType, candidateObjectSchema, } from "./build-contract.js";
+/**
+ * The Computer's own egress for its build job's `/jobs/:id/*` reports. A
+ * live build uploads each built object alone, streamed straight into the
+ * host's content-addressed store, then submits the small manifest naming
+ * them through Team submission custody, then reports bytes/status. Selection
+ * and promotion are never admitted here. The
+ * Computer presents no credential of its own: every decision is
+ * port-injected so a host (Hub today, Oyster's standalone host once it
+ * mounts a Computer build) supplies its own admission, submission and event
+ * recording without this module reaching into either host's state.
+ */
+const statusSchema = z.strictObject({
+    status: z.enum(["succeeded", "failed"]),
+    detail: z.string().max(2_000).optional(),
+});
+const artifactSchema = z.strictObject({
+    digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    bytes: z.number().int().nonnegative(),
+});
+/** True when an admitted Git principal is a build job's job-scoped read
+ * credential rather than an Agent or a Workflow Git pass. A host's Git
+ * egress uses this to admit the job-scoped read clone while refusing any
+ * write and skipping push-event recording for it. Generic so a host's own
+ * wider principal union still narrows away the "build" member afterward,
+ * exactly as the literal `principal.kind === "build"` comparison it
+ * replaces did. */
+export function isBuildGitPrincipal(principal) {
+    return principal.kind === "build";
+}
+/**
+ * The build-report handler for `/jobs/:id/(candidate|artifact|status)` and
+ * `PUT /jobs/:id/objects/sha256-<hex>`. `admitBuild` is the host's own
+ * live-job lookup; `admitObject` admits one object upload for a live job's
+ * grant and answers its size bound; `storeObject` streams an admitted object
+ * into the host's content-addressed store, which verifies its digest;
+ * `submitCandidate` hands an admitted manifest to the host's Publisher
+ * custody; `record` delivers a reported fact to the host's own projection.
+ * `report` observes a body or JSON decode failure without changing its 400
+ * outcome; a host may wire its own structured logger or omit it.
+ */
+export function createBuildEgress(options) {
+    const report = options.report ??
+        ((operation, cause) => {
+            console.error(operation, cause);
+        });
+    const putObject = async (request, jobId, hex) => {
+        const admitted = await options.admitObject(jobId, request.headers.get("X-Team-App-Build") ?? "");
+        if (admitted === null)
+            return new Response(null, { status: 403 });
+        // The stated length bounds what the store takes before a byte moves.
+        const length = request.headers.get("Content-Length") ?? "";
+        if (!/^(0|[1-9][0-9]{0,14})$/u.test(length))
+            return new Response(null, { status: 411 });
+        const byteLength = Number(length);
+        if (byteLength > admitted.maxObjectBytes) {
+            await request.body?.cancel();
+            return new Response(null, { status: 413 });
+        }
+        const mediaType = candidateObjectMediaType(request.headers.get("Content-Type"));
+        if (mediaType === null) {
+            await request.body?.cancel();
+            return new Response(null, { status: 415 });
+        }
+        const stored = await options.storeObject(Schema.decodeUnknownSync(candidateObjectSchema)({
+            digest: `sha256:${hex}`,
+            byteLength,
+        }), request.body, mediaType);
+        return new Response(null, { status: stored === "stored" ? 204 : 400 });
+    };
+    return Object.freeze({
+        async fetch(request, url) {
+            if (url.search !== "" || url.username || url.password)
+                return new Response(null, { status: 403 });
+            const object = /^\/jobs\/([a-zA-Z0-9_-]{1,128})\/objects\/sha256-([0-9a-f]{64})$/u.exec(url.pathname);
+            if (object !== null) {
+                const [, jobId = "", hex = ""] = object;
+                return request.method === "PUT"
+                    ? putObject(request, jobId, hex)
+                    : new Response(null, { status: 403 });
+            }
+            const match = /^\/jobs\/([a-zA-Z0-9_-]{1,128})\/(status|artifact|candidate)$/u.exec(url.pathname);
+            const jobId = match?.[1];
+            const action = match?.[2];
+            if (jobId === undefined || request.method !== "POST")
+                return new Response(null, { status: 403 });
+            const job = await options.admitBuild(jobId);
+            if (job === null)
+                return new Response(null, { status: 403 });
+            if (action === "candidate") {
+                let manifest;
+                try {
+                    if (request.body === null)
+                        return new Response(null, { status: 400 });
+                    let size = 0;
+                    const bounded = request.body.pipeThrough(new TransformStream({
+                        transform(chunk, controller) {
+                            size += chunk.byteLength;
+                            if (size > TEAM_APP_CANDIDATE_MANIFEST_MAX_BYTES)
+                                throw new Error("candidate manifest oversize");
+                            controller.enqueue(chunk);
+                        },
+                    }));
+                    manifest = Schema.decodeUnknownSync(teamAppCandidateManifestSchema, {
+                        onExcessProperty: "error",
+                    })(await new Response(bounded).json());
+                }
+                catch {
+                    return new Response(null, { status: 400 });
+                }
+                return options.submitCandidate(jobId, manifest, request.headers.get("X-Team-App-Build") ?? "", job.credentialId);
+            }
+            let json;
+            try {
+                json = await request.json();
+            }
+            catch (cause) {
+                report("packages/oyster/src/build-egress.ts:report", cause);
+                return new Response(null, { status: 400 });
+            }
+            if (action === "artifact") {
+                const artifact = artifactSchema.safeParse(json);
+                if (!artifact.success)
+                    return new Response(null, { status: 400 });
+                await options.record({
+                    kind: "build-artifact",
+                    jobId,
+                    credentialId: job.credentialId,
+                    ...artifact.data,
+                });
+                return new Response(null, { status: 204 });
+            }
+            const status = statusSchema.safeParse(json);
+            if (!status.success)
+                return new Response(null, { status: 400 });
+            await options.record({
+                kind: "build-status",
+                jobId,
+                credentialId: job.credentialId,
+                status: status.data.status,
+                detail: status.data.detail ?? null,
+            });
+            return new Response(null, { status: 204 });
+        },
+    });
+}

package/dist/build-jobs.d.ts

@@ -0,0 +1,2 @@
+/** Team build job lifecycle and the fixed builder command; Worker-safe, no Node-only build tooling. */
+export { createTeamBuildPublisher, teamAppBuildCommand, type TeamBuildJob, type BuildCredential, type TeamBuildComputer, } from "./build/build-jobs.js";

package/dist/build-jobs.js

@@ -0,0 +1,2 @@
+/** Team build job lifecycle and the fixed builder command; Worker-safe, no Node-only build tooling. */
+export { createTeamBuildPublisher, teamAppBuildCommand, } from "./build/build-jobs.js";