@fungi.computer/puffball 0.0.0-stage → 0.0.1

package/dist/background-replay.d.ts

@@ -0,0 +1,115 @@
+import * as z from "zod";
+import type { Sha256Digest } from "./internal/app-release-contract.js";
+import { type HostActor, type AppMethodCallContext } from "./app-method-runtime.js";
+import type { AppApi } from "./app-vocabulary.js";
+export { backgroundSyncAllowed } from "./internal/background-sync.js";
+/** The caller's single lightweight grammar for a host-sealed enqueue origin. */
+export declare const backgroundOriginSchema: import("zod/mini").ZodMiniObject<{
+    method: import("zod/mini").ZodMiniString<string>;
+    seal: import("zod/mini").ZodMiniString<string>;
+}, z.core.$strict>;
+/** Origin evidence, never a retained grant or credential. */
+export type BackgroundOrigin = z.output<typeof backgroundOriginSchema>;
+/** The closed result of checking a claimed job's origin in a fresh replay frame. */
+export declare const claimedJobAdmissionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"admitted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    code: z.ZodLiteral<"access_changed">;
+}, z.core.$strict>]>;
+/** A claim either passes origin admission or refuses before binding effects. */
+export type ClaimedJobAdmission = z.output<typeof claimedJobAdmissionSchema>;
+/** Host-minted replay port; an App cannot declare this binding. */
+export type BackgroundBinding = Readonly<{
+    /** Check the actual claimed job's origin once in this frame. */
+    admit: (origin: BackgroundOrigin) => Promise<ClaimedJobAdmission>;
+}>;
+/** Derive a non-extractable host signing key; no secret is sent to an App. */
+export declare function backgroundOriginKey(secret: string): Promise<CryptoKey>;
+/** Seal only host-verified Instance, member lane and foreground method attribution. */
+export declare function sealBackgroundOrigin(key: CryptoKey, claims: Readonly<{
+    instanceId: string;
+    lane: string;
+    method: string;
+}>): Promise<BackgroundOrigin>;
+/** Verify origin evidence against this frame's fresh admission; guest input never throws. */
+export declare function admitClaimedOrigin(key: CryptoKey, frame: Readonly<{
+    instanceId: string;
+    lane: string;
+    admitted: readonly string[];
+}>, raw: unknown): Promise<ClaimedJobAdmission>;
+/** A queue lane is an actor identity, never a credential or grant. */
+export declare function actorLane(actor: HostActor): string;
+/** Only ordinary member calls may enqueue background work; ancestry is host-held. */
+export declare function mayDefer(context: AppMethodCallContext, ancestry: readonly string[]): boolean;
+/** Host-only projection: replace incoming eligibility with the verified write's sealed origin. */
+export declare function backgroundContext(context: AppMethodCallContext, ancestry: readonly string[], method: Readonly<{
+    name: string;
+    effect: AppApi["methods"][string]["effect"];
+}>, origin: BackgroundOrigin | undefined): AppMethodCallContext;
+/** App-side eligibility reads only the host-attested context; it never invents ancestry. */
+export declare function mayEnqueueBackground(context: AppMethodCallContext): boolean;
+/** Identity and observed revisions only. Unknown fields, including bearer material, refuse. */
+export declare const backgroundWakeSchema: z.ZodObject<{
+    installationId: z.ZodString;
+    actor: z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"member">;
+        memberId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>;
+    lane: z.ZodString;
+    originMethod: z.ZodString;
+    observed: z.ZodObject<{
+        authorityVersion: z.ZodNumber;
+        artifactDigest: z.ZodCustom<Sha256Digest, Sha256Digest>;
+        membershipVersion: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    epoch: z.ZodNumber;
+}, z.core.$strict>;
+/** A host wake cannot confer authority without fresh directory and method admission. */
+export type BackgroundWake = z.output<typeof backgroundWakeSchema>;
+/** A retained identity eligible for member-only replay. */
+export type BackgroundMember = BackgroundWake["actor"];
+/** The App can settle a refused lane without receiving any binding authority. */
+export declare const backgroundRefusalCodeSchema: z.ZodEnum<{
+    access_changed: "access_changed";
+    installation_unavailable: "installation_unavailable";
+}>;
+/** Cleanup payload for one refused member lane; contains no actor or authority. */
+export declare const backgroundSyncRefusalSchema: z.ZodObject<{
+    lane: z.ZodString;
+    code: z.ZodEnum<{
+        access_changed: "access_changed";
+        installation_unavailable: "installation_unavailable";
+    }>;
+}, z.core.$strict>;
+/** One available App's member-lane cleanup, delivered with zero binding grants. */
+export type BackgroundSyncRefusal = z.output<typeof backgroundSyncRefusalSchema>;
+/** Closed, durable refusal reasons for the affected member lane. */
+export type BackgroundRefusalCode = z.output<typeof backgroundRefusalCodeSchema>;
+/** Existing method admission outcomes interpreted by the replay owner. */
+export type BackgroundAdmission = Readonly<{
+    kind: "admitted";
+    context: AppMethodCallContext;
+}> | Readonly<{
+    kind: "refused";
+    code: "level_too_low" | "requires_not_granted" | "not_approved" | "denied" | "unavailable" | "stale_authority";
+}>;
+/** Directory resolution and fresh continuation admission remain host-owned. */
+export type BackgroundReplayPorts<Principal> = Readonly<{
+    /** Resolve the retained member using the host's live directory, without bearer replay. */
+    resolve: (actor: BackgroundMember) => Promise<Principal | null>;
+    /** Admit backend.sync.method as this principal with fresh method-scoped grants. */
+    admit: (principal: Principal, wake: BackgroundWake) => Promise<BackgroundAdmission>;
+}>;
+/** A refused wake settles its lane; retry uses the existing Carrier backoff. */
+export type BackgroundReplayDecision = Readonly<{
+    kind: "admitted";
+    context: AppMethodCallContext;
+}> | Readonly<{
+    kind: "refused";
+    code: BackgroundRefusalCode;
+}> | Readonly<{
+    kind: "retry";
+}>;
+/** Resolve then re-admit. Observed revisions are evidence, never equality pins. */
+export declare function readmitBackground<Principal>(input: unknown, ports: BackgroundReplayPorts<Principal>): Promise<BackgroundReplayDecision>;

package/dist/background-replay.js

@@ -0,0 +1,175 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import * as Base64Url from "effect/encoding/Base64Url";
+import { WatchdogQueuedJobSchema } from "@fungi.computer/watchdog";
+import { sha256DigestSchema } from "./internal/app-release-schema.js";
+import { hostActorSchema, appMethodCallerSchema, isAppApiMethodName, parseAppMethodCallContext, } from "./app-method-runtime.js";
+export { backgroundSyncAllowed } from "./internal/background-sync.js";
+/** The caller's single lightweight grammar for a host-sealed enqueue origin. */
+export const backgroundOriginSchema = appMethodCallerSchema.shape.backgroundOrigin.def.innerType;
+/** The closed result of checking a claimed job's origin in a fresh replay frame. */
+export const claimedJobAdmissionSchema = z.union([
+    z.strictObject({ kind: z.literal("admitted") }),
+    z.strictObject({
+        kind: z.literal("refused"),
+        code: z.literal("access_changed"),
+    }),
+]);
+const originBytes = (claims) => new TextEncoder().encode(JSON.stringify([
+    "fungi.background-origin/1",
+    claims.instanceId,
+    claims.lane,
+    claims.method,
+]));
+/** Derive a non-extractable host signing key; no secret is sent to an App. */
+export async function backgroundOriginKey(secret) {
+    const text = new TextEncoder();
+    const material = await crypto.subtle.importKey("raw", text.encode(secret), "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: text.encode("fungi.app.background-origin"),
+        info: text.encode("v1"),
+    }, material, { name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign", "verify"]);
+}
+/** Seal only host-verified Instance, member lane and foreground method attribution. */
+export async function sealBackgroundOrigin(key, claims) {
+    const signature = await crypto.subtle.sign("HMAC", key, originBytes(claims));
+    return backgroundOriginSchema.parse({
+        method: claims.method,
+        seal: Base64Url.encode(new Uint8Array(signature)),
+    });
+}
+/** Verify origin evidence against this frame's fresh admission; guest input never throws. */
+export async function admitClaimedOrigin(key, frame, raw) {
+    const refused = {
+        kind: "refused",
+        code: "access_changed",
+    };
+    const parsed = backgroundOriginSchema.safeParse(raw);
+    if (!parsed.success)
+        return refused;
+    const decoded = Base64Url.decode(parsed.data.seal);
+    if (decoded._tag === "Failure" ||
+        Base64Url.encode(decoded.success) !== parsed.data.seal)
+        return refused;
+    try {
+        const valid = await crypto.subtle.verify("HMAC", key, new Uint8Array(decoded.success), originBytes({
+            instanceId: frame.instanceId,
+            lane: frame.lane,
+            method: parsed.data.method,
+        }));
+        return valid && frame.admitted.includes(parsed.data.method)
+            ? { kind: "admitted" }
+            : refused;
+    }
+    catch {
+        return refused;
+    }
+}
+/** A queue lane is an actor identity, never a credential or grant. */
+export function actorLane(actor) {
+    switch (actor.kind) {
+        case "member":
+            return `member:${actor.memberId}`;
+        case "agent":
+            return `agent:${actor.agentId}`;
+        case "team-key":
+            return `team-key:${actor.keyId}`;
+    }
+}
+/** Only ordinary member calls may enqueue background work; ancestry is host-held. */
+export function mayDefer(context, ancestry) {
+    return (context.actor.kind === "member" &&
+        context.workflow === undefined &&
+        ancestry.length === 0 &&
+        Schema.is(WatchdogQueuedJobSchema.fields.lane)(actorLane(context.actor)));
+}
+/** Host-only projection: replace incoming eligibility with the verified write's sealed origin. */
+export function backgroundContext(context, ancestry, method, origin) {
+    const caller = { ...parseAppMethodCallContext(context, true) };
+    delete caller.backgroundLane;
+    delete caller.backgroundOrigin;
+    if (method.effect !== "write" || !mayDefer(caller, ancestry))
+        return caller;
+    const sealed = backgroundOriginSchema.parse(origin);
+    if (sealed.method !== method.name)
+        throw new Error("Background origin must match the verified foreground method");
+    return {
+        ...caller,
+        backgroundLane: actorLane(caller.actor),
+        backgroundOrigin: sealed,
+    };
+}
+/** App-side eligibility reads only the host-attested context; it never invents ancestry. */
+export function mayEnqueueBackground(context) {
+    return (context.actor.kind === "member" &&
+        context.workflow === undefined &&
+        context.backgroundOrigin !== undefined &&
+        context.backgroundLane === actorLane(context.actor) &&
+        Schema.is(WatchdogQueuedJobSchema.fields.lane)(context.backgroundLane));
+}
+const member = z.strictObject(hostActorSchema.def.options[0].shape);
+const revision = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+/** Identity and observed revisions only. Unknown fields, including bearer material, refuse. */
+export const backgroundWakeSchema = z
+    .strictObject({
+    installationId: z.string().min(1).max(256),
+    actor: member,
+    lane: z
+        .string()
+        .refine((value) => Schema.is(WatchdogQueuedJobSchema.fields.lane)(value)),
+    originMethod: z.string().refine(isAppApiMethodName),
+    observed: z.strictObject({
+        authorityVersion: revision,
+        artifactDigest: z.custom((value) => Schema.is(sha256DigestSchema)(value)),
+        // Oyster has no member revision. The Hub supplies its real directory revision.
+        membershipVersion: revision.optional(),
+    }),
+    epoch: revision,
+})
+    .refine((wake) => wake.lane === actorLane(wake.actor), {
+    message: "Wake lane must name its member",
+});
+/** The App can settle a refused lane without receiving any binding authority. */
+export const backgroundRefusalCodeSchema = z.enum([
+    "access_changed",
+    "installation_unavailable",
+]);
+/** Cleanup payload for one refused member lane; contains no actor or authority. */
+export const backgroundSyncRefusalSchema = z.strictObject({
+    lane: z
+        .string()
+        .startsWith("member:")
+        .min(8)
+        .refine((value) => Schema.is(WatchdogQueuedJobSchema.fields.lane)(value)),
+    code: backgroundRefusalCodeSchema,
+});
+/** Resolve then re-admit. Observed revisions are evidence, never equality pins. */
+export async function readmitBackground(input, ports) {
+    const wake = backgroundWakeSchema.parse(input);
+    const principal = await ports.resolve(wake.actor);
+    if (principal === null)
+        return { kind: "refused", code: "access_changed" };
+    const decision = await ports.admit(principal, wake);
+    if (decision.kind === "admitted") {
+        const context = { ...parseAppMethodCallContext(decision.context, true) };
+        // Fresh admission of a continuation does not grant another enqueue wake.
+        delete context.backgroundLane;
+        delete context.backgroundOrigin;
+        if (!mayDefer(context, []) || actorLane(context.actor) !== wake.lane)
+            return { kind: "refused", code: "access_changed" };
+        return { kind: "admitted", context };
+    }
+    switch (decision.code) {
+        case "stale_authority":
+            return { kind: "retry" };
+        case "unavailable":
+            return { kind: "refused", code: "installation_unavailable" };
+        case "level_too_low":
+        case "requires_not_granted":
+        case "not_approved":
+        case "denied":
+            return { kind: "refused", code: "access_changed" };
+    }
+}

package/dist/buyer-references.d.ts

@@ -0,0 +1,69 @@
+import * as Schema from "effect/Schema";
+import type { AppReleaseD1Database } from "./cloudflare.js";
+/** Positive installed-release custody. This record alone never grants access to a caller. */
+export declare const buyerReleaseReferenceSchema: Schema.Struct<{
+    readonly buyerTeamId: Schema.String;
+    readonly installationId: Schema.String;
+    readonly appId: Schema.refine<import("./index.js").AppId, Schema.String>;
+    readonly releaseId: Schema.refine<import("./index.js").ReleaseId, Schema.String>;
+    readonly artifactDigest: Schema.refine<import("./index.js").Sha256Digest, Schema.String>;
+    readonly publicSurfaceId: Schema.refine<import("./index.js").PublicSurfaceId, Schema.String>;
+    readonly stableRoute: Schema.refine<import("./index.js").StableRoute, Schema.String>;
+    readonly acquisitionVersion: Schema.Number;
+    readonly acquisitionDecisionId: Schema.String;
+    readonly selectionSequence: Schema.Number;
+}>;
+export type BuyerReleaseReference = Schema.Schema.Type<typeof buyerReleaseReferenceSchema>;
+/** No Surface FK: buyer references survive seller erasure and are the revocation recipient index. */
+export declare const buyerReferenceSchemaSql: string;
+/** Team admission owns the positive acquisition check before recording an install's retained basis. */
+export declare function createD1BuyerReferences(database: AppReleaseD1Database): {
+    retain: (raw: BuyerReleaseReference) => Promise<boolean>;
+    read: (input: {
+        buyerTeamId: string;
+        installationId: string;
+        releaseId: string;
+    }) => Promise<{
+        readonly buyerTeamId: string;
+        readonly installationId: string;
+        readonly appId: import("./index.js").AppId;
+        readonly releaseId: import("./index.js").ReleaseId;
+        readonly artifactDigest: import("./index.js").Sha256Digest;
+        readonly publicSurfaceId: import("./index.js").PublicSurfaceId;
+        readonly stableRoute: import("./index.js").StableRoute;
+        readonly acquisitionVersion: number;
+        readonly acquisitionDecisionId: string;
+        readonly selectionSequence: number;
+    } | null>;
+    readRetained: (input: {
+        buyerTeamId: string;
+        installationId: string;
+        releaseId: string;
+    }) => Promise<BuyerReleaseReference | null>;
+    readPublication: (stableRoute: string, releaseId: string) => Promise<{
+        readonly buyerTeamId: string;
+        readonly installationId: string;
+        readonly appId: import("./index.js").AppId;
+        readonly releaseId: import("./index.js").ReleaseId;
+        readonly artifactDigest: import("./index.js").Sha256Digest;
+        readonly publicSurfaceId: import("./index.js").PublicSurfaceId;
+        readonly stableRoute: import("./index.js").StableRoute;
+        readonly acquisitionVersion: number;
+        readonly acquisitionDecisionId: string;
+        readonly selectionSequence: number;
+    } | null>;
+    readFrozenInstallation: (buyerTeamId: string, installationId: string, appId: string) => Promise<{
+        readonly buyerTeamId: string;
+        readonly installationId: string;
+        readonly appId: import("./index.js").AppId;
+        readonly releaseId: import("./index.js").ReleaseId;
+        readonly artifactDigest: import("./index.js").Sha256Digest;
+        readonly publicSurfaceId: import("./index.js").PublicSurfaceId;
+        readonly stableRoute: import("./index.js").StableRoute;
+        readonly acquisitionVersion: number;
+        readonly acquisitionDecisionId: string;
+        readonly selectionSequence: number;
+    } | null>;
+    releaseInstallation: (buyerTeamId: string, installationId: string) => Promise<void>;
+    affectedApps: (releaseId: string) => Promise<import("./index.js").AppId[]>;
+};

package/dist/buyer-references.js

@@ -0,0 +1,154 @@
+import * as Schema from "effect/Schema";
+import { appIdSchema, publicSurfaceIdSchema, releaseIdSchema, sha256DigestSchema, stableRouteSchema, } from "./internal/app-release-schema.js";
+const identity = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(256)));
+/** Positive installed-release custody. This record alone never grants access to a caller. */
+export const buyerReleaseReferenceSchema = Schema.Struct({
+    buyerTeamId: identity,
+    installationId: identity,
+    appId: appIdSchema,
+    releaseId: releaseIdSchema,
+    artifactDigest: sha256DigestSchema,
+    publicSurfaceId: publicSurfaceIdSchema,
+    stableRoute: stableRouteSchema,
+    acquisitionVersion: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+    acquisitionDecisionId: identity,
+    selectionSequence: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+});
+/** No Surface FK: buyer references survive seller erasure and are the revocation recipient index. */
+export const buyerReferenceSchemaSql = `CREATE TABLE app_release_buyer_references (
+  buyer_team_id TEXT NOT NULL, installation_id TEXT NOT NULL,
+  app_id TEXT NOT NULL REFERENCES app_release_apps(app_id),
+  release_id TEXT NOT NULL REFERENCES app_release_releases(release_id),
+  artifact_digest TEXT NOT NULL, public_surface_id TEXT NOT NULL, stable_route TEXT NOT NULL,
+  acquisition_version INTEGER NOT NULL CHECK(acquisition_version>0),
+  acquisition_decision_id TEXT NOT NULL, selection_sequence INTEGER NOT NULL CHECK(selection_sequence>0),
+  PRIMARY KEY(buyer_team_id,installation_id,release_id)
+) STRICT;`.replaceAll("\n", " ") +
+    "\n" +
+    `CREATE INDEX app_release_buyers_by_release ON app_release_buyer_references(release_id,buyer_team_id,installation_id);`;
+const columns = `buyer_team_id AS buyerTeamId,installation_id AS installationId,app_id AS appId,
+  release_id AS releaseId,artifact_digest AS artifactDigest,public_surface_id AS publicSurfaceId,
+  stable_route AS stableRoute,acquisition_version AS acquisitionVersion,
+  acquisition_decision_id AS acquisitionDecisionId,selection_sequence AS selectionSequence`;
+/** Team admission owns the positive acquisition check before recording an install's retained basis. */
+export function createD1BuyerReferences(database) {
+    const read = async (input) => {
+        const row = await database
+            .prepare(`SELECT ${columns} FROM app_release_buyer_references
+      WHERE buyer_team_id=? AND installation_id=? AND release_id=?`)
+            .bind(input.buyerTeamId, input.installationId, input.releaseId)
+            .first();
+        return row === null
+            ? null
+            : Schema.decodeUnknownSync(buyerReleaseReferenceSchema)(row);
+    };
+    /** Retained acquisition authority is independent of current route custody, but never of verification or revocation. */
+    const readRetained = async (input) => {
+        const row = await database
+            .prepare(`SELECT ${columns} FROM app_release_buyer_references b
+      WHERE buyer_team_id=? AND installation_id=? AND release_id=?
+        AND EXISTS (SELECT 1 FROM app_release_releases r
+          JOIN app_release_release_verifications v ON v.release_id=r.release_id
+          WHERE r.release_id=b.release_id AND r.app_id=b.app_id
+            AND r.artifact_digest=b.artifact_digest AND v.artifact_digest=b.artifact_digest)
+        AND NOT EXISTS (SELECT 1 FROM app_release_transitions t
+          WHERE t.release_id=b.release_id AND t.operation_kind='revocation')`)
+            .bind(input.buyerTeamId, input.installationId, input.releaseId)
+            .first();
+        return row === null
+            ? null
+            : Schema.decodeUnknownSync(buyerReleaseReferenceSchema)(row);
+    };
+    const retain = async (raw) => {
+        const input = Schema.decodeUnknownSync(buyerReleaseReferenceSchema, {
+            onExcessProperty: "error",
+        })(raw);
+        await database
+            .prepare(`INSERT INTO app_release_buyer_references
+      (buyer_team_id,installation_id,app_id,release_id,artifact_digest,public_surface_id,stable_route,
+       acquisition_version,acquisition_decision_id,selection_sequence)
+      SELECT ?,?,?,?,?,?,?,?,?,? WHERE EXISTS (
+        SELECT 1 FROM app_release_route_claims c
+        JOIN app_release_public_surfaces s ON s.public_surface_id=c.public_surface_id
+        JOIN app_release_releases r ON r.app_id=s.app_id
+        JOIN app_release_release_verifications v ON v.release_id=r.release_id AND v.artifact_digest=r.artifact_digest
+        JOIN app_release_transitions t ON t.public_surface_id=s.public_surface_id AND t.release_id=r.release_id
+        WHERE c.state='held' AND c.public_surface_id=? AND c.stable_route=? AND s.app_id=?
+          AND r.release_id=? AND r.artifact_digest=? AND t.sequence=? AND t.operation_kind IN ('promotion','rollback')
+          AND NOT EXISTS (SELECT 1 FROM app_release_surface_retirements x WHERE x.public_surface_id=c.public_surface_id)
+          AND NOT EXISTS (SELECT 1 FROM app_release_safety_takedowns a WHERE a.app_id=s.app_id AND a.stable_route=s.stable_route)
+          AND NOT EXISTS (SELECT 1 FROM app_release_transitions revoked WHERE revoked.release_id=r.release_id AND revoked.operation_kind='revocation')
+      ) ON CONFLICT(buyer_team_id,installation_id,release_id) DO UPDATE SET
+        acquisition_version=MAX(acquisition_version,excluded.acquisition_version),
+        acquisition_decision_id=CASE WHEN excluded.acquisition_version>acquisition_version THEN excluded.acquisition_decision_id ELSE acquisition_decision_id END,
+        selection_sequence=MAX(selection_sequence,excluded.selection_sequence)
+      WHERE app_id=excluded.app_id AND artifact_digest=excluded.artifact_digest
+        AND public_surface_id=excluded.public_surface_id AND stable_route=excluded.stable_route`)
+            .bind(input.buyerTeamId, input.installationId, input.appId, input.releaseId, input.artifactDigest, input.publicSurfaceId, input.stableRoute, input.acquisitionVersion, input.acquisitionDecisionId, input.selectionSequence, input.publicSurfaceId, input.stableRoute, input.appId, input.releaseId, input.artifactDigest, input.selectionSequence)
+            .run();
+        const saved = await read(input);
+        return (saved !== null &&
+            saved.appId === input.appId &&
+            saved.artifactDigest === input.artifactDigest &&
+            saved.publicSurfaceId === input.publicSurfaceId &&
+            saved.stableRoute === input.stableRoute &&
+            saved.acquisitionVersion >= input.acquisitionVersion &&
+            (saved.acquisitionVersion > input.acquisitionVersion ||
+                saved.acquisitionDecisionId === input.acquisitionDecisionId) &&
+            saved.selectionSequence >= input.selectionSequence);
+    };
+    /** Formerly public immutable bytes remain deliverable while a buyer holds this exact publication. */
+    const readPublication = async (stableRoute, releaseId) => {
+        const row = await database
+            .prepare(`SELECT ${columns} FROM app_release_buyer_references
+      WHERE stable_route=? AND release_id=? ORDER BY buyer_team_id,installation_id LIMIT 1`)
+            .bind(stableRoute, releaseId)
+            .first();
+        if (row === null)
+            return null;
+        const reference = Schema.decodeUnknownSync(buyerReleaseReferenceSchema)(row);
+        return readRetained(reference);
+    };
+    /** Freeze following installs at their last admitted publication when that Surface loses custody. */
+    const readFrozenInstallation = async (buyerTeamId, installationId, appId) => {
+        const row = await database
+            .prepare(`SELECT ${columns} FROM app_release_buyer_references b
+      WHERE buyer_team_id=? AND installation_id=? AND app_id=?
+        AND NOT EXISTS (SELECT 1 FROM app_release_route_claims c
+          WHERE c.public_surface_id=b.public_surface_id AND c.state='held'
+            AND NOT EXISTS (SELECT 1 FROM app_release_surface_retirements x WHERE x.public_surface_id=c.public_surface_id))
+      ORDER BY selection_sequence DESC,release_id LIMIT 1`)
+            .bind(buyerTeamId, installationId, appId)
+            .first();
+        return row === null
+            ? null
+            : Schema.decodeUnknownSync(buyerReleaseReferenceSchema)(row);
+    };
+    const releaseInstallation = async (buyerTeamId, installationId) => {
+        await database
+            .prepare("DELETE FROM app_release_buyer_references WHERE buyer_team_id=? AND installation_id=?")
+            .bind(buyerTeamId, installationId)
+            .run();
+    };
+    const affectedApps = async (releaseId) => {
+        // Release identity has one App owner; the indexed existence read is bounded independently of buyer count.
+        const result = await database
+            .prepare(`SELECT DISTINCT app_id AS appId FROM app_release_buyer_references WHERE release_id=? LIMIT 2`)
+            .bind(releaseId)
+            .all();
+        const values = result.results.map((row) => Schema.decodeUnknownSync(Schema.Struct({ appId: appIdSchema }))(row)
+            .appId);
+        if (values.length > 1)
+            throw new Error("Buyer Release owner conflicts");
+        return values;
+    };
+    return {
+        retain,
+        read,
+        readRetained,
+        readPublication,
+        readFrozenInstallation,
+        releaseInstallation,
+        affectedApps,
+    };
+}

