cloudflare

Import

Import

import * as api from "@fungi.computer/puffball/cloudflare";

Exports

Kind	Export	Description
Ttype alias	AssetR2Object	Native R2 metadata: checksums are validated by R2, not custom metadata claims.
Ttype alias	AssetR2Bucket	Native R2 operations required to verify and serve one asset build.
Ttype alias	AppReleaseTransitionObligation	Durable catalog-scoped fact awaiting delivery to a separately owned Team.
Ttype alias	AppReleaseAffectedSurface	Catalog-owned public-Surface material carried with a transition obligation.
Ttype alias	AppReleaseTeamRecipient	Durable delivery state for one Team recipient of a transition obligation.
Ttype alias	AppReleaseTeamRecipientPage	One ordered page of Team IDs returned by the separately owned Team directory.
Ttype alias	AppReleaseTeamRecipientOutcome	Terminal delivery outcome recorded for one Team recipient.
Ttype alias	AppReleaseTransitionObligationStore	D1-only at-least-once read/ack seam; Team routing remains outside App Release.
Ttype alias	AppReleaseSurfaceTransitionBasis	Selected Release basis from the same D1 authority snapshot, including its transition sequence.
Ttype alias	AppReleaseD1QueryResult	Structural result returned by the D1 operations used by App Release.
Ttype alias	AppReleaseD1PreparedStatement	Structural prepared-statement surface needed by the D1-backed store.
Ttype alias	AppReleaseD1Database	Structural D1 surface kept independent of Cloudflare vendor declarations.
Ttype alias	AppReleaseR2Object	Structural R2 object surface needed by the artifact reader.
Ttype alias	AppReleaseR2Bucket	Structural R2 surface kept independent of Cloudflare vendor declarations.
Ttype alias	ErasureBucket	R2 operations used by the scoped Team erasure owner.
Ttype alias	ArtifactSnapshotPolicy	Trusted composition limit for reading one immutable artifact.
constconstant	appArtifactErasureReadbackSchema	The erasure coordinator consumes this owner-issued readback, including outstanding buyer custody.
constconstant	APP_RELEASE_D1_FRESH_SCHEMA	The one current App Release D1 schema for an empty catalog.
fnfunction	createTeamAppReleaseErasure()	Read every catalog reference before deleting content-addressed R2 objects.
fnfunction	createD1TeamAppPublisherRegistry()	Create the native registry that joins a Team publisher to one App/source.
fnfunction	createD1AppReleaseStore()	Create the D1-backed App Release store with private public-website authority.
fnfunction	createR2ArtifactReader()	Create the R2-backed artifact reader for opaque artifact references.
fnfunction	createD1TransitionObligationStore()	Open the D1-only obligation adjunct for a future owner-driven dispatcher. The ordinary App Release store contract intentionally does not expose it.
fnfunction	readD1SurfaceTransitionBasis()	Resolve one previously selected Release on a Surface and retain the exact transition sequence. The Release need not remain the Surface’s current default, but it must still be verified, active, and owned by that Surface.
fnfunction	matchEligibleSurfaceTransitionBasis()	Match one eligible selected Release without leaking store-result branching to consumers.

AssetR2ObjectTtype alias

Signature

type AssetR2Object = object;

Native R2 metadata: checksums are validated by R2, not custom metadata claims.

Properties

version

Signature

readonly version: string;

size

Signature

readonly size: number;

checksums

Signature

readonly checksums: object;

sha256?

Signature

readonly optional sha256?: ArrayBuffer;

---

AssetR2BucketTtype alias

Signature

type AssetR2Bucket = object;

Native R2 operations required to verify and serve one asset build.

Methods

head()

Signature

head(key): Promise<AssetR2Object | null>;

Read immutable object metadata without loading its body.

Parameters

Parameter	Type
key	string

Returns

Promise<AssetR2Object | null>

get()

Signature

get(key): Promise<AssetR2Object & object | null>;

Read immutable object metadata and its streaming body.

Parameters

Parameter	Type
key	string

Returns

Promise<AssetR2Object & object | null>

---

AppReleaseTransitionObligationTtype alias

Signature

type AppReleaseTransitionObligation = object;

Durable catalog-scoped fact awaiting delivery to a separately owned Team.

Properties

sequence

Signature

readonly sequence: number;

transition

Signature

readonly transition: ReleaseTransition;

