# 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<bytes, IoError>; readMany(self: Self, parts: Vec<i64>): Result<bytes, IoError>; writeAt(self: Self, offset: i64, data: bytes): Result<i64, IoError>; truncate(self: Self, length: i64): Result<i64, IoError>; sync(self: Self): Result<bool, IoError>; size(self: Self): Result<i64, IoError>; 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<Vec<string>, 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<Vec<string>, IoError>; entries(self: Self, path: string): Result<Entries, IoError>; open(self: Self, path: string, mode: i64): Result<File, IoError>; readFile(self: Self, path: string): Result<bytes, IoError>; replaceFile(self: Self, path: string, data: bytes): Result<i64, IoError>; replaceRange(self: Self, path: string, source: File, start: i64, length: i64, windowBytes: i64): Result<i64, IoError>; remove(self: Self, path: string): Result<bool, IoError>; sync(self: Self): Result<bool, IoError>; }
```

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<i64>; }
```

Bytes charged include retained open entries and admitted in-flight replacements.

- `disk`: `M37.Disk`
- `used`: `gizlang_task.Cell<i64>`

### `ResourceLease`

```gizlang
type ResourceLease = { owner: Ref<bool>; slot: i64; generation: i64; }
```

A claim on resources: its owner, slot and generation, so an old lease cannot name a reused slot.

- `owner`: `Ref<bool>`
- `slot`: `i64`
- `generation`: `i64`

### `Resources`

```gizlang
type Resources = { identity: Ref<bool>; memoryLimit: i64; temporaryLimit: i64; memoryUsed: i64; temporaryUsed: i64; claims: Vec<ResourceClaim>; cursor: i64; binding: Option<ResourceLease>; serial: i64; }
```

Memory and temporary-disk credit with limits, and the claims that hold it.

- `identity`: `Ref<bool>`
- `memoryLimit`: `i64`
- `temporaryLimit`: `i64`
- `memoryUsed`: `i64`
- `temporaryUsed`: `i64`
- `claims`: `Vec<M37.ResourceClaim>`
- `cursor`: `i64`
- `binding`: `_gizlang_sdk_core.Option<M37.ResourceLease>`
- `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<Resources>; } | { kind: "fenced"; scope: Ref<Resources>; 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<IoReceipts>; }
```

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<M37.IoReceipts>`

### `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<bytes>; vals: Vec<i64>; links: Vec<OrderedLink>; 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<bytes>`
- `vals`: `Vec<i64>`
- `links`: `Vec<M37.OrderedLink>`
- `count`: `i64`
- `wire`: `i64`

### `CachedPage`

```gizlang
type CachedPage = { cache: ResourceLease; slot: i64; generation: i64; data: bytes; node: Option<OrderedPage>; }
```

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<M37.OrderedPage>`

### `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<IoReceipts>; files: Ref<Map<bytes, File>>; }
```

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<M37.IoReceipts>`
- `files`: `Ref<_gizlang_sdk_collections.Map<bytes, M37.File>>`

### `CacheReadResult`

```gizlang
type CacheReadResult = { page: Result<LeasedPage, IoError>; file: Option<File>; }
```

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<M37.LeasedPage, gizlang_system.IoError>`
- `file`: `_gizlang_sdk_core.Option<M37.File>`

### `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<OrderedPage>; }
```

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<M37.OrderedPage>`

### `PageCache`

```gizlang
type PageCache = { disk: Disk; state: Ref<CacheState>; }
```

A cache of decoded pages of DISK, shared by its copies.

- `disk`: `M37.Disk`
- `state`: `Ref<M37.CacheState>`

## Functions

### `nativePages`

```gizlang
function nativePages(disk: Disk, credits: mut ResourceContext, dataPath: string, indexPath: string, object: bytes, maxPageBytes: i64, cacheBytes: i64, cacheSlots: i64): Result<Ref<NativePages>, 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<T>(owner: Ref<NativePages>, operation: (pages: mut NativePages) => Result<T, IoError> effects { read, write, fail, io, console }): Result<T, IoError>
```

The result of OPERATION on the pages of OWNER.

### `syncPages`

