@dereekb/firebase 13.42.0 → 14.0.0

package/src/lib/model/formspace/formspace.d.ts

@@ -0,0 +1,461 @@
+import { type Maybe, type SlashPathFile } from '@dereekb/util';
+import { type GrantedReadRole, type GrantedUpdateRole, type GrantedDeleteRole } from '@dereekb/model';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type FirebaseAuthOwnershipKey, type FirebaseAuthUserId, type FirestoreModelKey } from '../../common';
+import { type NotificationKey } from '../notification/notification.id';
+import { type StorageFileId } from '../storagefile/storagefile.id';
+import { type FormSpaceFileSlot, type FormSpaceType } from './formspace.id';
+/**
+ * @module formspace
+ *
+ * Defines the FormSpace Firestore model: a generic, type-registered container that parks a client-side
+ * form's JSON while the user fills it out, accepts a bounded set of file uploads against it, and hands the
+ * finished result to server code that knows what to do with it.
+ *
+ * **Why one document.** The form's own values live embedded in `d` as pass-through JSON. Files are the
+ * thing that is actually large, and they live in GCS as ordinary {@link StorageFile}s inside a
+ * {@link StorageFileGroup} keyed by the FormSpace — so every existing sync / zip / delete behaviour applies
+ * unchanged and the document itself stays far under Firestore's 1 MiB ceiling.
+ *
+ * **Submission.** Submitting stamps `sat`, locks the space out of further edits, and moves `ps` to
+ * QUEUED_FOR_PROCESSING. A NotificationTask keyed by the space then dispatches to the registered
+ * server-side handler for its type, inheriting the checkpoint / retry / delay semantics every other task in
+ * the system already uses. `ps` mirrors {@link StorageFileProcessingState} field-for-field for exactly that
+ * reason: it is the same lifecycle.
+ */
+/**
+ * Model identity for the FormSpace collection (collection name: `formSpace`, prefix: `fsp`).
+ *
+ * Deliberately not `fs`: too easy to misread against `sf` (StorageFile) in `firestore.rules`.
+ */
+export declare const formSpaceIdentity: import("../..").RootFirestoreModelIdentity<"formSpace", "fsp">;
+/**
+ * Lifecycle state of a {@link FormSpace}.
+ *
+ * Only DRAFT is editable. SUBMITTED is awaiting or undergoing processing, and is the one state a space can
+ * come BACK from: a type declaring a reopen policy lets a caller holding the `reopen` role return the space
+ * to DRAFT until it is fully locked. EXPIRED (retired by the sweep before it was ever submitted) and
+ * ARCHIVED (kept for the record after processing concluded) stay terminal — {@link isFormSpaceReopenable}
+ * requires SUBMITTED, so neither is reachable by a reopen.
+ */
+export declare enum FormSpaceState {
+    DRAFT = 0,
+    SUBMITTED = 1,
+    EXPIRED = 2,
+    ARCHIVED = 3
+}
+/**
+ * Processing state of a submitted {@link FormSpace}.
+ *
+ * Mirrors {@link StorageFileProcessingState} value-for-value, because it drives the same NotificationTask
+ * machinery and a reader that already knows one should not have to learn a second vocabulary.
+ */
+export declare enum FormSpaceProcessingState {
+    INIT_OR_NONE = 0,
+    QUEUED_FOR_PROCESSING = 1,
+    PROCESSING = 2,
+    FAILED = 3,
+    SUCCESS = 4,
+    DO_NOT_PROCESS = 5
+}
+/**
+ * Validation state of one {@link FormSpaceFile}.
+ *
+ * A slot that declares no validator leaves every file at NONE — "nothing to check" and "checked and fine"
+ * are deliberately distinct, so a type that gains a validator later does not silently inherit a pass.
+ */
+export declare enum FormSpaceFileValidationState {
+    NONE = 0,
+    PENDING = 1,
+    VALID = 2,
+    INVALID = 3
+}
+/**
+ * Why validation could not reach a verdict about a file's CONTENT.
+ *
+ * Closed, unlike {@link FormSpaceFile.r}, because every member here is infrastructural: the object was gone,
+ * the file was superseded mid-check, no validator was registered, the validator threw. A content rejection's
+ * reason is written by the validator for a human to read and so cannot be enumerated.
+ */
+export type FormSpaceFileValidationFailureReason = 'replaced' | 'file_unavailable' | 'no_validator' | 'error';
+/**
+ * One file currently held in a {@link FormSpace} slot.
+ *
+ * The FormSpace's `f` array is the ONLY authority on what a space currently holds. The StorageFiles
+ * themselves are not queryable by the owner (`firestore.rules` grants `get` but not `list` on `/sf`) and the
+ * StorageFileGroup's own `f[]` is populated lazily by the group-sync sweep, so neither can answer "what is in
+ * this folder" at the moment an upload is accepted. This array is written in the same transaction that
+ * accepts the upload, so it always can.
+ *
+ * @dbxModelSubObject
+ */
+export interface FormSpaceFile {
+    /**
+     * The slot this file fills.
+     *
+     * @dbxModelVariable slot
+     */
+    sl: FormSpaceFileSlot;
+    /**
+     * The id of the StorageFile holding the bytes.
+     *
+     * @dbxModelVariable storageFileId
+     */
+    sf: StorageFileId;
+    /**
+     * The user who put the file here.
+     *
+     * On a single-user space this always equals the space's `u`; on a SHARED one it is whichever member
+     * actually uploaded, which is the only thing that can answer "is this MY file". Absent on an entry written
+     * before the field existed, where the space's `u` was necessarily the uploader — which is exactly what
+     * {@link formSpaceFileUploaderId} falls back to.
+     *
+     * @dbxModelVariable uploadedBy
+     */
+    ub?: Maybe<FirebaseAuthUserId>;
+    /**
+     * The file's name, as it was uploaded.
+     *
+     * @dbxModelVariable fileName
+     */
+    n: SlashPathFile;
+    /**
+     * Validation state.
+     *
+     * @dbxModelVariable validationState
+     */
+    v: FormSpaceFileValidationState;
+    /**
+     * Free-text reason the file was judged INVALID, written for the owner to act on.
+     *
+     * @dbxModelVariable invalidReason
+     */
+    r?: Maybe<string>;
+    /**
+     * Reason validation never reached a content verdict, if it did not.
+     *
+     * @dbxModelVariable failureReason
+     */
+    fr?: Maybe<FormSpaceFileValidationFailureReason>;
+    /**
+     * The date the upload was accepted.
+     *
+     * @dbxModelVariable uploadedAt
+     */
+    at: Date;
+    /**
+     * The date validation concluded, if it has.
+     *
+     * @dbxModelVariable validatedAt
+     */
+    vat?: Maybe<Date>;
+}
+/**
+ * Firestore sub-object converter for {@link FormSpaceFile}.
+ *
+ * Dates are stored as Unix seconds rather than timestamps, matching {@link storageFileGroupEmbeddedFile}:
+ * these are embedded in an array that is rewritten on every upload, and the compact form keeps the document
+ * small enough that the array is never the reason a space approaches Firestore's ceiling.
+ */
+export declare const formSpaceFileSubObject: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<FormSpaceFile, Partial<import("@dereekb/util").ReplaceType<FormSpaceFile, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * The arbitrary JSON a FormSpace parks while the user fills the form out.
+ *
+ * PASS-THROUGH: the framework never interprets it. The type's handler is what gives it meaning, and an app
+ * narrows this generic to its own interface at the point it reads the space.
+ */
+export type FormSpaceData = Record<string, unknown>;
+/**
+ * A type-registered container for a client-side form: its in-progress JSON, its uploads, and its
+ * submission state.
+ *
+ * `o` drives `resourceIsOwnedByAuthOwnershipKey()` in the security rules identically to `sf` / `sfg` / `cal`,
+ * and `ps` / `pn` / `pat` mirror {@link StorageFile}'s processing triple exactly.
+ *
+ * @template T - the shape of the embedded form data
+ * @dbxModel
+ * @dbxModelRead owner
+ * @dbxModelArchetype root-entity
+ * @dbxModelArchetype state-machine-item
+ */
+export interface FormSpace<T extends FormSpaceData = FormSpaceData> {
+    /**
+     * The kind of form this space holds, resolving its upload restrictions, expiration policy, and the
+     * server-side handler its submission is dispatched to.
+     *
+     * @dbxModelVariable formSpaceType
+     */
+    t: FormSpaceType;
+    /**
+     * Display name of the space, for the owner's own list of in-progress forms.
+     *
+     * @dbxModelVariable displayName
+     */
+    n?: Maybe<string>;
+    /**
+     * Lifecycle state. Only DRAFT is editable.
+     *
+     * @dbxModelVariable state
+     */
+    s: FormSpaceState;
+    /**
+     * Processing state of the submission.
+     *
+     * @dbxModelVariable processingState
+     */
+    ps: FormSpaceProcessingState;
+    /**
+     * The form's own values, stored as pass-through JSON.
+     *
+     * @dbxModelVariable data
+     */
+    d?: Maybe<T>;
+    /**
+     * The user the space belongs to. Set at creation and never changed.
+     *
+     * @dbxModelVariable userId
+     */
+    u: FirebaseAuthUserId;
+    /**
+     * Ownership key, if applicable. Drives read access in the security rules.
+     *
+     * @dbxModelVariable ownerKey
+     */
+    o?: Maybe<FirebaseAuthOwnershipKey>;
+    /**
+     * Key of the model this space was opened against, when it was opened against one.
+     *
+     * A TARGETING HANDLE, not an identity — several concurrent spaces may share one target, which is exactly
+     * why the FormSpace does not derive its own id from it.
+     *
+     * @dbxModelVariable targetModelKey
+     */
+    m?: Maybe<FirestoreModelKey>;
+    /**
+     * Monotonic count of uploads this space has ACCEPTED over its whole lifetime.
+     *
+     * NOT a live file count: superseding a slot still increments it. It exists so `maxUploads` can be
+     * enforced inside the same transaction that creates the StorageFile, which a query-based count could not
+     * do without a read of the whole collection.
+     *
+     * @dbxModelVariable uploadCount
+     */
+    uc: number;
+    /**
+     * The next index a file's permanent storage path is keyed by.
+     *
+     * NOT an index into `f`, and not a count of anything. It advances when a path is CLAIMED — before the
+     * bytes are copied and before the upload is accepted — so a claim that never becomes a file leaves a
+     * gap, which is the point. A gap costs nothing; a reused index puts two StorageFiles on one object, and
+     * deleting either then destroys the other's bytes.
+     *
+     * Deliberately separate from `uc`. `uc` is the upload BUDGET and must not move for a refused upload;
+     * this must move for every path handed out, refused or not.
+     *
+     * @dbxModelVariable nextFileIndex
+     */
+    fi: number;
+    /**
+     * Every file the space currently holds, across every slot.
+     *
+     * THE authority on the space's files. It is written in the same transaction that increments `uc`, so it is
+     * correct the instant an upload is accepted — which neither a StorageFile query (the owner cannot `list`
+     * `/sf`) nor the StorageFileGroup's lazily-synced `f[]` is.
+     *
+     * Flat rather than a map of slot to files: one array converts with one {@link firestoreObjectArray}, and
+     * the per-slot views callers actually want are a filter away. Bounded by the type's `maxUploads`.
+     *
+     * Distinct from `uc`: superseding a slot drops the old entry and appends a new one, leaving the length
+     * unchanged while `uc` still advances.
+     *
+     * @dbxModelVariable files
+     */
+    f: FormSpaceFile[];
+    /**
+     * The NotificationTask key processing this space's submission.
+     *
+     * Set when the submission is queued; cleared once processing is no longer PROCESSING.
+     *
+     * @dbxModelVariable processingNotificationKey
+     */
+    pn?: Maybe<NotificationKey>;
+    /**
+     * The date `ps` was last moved to PROCESSING. Used to detect a stuck task.
+     *
+     * @dbxModelVariable processingAt
+     */
+    pat?: Maybe<Date>;
+    /**
+     * Created at date.
+     *
+     * @dbxModelVariable createdAt
+     */
+    cat: Date;
+    /**
+     * Updated at date. Moves on every content change.
+     *
+     * @dbxModelVariable updatedAt
+     */
+    uat: Date;
+    /**
+     * The date the CURRENT submission was made, if the space is submitted. Its presence IS the lock.
+     *
+     * Cleared by a reopen, which is what hands the space back as an editable draft, so it always describes
+     * the submission in force NOW rather than the history. `fsat` is what remembers the first one.
+     *
+     * @dbxModelVariable submittedAt
+     */
+    sat?: Maybe<Date>;
+    /**
+     * The date the space was FIRST submitted, if it ever was.
+     *
+     * Never cleared. Since a reopen clears `sat`, without this the fact that the space was submitted at all —
+     * and when — would be destroyed by the first reopen. It is also the anchor
+     * {@link resolveFormSpaceLocksAt} measures the type's `reopenableUntil` from, which is what stops a
+     * reopen/resubmit round from walking the lock deadline forward.
+     *
+     * @dbxModelVariable firstSubmittedAt
+     */
+    fsat?: Maybe<Date>;
+    /**
+     * The date processing of the submission concluded, if it has.
+     *
+     * @dbxModelVariable completedAt
+     */
+    cpat?: Maybe<Date>;
+    /**
+     * The date this space becomes eligible for the expiration sweep, if it expires at all.
+     *
+     * CLEARED whenever the space leaves the expirable window — on submit, and on expiry itself. That is what
+     * keeps {@link formSpacesDueForExpirationQuery} on a single-field inequality: Firestore skips a document
+     * where the field is absent, so a cleared `eat` removes the space from the sweep entirely.
+     *
+     * @dbxModelVariable expiresAt
+     */
+    eat?: Maybe<Date>;
+    /**
+     * The date reopening stops being possible — the instant the submission becomes FULLY LOCKED.
+     *
+     * Written once, on the first submit, as `fsat + reopenableUntil`, and never moved afterwards; an explicit
+     * lock sets it to that moment instead. Absent means there is no CEILING, not that the space is locked:
+     * the type's `reopenableFor` is the master switch, and a type declaring neither is simply never
+     * reopenable. The same "an absent field is an absent gate" convention `eat` uses.
+     *
+     * Stored as an ISO8601 string like every other date here, which means `firestore.rules` CANNOT compare it
+     * against `request.time` — rules convert only bool/int/float/null to a string, never a timestamp. A
+     * downstream app that needs the lock predicate inside its OWN rules has to denormalize a unix-seconds
+     * mirror onto its own model and compare that. Reading this field over a callable, or over the `get` the
+     * rules already grant, needs no mirror at all.
+     *
+     * @dbxModelVariable locksAt
+     */
+    lat?: Maybe<Date>;
+    /**
+     * The user who locked the submission early, when a caller did rather than the deadline passing.
+     *
+     * @dbxModelVariable lockedBy
+     */
+    lby?: Maybe<FirebaseAuthUserId>;
+    /**
+     * Monotonic count of times this space has been REOPENED after a submission.
+     *
+     * Doubles as the submission-attempt generation. The submission task is keyed by it, so a resubmit gets a
+     * fresh task instead of colliding with the finished one, and a task still carrying a stale count is
+     * fenced off rather than clobbering the attempt in force.
+     *
+     * Monotonic for the same reason `uc` is: it counts rounds that happened, and a counter something can
+     * rewind is not a bound. Capped by the type's `maxReopens`.
+     *
+     * @dbxModelVariable reopenCount
+     */
+    rc: number;
+    /**
+     * The date the space was last reopened, if it ever was.
+     *
+     * @dbxModelVariable reopenedAt
+     */
+    rat?: Maybe<Date>;
+    /**
+     * The user who last reopened the space.
+     *
+     * @dbxModelVariable reopenedBy
+     */
+    rby?: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * Permission roles for FormSpace operations.
+ *
+ * `submit` is separate from `update` because it is the one-way door: an owner who may edit a draft is not
+ * necessarily the party allowed to finalize it.
+ *
+ * `uploadFile` and `removeFile` are separate from `update` for the mirror-image reason. On a SHARED space a
+ * member contributes files to a form whose `d` belongs to everyone; letting them add or take back their own
+ * file must not also let them rewrite the form. WHICH files a `removeFile` holder may remove is a second,
+ * per-file question the type's {@link FormSpaceFileAccess} answers — the role only opens the door.
+ *
+ * The two are enforced in DIFFERENT places, because an upload and a removal arrive by different routes.
+ * `removeFile` gates a callable, so a role map answers it directly. An upload has no callable at all — the
+ * client writes bytes into its own storage namespace and a storage trigger picks them up with no auth
+ * context to build a role map from — so `uploadFile` is the DECLARATION of who may contribute, and
+ * `FormSpaceUploadAuthorizationDelegate` is where the same app policy is actually applied. Grant them
+ * together, to the same people.
+ *
+ * `reopen` and `lock` are the two halves of undoing that door, and are separate from each other as much as
+ * from `submit`. `reopen` returns a submitted space to DRAFT; WHETHER it may be reopened at all is the
+ * type's own policy, re-asserted inside the action's transaction, so the role only says who is allowed to
+ * ask. `lock` goes the other way and ends the reopen window early — in a two-party flow that is a
+ * privilege the party who submitted should not automatically hold over the party reviewing, which is
+ * exactly why it is not folded into `reopen`.
+ */
+export type FormSpaceRoles = GrantedReadRole | GrantedUpdateRole | GrantedDeleteRole | 'submit' | 'uploadFile' | 'removeFile' | 'reopen' | 'lock';
+/**
+ * Firestore document wrapper for a {@link FormSpace}.
+ *
+ * Deliberately NOT generic over the form data. The converter and the collection are both typed to the base
+ * {@link FormSpace}, so a generic here would be a type-level claim nothing downstream could honour — a
+ * caller that knows its type's shape narrows `d` at the read site instead.
+ */
+export declare class FormSpaceDocument extends AbstractFirestoreDocument<FormSpace, FormSpaceDocument, typeof formSpaceIdentity> {
+    get modelIdentity(): import("../..").RootFirestoreModelIdentity<"formSpace", "fsp">;
+}
+/**
+ * Snapshot converter for {@link FormSpace} documents.
+ */
+export declare const formSpaceConverter: import("../..").SnapshotConverterFunctions<FormSpace<FormSpaceData>, Partial<import("@dereekb/util").ReplaceType<FormSpace<FormSpaceData>, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Returns the raw Firestore CollectionReference for the FormSpace collection.
+ *
+ * @param context - The Firestore context to use.
+ * @returns The CollectionReference for FormSpace documents.
+ */
+export declare function formSpaceCollectionReference(context: FirestoreContext): CollectionReference<FormSpace>;
+/**
+ * Typed FirestoreCollection for {@link FormSpace} documents.
+ */
+export type FormSpaceFirestoreCollection = FirestoreCollection<FormSpace, FormSpaceDocument>;
+/**
+ * Creates a fully configured {@link FormSpaceFirestoreCollection} with snapshot conversion and document factory.
+ *
+ * @param firestoreContext - The Firestore context to use.
+ * @returns A configured FormSpaceFirestoreCollection.
+ *
+ * @example
+ * ```ts
+ * const collection = formSpaceFirestoreCollection(firestoreContext);
+ * const doc = collection.documentAccessor().loadDocumentForId(formSpaceId);
+ * ```
+ */
+export declare function formSpaceFirestoreCollection(firestoreContext: FirestoreContext): FormSpaceFirestoreCollection;
+/**
+ * Abstract base providing access to the FormSpace Firestore collection.
+ *
+ * Implement this in your app module to wire up the collection for dependency injection.
+ *
+ * @dbxModelGroup FormSpace
+ */
+export declare abstract class FormSpaceFirestoreCollections {
+    abstract readonly formSpaceCollection: FormSpaceFirestoreCollection;
+}
+/**
+ * Union of all FormSpace-related model identity types.
+ */
+export type FormSpaceTypes = typeof formSpaceIdentity;

package/src/lib/model/formspace/formspace.id.d.ts

@@ -0,0 +1,60 @@
+import { type FirestoreModelId, type FirestoreModelKey, twoWayFlatFirestoreModelKey } from '../../common';
+/**
+ * @module formspace.id
+ *
+ * Identity types for the FormSpace model.
+ *
+ * A FormSpace has an ARBITRARY, auto-generated id rather than an id derived from another model's key: a
+ * user may hold several spaces of the same type against the same target at once (a resubmission, a second
+ * application), so a derived id would make two concurrent drafts collide. The association to another model
+ * is carried by the optional `m` (targetModelKey) field instead.
+ */
+/**
+ * Firestore document id for a FormSpace. Auto-generated.
+ */
+export type FormSpaceId = FirestoreModelId;
+/**
+ * Full Firestore document key (collection path + id) for a FormSpace.
+ */
+export type FormSpaceKey = FirestoreModelKey;
+/**
+ * The {@link FormSpaceId} of a space whose identity IS the model it was opened against.
+ *
+ * `formSpaceIdForModel('gb/abc123') // 'gb_abc123'`
+ *
+ * The DEFAULT shape is the one this module's own doc describes: an arbitrary id, because several concurrent
+ * drafts may target one model. This is the other shape — a space SHARED by everyone who reaches the target,
+ * where "one space per target" is the identity itself. There, a generated id is a bug rather than a
+ * convenience: two callers bootstrapping at once each mint a "shared" space, and neither sees the other's
+ * files. Deriving the id makes the create idempotent and lets a client read the space with a plain `get`
+ * before it has ever called create.
+ *
+ * Same construction as {@link calendarIdForModel}, and for the same reason.
+ */
+export declare const formSpaceIdForModel: typeof twoWayFlatFirestoreModelKey;
+/**
+ * Arbitrary string describing the kind of form a FormSpace holds, driving its upload restrictions, its
+ * expiration policy, and the server-side handler its submission is dispatched to through the app's
+ * {@link FormSpaceTypeConfig} registry.
+ *
+ * Open by design, exactly like {@link StorageFilePurpose} and {@link CalendarType}: a downstream app
+ * registers its own types without a library change.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:form-space
+ */
+export type FormSpaceType = string;
+/**
+ * Names one upload "slot" within a FormSpace — the resume, the cover letter, the photo of the ID.
+ *
+ * A slot is stored on the uploaded {@link StorageFile} as its `pg` (purposeSubgroup), which is what makes
+ * "replace the file in this slot" the existing `flagPreviousForDelete` behaviour rather than new machinery.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:form-space
+ */
+export type FormSpaceFileSlot = string;

package/src/lib/model/formspace/formspace.permission.d.ts

@@ -0,0 +1,47 @@
+import { type Getter, type Maybe } from '@dereekb/util';
+import { type FirebaseModelContext, type FirebasePermissionServiceModel, type FirestoreModelKey, type GrantRolesOtherwiseFunction, type GrantedRolesOtherwiseFunctionResult } from '../../common';
+import { type FormSpace, type FormSpaceDocument, type FormSpaceRoles } from './formspace';
+/**
+ * Configuration for {@link grantFormSpaceRolesForUserAuthFunction}, providing the permission
+ * service output, auth context, and target FormSpace document.
+ */
+export interface GrantFormSpaceRolesForUserAuthFunctionConfig<T extends FirebaseModelContext> {
+    readonly output: FirebasePermissionServiceModel<FormSpace, FormSpaceDocument>;
+    readonly context: T;
+    readonly model: FormSpaceDocument;
+}
+/**
+ * Input for the role granting function, specifying which roles to grant based on
+ * user ownership and/or ownership key matching.
+ */
+export interface GrantFormSpaceRolesForUserAuthInput {
+    /**
+     * Roles to grant if the user matches the FormSpace's `u` value.
+     */
+    readonly rolesForFormSpaceUser?: Maybe<Getter<GrantedRolesOtherwiseFunctionResult<FormSpaceRoles>>>;
+    /**
+     * Roles to grant if the FormSpace carries an ownership key.
+     */
+    readonly rolesForFormSpaceOwnershipKey?: Maybe<(ownershipKey: FirestoreModelKey) => GrantedRolesOtherwiseFunctionResult<FormSpaceRoles>>;
+}
+export type GrantFormSpaceRolesForUserAuthFunction = (input: GrantFormSpaceRolesForUserAuthInput) => GrantRolesOtherwiseFunction<FormSpaceRoles>;
+/**
+ * Creates a function that grants {@link FormSpaceRoles} based on the authentication context.
+ *
+ * Mirrors {@link grantStorageFileRolesForUserAuthFunction}: the two conditions — the caller IS the space's
+ * user, and the space carries an ownership key the caller satisfies — are evaluated in parallel and merged.
+ *
+ * @param config - Permission output, auth context, and target document for the grant.
+ * @returns Builder that takes role configuration and yields a GrantRolesOtherwiseFunction.
+ *
+ * @example
+ * ```ts
+ * const grantRoles = grantFormSpaceRolesForUserAuthFunction({ output, context, model });
+ * const otherwise = grantRoles({
+ *   rolesForFormSpaceUser: () => ({ read: true, update: true, submit: true, delete: true })
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function grantFormSpaceRolesForUserAuthFunction<T extends FirebaseModelContext>(config: GrantFormSpaceRolesForUserAuthFunctionConfig<T>): GrantFormSpaceRolesForUserAuthFunction;

package/src/lib/model/formspace/formspace.processing.d.ts

@@ -0,0 +1,86 @@
+import { type Maybe } from '@dereekb/util';
+import { type StorageFileMetadata } from '../storagefile/storagefile.id';
+import { type StorageFileProcessingSubtask, type StorageFileProcessingSubtaskMetadata } from '../storagefile/storagefile.task';
+import { type FormSpaceFileValidationFailureReason } from './formspace';
+import { type FormSpaceFileSlot } from './formspace.id';
+/**
+ * @module formspace.processing
+ *
+ * The subtask vocabulary and StorageFile metadata for validating a file uploaded into a FormSpace.
+ *
+ * FormSpace validation rides the EXISTING `SFP` storage-file processing task rather than a task type of its
+ * own: a validated attachment is a StorageFile being processed, and the retry, stuck-detection, delay, and
+ * cleanup behaviour it inherits is the whole reason the purpose-processor mechanism exists. The processor
+ * that consumes these lives server-side, in `@dereekb/firebase-server/model`.
+ */
+/**
+ * The first checkpoint: make sure the FormSpace knows this file exists.
+ *
+ * The upload initializer already writes the entry, in the same transaction that increments `uc` — that is
+ * what makes `maxFiles` enforceable and what gives the owner an entry the moment the upload is accepted.
+ * This step RECONCILES: it re-adds an entry for a StorageFile that carries this purpose but is missing from
+ * its space, which is the case for a file created by any path other than that initializer.
+ *
+ * It runs before validation so a reconciled file is validated in the same task rather than waiting for the
+ * next sweep to notice it.
+ */
+export declare const FORM_SPACE_PURPOSE_REGISTER_SUBTASK: StorageFileProcessingSubtask;
+/**
+ * The second checkpoint: run the slot's registered validator.
+ *
+ * One checkpoint rather than a `send`/`retrieve` pair like the resume check: a validator that needs to wait
+ * on something returns a `pending` verdict with a retry delay, which re-enters this same checkpoint. A
+ * second checkpoint would only add a state the validator cannot see.
+ */
+export declare const FORM_SPACE_PURPOSE_VALIDATE_SUBTASK: StorageFileProcessingSubtask;
+/**
+ * Type alias for the FormSpace file processing checkpoints.
+ */
+export type FormSpaceFileValidationSubtask = typeof FORM_SPACE_PURPOSE_REGISTER_SUBTASK | typeof FORM_SPACE_PURPOSE_VALIDATE_SUBTASK;
+/**
+ * Metadata carried between runs of the FormSpace file validation subtask.
+ *
+ * The verdict is recorded here as well as on the FormSpace because the cleanup step — which is what writes
+ * the StorageFile's final processing state — runs after the flow and can only see the persisted metadata.
+ */
+export interface FormSpaceFileValidationSubtaskMetadata extends StorageFileProcessingSubtaskMetadata {
+    /**
+     * The slot the file fills, copied from the StorageFile on the first run.
+     */
+    readonly slot?: Maybe<FormSpaceFileSlot>;
+    /**
+     * Whether the concluded verdict judged the file valid.
+     */
+    readonly valid?: Maybe<boolean>;
+    /**
+     * Free-text reason the file was judged invalid.
+     */
+    readonly reason?: Maybe<string>;
+    /**
+     * Reason no content verdict was reached.
+     */
+    readonly failureReason?: Maybe<FormSpaceFileValidationFailureReason>;
+    /**
+     * How many times the validator has been asked for a verdict.
+     */
+    readonly attempts?: Maybe<number>;
+    /**
+     * Whether the register step had to add the file back to its FormSpace.
+     *
+     * Normally false — the upload initializer already registered it. A true here means the file reached
+     * processing without its space knowing about it, which is worth being able to see after the fact.
+     */
+    readonly reconciled?: Maybe<boolean>;
+}
+/**
+ * Metadata written onto a validated FormSpace file's StorageFile.
+ *
+ * Mirrors what lands on the FormSpace, so a StorageFile inspected on its own still explains itself. A
+ * validator that wants to record more (extracted dates, a page count) returns its own metadata, which
+ * REPLACES this rather than merging — the validator owns the shape it needs downstream.
+ */
+export interface FormSpaceFileValidationStorageFileMetadata extends StorageFileMetadata {
+    readonly valid: boolean;
+    readonly reason?: Maybe<string>;
+    readonly checkedAt: Date;
+}