transitionId

Signature

readonly transitionId: AppTransitionId;

affectedPublicSurfaceIds

Signature

readonly affectedPublicSurfaceIds: readonly PublicSurfaceId[];

affectedSurfaces

Signature

readonly affectedSurfaces: readonly AppReleaseAffectedSurface[];

Catalog-owned material needed by a Team without a second catalog read.

affectedBuyerApps

Signature

readonly affectedBuyerApps: readonly AppId[];

enumeration

Signature

readonly enumeration: object;

The last opaque Global Team cursor and whether enumeration is complete.

cursor

Signature

readonly cursor: string | null;

complete

Signature

readonly complete: boolean;

state

Signature

readonly state: "pending" | "acknowledged";

---

AppReleaseAffectedSurfaceTtype alias

Signature

type AppReleaseAffectedSurface = object;

Catalog-owned public-Surface material carried with a transition obligation.

Properties

publicSurfaceId

Signature

readonly publicSurfaceId: PublicSurfaceId;

appId

Signature

readonly appId: AppId;

stableRoute

Signature

readonly stableRoute: StableRoute;

---

AppReleaseTeamRecipientTtype alias

Signature

type AppReleaseTeamRecipient = object;

Durable delivery state for one Team recipient of a transition obligation.

Properties

teamId

Signature

readonly teamId: string;

state

Signature

readonly state: "pending" | "applied" | "no-op" | "expired";

---

AppReleaseTeamRecipientPageTtype alias

Signature

type AppReleaseTeamRecipientPage = object;

One ordered page of Team IDs returned by the separately owned Team directory.

Properties

cursor?

Signature

readonly optional cursor?: string | null;

Null identifies the first page; all later cursors remain opaque strings.

nextCursor?

Signature

readonly optional nextCursor?: string | null;

teamIds

Signature

readonly teamIds: readonly string[];

complete

Signature

readonly complete: boolean;

---

AppReleaseTeamRecipientOutcomeTtype alias

Signature

type AppReleaseTeamRecipientOutcome = "applied" | "no-op" | "expired";

Terminal delivery outcome recorded for one Team recipient.

---

AppReleaseTransitionObligationStoreTtype alias

Signature

type AppReleaseTransitionObligationStore = object;

D1-only at-least-once read/ack seam; Team routing remains outside App Release.

Methods

readByTransitionId()

Signature

readByTransitionId(transitionId): Promise<AppReleaseStoreResult<
  | AppReleaseTransitionObligation
  | {
  kind: "absent";
}>>;

Read one obligation by its immutable transition identity, or report it absent.

Parameters

Parameter	Type
transitionId	AppTransitionId

Returns

Promise<AppReleaseStoreResult< | AppReleaseTransitionObligation | { kind: "absent"; }>>

read()

Signature

read(options): Promise<AppReleaseStoreResult<readonly AppReleaseTransitionObligation[]>>;

Read pending obligations after a sequence cursor in ascending sequence order.

Parameters

Parameter	Type
options	{ afterSequence?: number; limit?: number; }
options.afterSequence?	number
options.limit?	number

Returns

Promise<AppReleaseStoreResult<readonly AppReleaseTransitionObligation[]>>

recordTeamRecipientPage()

Signature

recordTeamRecipientPage(sequence, page): Promise<AppReleaseStoreResult<
  | AppReleaseTransitionObligation
  | {
  kind: "absent";
}>>;

Persist the next ordered Team-recipient page; identical replays are idempotent.

Parameters

Parameter	Type
sequence	number
page	AppReleaseTeamRecipientPage

Returns

Promise<AppReleaseStoreResult< | AppReleaseTransitionObligation | { kind: "absent"; }>>

readPendingTeamRecipients()

Signature

readPendingTeamRecipients(options): Promise<AppReleaseStoreResult<readonly AppReleaseTeamRecipient[]>>;

Read pending recipients for one obligation in stable Team-ID order.

Parameters

Parameter	Type
options	{ sequence: number; limit?: number; }
options.sequence	number
options.limit?	number

Returns

Promise<AppReleaseStoreResult<readonly AppReleaseTeamRecipient[]>>

recordTeamRecipientOutcome()

Signature

recordTeamRecipientOutcome(
   sequence,
   teamId,
   outcome
): Promise<AppReleaseStoreResult<
  | AppReleaseTeamRecipient
  | {
  kind: "absent";
}>>;