package/dist/cloudflare-assets.d.ts

@@ -0,0 +1,48 @@
+import type { AppReleaseCatalog, ReleaseId, ResolvedApp, StableRoute } from "./index.js";
+import { type AssetBuildPolicy, type BuildAsset } from "./assets.js";
+/** Native R2 metadata: checksums are validated by R2, not custom metadata claims. */
+export type AssetR2Object = {
+    readonly version: string;
+    readonly size: number;
+    readonly checksums: {
+        readonly sha256?: ArrayBuffer;
+    };
+};
+/** Native R2 operations required to verify and serve one asset build. */
+export type AssetR2Bucket = {
+    /** Read immutable object metadata without loading its body. */
+    head(key: string): Promise<AssetR2Object | null>;
+    /** Read immutable object metadata and its streaming body. */
+    get(key: string): Promise<(AssetR2Object & {
+        readonly body: ReadableStream<Uint8Array>;
+    }) | null>;
+};
+/** A missing referenced object is an unavailable build, never an unknown-path 404. */
+export declare class AssetBuildUnavailableError extends Error {
+    constructor();
+}
+export declare function matchesAssetObject(asset: BuildAsset, object: AssetR2Object | null): boolean;
+/** Verify every reference with bounded sequential native metadata reads. */
+export declare function verifyAssetBuildObjects(bytes: Uint8Array, bucket: Pick<AssetR2Bucket, "head">, policy: AssetBuildPolicy): Promise<void>;
+/**
+ * Caller supplies its owner-selected Release on every request. Catalog resolves
+ * and rechecks eligibility; neither pathname nor child ASSETS selects authority.
+ */
+export declare function readSelectedAssetBuild(options: {
+    /** App snapshot resolved by the caller at this delivery boundary. */
+    app: ResolvedApp;
+    /** Trusted host mount pathname; a handle-root shell supplies "/". */
+    base: string;
+    bucket: AssetR2Bucket;
+    policy: AssetBuildPolicy;
+    request: Request;
+}): Promise<Response>;
+/** Anonymous Surface delivery uses its current selection, never arbitrary unpublished IDs. */
+export declare function readPublicAssetBuild(options: {
+    catalog: Pick<AppReleaseCatalog, "resolvePublicAssetBuildVersion">;
+    stableRoute: StableRoute;
+    expectedReleaseId: ReleaseId;
+    bucket: AssetR2Bucket;
+    policy: AssetBuildPolicy;
+    request: Request;
+}): Promise<Response>;