```gizlang
function syncPages(owner: Ref<NativePages>): Result<bool, IoError>
```

Makes the files of OWNER durable.

Effects: fail, read, write, console, io.

### `pageFiles`

```gizlang
function pageFiles(owner: Ref<NativePages>): Result<NativeFiles, IoError>
```

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<NativePages>): Result<bool, IoError>
```

Closes the cache and the files of OWNER.

Effects: fail, read, write, console, io.

### `diskSet`

```gizlang
function diskSet(disks: Vec<Disk>): 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<Quota, IoError>
```

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<ResourcePolicy, IoError>
```

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<ResourcePolicy, IoError>
```

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<Resources, IoError>
```

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<Resources, IoError>
```

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<Resources>, memory: i64, temporary: i64): Result<ResourceLease, IoError>
```

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<Resources>, lease: ResourceLease, memory: i64, temporary: i64): Result<bool, IoError>
```

Resources.resize on the shared SCOPE.

Effects: fail, read, write, console, io.

### `releaseScoped`

```gizlang
function releaseScoped(scope: Ref<Resources>, lease: ResourceLease): Result<bool, IoError>
```

Resources.release on the shared SCOPE.

Effects: fail, read, write, console, io.

### `grantedScoped`

```gizlang
function grantedScoped(scope: Ref<Resources>, 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<Resources>): i64
```

The ledger's mark for releaseSince.

Effects: fail, read.

### `releaseSinceScoped`

```gizlang
function releaseSinceScoped(scope: Ref<Resources>, mark: i64): i64
```

Resources.releaseSince on the ledger SCOPE holds.

Effects: fail, read, write, console, io.

### `beginFenceScoped`

```gizlang
function beginFenceScoped(scope: Ref<Resources>, memory: i64, temporary: i64): Result<ResourceLease, IoError>
```

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<Resources>, fence: ResourceLease): Result<bool, IoError>
```

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<Resources>, fence: ResourceLease): Result<ResourceUsage, IoError>
```

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<TempPages, IoError>
```

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<i64, IoError>
```

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<TempPages, IoError>
```

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<Resources>, maxPageBytes: i64): Result<TempPages, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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, IoError>
```

pageCache with CONTEXT.

Effects: fail, read, write, console, io.

### `pageCache`

```gizlang
function pageCache(disk: Disk, credits: mut Resources, slots: i64, memoryBytes: i64): Result<PageCache, IoError>
```

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<bytes, IoError>
```

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<ResourceUsage, IoError>
```

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<ResourceLease, IoError>
```

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<bool, IoError>
```

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<bool, IoError>
```

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<ResourceLease, IoError>
```

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<ResourceUsage, IoError>
```

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<PageRange, IoError>
```

TempPages.append with CONTEXT.

Effects: fail, read, write, console, io.

### `TempPages.nextContext`

```gizlang
function TempPages.nextContext(self: TempPages, context: mut ResourceContext, offset: i64): Result<Option<PageRange>, 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<LeasedPage, IoError>
```

TempPages.read with CONTEXT.

Effects: fail, read, write, console, io.

### `TempPages.sealContext`

```gizlang
function TempPages.sealContext(self: mut TempPages, context: mut ResourceContext): Result<bool, IoError>
```

TempPages.seal with CONTEXT.

Effects: fail, read.

### `TempPages.closeContext`

```gizlang
function TempPages.closeContext(self: mut TempPages, context: mut ResourceContext): Result<bool, IoError>
```

TempPages.close with CONTEXT.

Effects: fail, read, write, console, io.

### `LeasedPage.closeContext`

```gizlang
function LeasedPage.closeContext(self: mut LeasedPage, context: mut ResourceContext): Result<bool, IoError>
```

LeasedPage.close with CONTEXT.

Effects: fail, read, write, console, io.

### `ResourceContext.serialCredits`

```gizlang
function ResourceContext.serialCredits(self: ResourceContext): Option<Resources>
```

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<ResourceLease, IoError>
```

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<bool, IoError>
```

Resources.resize with this context.

Effects: fail, read, write, console, io.

### `ResourceContext.release`

```gizlang
function ResourceContext.release(self: mut ResourceContext, lease: ResourceLease): Result<bool, IoError>
```

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<bytes, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<bool, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<LeasedPage, IoError>
```

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<Resources>, offset: i64, length: i64, crc: u64): Result<LeasedPage, IoError>
```

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<LeasedPage, IoError>
```

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<PageRange, IoError>
```

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<Resources>, data: bytes): Result<PageRange, IoError>
```

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<Vec<bytes>>): Result<TemporaryRange, IoError>
```

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<Resources>, sections: Vec<Vec<bytes>>): Result<TemporaryRange, IoError>
```

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<Vec<bytes>>): Result<TemporaryRange, IoError>
```

TempPages.appendParts with CONTEXT.

Effects: fail, read, write, console, io.

### `TempPages.next`

```gizlang
function TempPages.next(self: TempPages, credits: mut Resources, offset: i64): Result<Option<PageRange>, 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<Resources>, offset: i64): Result<Option<PageRange>, 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<LeasedPage, IoError>
```

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<Resources>, page: PageRange): Result<LeasedPage, IoError>
```

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<bool, IoError>
```

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<Resources>): Result<bool, IoError>
```