Record a pending recipient’s terminal outcome; conflicting replays fail.

Parameters

Parameter	Type
sequence	number
teamId	string
outcome	AppReleaseTeamRecipientOutcome

Returns

Promise<AppReleaseStoreResult< | AppReleaseTeamRecipient | { kind: "absent"; }>>

acknowledge()

Signature

acknowledge(sequence): Promise<AppReleaseStoreResult<
  | AppReleaseTransitionObligation
  | {
  kind: "absent";
}>>;

Acknowledge only after enumeration is complete and no recipients remain pending.

Parameters

Parameter	Type
sequence	number

Returns

Promise<AppReleaseStoreResult< | AppReleaseTransitionObligation | { kind: "absent"; }>>

---

AppReleaseSurfaceTransitionBasisTtype alias

Signature

type AppReleaseSurfaceTransitionBasis =
  | {
      kind: "absent";
    }
  | {
      kind: "ambiguous";
    }
  | {
      kind: "none";
      appId: AppId;
      publicSurfaceId: PublicSurfaceId;
    }
  | {
      kind: "selected";
      appId: AppId;
      publicSurfaceId: PublicSurfaceId;
      releaseId: ReleaseId;
      sequence: number;
      eligibility: "eligible" | "ineligible";
      checkedAt: number;
    };

Selected Release basis from the same D1 authority snapshot, including its transition sequence.

Union Members

Type Literal

Signature

{
  kind: "absent";
}

---

Type Literal

Signature

{
  kind: "ambiguous";
}

---

Type Literal

Signature

{
  kind: "none";
  appId: AppId;
  publicSurfaceId: PublicSurfaceId;
}

---

Type Literal

Signature

{
  kind: "selected";
  appId: AppId;
  publicSurfaceId: PublicSurfaceId;
  releaseId: ReleaseId;
  sequence: number;
  eligibility: "eligible" | "ineligible";
  checkedAt: number;
}

Name	Type	Description
kind	"selected"	-
appId	AppId	-
publicSurfaceId	PublicSurfaceId	-
releaseId	ReleaseId	-
sequence	number	-
eligibility	"eligible" | "ineligible"	-
checkedAt	number	Authority-read start time; consumers may only shorten its horizon.

---

AppReleaseD1QueryResultTtype alias

Signature

type AppReleaseD1QueryResult = object;

Structural result returned by the D1 operations used by App Release.

Properties

success

Signature

readonly success: boolean;

Whether D1 completed the operation successfully.

results

Signature

readonly results: readonly unknown[];

Untrusted row values returned by the operation.

---

AppReleaseD1PreparedStatementTtype alias

Signature

type AppReleaseD1PreparedStatement = object;

Structural prepared-statement surface needed by the D1-backed store.

Methods

bind()

Signature

bind(...values): AppReleaseD1PreparedStatement;

Bind positional values and return the statement to execute.

Parameters

Parameter	Type
…values	unknown[]

Returns

AppReleaseD1PreparedStatement

first()

Signature

first(): Promise<object | null>;

Read the first untrusted row, or null when none exists.

Returns

Promise<object | null>

all()

Signature

all(): Promise<AppReleaseD1QueryResult>;

Read all matching rows.

Returns

Promise<AppReleaseD1QueryResult>

run()

Signature

run(): Promise<AppReleaseD1QueryResult>;

Execute a mutating statement.

Returns

Promise<AppReleaseD1QueryResult>

---

AppReleaseD1DatabaseTtype alias

Signature

type AppReleaseD1Database = object;

Structural D1 surface kept independent of Cloudflare vendor declarations.

Methods

prepare()

Signature

prepare(query): AppReleaseD1PreparedStatement;

Prepare one SQL statement for binding and execution.

Parameters

Parameter	Type
query	string

Returns

AppReleaseD1PreparedStatement

batch()

Signature

batch(statements): Promise<readonly AppReleaseD1QueryResult[]>;

Execute a group of statements atomically in native D1.

Parameters

Parameter	Type
statements	readonly AppReleaseD1PreparedStatement[]

Returns

Promise<readonly AppReleaseD1QueryResult[]>

---

AppReleaseR2ObjectTtype alias

Signature

type AppReleaseR2Object = object;

Structural R2 object surface needed by the artifact reader.