package/dist/cloudflare-assets.js

@@ -0,0 +1,105 @@
+import { handleAssetRequest, } from "@fungi.computer/cloudflare-worker-bundler/assets";
+import { assetBuildMediaType, decodeAssetBuild, publicAssetBase, } from "./assets.js";
+/** A missing referenced object is an unavailable build, never an unknown-path 404. */
+export class AssetBuildUnavailableError extends Error {
+    constructor() {
+        super("Asset build unavailable");
+        this.name = "AssetBuildUnavailableError";
+    }
+}
+export function matchesAssetObject(asset, object) {
+    if (!object?.checksums.sha256 ||
+        object.version !== asset.version ||
+        object.size !== asset.byteLength)
+        return false;
+    const digest = Array.from(new Uint8Array(object.checksums.sha256), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `sha256:${digest}` === asset.digest;
+}
+/** Verify every reference with bounded sequential native metadata reads. */
+export async function verifyAssetBuildObjects(bytes, bucket, policy) {
+    const build = decodeAssetBuild(bytes, policy);
+    for (const asset of build.assets) {
+        if (!matchesAssetObject(asset, await bucket.head(asset.artifactRef)))
+            throw new AssetBuildUnavailableError();
+    }
+}
+/**
+ * Caller supplies its owner-selected Release on every request. Catalog resolves
+ * and rechecks eligibility; neither pathname nor child ASSETS selects authority.
+ */
+export async function readSelectedAssetBuild(options) {
+    if (options.app.ui?.mediaType !== assetBuildMediaType)
+        throw new AssetBuildUnavailableError();
+    return serveAssetBuild(options.app.ui, {
+        ...options,
+        expectedBase: options.base,
+        allowRelativeMount: true,
+    });
+}
+/** Anonymous Surface delivery uses its current selection, never arbitrary unpublished IDs. */
+export async function readPublicAssetBuild(options) {
+    const snapshot = await options.catalog.resolvePublicAssetBuildVersion(options.stableRoute, options.expectedReleaseId);
+    return serveAssetBuild(snapshot, {
+        ...options,
+        expectedBase: publicAssetBase(options.stableRoute, options.expectedReleaseId),
+        allowRelativeMount: true,
+    });
+}
+async function serveAssetBuild(snapshot, options) {
+    const build = decodeAssetBuild(snapshot.bytes.copy(), options.policy);
+    const base = build.base === "./" && options.allowRelativeMount
+        ? (options.expectedBase ?? "/")
+        : build.base;
+    if (options.expectedBase !== undefined && base !== options.expectedBase)
+        throw new AssetBuildUnavailableError();
+    const url = new URL(options.request.url);
+    if (url.pathname === base.slice(0, -1)) {
+        url.pathname = base;
+        return new Response(null, {
+            status: 307,
+            headers: {
+                Location: url.pathname + url.search,
+                "Cache-Control": "no-store",
+            },
+        });
+    }
+    if (!url.pathname.startsWith(base))
+        return new Response(null, { status: 404 });
+    url.pathname = "/" + url.pathname.slice(base.length);
+    const assetRequest = new Request(url, options.request);
+    const byPath = new Map(build.assets.map((asset) => [asset.path, asset]));
+    const manifest = new Map(build.assets.map((asset) => [
+        asset.path,
+        { contentType: asset.contentType, etag: asset.digest },
+    ]));
+    const response = await handleAssetRequest(assetRequest, manifest, {
+        async get(pathname) {
+            const asset = byPath.get(pathname);
+            if (!asset)
+                throw new AssetBuildUnavailableError();
+            const object = await options.bucket.get(asset.artifactRef);
+            // This metadata and body belong to the same native get result. A changed
+            // key cannot reuse old verification or leak replacement bytes.
+            if (!object || !matchesAssetObject(asset, object)) {
+                if (object)
+                    await object.body.cancel();
+                throw new AssetBuildUnavailableError();
+            }
+            return object.body;
+        },
+    }, { not_found_handling: "single-page-application" });
+    if (response && response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("Location");
+        if (location) {
+            const destination = new URL(location, url);
+            // Only maintained same-origin asset redirects are configured here.
+            if (destination.origin !== url.origin)
+                throw new AssetBuildUnavailableError();
+            destination.pathname = base + destination.pathname.slice(1);
+            const headers = new Headers(response.headers);
+            headers.set("Location", destination.pathname + destination.search + destination.hash);
+            return new Response(response.body, { status: response.status, headers });
+        }
+    }
+    return response ?? new Response("Not Found", { status: 404 });
+}