LeasedPage.close on the shared SCOPE.

Effects: fail, read, write, console, io.

### `TempPages.seal`

```gizlang
function TempPages.seal(self: mut TempPages, credits: Resources): Result<bool, IoError>
```

Ends the appends; reads may start.

Effects: fail.

### `TempPages.sealScoped`

```gizlang
function TempPages.sealScoped(self: mut TempPages, scope: Ref<Resources>): Result<bool, IoError>
```

TempPages.seal on the shared SCOPE.

Effects: fail, read.

### `TempPages.reset`

```gizlang
function TempPages.reset(self: mut TempPages, credits: mut Resources): Result<bool, IoError>
```

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<Resources>): Result<bool, IoError>
```

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<bool, IoError>
```

TempPages.reset with CONTEXT.

Effects: fail, read, write, console, io.

### `TempPages.close`

```gizlang
function TempPages.close(self: mut TempPages, credits: mut Resources): Result<bool, IoError>
```

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<Resources>): Result<bool, IoError>
```

TempPages.close on the shared SCOPE.

Effects: fail, read, write, console, io.

### `Disk.fileSize`

```gizlang
function Disk.fileSize(self: Disk, path: string): Result<i64, IoError>
```

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<bool, IoError>
```

PageCache.close with CONTEXT.

Effects: fail, read, write, console, io.

### `PageCache.close`

```gizlang
function PageCache.close(self: mut PageCache, credits: mut Resources): Result<bool, IoError>
```

Closes the cache and gives back its pages.

Effects: fail, write, io.

### `PageCache.closeScoped`

```gizlang
function PageCache.closeScoped(self: mut PageCache, scope: Ref<Resources>): Result<bool, IoError>
```

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<bool, IoError>
```

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<bool, IoError>
```

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<CacheAdmission, IoError>
```

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<CachedPage, IoError>
```

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<CachedPage, IoError>
```

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<CachedPage, IoError>
```

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<Resources>, address: StoredPage): Result<CachedPage, IoError>
```

PageCache.pin on the shared SCOPE.

Effects: fail, read, write, console, io.

### `PageCache.resident`

```gizlang
function PageCache.resident(self: mut PageCache, address: StoredPage): Option<ResidentPage>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

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<i64, IoError>
```

PageCache.invalidateTail with CONTEXT.

Effects: fail, read, write, console, io.

### `PageCache.invalidateTailScoped`

```gizlang
function PageCache.invalidateTailScoped(self: mut PageCache, scope: Ref<Resources>, object: bytes, path: string, start: i64): Result<i64, IoError>
```

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<bool, IoError>
```

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<CachedPage, IoError>
```

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<bool, IoError>
```

Unpins the page.

Effects: fail, write.

### `CachedPage.closeContext`

```gizlang
function CachedPage.closeContext(self: mut CachedPage, cache: mut PageCache, context: mut ResourceContext): Result<bool, IoError>
```

