@fungi.computer/puffball 0.0.0-stage → 0.0.1

package/dist/cloudflare.d.ts

@@ -0,0 +1,254 @@
+import { type AssetBuildPolicy } from "./assets.js";
+import type { AssetR2Bucket } from "./cloudflare-assets.js";
+export type { AssetR2Bucket, AssetR2Object } from "./cloudflare-assets.js";
+import * as Schema from "effect/Schema";
+export type { ArtifactSnapshotPolicy } from "./internal/verified-artifact-snapshot.js";
+import { type ArtifactSnapshotPolicy } from "./internal/verified-artifact-snapshot.js";
+import type { AppReleaseStoreResult, AppTransitionId, ArtifactReader, ReleaseTransition } from "./internal/app-release-contract.js";
+import type { PromiseAppReleaseStore } from "./internal/app-release-contract.js";
+import type { AppId, PublicSurfaceId, ReleaseId } from "./internal/app-release-contract.js";
+import { type TeamAppPublisherRegistry } from "./publisher.js";
+/** Durable catalog-scoped fact awaiting delivery to a separately owned Team. */
+export type AppReleaseTransitionObligation = {
+    readonly sequence: number;
+    readonly transition: ReleaseTransition;
+    readonly transitionId: AppTransitionId;
+    readonly affectedPublicSurfaceIds: readonly PublicSurfaceId[];
+    /** Catalog-owned material needed by a Team without a second catalog read. */
+    readonly affectedSurfaces: readonly AppReleaseAffectedSurface[];
+    readonly affectedBuyerApps: readonly AppId[];
+    /** The last opaque Global Team cursor and whether enumeration is complete. */
+    readonly enumeration: {
+        readonly cursor: string | null;
+        readonly complete: boolean;
+    };
+    readonly state: "pending" | "acknowledged";
+};
+/** Catalog-owned public-Surface material carried with a transition obligation. */
+export type AppReleaseAffectedSurface = {
+    readonly publicSurfaceId: PublicSurfaceId;
+    readonly appId: AppId;
+    readonly stableRoute: import("./internal/app-release-contract.js").StableRoute;
+};
+/** Durable delivery state for one Team recipient of a transition obligation. */
+export type AppReleaseTeamRecipient = {
+    readonly teamId: string;
+    readonly state: "pending" | "applied" | "no-op" | "expired";
+};
+/** One ordered page of Team IDs returned by the separately owned Team directory. */
+export type AppReleaseTeamRecipientPage = {
+    /** Null identifies the first page; all later cursors remain opaque strings. */
+    readonly cursor?: string | null | undefined;
+    readonly nextCursor?: string | null | undefined;
+    readonly teamIds: readonly string[];
+    readonly complete: boolean;
+};
+/** Terminal delivery outcome recorded for one Team recipient. */
+export type AppReleaseTeamRecipientOutcome = "applied" | "no-op" | "expired";
+/** D1-only at-least-once read/ack seam; Team routing remains outside App Release. */
+export type AppReleaseTransitionObligationStore = {
+    /** Read one obligation by its immutable transition identity, or report it absent. */
+    readByTransitionId(transitionId: AppTransitionId): Promise<AppReleaseStoreResult<AppReleaseTransitionObligation | {
+        readonly kind: "absent";
+    }>>;
+    /** Read pending obligations after a sequence cursor in ascending sequence order. */
+    read(options: {
+        readonly afterSequence?: number | undefined;
+        readonly limit?: number | undefined;
+    }): Promise<AppReleaseStoreResult<readonly AppReleaseTransitionObligation[]>>;
+    /** Persist the next ordered Team-recipient page; identical replays are idempotent. */
+    recordTeamRecipientPage(sequence: number, page: AppReleaseTeamRecipientPage): Promise<AppReleaseStoreResult<AppReleaseTransitionObligation | {
+        readonly kind: "absent";
+    }>>;
+    /** Read pending recipients for one obligation in stable Team-ID order. */
+    readPendingTeamRecipients(options: {
+        readonly sequence: number;
+        readonly limit?: number | undefined;
+    }): Promise<AppReleaseStoreResult<readonly AppReleaseTeamRecipient[]>>;
+    /** Record a pending recipient's terminal outcome; conflicting replays fail. */
+    recordTeamRecipientOutcome(sequence: number, teamId: string, outcome: AppReleaseTeamRecipientOutcome): Promise<AppReleaseStoreResult<AppReleaseTeamRecipient | {
+        readonly kind: "absent";
+    }>>;
+    /** Acknowledge only after enumeration is complete and no recipients remain pending. */
+    acknowledge(sequence: number): Promise<AppReleaseStoreResult<AppReleaseTransitionObligation | {
+        readonly kind: "absent";
+    }>>;
+};
+/** Selected Release basis from the same D1 authority snapshot, including its transition sequence. */
+export type AppReleaseSurfaceTransitionBasis = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "ambiguous";
+} | {
+    readonly kind: "none";
+    readonly appId: AppId;
+    readonly publicSurfaceId: PublicSurfaceId;
+} | {
+    readonly kind: "selected";
+    readonly appId: AppId;
+    readonly publicSurfaceId: PublicSurfaceId;
+    readonly releaseId: ReleaseId;
+    readonly sequence: number;
+    readonly eligibility: "eligible" | "ineligible";
+    /** Authority-read start time; consumers may only shorten its horizon. */
+    readonly checkedAt: number;
+};
+/** Structural result returned by the D1 operations used by App Release. */
+export type AppReleaseD1QueryResult = {
+    /** Whether D1 completed the operation successfully. */
+    readonly success: boolean;
+    /** Untrusted row values returned by the operation. */
+    readonly results: readonly unknown[];
+};
+/** Structural prepared-statement surface needed by the D1-backed store. */
+export type AppReleaseD1PreparedStatement = {
+    /** Bind positional values and return the statement to execute. */
+    bind(...values: unknown[]): AppReleaseD1PreparedStatement;
+    /** Read the first untrusted row, or `null` when none exists. */
+    first(): Promise<object | null>;
+    /** Read all matching rows. */
+    all(): Promise<AppReleaseD1QueryResult>;
+    /** Execute a mutating statement. */
+    run(): Promise<AppReleaseD1QueryResult>;
+};
+/** Structural D1 surface kept independent of Cloudflare vendor declarations. */
+export type AppReleaseD1Database = {
+    /** Prepare one SQL statement for binding and execution. */
+    prepare(query: string): AppReleaseD1PreparedStatement;
+    /** Execute a group of statements atomically in native D1. */
+    batch(statements: readonly AppReleaseD1PreparedStatement[]): Promise<readonly AppReleaseD1QueryResult[]>;
+};
+/** Structural R2 object surface needed by the artifact reader. */
+export type AppReleaseR2Object = {
+    /** Native immutable object version checked for referenced App children. */
+    readonly version: string;
+    /** Object size in bytes, checked before the body is buffered. */
+    readonly size: number;
+    /** HTTP metadata retained with the object, when present. */
+    readonly httpMetadata?: {
+        /** Declared media type for the stored object. */
+        readonly contentType?: string;
+    };
+    /** Read the immutable object body. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+/** Structural R2 surface kept independent of Cloudflare vendor declarations. */
+export type AppReleaseR2Bucket = {
+    /** Read one object by its opaque storage key. */
+    get(key: string): Promise<AppReleaseR2Object | null>;
+};
+/** R2 operations used by the scoped Team erasure owner. */
+export type ErasureBucket = AppReleaseR2Bucket & {
+    /** Read the metadata for an exact object key. */
+    head(key: string): Promise<object | null>;
+    /** Delete an exact object key after catalog references are checked. */
+    delete(key: string): Promise<void>;
+};
+/** Read every catalog reference before deleting content-addressed R2 objects. */
+export declare function createTeamAppReleaseErasure(database: AppReleaseD1Database, bucket: ErasureBucket, assetPolicy?: AssetBuildPolicy, now?: () => number): {
+    /** Reject any live App or R2 key outside this Team's current or retry scope. */
+    verifyManifest(teamId: string, appIds: readonly string[], keys: readonly string[]): Promise<{
+        teamId: string;
+        apps: {
+            appId: string;
+            keys: readonly string[];
+        }[];
+        repositories: string[];
+    }>;
+    /** Inventory Team catalog rows, exclusive objects, and source repositories. */
+    preflight(teamId: string): Promise<{
+        teamId: string;
+        apps: {
+            appId: string;
+            keys: readonly string[];
+        }[];
+        repositories: string[];
+    }>;
+    /** Remove one Team's catalog and exclusive objects, resuming pending jobs. */
+    erase(teamId: string): Promise<{
+        apps: number;
+    }>;
+    /** Verify the named Apps, pending jobs, obligations and exclusive objects. */
+    readback(teamId: string, appIds: readonly string[], keys: readonly string[]): Promise<{
+        clear: boolean;
+        personalClear: boolean;
+        retainedArtifacts: {
+            releaseIds: readonly ReleaseId[];
+            disposition_id: string;
+            app_id: AppId;
+            release_ids_json: string;
+            artifact_roots_json: string;
+            created_at: number;
+            state: "pending" | "revoked" | "retaining" | "retained" | "revoking";
+            request_id: string | null;
+            reason: string | null;
+            completed_at: number | null;
+        }[];
+        remaining: string[];
+        pending: string[];
+        obligationTeams: string[];
+        obligationPages: string[];
+        objects: string[];
+    }>;
+};
+/** The erasure coordinator consumes this owner-issued readback, including outstanding buyer custody. */
+export declare const appArtifactErasureReadbackSchema: Schema.Struct<{
+    readonly clear: Schema.Boolean;
+    readonly personalClear: Schema.Boolean;
+    readonly retainedArtifacts: Schema.$Array<Schema.Struct<{
+        readonly releaseIds: Schema.$Array<Schema.refine<ReleaseId, Schema.String>>;
+        readonly disposition_id: Schema.String;
+        readonly app_id: Schema.refine<AppId, Schema.String>;
+        readonly release_ids_json: Schema.String;
+        readonly artifact_roots_json: Schema.String;
+        readonly created_at: Schema.Number;
+        readonly state: Schema.Literals<readonly ["pending", "retaining", "retained", "revoking", "revoked"]>;
+        readonly request_id: Schema.NullOr<Schema.String>;
+        readonly reason: Schema.NullOr<Schema.String>;
+        readonly completed_at: Schema.NullOr<Schema.Number>;
+    }>>;
+    readonly remaining: Schema.$Array<Schema.String>;
+    readonly pending: Schema.$Array<Schema.String>;
+    readonly obligationTeams: Schema.$Array<Schema.String>;
+    readonly obligationPages: Schema.$Array<Schema.String>;
+    readonly objects: Schema.$Array<Schema.String>;
+}>;
+/** The one current App Release D1 schema for an empty catalog. */
+export declare const APP_RELEASE_D1_FRESH_SCHEMA: string;
+/** Create the native registry that joins a Team publisher to one App/source. */
+export declare function createD1TeamAppPublisherRegistry(database: AppReleaseD1Database): TeamAppPublisherRegistry;
+/** Create the D1-backed App Release store with private public-website authority. */
+export declare function createD1AppReleaseStore(database: AppReleaseD1Database): PromiseAppReleaseStore & {
+    readonly transitionObligations: AppReleaseTransitionObligationStore;
+};
+/**
+ * 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.
+ */
+export declare function createR2ArtifactReader(bucket: AppReleaseR2Bucket, policy?: ArtifactSnapshotPolicy, assets?: {
+    readonly bucket: Pick<AssetR2Bucket, "head">;
+    readonly policy: AssetBuildPolicy;
+}): ArtifactReader;
+/**
+ * Open the D1-only obligation adjunct for a future owner-driven dispatcher.
+ * The ordinary App Release store contract intentionally does not expose it.
+ */
+export declare function createD1TransitionObligationStore(database: AppReleaseD1Database): AppReleaseTransitionObligationStore;
+/**
+ * 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.
+ */
+export declare function readD1SurfaceTransitionBasis(database: AppReleaseD1Database, stableRoute: import("./internal/app-release-contract.js").StableRoute, releaseId: ReleaseId, now?: () => number): Promise<AppReleaseStoreResult<AppReleaseSurfaceTransitionBasis>>;
+/** Match one eligible selected Release without leaking store-result branching to consumers. */
+export declare function matchEligibleSurfaceTransitionBasis(result: AppReleaseStoreResult<AppReleaseSurfaceTransitionBasis>, expected: Readonly<{
+    appId: AppId;
+    releaseId: ReleaseId;
+    sequence?: number;
+}>): Extract<AppReleaseSurfaceTransitionBasis, {
+    kind: "selected";
+}> | null;