# gizfs:disk What the engine needs of a directory and its files. The engine and log take these interfaces, not gizlang:system's Dir and Stream, so a test can put a disk between them that fails where a real one can: a failed sync stops the engine. ```gizlang import * as Disk from "gizfs:disk"; ``` ## Types ### `NativePages` ```gizlang type NativePages = { disk: Disk; data: File; index: File; dataPath: string; indexPath: string; object: bytes; cache: PageCache; credits: ResourceContext; maxPageBytes: i64; } ``` One physical page owner for mutable catalog candidates and derived indexes. Roots remain values; files/cache/credits are execution resources, never a second transaction or durability authority. - `disk`: `M37.Disk` - `data`: `M37.File` - `index`: `M37.File` - `dataPath`: `string` - `indexPath`: `string` - `object`: `bytes` - `cache`: `M37.PageCache` - `credits`: `M37.ResourceContext` - `maxPageBytes`: `i64` ### `NativeFiles` ```gizlang type NativeFiles = { object: bytes; dataPath: string; indexPath: string; dataEnd: i64; indexEnd: i64; } ``` The object and paths of the files of a page owner, and their ends. - `object`: `bytes` - `dataPath`: `string` - `indexPath`: `string` - `dataEnd`: `i64` - `indexEnd`: `i64` ### `File` ```gizlang interface File { readAt(self: Self, offset: i64, count: i64): Result; readMany(self: Self, parts: Vec): Result; writeAt(self: Self, offset: i64, data: bytes): Result; truncate(self: Self, length: i64): Result; sync(self: Self): Result; size(self: Self): Result; close(self: Self): bool; } ``` A file of a disk: positional reads and writes, size, sync and close. - `readAt` - `readMany` - `writeAt` - `truncate` - `sync` - `size` - `close` ### `Entries` ```gizlang interface Entries { read(self: Self, limit: i64): Result, IoError>; close(self: Self): bool; } ``` A cursor over the names of a folder of a disk. - `read` - `close` ### `Disk` ```gizlang interface Disk { list(self: Self, path: string): Result, IoError>; entries(self: Self, path: string): Result; open(self: Self, path: string, mode: i64): Result; readFile(self: Self, path: string): Result; replaceFile(self: Self, path: string, data: bytes): Result; replaceRange(self: Self, path: string, source: File, start: i64, length: i64, windowBytes: i64): Result; remove(self: Self, path: string): Result; sync(self: Self): Result; } ``` A store of named files: a folder, a set of folders, a quota, or nowhere. - `list` - `entries` - `open` - `readFile` - `replaceFile` - `replaceRange` - `remove` - `sync` ### `DirDisk` ```gizlang type DirDisk = { dir: Dir; } ``` A directory of the real file system. - `dir`: `gizlang_system.Dir` ### `Quota` ```gizlang type Quota = { disk: Disk; used: Task.Cell; } ``` Bytes charged include retained open entries and admitted in-flight replacements. - `disk`: `M37.Disk` - `used`: `gizlang_task.Cell` ### `ResourceLease` ```gizlang type ResourceLease = { owner: Ref; slot: i64; generation: i64; } ``` A claim on resources: its owner, slot and generation, so an old lease cannot name a reused slot. - `owner`: `Ref` - `slot`: `i64` - `generation`: `i64` ### `Resources` ```gizlang type Resources = { identity: Ref; memoryLimit: i64; temporaryLimit: i64; memoryUsed: i64; temporaryUsed: i64; claims: Vec; cursor: i64; binding: Option; serial: i64; } ``` Memory and temporary-disk credit with limits, and the claims that hold it. - `identity`: `Ref` - `memoryLimit`: `i64` - `temporaryLimit`: `i64` - `memoryUsed`: `i64` - `temporaryUsed`: `i64` - `claims`: `Vec` - `cursor`: `i64` - `binding`: `_gizlang_sdk_core.Option` - `serial`: `i64` — The claims issued so far: a mark a statement takes before it runs (releaseSince). ### `ResourceUsage` ```gizlang type ResourceUsage = { memory: i64; temporary: i64; memoryLimit: i64; temporaryLimit: i64; pressured: bool; } ``` The memory and temporary bytes in use, their limits, and whether the memory is under pressure. - `memory`: `i64` - `temporary`: `i64` - `memoryLimit`: `i64` - `temporaryLimit`: `i64` - `pressured`: `bool` ### `ResourcePolicy` ```gizlang type ResourcePolicy = { memory: i64; temporary: i64; maxLeases: i64; cacheSlots: i64; pageBytes: i64; manifestBytes: i64; queryBytes: i64; queryRows: i64; } ``` Internal geometry comes from one caller-supplied allocator ceiling and temporary/disk credit. These are admission limits, never an estimate of available memory or RSS. - `memory`: `i64` - `temporary`: `i64` - `maxLeases`: `i64` - `cacheSlots`: `i64` - `pageBytes`: `i64` - `manifestBytes`: `i64` - `queryBytes`: `i64` - `queryRows`: `i64` ### `ResourceContext` ```gizlang type ResourceContext = | { kind: "serial"; credits: Resources; } | { kind: "scoped"; scope: Ref; } | { kind: "fenced"; scope: Ref; fence: ResourceLease; } ``` One accounting capability for shared Store algorithms. A scoped capability carries only the issuing actor reference; it never retains a loaded ledger across IO. - `serial` - `scoped` - `fenced` ### `PageRange` ```gizlang type PageRange = { owner: ResourceLease; offset: i64; length: i64; crc: u64; } ``` Immutable range coordinates are independent of a resident address. A range belongs to one live arena lease, so an old handle cannot name a subsequently reused file or lease. - `owner`: `M37.ResourceLease` - `offset`: `i64` - `length`: `i64` - `crc`: `u64` ### `LeasedPage` ```gizlang type LeasedPage = { lease: ResourceLease; data: bytes; } ``` The bytes of a page and the lease that pays for them. - `lease`: `M37.ResourceLease` - `data`: `bytes` ### `IoReceipts` ```gizlang type IoReceipts = { readBytes: i64; writeBytes: i64; reads: i64; writes: i64; readUnknown: bool; writeUnknown: bool; } ``` Successful positional transfers, not logical payload sizes or resource grants. An error may hide a partial OS transfer; its direction stays unknown thereafter. The counters saturate instead of wrapping. Copies of an arena share one file lineage. - `readBytes`: `i64` - `writeBytes`: `i64` - `reads`: `i64` - `writes`: `i64` - `readUnknown`: `bool` - `writeUnknown`: `bool` ### `TempPages` ```gizlang type TempPages = { directory: Dir; disk: Disk; file: File; lease: ResourceLease; end: i64; maxPageBytes: i64; sealed: bool; closed: bool; poisoned: bool; fileClosed: bool; removed: bool; receipts: Ref; } ``` Temporary pages in a scratch file: pages are appended, read in order, then the file is reset or closed. - `directory`: `gizlang_system.Dir` - `disk`: `M37.Disk` - `file`: `M37.File` - `lease`: `M37.ResourceLease` - `end`: `i64` - `maxPageBytes`: `i64` - `sealed`: `bool` - `closed`: `bool` - `poisoned`: `bool` - `fileClosed`: `bool` - `removed`: `bool` - `receipts`: `Ref` ### `TemporaryRange` ```gizlang type TemporaryRange = { start: i64; end: i64; } ``` A batch is admitted before any page is written. The same physical append and rollback owner is used for a page or a whole unpublished frame. Parts are not concatenated. - `start`: `i64` - `end`: `i64` ### `StoredPage` ```gizlang type StoredPage = { object: bytes; path: string; offset: i64; length: i64; crc: u64; } ``` Store supplies the page-history identity; published ranges are immutable even in an append arena. The cache never invents logical versions or reuses unpublished tail bytes. - `object`: `bytes` - `path`: `string` - `offset`: `i64` - `length`: `i64` - `crc`: `u64` ### `PagePosition` ```gizlang type PagePosition = { offset: i64; length: i64; crc: u64; } ``` Root positions are independent of the node-local arena binding. Only an admitted physical owner supplies an object scope and file when they are used. - `offset`: `i64` - `length`: `i64` - `crc`: `u64` ### `OrderedLink` ```gizlang type OrderedLink = { offset: i64; length: i64; crc: u64; count: i64; } ``` A link to an ordered child page, and an ordered page as decoded. The cache keeps a decoded page with its bytes, so a page is decoded once while it stays resident. - `offset`: `i64` - `length`: `i64` - `crc`: `u64` - `count`: `i64` ### `OrderedPage` ```gizlang type OrderedPage = { level: i64; keys: Vec; vals: Vec; links: Vec; count: i64; wire: i64; } ``` A decoded page of a paged ordered tree: its level, keys, values, links to child pages and count. - `level`: `i64` - `keys`: `Vec` - `vals`: `Vec` - `links`: `Vec` - `count`: `i64` - `wire`: `i64` ### `CachedPage` ```gizlang type CachedPage = { cache: ResourceLease; slot: i64; generation: i64; data: bytes; node: Option; } ``` A pin of a resident page. The slot counts its pins; a pin holds no grant of its own. - `cache`: `M37.ResourceLease` - `slot`: `i64` - `generation`: `i64` - `data`: `bytes` - `node`: `_gizlang_sdk_core.Option` ### `PageCacheUsage` ```gizlang type PageCacheUsage = { memoryLimit: i64; metadataBytes: i64; liveBytes: i64; pendingReads: i64; } ``` The memory limit of a page cache, the bytes of its metadata and live pages, and its reads in flight. - `memoryLimit`: `i64` - `metadataBytes`: `i64` - `liveBytes`: `i64` - `pendingReads`: `i64` ### `CacheRead` ```gizlang type CacheRead = { slot: i64; generation: i64; address: StoredPage; key: bytes; digest: bytes; page: ResourceLease; credit: i64; disk: Disk; receipts: Ref; files: Ref>; } ``` The read of a miss. It holds its own slot, grants, disk and receipt lineage, and no cache state, so any task can run it while the cache serves hits and other misses. - `slot`: `i64` - `generation`: `i64` - `address`: `M37.StoredPage` - `key`: `bytes` - `digest`: `bytes` - `page`: `M37.ResourceLease` - `credit`: `i64` - `disk`: `M37.Disk` - `receipts`: `Ref` - `files`: `Ref<_gizlang_sdk_collections.Map>` ### `CacheReadResult` ```gizlang type CacheReadResult = { page: Result; file: Option; } ``` What a read gives back: the page, and the file when its close failed. That file stays with the slot until a drain closes it. - `page`: `_gizlang_sdk_core.Result` - `file`: `_gizlang_sdk_core.Option` ### `CacheAdmission` ```gizlang type CacheAdmission = | { kind: "resident"; page: CachedPage; } | { kind: "read"; plan: CacheRead; } ``` A page that the cache holds, or the plan of a read that it must do. - `resident` - `read` ### `ResidentPage` ```gizlang type ResidentPage = { data: bytes; node: Option; } ``` A resident page for a synchronous point read, with no pin and no grant: its bytes and its decoded node, or none when the page is not resident (the caller then pins it, which reads it). The caller copies what it needs before it can suspend: an eviction afterwards frees nothing that the copy still refers to. A point read's pins took most of an index seek (a pin and its grant at each level). A hit marks the slot referenced, as a pin does. - `data`: `bytes` - `node`: `_gizlang_sdk_core.Option` ### `PageCache` ```gizlang type PageCache = { disk: Disk; state: Ref; } ``` A cache of decoded pages of DISK, shared by its copies. - `disk`: `M37.Disk` - `state`: `Ref` ## Functions ### `nativePages` ```gizlang function nativePages(disk: Disk, credits: mut ResourceContext, dataPath: string, indexPath: string, object: bytes, maxPageBytes: i64, cacheBytes: i64, cacheSlots: i64): Result, IoError> ``` The page owner of the data file DATAPATH and the index file INDEXPATH of OBJECT on DISK, with its page cache. Effects: fail, read, write, console, io. ### `withPages` ```gizlang function withPages(owner: Ref, operation: (pages: mut NativePages) => Result effects { read, write, fail, io, console }): Result ``` The result of OPERATION on the pages of OWNER. ### `syncPages` ```gizlang function syncPages(owner: Ref): Result ``` Makes the files of OWNER durable. Effects: fail, read, write, console, io. ### `pageFiles` ```gizlang function pageFiles(owner: Ref): Result ``` A frozen prefix of the one shared arena includes every semantic owner's published root, including lifecycle cuts and their derived page indexes. Effects: fail, read, io. ### `closePages` ```gizlang function closePages(owner: Ref): Result ``` Closes the cache and the files of OWNER. Effects: fail, read, write, console, io. ### `diskSet` ```gizlang function diskSet(disks: Vec): Disk ``` A disk that spreads its files over DISKS, or the one disk. Effects: fail. ### `diskOf` ```gizlang function diskOf(dir: Dir): Disk ``` The disk of the folder DIR. ### `nowhere` ```gizlang function nowhere(): Disk ``` A disk that fails each operation with an I/O error. Effects: fail. ### `nowhereFile` ```gizlang function nowhereFile(): File ``` A file that fails each operation with an I/O error. Effects: fail. ### `quotaDisk` ```gizlang function quotaDisk(inner: Disk, limit: i64): Result ``` INNER with a limit of LIMIT bytes over all its files. It fails when it cannot measure the files that are there. Effects: fail, io. ### `hostPolicy` ```gizlang function hostPolicy(quota: i64): Result ``` The policy of a database actor: half the runtime's memory limit (Memory.limitBytes, the one owner of the process's memory) less the process's fixed cost, at least 64 MiB, and spill credit within QUOTA (0: none). Half the whole limit put a restarted gizdb under 256 MiB at 295 MB: its cells and a scan's window (144 MB) on top of 143 MB held before. Its data (resident and cold columns) takes half of that again (Engine.dataBudget), and the rest of the limit stays for values no credit counts. A quarter of the memory available, up to 16 GiB, passed the runtime's 4 GiB on larger hosts: a 100M-row COPY stopped with R011. The server and the data actor (db/access.giz) both size themselves here. Effects: fail, read. ### `resourcePolicy` ```gizlang function resourcePolicy(memory: i64, temporary: i64): Result ``` The resource policy of MEMORY bytes (at least 1 MiB) and TEMPORARY bytes, with its cache and lease geometry. Effects: fail. ### `resourcesForPolicy` ```gizlang function resourcesForPolicy(policy: ResourcePolicy): Result ``` The resources of POLICY. It fails when POLICY is not one that resourcePolicy gives. Effects: fail, write. ### `resources` ```gizlang function resources(memory: i64, temporary: i64, maxLeases: i64): Result ``` Admission credits include a bounded lease directory. They do not replace the runtime's allocator accounting or claim to measure RSS. A lease is not clonable ownership. Effects: fail, write. ### `reserveScoped` ```gizlang function reserveScoped(scope: Ref, memory: i64, temporary: i64): Result ``` Actor scopes publish each ledger mutation before IO can suspend. Never keep a loaded Resources value across IO: finalization reloads the same issuing owner. Effects: fail, read, write, console, io. ### `resizeScoped` ```gizlang function resizeScoped(scope: Ref, lease: ResourceLease, memory: i64, temporary: i64): Result ``` Resources.resize on the shared SCOPE. Effects: fail, read, write, console, io. ### `releaseScoped` ```gizlang function releaseScoped(scope: Ref, lease: ResourceLease): Result ``` Resources.release on the shared SCOPE. Effects: fail, read, write, console, io. ### `grantedScoped` ```gizlang function grantedScoped(scope: Ref, lease: ResourceLease): i64 ``` The memory LEASE holds, or -1 when it is not live: a grant that already covers a need takes no resize. Effects: fail, write. ### `resourceSerial` ```gizlang function resourceSerial(scope: Ref): i64 ``` The ledger's mark for releaseSince. Effects: fail, read. ### `releaseSinceScoped` ```gizlang function releaseSinceScoped(scope: Ref, mark: i64): i64 ``` Resources.releaseSince on the ledger SCOPE holds. Effects: fail, read, write, console, io. ### `beginFenceScoped` ```gizlang function beginFenceScoped(scope: Ref, memory: i64, temporary: i64): Result ``` Starts a fence of MEMORY and TEMPORARY bytes on the shared SCOPE: the leases under it share its bytes. Effects: fail, read, write, console, io. ### `closeFenceScoped` ```gizlang function closeFenceScoped(scope: Ref, fence: ResourceLease): Result ``` Closes the fence FENCE on the shared SCOPE, and gives back its bytes. Effects: fail, read, write, console, io. ### `fenceUsageScoped` ```gizlang function fenceUsageScoped(scope: Ref, fence: ResourceLease): Result ``` Resources.fenceUsage on the shared SCOPE. Effects: fail, read. ### `serialContext` ```gizlang function serialContext(credits: mut Resources): ResourceContext ``` A serial context that holds CREDITS, moved: CREDITS is parked until the caller stores the context's ledger back (serialCredits). Effects: fail. ### `tempPagesContext` ```gizlang function tempPagesContext(sys: System, context: mut ResourceContext, maxPageBytes: i64): Result ``` IO dispatch preserves the issuing owner: a scoped ledger is never copied across suspension. Effects: fail, read, write, console, io. ### `tempPagesMemoryCredit` ```gizlang function tempPagesMemoryCredit(maxPageBytes: i64, liveFiles: i64): Result ``` Arena metadata plus the largest grant for ONE sequential active operation. Header certification releases its grant before payload admission. Returned pages retained across operations, concurrent IO, caller buffers and the issuer directory are separate live charges. This is admission geometry, not allocator/RSS or slot capacity. Zero files require no credit but still validate the page bound. No IO or allocation occurs. Effects: fail. ### `tempPages` ```gizlang function tempPages(sys: System, credits: mut Resources, maxPageBytes: i64): Result ``` One private grant and one append-only scratch file per query scope. Temporary data is reconstructible and never enters WAL. No resident entry is allocated per appended page. Effects: fail, write, io. ### `tempPagesScoped` ```gizlang function tempPagesScoped(sys: System, scope: Ref, maxPageBytes: i64): Result ``` Temporary pages on the shared SCOPE, in a new scratch file, with pages of at most MAXPAGEBYTES. Effects: fail, read, write, console, io. ### `pagePosition` ```gizlang function pagePosition(page: StoredPage): PagePosition ``` The position of PAGE in its file. ### `bindPage` ```gizlang function bindPage(position: PagePosition, object: bytes, path: string): StoredPage ``` The page at POSITION in OBJECT of the file at PATH. ### `pageCacheMetadataCredit` ```gizlang function pageCacheMetadataCredit(slots: i64): Result ``` Fixed metadata credit; dynamic bytes, retained decode/output buffers and issuer directory slots remain separate. This is admission geometry, not allocator RSS. Effects: fail. ### `pageCacheReadCredit` ```gizlang function pageCacheReadCredit(pageBytes: i64, pathBytes: i64): Result ``` A miss's coordinate/key and byte grants, from the SAME pin admission helpers. Successful publication shrinks the one grant to pageCacheResidentCredit. A hit takes no grant: its key is transient, in addition to all existing residents and pending IO. Effects: fail. ### `pageCacheResidentCredit` ```gizlang function pageCacheResidentCredit(pageBytes: i64, pathBytes: i64): Result ``` What a published page keeps: its bytes, their allocation header and its key. Its read needed pageCacheReadCredit until it ended, for the read buffer and the copy. Effects: fail. ### `pageKey` ```gizlang function pageKey(page: StoredPage): bytes ``` A stored page's identity as bytes: its file, object, place and seal (the page cache's key, and the row memo's owner). Effects: fail. ### `pageCacheContext` ```gizlang function pageCacheContext(disk: Disk, context: mut ResourceContext, slots: i64, memoryBytes: i64): Result ``` pageCache with CONTEXT. Effects: fail, read, write, console, io. ### `pageCache` ```gizlang function pageCache(disk: Disk, credits: mut Resources, slots: i64, memoryBytes: i64): Result ``` A page cache of DISK with SLOTS slots and at most MEMORYBYTES bytes, charged to CREDITS. Effects: fail, write. ## Methods ### `Disk.readRange` ```gizlang function Disk.readRange(self: Disk, path: string, offset: i64, count: i64, limit: i64): Result ``` Caller-admitted physical window; closes the temporary handle on every path. Effects: fail, read, write, io. ### `Resources.usage` ```gizlang function Resources.usage(self: Resources): ResourceUsage ``` The bytes in use and the limits. ### `Resources.limit` ```gizlang function Resources.limit(self: mut Resources, memory: i64, temporary: i64): Result ``` Reducing a limit preserves live work and reports pressure; it never invalidates a lease. Effects: fail. ### `Resources.available` ```gizlang function Resources.available(self: Resources): i64 ``` Headroom is the intersection of global credit and the bound execution cap. Effects: fail. ### `Resources.reserve` ```gizlang function Resources.reserve(self: mut Resources, memory: i64, temporary: i64): Result ``` A lease of MEMORY and TEMPORARY bytes. It fails when they do not fit. Effects: fail. ### `Resources.resize` ```gizlang function Resources.resize(self: mut Resources, lease: ResourceLease, memory: i64, temporary: i64): Result ``` Changes LEASE to MEMORY and TEMPORARY bytes. It fails when the lease is stale or the bytes do not fit. Effects: fail. ### `Resources.release` ```gizlang function Resources.release(self: mut Resources, lease: ResourceLease): Result ``` Gives back LEASE. It fails when the lease is stale. Effects: fail. ### `Resources.beginFence` ```gizlang function Resources.beginFence(self: mut Resources, memory: i64, temporary: i64): Result ``` A fence holds no placeholder bytes: its children consume the global grant once. The already admitted directory owns its metadata and generation. Effects: fail. ### `Resources.fenceUsage` ```gizlang function Resources.fenceUsage(self: Resources, fence: ResourceLease): Result ``` The bytes in use under the fence FENCE, and its limits. Effects: fail. ### `Resources.releaseSince` ```gizlang function Resources.releaseSince(self: mut Resources, mark: i64): i64 ``` Releases the claims issued after MARK (a value of Resources.serial), children before their fences: what a statement left reserved when it ended with a runtime fault, which ran no cleanup (db/sql/exec/stored.giz abandonStored). Left, they held its fence open and its session's close failed ("not enough memory"), which made storage read-only. The statement ran alone on its loop, so every claim past the mark is its own. The number of claims released. Effects: fail. ### `TempPages.appendContext` ```gizlang function TempPages.appendContext(self: mut TempPages, context: mut ResourceContext, data: bytes): Result ``` TempPages.append with CONTEXT. Effects: fail, read, write, console, io. ### `TempPages.nextContext` ```gizlang function TempPages.nextContext(self: TempPages, context: mut ResourceContext, offset: i64): Result, IoError> ``` TempPages.next with CONTEXT. Effects: fail, read, write, console, io. ### `TempPages.readContext` ```gizlang function TempPages.readContext(self: TempPages, context: mut ResourceContext, page: PageRange): Result ``` TempPages.read with CONTEXT. Effects: fail, read, write, console, io. ### `TempPages.sealContext` ```gizlang function TempPages.sealContext(self: mut TempPages, context: mut ResourceContext): Result ``` TempPages.seal with CONTEXT. Effects: fail, read. ### `TempPages.closeContext` ```gizlang function TempPages.closeContext(self: mut TempPages, context: mut ResourceContext): Result ``` TempPages.close with CONTEXT. Effects: fail, read, write, console, io. ### `LeasedPage.closeContext` ```gizlang function LeasedPage.closeContext(self: mut LeasedPage, context: mut ResourceContext): Result ``` LeasedPage.close with CONTEXT. Effects: fail, read, write, console, io. ### `ResourceContext.serialCredits` ```gizlang function ResourceContext.serialCredits(self: ResourceContext): Option ``` The resources of a serial context, or none. ### `ResourceContext.available` ```gizlang function ResourceContext.available(self: ResourceContext): i64 ``` The memory bytes that are still free. Effects: fail, read. ### `ResourceContext.memoryLimit` ```gizlang function ResourceContext.memoryLimit(self: ResourceContext): i64 ``` The memory limit. Effects: fail, read. ### `ResourceContext.valid` ```gizlang function ResourceContext.valid(self: ResourceContext, lease: ResourceLease): bool ``` Whether LEASE is live. Effects: fail, read, write. ### `ResourceContext.reserve` ```gizlang function ResourceContext.reserve(self: mut ResourceContext, memory: i64, temporary: i64): Result ``` Resources.reserve with this context. Effects: fail, read, write, console, io. ### `ResourceContext.resize` ```gizlang function ResourceContext.resize(self: mut ResourceContext, lease: ResourceLease, memory: i64, temporary: i64): Result ``` Resources.resize with this context. Effects: fail, read, write, console, io. ### `ResourceContext.release` ```gizlang function ResourceContext.release(self: mut ResourceContext, lease: ResourceLease): Result ``` Resources.release with this context. Effects: fail, read, write, console, io. ### `TempPages.ioReceipts` ```gizlang function TempPages.ioReceipts(self: TempPages): IoReceipts ``` The I/O counters of the file. Effects: fail, read. ### `File.readExact` ```gizlang function File.readExact(self: File, offset: i64, count: i64): Result ``` Positional IO is exact or fails. Short reads/writes make progress without retaining a second whole file. Allocation admission remains with the caller's one Resources owner. Effects: fail, read, write, io. ### `File.writeExact` ```gizlang function File.writeExact(self: File, offset: i64, data: bytes): Result ``` Writes all of DATA at OFFSET; the bytes written. It fails on a short write. Effects: fail, read, write, console, io. ### `File.writeAhead` ```gizlang function File.writeAhead(self: File, offset: i64, data: bytes, allocated: i64, limit: i64): Result ``` Writes DATA at OFFSET of a log file that holds ALLOCATED written bytes and gives the new count. When DATA passes them, the same write puts zeros after it to LOG_AHEAD_BYTES more (at most LIMIT). Later writes then overwrite written zeros, and their sync flushes only data, not a new file size (a 4 KiB dsync write on backup: 1.8 ms into written zeros, 6.2 ms when it extends the file). The caller syncs. A log format that never writes a zero length prefix ends its log at one, and a bad frame with only zeros after it (File.zeroesFrom) is a torn tail. A write that fits is not refused for its zeros: DATA is written first, then the zeros, and zeros that do not fit (ENOSPC, or EDQUOT past a quota) are left out. A refused data write then means its bytes were not all written (a full disk can take part of one write). Any other error of the zeros fails the call, so a damaged disk stops the log. Effects: fail, read, write, console, io. ### `File.zeroesFrom` ```gizlang function File.zeroesFrom(self: File, from: i64, to: i64): Result ``` True when the file holds only zeros from FROM to TO: written ahead (File.writeAhead), never a frame. Effects: fail, read, write, io. ### `File.truncateExact` ```gizlang function File.truncateExact(self: File, length: i64): Result ``` A rollback/reset is confirmed only at the requested actual file length. truncate returns a status, not a byte count; verify size independently. The owning transaction still fences uncertain storage on either IO failure. Effects: fail, read, write, console, io. ### `File.copyRangeTo` ```gizlang function File.copyRangeTo(self: File, target: File, from: i64, to: i64, length: i64, windowBytes: i64): Result ``` Copies a certified range with one bounded window. The caller owns both handles, their disjoint ranges, publication and admission; this never closes or syncs them. Effects: fail, read, write, console, io. ### `File.copyRangeContext` ```gizlang function File.copyRangeContext(self: File, target: File, credits: mut ResourceContext, from: i64, to: i64, length: i64, windowBytes: i64): Result ``` A contextful caller charges the same copying primitive to its sole physical ledger. Copy failure remains the first error even when returning its window grant also fails. Effects: fail, read, write, console, io. ### `Disk.replaceRangeContext` ```gizlang function Disk.replaceRangeContext(self: Disk, path: string, source: File, credits: mut ResourceContext, start: i64, length: i64, windowBytes: i64): Result ``` Atomic range publication charges the same copying window as an exact range copy. The Disk's existing publisher owns staging/quota/durability, not a second writer here. Effects: fail, read, write, console, io. ### `File.readPage` ```gizlang function File.readPage(self: File, credits: mut Resources, offset: i64, length: i64, crc: u64): Result ``` One admitted page read used by persistent and temporary files. Effects: fail, read, write, io. ### `File.readPageScoped` ```gizlang function File.readPageScoped(self: File, scope: Ref, offset: i64, length: i64, crc: u64): Result ``` File.readPage on the shared SCOPE. Effects: fail, read, write, console, io. ### `File.readPageContext` ```gizlang function File.readPageContext(self: File, context: mut ResourceContext, offset: i64, length: i64, crc: u64): Result ``` File.readPage with CONTEXT. Effects: fail, read, write, console, io. ### `ResourceLease.same` ```gizlang function ResourceLease.same(self: ResourceLease, other: ResourceLease): bool ``` Whether the two leases are the same claim. Effects: fail. ### `TempPages.append` ```gizlang function TempPages.append(self: mut TempPages, credits: mut Resources, data: bytes): Result ``` A short write is completed; an error rolls back the unpublished tail. Failed rollback poisons this temporary arena until cleanup, without releasing bytes still on disk. Effects: fail, read, write, console, io. ### `TempPages.appendScoped` ```gizlang function TempPages.appendScoped(self: mut TempPages, scope: Ref, data: bytes): Result ``` TempPages.append on the shared SCOPE. Effects: fail, read, write, console, io. ### `TempPages.appendParts` ```gizlang function TempPages.appendParts(self: mut TempPages, credits: mut Resources, sections: Vec>): Result ``` Appends SECTIONS as one page; the range of its bytes. Effects: fail, read, write, console, io. ### `TempPages.appendPartsScoped` ```gizlang function TempPages.appendPartsScoped(self: mut TempPages, scope: Ref, sections: Vec>): Result ``` TempPages.appendParts on the shared SCOPE. Effects: fail, read, write, console, io. ### `TempPages.appendPartsContext` ```gizlang function TempPages.appendPartsContext(self: mut TempPages, context: mut ResourceContext, sections: Vec>): Result ``` TempPages.appendParts with CONTEXT. Effects: fail, read, write, console, io. ### `TempPages.next` ```gizlang function TempPages.next(self: TempPages, credits: mut Resources, offset: i64): Result, IoError> ``` Sequential page directory is stored beside each payload, not retained as a growing Vec. Effects: fail, read, write, io. ### `TempPages.nextScoped` ```gizlang function TempPages.nextScoped(self: TempPages, scope: Ref, offset: i64): Result, IoError> ``` TempPages.next on the shared SCOPE. Effects: fail, read, write, console, io. ### `PageRange.after` ```gizlang function PageRange.after(self: PageRange): i64 ``` The offset after the page. Effects: fail. ### `TempPages.read` ```gizlang function TempPages.read(self: TempPages, credits: mut Resources, page: PageRange): Result ``` The bytes of PAGE, with a lease of CREDITS. It fails when the CRC does not match. Effects: fail, read, write, io. ### `TempPages.readScoped` ```gizlang function TempPages.readScoped(self: TempPages, scope: Ref, page: PageRange): Result ``` TempPages.read on the shared SCOPE. Effects: fail, read, write, console, io. ### `CacheRead.read` ```gizlang function CacheRead.read(self: CacheRead): CacheReadResult ``` Reads the page through the cache's open file. Give the result to the cache that admitted the read. Effects: fail, read, write, io. ### `LeasedPage.close` ```gizlang function LeasedPage.close(self: mut LeasedPage, credits: mut Resources): Result ``` Callers must drop all borrowed bytes before closing a page. The managed allocator retains physical ownership if a trusted caller deliberately copies bytes outside the lease. Effects: fail. ### `LeasedPage.closeScoped` ```gizlang function LeasedPage.closeScoped(self: mut LeasedPage, scope: Ref): Result ``` LeasedPage.close on the shared SCOPE. Effects: fail, read, write, console, io. ### `TempPages.seal` ```gizlang function TempPages.seal(self: mut TempPages, credits: Resources): Result ``` Ends the appends; reads may start. Effects: fail. ### `TempPages.sealScoped` ```gizlang function TempPages.sealScoped(self: mut TempPages, scope: Ref): Result ``` TempPages.seal on the shared SCOPE. Effects: fail, read. ### `TempPages.reset` ```gizlang function TempPages.reset(self: mut TempPages, credits: mut Resources): Result ``` Reuse only after the owning consumer drained the arena. Lease rotation fences all old coordinates/arena copies; zero-byte reservation avoids a release/readmit headroom gap. Effects: fail, read, write, console, io. ### `TempPages.resetScoped` ```gizlang function TempPages.resetScoped(self: mut TempPages, scope: Ref): Result ``` TempPages.reset on the shared SCOPE. Effects: fail, read, write, console, io. ### `TempPages.resetContext` ```gizlang function TempPages.resetContext(self: mut TempPages, context: mut ResourceContext): Result ``` TempPages.reset with CONTEXT. Effects: fail, read, write, console, io. ### `TempPages.close` ```gizlang function TempPages.close(self: mut TempPages, credits: mut Resources): Result ``` Deletion, then credit release. Failure keeps temporary-space credit rather than silently claiming that files left behind no longer use the query's allowance. Effects: fail, read, write, console, io. ### `TempPages.closeScoped` ```gizlang function TempPages.closeScoped(self: mut TempPages, scope: Ref): Result ``` TempPages.close on the shared SCOPE. Effects: fail, read, write, console, io. ### `Disk.fileSize` ```gizlang function Disk.fileSize(self: Disk, path: string): Result ``` The size in bytes of the file `path`. Effects: fail, io. ### `PageCache.isClosed` ```gizlang function PageCache.isClosed(self: PageCache): bool ``` Whether the cache is closed. Effects: fail, read. ### `PageCache.hits` ```gizlang function PageCache.hits(self: PageCache): i64 ``` The number of reads that found their page in the cache. Effects: fail, read. ### `PageCache.misses` ```gizlang function PageCache.misses(self: PageCache): i64 ``` The number of reads that read the file. Effects: fail, read. ### `PageCache.indexed` ```gizlang function PageCache.indexed(self: PageCache): i64 ``` The number of pages in the cache. Effects: fail, read. ### `PageCache.ioReceipts` ```gizlang function PageCache.ioReceipts(self: PageCache): IoReceipts ``` The I/O counters of the cache's reads. Effects: fail, read. ### `PageCache.usage` ```gizlang function PageCache.usage(self: PageCache): PageCacheUsage ``` The memory of the cache. Effects: fail, read. ### `PageCache.closeContext` ```gizlang function PageCache.closeContext(self: mut PageCache, context: mut ResourceContext): Result ``` PageCache.close with CONTEXT. Effects: fail, read, write, console, io. ### `PageCache.close` ```gizlang function PageCache.close(self: mut PageCache, credits: mut Resources): Result ``` Closes the cache and gives back its pages. Effects: fail, write, io. ### `PageCache.closeScoped` ```gizlang function PageCache.closeScoped(self: mut PageCache, scope: Ref): Result ``` PageCache.close on the shared SCOPE. Effects: fail, read, write, console, io. ### `PageCache.drain` ```gizlang function PageCache.drain(self: mut PageCache, credits: mut Resources): Result ``` Waits for the reads in flight and closes the files that they keep. Effects: fail, write, io. ### `PageCache.drainContext` ```gizlang function PageCache.drainContext(self: mut PageCache, context: mut ResourceContext): Result ``` PageCache.drain with CONTEXT. Effects: fail, read, write, console, io. ### `PageCache.admitContext` ```gizlang function PageCache.admitContext(self: mut PageCache, context: mut ResourceContext, address: StoredPage): Result ``` The page at ADDRESS when the cache holds it, else the plan of its read (the first half of a pin). Effects: fail, read, write, console, io. ### `PageCache.completeContext` ```gizlang function PageCache.completeContext(self: mut PageCache, context: mut ResourceContext, plan: CacheRead, read: CacheReadResult): Result ``` Puts the page of the read PLAN in the cache (the second half of a pin). Effects: fail, read, write, console, io. ### `PageCache.pinContext` ```gizlang function PageCache.pinContext(self: mut PageCache, context: mut ResourceContext, address: StoredPage): Result ``` A pin: the admission and the publication hold the state, the read between them does not. Effects: fail, read, write, console, io. ### `PageCache.loading` ```gizlang function PageCache.loading(self: PageCache, address: StoredPage): bool ``` True while a read of ADDRESS is in flight (admitted and not yet completed). Effects: fail, read. ### `PageCache.pin` ```gizlang function PageCache.pin(self: mut PageCache, credits: mut Resources, address: StoredPage): Result ``` The page at ADDRESS, from the cache or the file, pinned until CachedPage.close. Effects: fail, read, write, console, io. ### `PageCache.pinScoped` ```gizlang function PageCache.pinScoped(self: mut PageCache, scope: Ref, address: StoredPage): Result ``` PageCache.pin on the shared SCOPE. Effects: fail, read, write, console, io. ### `PageCache.resident` ```gizlang function PageCache.resident(self: mut PageCache, address: StoredPage): Option ``` The page at ADDRESS when the cache holds it, without a read. Effects: fail, write. ### `PageCache.reclaim` ```gizlang function PageCache.reclaim(self: mut PageCache, credits: mut Resources, bytes: i64): Result ``` Drops unpinned pages until BYTES bytes are free; the bytes freed. Effects: fail, write. ### `PageCache.reclaimContext` ```gizlang function PageCache.reclaimContext(self: mut PageCache, context: mut ResourceContext, bytes: i64): Result ``` PageCache.reclaim with CONTEXT. Effects: fail, read, write, console, io. ### `PageCache.invalidateTail` ```gizlang function PageCache.invalidateTail(self: mut PageCache, credits: mut Resources, object: bytes, path: string, start: i64): Result ``` Drops the cached pages of the file PATH of OBJECT from START, after the file was cut there; the pages dropped. Effects: fail, write, io. ### `PageCache.invalidateTailContext` ```gizlang function PageCache.invalidateTailContext(self: mut PageCache, context: mut ResourceContext, object: bytes, path: string, start: i64): Result ``` PageCache.invalidateTail with CONTEXT. Effects: fail, read, write, console, io. ### `PageCache.invalidateTailScoped` ```gizlang function PageCache.invalidateTailScoped(self: mut PageCache, scope: Ref, object: bytes, path: string, start: i64): Result ``` PageCache.invalidateTail on the shared SCOPE. Effects: fail, write, io. ### `PageCache.keepNodeContext` ```gizlang function PageCache.keepNodeContext(self: mut PageCache, context: mut ResourceContext, page: CachedPage, node: OrderedPage, credit: i64): Result ``` Keeps NODE, the decoded PAGE, in the cache, charged CREDIT bytes. Effects: fail, read, write, console, io. ### `PageCache.seedContext` ```gizlang function PageCache.seedContext(self: mut PageCache, context: mut ResourceContext, address: StoredPage, data: bytes): Result ``` Puts DATA in the cache as the page at ADDRESS, pinned. Effects: fail, read, write, console, io. ### `CachedPage.close` ```gizlang function CachedPage.close(self: mut CachedPage, cache: mut PageCache, credits: Resources): Result ``` Unpins the page. Effects: fail, write. ### `CachedPage.closeContext` ```gizlang function CachedPage.closeContext(self: mut CachedPage, cache: mut PageCache, context: mut ResourceContext): Result ``` CachedPage.close with CONTEXT. Effects: fail, read, write. ### `CachedPage.closeScoped` ```gizlang function CachedPage.closeScoped(self: mut CachedPage, cache: mut PageCache, scope: Ref): Result ``` CachedPage.close on the shared SCOPE. Effects: fail, read, write. ### `PageCache.lease` ```gizlang function PageCache.lease(self: PageCache): ResourceLease ``` The lease of the cache's metadata. Effects: fail, read. ## Constants ### `STORED_OBJECT_BYTES` ```gizlang const STORED_OBJECT_BYTES = 32 ``` The bytes of a stored object identity. ### `STORED_PATH_BYTES` ```gizlang const STORED_PATH_BYTES = 4096 ``` The most bytes of a stored path. ### `TEMP_PAGES_METADATA_BYTES` ```gizlang const TEMP_PAGES_METADATA_BYTES = 312 ``` The memory credit of the metadata of temporary pages. ### `LOG_AHEAD_BYTES` ```gizlang const LOG_AHEAD_BYTES = 4194304 ``` Bytes a log file grows by at a time (File.writeAhead).