# gizfs:object Object names are semantic catalog entries over the same immutable Store as files. This owner is deterministic; only the volume journal publishes commands. ```gizlang import * as Object from "gizfs:object"; ``` ## Types ### `Bucket` ```gizlang type Bucket = { name: string; tenant: string; } ``` A bucket and the tenant that owns it. - `name`: `string` - `tenant`: `string` ### `Entry` ```gizlang type Entry = { bucket: string; key: string; chunks: Vec; size: i64; etag: string; contentType: string; metadata: Vec; modified: i64; version: i64; retainUntil: i64; held: bool; } ``` An object: its bucket, key, chunks, size, ETag, type, metadata, time, version, and retention. - `bucket`: `string` - `key`: `string` - `chunks`: `Vec<_gizlang_lib_fs__store.Identity>` - `size`: `i64` - `etag`: `string` - `contentType`: `string` - `metadata`: `Vec` - `modified`: `i64` - `version`: `i64` - `retainUntil`: `i64` - `held`: `bool` ### `Version` ```gizlang type Version = { entry: Entry; deleted: bool; } ``` An object version, or a delete marker when DELETED. - `entry`: `M42.Entry` - `deleted`: `bool` ### `Metadata` ```gizlang type Metadata = { name: string; value: string; } ``` A user metadata entry of an object. - `name`: `string` - `value`: `string` ### `Part` ```gizlang type Part = { number: i64; entry: Entry; } ``` A part of a multipart upload. - `number`: `i64` - `entry`: `M42.Entry` ### `PartTag` ```gizlang type PartTag = { number: i64; etag: string; } ``` A part number and its ETag, as a complete request lists them. - `number`: `i64` - `etag`: `string` ### `Upload` ```gizlang type Upload = { id: string; entry: Entry; parts: Catalog; } ``` A multipart upload: its id, the object that it makes, and its parts. - `id`: `string` - `entry`: `M42.Entry` - `parts`: `_gizlang_lib_fs__catalog.Catalog` ### `RootChange` ```gizlang type RootChange = { source: string; roots: Option>; } ``` Disposable mutation effects, never serialized or used as catalog authority. A missing roots value drops exactly one source; a present value replaces it. - `source`: `string` - `roots`: `_gizlang_sdk_core.Option>` ### `State` ```gizlang type State = { policy: Durability; buckets: Catalog; entries: Catalog; markers: Catalog; history: Catalog; uploads: Catalog; sequence: i64; maxObjects: i64; maxChunks: i64; rootCount: i64; rootChanges: Vec; encodedBytes: i64; uploadPaths: Ordered; pathNodes: i64; pathSlots: i64; } ``` The object catalog of a store: buckets, objects, delete markers, old versions and uploads, with their limits. - `policy`: `_gizlang_lib_fs__store.Durability` - `buckets`: `_gizlang_lib_fs__catalog.Catalog` - `entries`: `_gizlang_lib_fs__catalog.Catalog` - `markers`: `_gizlang_lib_fs__catalog.Catalog` - `history`: `_gizlang_lib_fs__catalog.Catalog` - `uploads`: `_gizlang_lib_fs__catalog.Catalog` - `sequence`: `i64` - `maxObjects`: `i64` - `maxChunks`: `i64` - `rootCount`: `i64` - `rootChanges`: `Vec` - `encodedBytes`: `i64` - `uploadPaths`: `M39.Ordered` - `pathNodes`: `i64` - `pathSlots`: `i64` ### `Command` ```gizlang type Command = | { kind: "bucket"; tenant: string; name: string; remove: bool; } | { kind: "put"; tenant: string; entry: Entry; chunks: Vec; baseVersion: i64; } | { kind: "delete"; tenant: string; bucket: string; key: string; baseVersion: i64; modified: i64; } | { kind: "removeVersion"; tenant: string; bucket: string; key: string; version: i64; now: i64; } | { kind: "setLegalHold"; tenant: string; bucket: string; key: string; version: i64; held: bool; } | { kind: "extendRetention"; tenant: string; bucket: string; key: string; version: i64; retainUntil: i64; } | { kind: "beginUpload"; tenant: string; id: string; entry: Entry; } | { kind: "putPart"; tenant: string; id: string; part: Part; chunks: Vec; } | { kind: "completeUpload"; tenant: string; id: string; parts: Vec; baseVersion: i64; etag: string; modified: i64; } | { kind: "abortUpload"; tenant: string; id: string; } | { kind: "copy"; tenant: string; sourceBucket: string; sourceKey: string; sourceVersion: i64; entry: Entry; baseVersion: i64; } ``` A change of the object catalog: bucket, put, delete, version, retention, upload, part, complete, abort or copy. - `bucket` - `put` - `delete` - `removeVersion` - `setLegalHold` - `extendRetention` - `beginUpload` - `putPart` - `completeUpload` - `abortUpload` - `copy` ### `Outcome` ```gizlang type Outcome = { status: i64; code: string; etag: string; version: i64; modified: i64; } ``` What a command gave: its HTTP status and S3 code, and the ETag, version and time of the object. - `status`: `i64` - `code`: `string` - `etag`: `string` - `version`: `i64` - `modified`: `i64` ### `Position` ```gizlang type Position = { key: string; version: i64; upload: string; part: i64; } ``` One bounded query owner over canonical indexes. Summaries never include immutable manifests; normal pages inspect only matching index candidates. - `key`: `string` - `version`: `i64` - `upload`: `string` - `part`: `i64` ### `Query` ```gizlang type Query = { kind: string; bucket: string; prefix: string; delimiter: string; after: Position; limit: i64; budget: i64; terms: Vec; history: bool; uploadId: string; key: string; } ``` A list query: its kind, bucket, prefix and delimiter, where it starts, its limits, and its filters. - `kind`: `string` - `bucket`: `string` - `prefix`: `string` - `delimiter`: `string` - `after`: `M42.Position` - `limit`: `i64` - `budget`: `i64` - `terms`: `Vec` - `history`: `bool` - `uploadId`: `string` - `key`: `string` ### `Summary` ```gizlang type Summary = { key: string; version: i64; deleted: bool; latest: bool; etag: string; size: i64; modified: i64; upload: string; part: i64; group: bool; } ``` One row of a list page: an object, version, upload or part, or a common prefix (GROUP). - `key`: `string` - `version`: `i64` - `deleted`: `bool` - `latest`: `bool` - `etag`: `string` - `size`: `i64` - `modified`: `i64` - `upload`: `string` - `part`: `i64` - `group`: `bool` ### `Page` ```gizlang type Page = { rows: Vec; next: Position; truncated: bool; examined: i64; sequence: i64; copies: i64; domains: i64; } ``` A page of a list query, where the next page starts, and what the page cost. - `rows`: `Vec` - `next`: `M42.Position` - `truncated`: `bool` - `examined`: `i64` - `sequence`: `i64` - `copies`: `i64` - `domains`: `i64` ## Functions ### `formats` ```gizlang function formats(): Vec ``` The on-disk formats of this module. A test opens a committed store sample of every version. Effects: fail. ### `commandIntents` ```gizlang function commandIntents(state: State, tenant: string, command: Command): Result, string> ``` The access intents of COMMAND by TENANT: what it does to which bucket and key. It fails when the tenant does not own its target. Effects: fail, read, write, console, io. ### `queryIntents` ```gizlang function queryIntents(q: Query): Vec ``` The access intents of the query Q. Effects: fail. ### `viewIntents` ```gizlang function viewIntents(bucket: string, key: string, actions: i64): Result, string> ``` The access intent of ACTIONS on KEY of BUCKET. It fails when ACTIONS is not a valid set. Effects: fail. ### `stageIntents` ```gizlang function stageIntents(state: State, tenant: string, bucket: string, key: string): Result, string> ``` Staging is destination scoped and cannot reserve bytes for a new semantic record after catalog admission has closed. Existing multipart names may replace bounded parts; final publication still checks the exact catalog. Effects: fail, read, write, console, io. ### `projectForIntent` ```gizlang function projectForIntent(state: State, bucket: string, key: string, version: i64, uploadId: string, actions: i64): Result ``` A write/management projection keeps only condition/version descriptors. READ projections retain immutable manifests; byte delivery still requires the authority's principal-bound pin capability. Effects: fail, read, write, console, io. ### `versionSource` ```gizlang function versionSource(id: i64): string ``` The root source name of the object version ID. Effects: fail. ### `partSource` ```gizlang function partSource(id: string, number: i64): string ``` The root source name of part NUMBER of the upload ID. Effects: fail. ### `clearRootChanges` ```gizlang function clearRootChanges(state: mut State): void ``` Forgets the root changes that the last commands made. ### `pathWork` ```gizlang function pathWork(state: State): Vec ``` Logical managed-path writes, not allocator credit or measured RSS. Effects: fail. ### `snapshotBytes` ```gizlang function snapshotBytes(state: State): i64 ``` The bytes of the encoded snapshot of STATE. ### `writeOutcome` ```gizlang function writeOutcome(out: mut bytes, result: Outcome): void ``` Snapshots and native responses use the same bounded semantic outcome codec. Effects: fail. ### `newState` ```gizlang function newState(policy: Durability, maxObjects: i64, maxChunks: i64): Result ``` An empty catalog with POLICY and its limits. It fails when POLICY is not valid. Effects: fail, read, write, console, io. ### `validBucket` ```gizlang function validBucket(name: string): bool ``` Whether NAME is a valid S3 bucket name. Effects: fail. ### `validKey` ```gizlang function validKey(key: string): bool ``` Whether KEY is a valid object key (1 to 1024 bytes). Effects: fail. ### `pathKey` ```gizlang function pathKey(bucket: string, key: string): bytes ``` The catalog key of KEY in BUCKET. Effects: fail. ### `numberKey` ```gizlang function numberKey(number: i64): bytes ``` NUMBER as 8 big-endian bytes, which order as the numbers do. Effects: fail. ### `authorized` ```gizlang function authorized(state: State, tenant: string, bucket: string): bool ``` Whether TENANT owns BUCKET in this store. Effects: fail, read, write, console, io. ### `find` ```gizlang function find(state: State, bucket: string, key: string): i64 ``` The slot of the current object KEY of BUCKET, or -1. Effects: fail, read, write, console, io. ### `version` ```gizlang function version(state: State, bucket: string, key: string): i64 ``` The version of the current object or delete marker KEY of BUCKET, or 0. Effects: fail, read, write, console, io. ### `getVersion` ```gizlang function getVersion(state: State, tenant: string, bucket: string, key: string, id: i64): Result ``` The version ID of KEY in BUCKET, current or old. It fails with AccessDenied or NoSuchVersion. Effects: fail, read, write, console, io. ### `newQuery` ```gizlang function newQuery(kind: string, bucket: string): Query ``` A query of KIND on BUCKET with the default limits (1000 rows). ### `bucketPage` ```gizlang function bucketPage(state: State, tenant: string, q: Query, listed: (bucket: string) => bool): Result ``` The buckets of the tenant after `q.after.key` that `listed` admits, in name order. Effects: fail, read, write, console, io. ### `queryPage` ```gizlang function queryPage(state: State, tenant: string, q: Query): Result ``` The page of Q for TENANT. It fails when Q is not valid or TENANT does not own its bucket. Effects: fail, read, write, console, io. ### `encodeQuery` ```gizlang function encodeQuery(q: Query): bytes ``` The encoding of Q. Effects: fail. ### `decodeQuery` ```gizlang function decodeQuery(data: bytes): Result ``` The query of DATA. It fails when the encoding is not valid. Effects: fail, read, write, console, io. ### `encodePage` ```gizlang function encodePage(page: Page): bytes ``` The encoding of PAGE. Effects: fail. ### `decodePage` ```gizlang function decodePage(data: bytes): Result ``` The page of DATA. It fails when the encoding is not valid. Effects: fail, read, write, console, io. ### `roots` ```gizlang function roots(state: State): Vec ``` The shared GC owner sees every current and historical immutable root. Effects: fail, read, write, console, io. ### `upload` ```gizlang function upload(state: State, tenant: string, bucket: string, key: string, id: string): Result ``` The upload ID of KEY in BUCKET. It fails with AccessDenied or NoSuchUpload. Effects: fail, read, write, console, io. ### `selected` ```gizlang function selected(u: Upload, tags: Vec): Result, string> ``` Select the exact acknowledged parts. Completion never trusts client-supplied manifests; the committed staging catalog is the only byte reference owner. Effects: fail, read, write, console, io. ### `get` ```gizlang function get(state: State, tenant: string, bucket: string, key: string): Result ``` The current object KEY of BUCKET. It fails with AccessDenied or NoSuchKey. Effects: fail, read, write, console, io. ### `partChunkBytes` ```gizlang function partChunkBytes(chunk: Store.Chunk): i64 ``` Exact per-chunk contribution to putPart's two canonical manifest fields. Count, size and digest fields keep their existing fixed widths. Effects: fail. ### `encode` ```gizlang function encode(command: Command): bytes ``` The encoding of COMMAND. Effects: fail. ### `decode` ```gizlang function decode(data: bytes, maxChunks: i64): Result ``` The command of DATA, with at most MAXCHUNKS chunks. It fails when the encoding is not valid. Effects: fail, read, write, console, io. ### `requestDigest` ```gizlang function requestDigest(payload: bytes, maxChunks: i64): Result ``` Automatic ingress time does not change the logical request identity. An explicit retention deadline remains part of the canonical command digest. Effects: fail, read, write, console, io. ### `ingress` ```gizlang function ingress(payload: bytes, maxChunks: i64, now: i64): Result ``` Only trusted server ingress supplies expiry time; apply stays deterministic and replicas replay the exact stamped command already committed by Raft. Effects: fail, read, write, console, io. ### `apply` ```gizlang function apply(state: mut State, payload: bytes): Outcome ``` Publish an admitted catalog atomically. Exact canonical bytes are the sole snapshot sizing rule; a retained version cannot make later recovery impossible. Effects: fail, read, write, console, io. ### `project` ```gizlang function project(state: State, bucket: string, key: string, id: i64, uploadId: string): Result ``` Authorized selected-path projection or a bucket descriptor without rows. It owns no journal or byte store; the Volume read barrier supplies its cut. Effects: fail, read, write, console, io. ### `include` ```gizlang function include(destination: mut State, source: State): Result ``` Join two already-authorized projections; domain keys own deduplication. Effects: fail, read, write, console, io. ### `encodeState` ```gizlang function encodeState(state: State): bytes ``` The encoding of STATE (a snapshot). Effects: fail, read, write, console, io. ### `decodeState` ```gizlang function decodeState(data: bytes, policy: Durability): Result ``` The state of the snapshot DATA with POLICY. It fails when the snapshot is not valid. Effects: fail, read, write, console, io. ## Methods ### `Reader.objectOutcome` ```gizlang function Reader.objectOutcome(self: mut Reader): Outcome ``` The next outcome of the reader. Effects: fail, read, write, console, io. ## Constants ### `MAX_SNAPSHOT` ```gizlang const MAX_SNAPSHOT = 8388608 ``` The most bytes of an encoded object snapshot.