Properties

version

Signature

readonly version: string;

Native immutable object version checked for referenced App children.

size

Signature

readonly size: number;

Object size in bytes, checked before the body is buffered.

httpMetadata?

Signature

readonly optional httpMetadata?: object;

HTTP metadata retained with the object, when present.

contentType?

Signature

readonly optional contentType?: string;

Declared media type for the stored object.

Methods

arrayBuffer()

Signature

arrayBuffer(): Promise<ArrayBuffer>;

Read the immutable object body.

Returns

Promise<ArrayBuffer>

---

AppReleaseR2BucketTtype alias

Signature

type AppReleaseR2Bucket = object;

Structural R2 surface kept independent of Cloudflare vendor declarations.

Methods

get()

Signature

get(key): Promise<AppReleaseR2Object | null>;

Read one object by its opaque storage key.

Parameters

Parameter	Type
key	string

Returns

Promise<AppReleaseR2Object | null>

---

ErasureBucketTtype alias

Signature

type ErasureBucket = AppReleaseR2Bucket & object;

R2 operations used by the scoped Team erasure owner.

Type Declaration

Name	Type	Description
head()	(key) => Promise<object | null>	Read the metadata for an exact object key.
delete()	(key) => Promise<void>	Delete an exact object key after catalog references are checked.

---

ArtifactSnapshotPolicyTtype alias

Signature

type ArtifactSnapshotPolicy = Readonly<{
  maxBytes: number;
  maxManifestBytes?: number;
}>;

Trusted composition limit for reading one immutable artifact.

appArtifactErasureReadbackSchemaconstconstant

Signature

const appArtifactErasureReadbackSchema: Struct<{
  clear: Boolean;
  personalClear: Boolean;
  retainedArtifacts: $Array<
    Struct<{
      disposition_id: String;
      app_id: refine<AppId, String>;
      release_ids_json: String;
      artifact_roots_json: String;
      created_at: Number;
      state: Literals<
        readonly ["pending", "retaining", "retained", "revoking", "revoked"]
      >;
      request_id: NullOr<String>;
      reason: NullOr<String>;
      completed_at: NullOr<Number>;
      releaseIds: $Array<refine<ReleaseId, String>>;
    }>
  >;
  remaining: $Array<String>;
  pending: $Array<String>;
  obligationTeams: $Array<String>;
  obligationPages: $Array<String>;
  objects: $Array<String>;
}>;

The erasure coordinator consumes this owner-issued readback, including outstanding buyer custody.

---

APP_RELEASE_D1_FRESH_SCHEMAconstconstant

Signature

const APP_RELEASE_D1_FRESH_SCHEMA: string;

The one current App Release D1 schema for an empty catalog.

createTeamAppReleaseErasure()fnfunction

Signature

function createTeamAppReleaseErasure(
  database,
  bucket,
  assetPolicy?,
  now?,
): object;

Read every catalog reference before deleting content-addressed R2 objects.

Parameters

Parameter	Type	Default value
database	AppReleaseD1Database	undefined
bucket	ErasureBucket	undefined
assetPolicy?	{ maxManifestBytes: number; maxObjects: number; maxObjectBytes: number; maxTotalBytes: number; }	undefined
assetPolicy.maxManifestBytes?	number	positiveInteger
assetPolicy.maxObjects?	number	positiveInteger
assetPolicy.maxObjectBytes?	number	positiveInteger
assetPolicy.maxTotalBytes?	number	positiveInteger
now?	() => number	Date.now

Returns

Name	Type	Description
verifyManifest()	( teamId, appIds, keys ) => Promise<{ teamId: string; apps: object[]; repositories: string[]; }>	Reject any live App or R2 key outside this Team’s current or retry scope.
preflight()	(teamId) => Promise<{ teamId: string; apps: object[]; repositories: string[]; }>	Inventory Team catalog rows, exclusive objects, and source repositories.
erase()	(teamId) => Promise<{ apps: number; }>	Remove one Team’s catalog and exclusive objects, resuming pending jobs.
readback()	( teamId, appIds, keys ) => Promise<{ clear: boolean; personalClear: boolean; retainedArtifacts: object[]; remaining: string[]; pending: string[]; obligationTeams: string[]; obligationPages: string[]; objects: string[]; }>	Verify the named Apps, pending jobs, obligations and exclusive objects.

