> ## Documentation Index > Fetch the complete documentation index at: https://docs.bijection.com/llms.txt > Use this file to discover all available pages before exploring further. # Interface: FilesWriter > ctx.files in mutations and operations. [server](/api/modules/server).FilesWriter `ctx.files` in mutations and operations. ## Hierarchy * [`FilesReader`](/api/interfaces/server.FilesReader) ↳ **`FilesWriter`** ## Methods ### inspect ▸ **inspect**(`file`): `Promise`\<[`FileInfo`](/api/modules/values#fileinfo)> The metadata of a file, read through its locator. A protected file needs the route it is read through (`attachment(record, field)`), decided as delivery decides it, unless this transaction accepted it; its native row and current source permissions are read dependencies, so an erasure racing this transaction refuses its result or commit. Missing, erased and unauthorized files, and a protected file named without a route, throw `FileUnavailable`; an attachment whose field now names another file throws `FileAttachmentChanged`. An ordinary file needs no route. #### Parameters | Name | Type | | :- | :- | | `file` | [`AttachmentLocator`](/api/modules/files#attachmentlocator) \| [`FileRef`](/api/modules/values#fileref) | #### Returns `Promise`\<[`FileInfo`](/api/modules/values#fileinfo)> #### Inherited from [FilesReader](/api/interfaces/server.FilesReader).[inspect](/api/interfaces/server.FilesReader#inspect) *** ### isAvailable ▸ **isAvailable**(`file`): `Promise`\<`boolean`> Logical availability in this component's file namespace, including all ancestor erasure barriers. Reveals no metadata, permissions or byte capability; it does not probe physical blob existence. #### Parameters | Name | Type | | :- | :- | | `file` | [`FileRef`](/api/modules/values#fileref) | #### Returns `Promise`\<`boolean`> #### Inherited from [FilesReader](/api/interfaces/server.FilesReader).[isAvailable](/api/interfaces/server.FilesReader#isavailable) *** ### erasure ▸ **erasure**(`erasure`): `Promise`\<[`FileErasure`](/api/modules/server#fileerasure) | `null`> The progress of an accepted erasure of this component's file, read from durable state, or null when the reference names none. Reveals no digest, size, name or byte capability. #### Parameters | Name | Type | | :- | :- | | `erasure` | [`ErasureRef`](/api/modules/server#erasureref) | #### Returns `Promise`\<[`FileErasure`](/api/modules/server#fileerasure) | `null`> #### Inherited from [FilesReader](/api/interfaces/server.FilesReader).[erasure](/api/interfaces/server.FilesReader#erasure) *** ### inspectWorkloadGrant ▸ **inspectWorkloadGrant**(`file`, `options`): `Promise`\<[`WorkloadGrantInfo`](/api/interfaces/server.WorkloadGrantInfo)> This component's live workload grant of a file under the exact key. Current source permissions and erasure are read dependencies. Returns no URL or secret and never renews a delivery; suitable for queries and operation review. #### Parameters | Name | Type | | :- | :- | | `file` | [`FileRef`](/api/modules/values#fileref) | | `options` | `Object` | | `options.key` | `string` | #### Returns `Promise`\<[`WorkloadGrantInfo`](/api/interfaces/server.WorkloadGrantInfo)> #### Inherited from [FilesReader](/api/interfaces/server.FilesReader).[inspectWorkloadGrant](/api/interfaces/server.FilesReader#inspectworkloadgrant) *** ### accept ▸ **accept**(`staged`): `Promise`\<[`FileRef`](/api/modules/values#fileref)> Accept a staged file submitted to the current operation into its declared destination: `const file = await ctx.files.accept(source)`. The file, its attachment and the operation's other changes commit together. The engine checks at commit that the staged file belongs to this operation, input and destination, satisfies the declared bounds, and that the resulting record attaches it; accepting a file and not attaching it aborts the transaction. A failed transaction leaves the staged file reusable until its staging deadline. #### Parameters | Name | Type | | :- | :- | | `staged` | [`StagedFileRef`](/api/modules/values#stagedfileref) | #### Returns `Promise`\<[`FileRef`](/api/modules/values#fileref)> *** ### prepareUpload ▸ **prepareUpload**\<`Operation`>(`options`): `Promise`\<[`PreparedUpload`](/api/modules/server#preparedupload)> Prepare private, sealed staging for a declared operation file input. Transfer verifies the bytes; Save accepts the staged file in its ordinary business transaction. Upload selection and Save have separate request keys, so unrelated form fields remain editable while bytes arrive. #### Type parameters | Name | Type | | :- | :- | | `Operation` | extends [`OperationReference`](/api/modules/server#operationreference)\<`any`, `any`, `any`> | #### Parameters | Name | Type | | :- | :- | | `options` | [`PrepareUploadOptions`](/api/interfaces/server.PrepareUploadOptions)\<`Operation`> | #### Returns `Promise`\<[`PreparedUpload`](/api/modules/server#preparedupload)> *** ### erase ▸ **erase**(`file`): `Promise`\<[`FileErasure`](/api/modules/server#fileerasure)> Erase exact protected content. The file owner's disclosure rule must explicitly permit `storageErase`; read, replace and grant rights do not imply it. Detaching a relationship does not call erase. Requires every current attachment and source owner's erasure decision, and grants no permission to read the file. An attachment locator must still resolve to this exact file. A legal hold refuses it here, before acceptance; once accepted, nothing reopens access. Returns the accepted erasure request, `fenced` when this mutation commits, not an assertion that its work has finished: read its progress with `erasure`. #### Parameters | Name | Type | | :- | :- | | `file` | [`AttachmentLocator`](/api/modules/files#attachmentlocator) \| [`FileRef`](/api/modules/values#fileref) | #### Returns `Promise`\<[`FileErasure`](/api/modules/server#fileerasure)> *** ### eraseAttachments ▸ **eraseAttachments**(`record`): `Promise`\<`void`> Erase the immutable attachment scope established when this record's files were uploaded, including detached copies and transitive derivatives. The record's disclosure rule must permit `storageRecordErase`. Legal holds refuse it. Ordinary record deletion and detachment never call this method. Key destruction resumes durably after the mutation closes the scope. #### Parameters | Name | Type | | :- | :- | | `record` | [`GenericId`](/api/modules/values#genericid)\<`string`> | #### Returns `Promise`\<`void`> *** ### grant ▸ **grant**(`file`, `options`): `Promise`\<[`FileGrant`](/api/modules/files#filegrant)> Grant one recipient access to a protected file under current source policy, until `expires_at` (epoch milliseconds). The recipient reads it with the returned grant, itself a file locator. `request_key` makes a retried grant return the grant it already issued. #### Parameters | Name | Type | | :- | :- | | `file` | [`AttachmentLocator`](/api/modules/files#attachmentlocator) \| [`FileRef`](/api/modules/values#fileref) | | `options` | `Object` | | `options.request_key` | `string` | | `options.recipient` | `string` | | `options.expires_at` | `number` | #### Returns `Promise`\<[`FileGrant`](/api/modules/files#filegrant)> *** ### revoke ▸ **revoke**(`grant`): `Promise`\<`void`> Revoke one grant: no new read is admitted through it. Other grants and the stored bytes are unchanged. #### Parameters | Name | Type | | :- | :- | | `grant` | [`FileGrant`](/api/modules/files#filegrant) | #### Returns `Promise`\<`void`> *** ### grantWorkload ▸ **grantWorkload**(`file`, `options`): `Promise`\<`void`> Grant a workload this protected file's exact bytes until `expires_at` (at most `MAX_WORKLOAD_GRANT_LIFETIME_MS` ahead): this component's own work when `holder` is omitted, or an installed child (`holder`, e.g. `components.datasets`, and `key`, e.g. a version id). Call it in the mutation that admits the work: the file is read through the caller's current access (through its attachment, when a locator names one), and the commit is a disclosure of those reads to the workload, which the file's sources must permit. Repeating a grant the key holds live keeps it, and reads and discloses nothing. At most `MAX_WORKLOAD_GRANTS` per holder key; past it the refusal is a `BijectionError` `bound_exceeded` naming `WORKLOAD_GRANTS_BOUND`. #### Parameters | Name | Type | Description | | :- | :- | :- | | `file` | [`AttachmentLocator`](/api/modules/files#attachmentlocator) \| [`FileRef`](/api/modules/values#fileref) | - | | `options` | `Object` | - | | `options.holder?` | `object` | - | | `options.holder_function?` | [`FunctionHandle`](/api/modules/server#functionhandle)\<`"mutation"`> | A native handle of the receiving component's declared mutation. Supports a host-bound sibling input. The handle identifies a holder; the file's current source policies still authorize the transfer. | | `options.key` | `string` | - | | `options.format` | `string` | - | | `options.expires_at` | `number` | - | #### Returns `Promise`\<`void`> *** ### redeemWorkloadGrant ▸ **redeemWorkloadGrant**(`file`, `options`): `Promise`\<[`WorkloadDelivery`](/api/interfaces/server.WorkloadDelivery)> This component's workload grant, as a holder, of a file another component granted it under `key`, delivered to its worker: reads only the grant and the file's row, so it needs no identity. Only the holder redeems: called from any other component it finds no grant. Refused without a live grant. `expires_at` bounds this delivery in epoch milliseconds, independently of the grant, which it never extends. #### Parameters | Name | Type | | :- | :- | | `file` | [`FileRef`](/api/modules/values#fileref) \| `string` | | `options` | `Object` | | `options.key` | `string` | | `options.expires_at?` | `number` | #### Returns `Promise`\<[`WorkloadDelivery`](/api/interfaces/server.WorkloadDelivery)> *** ### passWorkloadGrants ▸ **passWorkloadGrants**(`from`, `to`): `Promise`\<`number`> Pass every live workload grant this component holds under `from` to its key `to` (a run's grants to its follow-up run), with fresh credentials and the same expiries; credentials issued under `from` stop working. A file `to` already holds keeps that grant. Refused past `MAX_WORKLOAD_GRANTS` under `to` (`bound_exceeded`). Returns the grants `to` gained. #### Parameters | Name | Type | | :- | :- | | `from` | `string` | | `to` | `string` | #### Returns `Promise`\<`number`> *** ### endWorkloadGrants ▸ **endWorkloadGrants**(`key`, `options?`): `Promise`\<`number`> End the workload grants this component holds under `key` (its run settled or was cancelled), or with `until` shorten them to end by then (its deadline). Never extends a grant. Returns the grants changed. #### Parameters | Name | Type | | :- | :- | | `key` | `string` | | `options?` | `Object` | | `options.until?` | `number` | #### Returns `Promise`\<`number`> This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.