CachedPage.close with CONTEXT.

Effects: fail, read, write.

### `CachedPage.closeScoped`

```gizlang
function CachedPage.closeScoped(self: mut CachedPage, cache: mut PageCache, scope: Ref<Resources>): Result<bool, IoError>
```

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).

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<bytes, IoError>; readMany(self: Self, parts: Vec<i64>): Result<bytes, IoError>; writeAt(self: Self, offset: i64, data: bytes): Result<i64, IoError>; truncate(self: Self, length: i64): Result<i64, IoError>; sync(self: Self): Result<bool, IoError>; size(self: Self): Result<i64, IoError>; 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<Vec<string>, 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<Vec<string>, IoError>; entries(self: Self, path: string): Result<Entries, IoError>; open(self: Self, path: string, mode: i64): Result<File, IoError>; readFile(self: Self, path: string): Result<bytes, IoError>; replaceFile(self: Self, path: string, data: bytes): Result<i64, IoError>; replaceRange(self: Self, path: string, source: File, start: i64, length: i64, windowBytes: i64): Result<i64, IoError>; remove(self: Self, path: string): Result<bool, IoError>; sync(self: Self): Result<bool, IoError>; }

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<i64>; }

Bytes charged include retained open entries and admitted in-flight replacements.

disk: M37.Disk
used: gizlang_task.Cell<i64>

`ResourceLease`

gizlang

type ResourceLease = { owner: Ref<bool>; slot: i64; generation: i64; }

A claim on resources: its owner, slot and generation, so an old lease cannot name a reused slot.

owner: Ref<bool>
slot: i64
generation: i64

`Resources`

gizlang

type Resources = { identity: Ref<bool>; memoryLimit: i64; temporaryLimit: i64; memoryUsed: i64; temporaryUsed: i64; claims: Vec<ResourceClaim>; cursor: i64; binding: Option<ResourceLease>; serial: i64; }

Memory and temporary-disk credit with limits, and the claims that hold it.

identity: Ref<bool>
memoryLimit: i64
temporaryLimit: i64
memoryUsed: i64
temporaryUsed: i64
claims: Vec<M37.ResourceClaim>
cursor: i64
binding: _gizlang_sdk_core.Option<M37.ResourceLease>
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<Resources>; } | { kind: "fenced"; scope: Ref<Resources>; 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<IoReceipts>; }

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<M37.IoReceipts>

`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<bytes>; vals: Vec<i64>; links: Vec<OrderedLink>; 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<bytes>
vals: Vec<i64>
links: Vec<M37.OrderedLink>
count: i64
wire: i64

`CachedPage`

gizlang

type CachedPage = { cache: ResourceLease; slot: i64; generation: i64; data: bytes; node: Option<OrderedPage>; }

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<M37.OrderedPage>

`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<IoReceipts>; files: Ref<Map<bytes, File>>; }

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<M37.IoReceipts>
files: Ref<_gizlang_sdk_collections.Map<bytes, M37.File>>

`CacheReadResult`

gizlang

type CacheReadResult = { page: Result<LeasedPage, IoError>; file: Option<File>; }

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<M37.LeasedPage, gizlang_system.IoError>
file: _gizlang_sdk_core.Option<M37.File>