---

createD1TeamAppPublisherRegistry()fnfunction

Signature

function createD1TeamAppPublisherRegistry(database): TeamAppPublisherRegistry;

Create the native registry that joins a Team publisher to one App/source.

Parameters

Parameter	Type
database	AppReleaseD1Database

Returns

TeamAppPublisherRegistry

---

createD1AppReleaseStore()fnfunction

Signature

function createD1AppReleaseStore(database): PromiseAppReleaseStore & object;

Create the D1-backed App Release store with private public-website authority.

Parameters

Parameter	Type
database	AppReleaseD1Database

Returns

PromiseAppReleaseStore & object

---

createR2ArtifactReader()fnfunction

Signature

function createR2ArtifactReader(bucket, policy?, assets?): ArtifactReader;

Create the R2-backed artifact reader for opaque artifact references.

Asset manifests are verified cheaply for delivery: the root bytes are digest-checked here, while the asset handler checks the requested object. Publication callers pass verification: "publication" to retain the complete manifest object sweep.

Parameters

Parameter	Type	Default value
bucket	AppReleaseR2Bucket	undefined
policy	ArtifactSnapshotPolicy	DEFAULT_ARTIFACT_SNAPSHOT_POLICY
assets?	{ bucket: Pick<AssetR2Bucket, "head">; policy: { maxManifestBytes: number; maxObjects: number; maxObjectBytes: number; maxTotalBytes: number; }; }	undefined
assets.bucket?	Pick<AssetR2Bucket, "head">	undefined
assets.policy?	{ maxManifestBytes: number; maxObjects: number; maxObjectBytes: number; maxTotalBytes: number; }	undefined
assets.policy.maxManifestBytes?	number	positiveInteger
assets.policy.maxObjects?	number	positiveInteger
assets.policy.maxObjectBytes?	number	positiveInteger
assets.policy.maxTotalBytes?	number	positiveInteger

Returns

ArtifactReader

---

createD1TransitionObligationStore()fnfunction

Signature

function createD1TransitionObligationStore(
  database,
): AppReleaseTransitionObligationStore;

Open the D1-only obligation adjunct for a future owner-driven dispatcher. The ordinary App Release store contract intentionally does not expose it.

Parameters

Parameter	Type
database	AppReleaseD1Database

Returns

AppReleaseTransitionObligationStore

---

readD1SurfaceTransitionBasis()fnfunction

Signature

function readD1SurfaceTransitionBasis(
  database,
  stableRoute,
  releaseId,
  now?,
): Promise<AppReleaseStoreResult<AppReleaseSurfaceTransitionBasis>>;

Resolve one previously selected Release on a Surface and retain the exact transition sequence. The Release need not remain the Surface’s current default, but it must still be verified, active, and owned by that Surface.

Parameters

Parameter	Type	Default value
database	AppReleaseD1Database	undefined
stableRoute	StableRoute	undefined
releaseId	ReleaseId	undefined
now	() => number	Date.now

Returns

Promise<AppReleaseStoreResult<AppReleaseSurfaceTransitionBasis>>

---

matchEligibleSurfaceTransitionBasis()fnfunction

Signature

function matchEligibleSurfaceTransitionBasis(
  result,
  expected,
): {
  kind: "selected";
  appId: AppId;
  publicSurfaceId: PublicSurfaceId;
  releaseId: ReleaseId;
  sequence: number;
  eligibility: "eligible" | "ineligible";
  checkedAt: number;
} | null;

Match one eligible selected Release without leaking store-result branching to consumers.

Parameters

Parameter	Type
result	AppReleaseStoreResult<AppReleaseSurfaceTransitionBasis>
expected	Readonly<{ appId: AppId; releaseId: ReleaseId; sequence?: number; }>

Returns

Type Literal

Signature

{
  kind: "selected";
  appId: AppId;
  publicSurfaceId: PublicSurfaceId;
  releaseId: ReleaseId;
  sequence: number;
  eligibility: "eligible" | "ineligible";
  checkedAt: number;
}

Name	Type	Description
kind	"selected"	-
appId	AppId	-
publicSurfaceId	PublicSurfaceId	-
releaseId	ReleaseId	-
sequence	number	-
eligibility	"eligible" | "ineligible"	-
checkedAt	number	Authority-read start time; consumers may only shorten its horizon.

---

null