`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<OrderedPage>; }

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<M37.OrderedPage>

`PageCache`

gizlang

type PageCache = { disk: Disk; state: Ref<CacheState>; }

A cache of decoded pages of DISK, shared by its copies.

disk: M37.Disk
state: Ref<M37.CacheState>

Functions

`nativePages`

gizlang

function nativePages(disk: Disk, credits: mut ResourceContext, dataPath: string, indexPath: string, object: bytes, maxPageBytes: i64, cacheBytes: i64, cacheSlots: i64): Result<Ref<NativePages>, 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<T>(owner: Ref<NativePages>, operation: (pages: mut NativePages) => Result<T, IoError> effects { read, write, fail, io, console }): Result<T, IoError>

The result of OPERATION on the pages of OWNER.

`syncPages`

gizlang

function syncPages(owner: Ref<NativePages>): Result<bool, IoError>

Makes the files of OWNER durable.

Effects: fail, read, write, console, io.

`pageFiles`

gizlang

function pageFiles(owner: Ref<NativePages>): Result<NativeFiles, IoError>

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<NativePages>): Result<bool, IoError>

Closes the cache and the files of OWNER.

Effects: fail, read, write, console, io.

`diskSet`

gizlang

function diskSet(disks: Vec<Disk>): 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<Quota, IoError>

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<ResourcePolicy, IoError>

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<ResourcePolicy, IoError>

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<Resources, IoError>

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<Resources, IoError>

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<Resources>, memory: i64, temporary: i64): Result<ResourceLease, IoError>

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<Resources>, lease: ResourceLease, memory: i64, temporary: i64): Result<bool, IoError>

Resources.resize on the shared SCOPE.

Effects: fail, read, write, console, io.

`releaseScoped`

gizlang

function releaseScoped(scope: Ref<Resources>, lease: ResourceLease): Result<bool, IoError>

Resources.release on the shared SCOPE.

Effects: fail, read, write, console, io.

`grantedScoped`

gizlang

function grantedScoped(scope: Ref<Resources>, 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<Resources>): i64

The ledger's mark for releaseSince.

Effects: fail, read.

`releaseSinceScoped`

gizlang

function releaseSinceScoped(scope: Ref<Resources>, mark: i64): i64

Resources.releaseSince on the ledger SCOPE holds.

Effects: fail, read, write, console, io.

`beginFenceScoped`

gizlang

function beginFenceScoped(scope: Ref<Resources>, memory: i64, temporary: i64): Result<ResourceLease, IoError>

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<Resources>, fence: ResourceLease): Result<bool, IoError>

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<Resources>, fence: ResourceLease): Result<ResourceUsage, IoError>

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<TempPages, IoError>

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<i64, IoError>

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<TempPages, IoError>

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<Resources>, maxPageBytes: i64): Result<TempPages, IoError>

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<i64, IoError>

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<i64, IoError>

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<i64, IoError>

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, IoError>

pageCache with CONTEXT.

Effects: fail, read, write, console, io.

`pageCache`

gizlang

function pageCache(disk: Disk, credits: mut Resources, slots: i64, memoryBytes: i64): Result<PageCache, IoError>

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<bytes, IoError>

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<ResourceUsage, IoError>

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<ResourceLease, IoError>

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<bool, IoError>

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<bool, IoError>

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<ResourceLease, IoError>

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<ResourceUsage, IoError>

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<PageRange, IoError>

TempPages.append with CONTEXT.

Effects: fail, read, write, console, io.

`TempPages.nextContext`

gizlang

function TempPages.nextContext(self: TempPages, context: mut ResourceContext, offset: i64): Result<Option<PageRange>, 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<LeasedPage, IoError>

TempPages.read with CONTEXT.

Effects: fail, read, write, console, io.

`TempPages.sealContext`

gizlang

function TempPages.sealContext(self: mut TempPages, context: mut ResourceContext): Result<bool, IoError>

TempPages.seal with CONTEXT.

Effects: fail, read.

`TempPages.closeContext`

gizlang

function TempPages.closeContext(self: mut TempPages, context: mut ResourceContext): Result<bool, IoError>

TempPages.close with CONTEXT.

Effects: fail, read, write, console, io.

`LeasedPage.closeContext`

gizlang

function LeasedPage.closeContext(self: mut LeasedPage, context: mut ResourceContext): Result<bool, IoError>

LeasedPage.close with CONTEXT.

Effects: fail, read, write, console, io.

`ResourceContext.serialCredits`

gizlang

function ResourceContext.serialCredits(self: ResourceContext): Option<Resources>

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<ResourceLease, IoError>

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<bool, IoError>

Resources.resize with this context.

Effects: fail, read, write, console, io.

`ResourceContext.release`

gizlang

function ResourceContext.release(self: mut ResourceContext, lease: ResourceLease): Result<bool, IoError>

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<bytes, IoError>

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<i64, IoError>

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<i64, IoError>

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<bool, IoError>

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<i64, IoError>

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<i64, IoError>

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<i64, IoError>

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<i64, IoError>

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<LeasedPage, IoError>

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<Resources>, offset: i64, length: i64, crc: u64): Result<LeasedPage, IoError>

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<LeasedPage, IoError>

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<PageRange, IoError>

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<Resources>, data: bytes): Result<PageRange, IoError>

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<Vec<bytes>>): Result<TemporaryRange, IoError>

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<Resources>, sections: Vec<Vec<bytes>>): Result<TemporaryRange, IoError>

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<Vec<bytes>>): Result<TemporaryRange, IoError>

TempPages.appendParts with CONTEXT.

Effects: fail, read, write, console, io.

`TempPages.next`

gizlang

function TempPages.next(self: TempPages, credits: mut Resources, offset: i64): Result<Option<PageRange>, 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<Resources>, offset: i64): Result<Option<PageRange>, 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<LeasedPage, IoError>

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<Resources>, page: PageRange): Result<LeasedPage, IoError>

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<bool, IoError>

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<Resources>): Result<bool, IoError>

LeasedPage.close on the shared SCOPE.

Effects: fail, read, write, console, io.

`TempPages.seal`

gizlang

function TempPages.seal(self: mut TempPages, credits: Resources): Result<bool, IoError>

Ends the appends; reads may start.

Effects: fail.

`TempPages.sealScoped`

gizlang

function TempPages.sealScoped(self: mut TempPages, scope: Ref<Resources>): Result<bool, IoError>

TempPages.seal on the shared SCOPE.

Effects: fail, read.

`TempPages.reset`

gizlang

function TempPages.reset(self: mut TempPages, credits: mut Resources): Result<bool, IoError>

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<Resources>): Result<bool, IoError>

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<bool, IoError>

TempPages.reset with CONTEXT.

Effects: fail, read, write, console, io.

`TempPages.close`

gizlang

function TempPages.close(self: mut TempPages, credits: mut Resources): Result<bool, IoError>

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<Resources>): Result<bool, IoError>

TempPages.close on the shared SCOPE.

Effects: fail, read, write, console, io.

`Disk.fileSize`

gizlang

function Disk.fileSize(self: Disk, path: string): Result<i64, IoError>

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<bool, IoError>

PageCache.close with CONTEXT.

Effects: fail, read, write, console, io.

`PageCache.close`

gizlang

function PageCache.close(self: mut PageCache, credits: mut Resources): Result<bool, IoError>

Closes the cache and gives back its pages.

Effects: fail, write, io.

`PageCache.closeScoped`

gizlang

function PageCache.closeScoped(self: mut PageCache, scope: Ref<Resources>): Result<bool, IoError>

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<bool, IoError>

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<bool, IoError>

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<CacheAdmission, IoError>

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<CachedPage, IoError>

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<CachedPage, IoError>

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<CachedPage, IoError>

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<Resources>, address: StoredPage): Result<CachedPage, IoError>

PageCache.pin on the shared SCOPE.

Effects: fail, read, write, console, io.

`PageCache.resident`

gizlang

function PageCache.resident(self: mut PageCache, address: StoredPage): Option<ResidentPage>

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<i64, IoError>

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<i64, IoError>

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<i64, IoError>

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<i64, IoError>

PageCache.invalidateTail with CONTEXT.

Effects: fail, read, write, console, io.

`PageCache.invalidateTailScoped`

gizlang

function PageCache.invalidateTailScoped(self: mut PageCache, scope: Ref<Resources>, object: bytes, path: string, start: i64): Result<i64, IoError>

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<bool, IoError>

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<CachedPage, IoError>

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<bool, IoError>

Unpins the page.

Effects: fail, write.

`CachedPage.closeContext`

gizlang

function CachedPage.closeContext(self: mut CachedPage, cache: mut PageCache, context: mut ResourceContext): Result<bool, IoError>

CachedPage.close with CONTEXT.

Effects: fail, read, write.

`CachedPage.closeScoped`

gizlang

function CachedPage.closeScoped(self: mut CachedPage, cache: mut PageCache, scope: Ref<Resources>): Result<bool, IoError>

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).