# Ark Fabric Glossary

This glossary records project terms from the Ark Fabric architecture. Terms are
accepted unless marked otherwise.

| Term | Status | Definition |
|---|---|---|
| Application-level fanout | Accepted | Sending the same object or chunk to multiple sites by application logic rather than relying on IP multicast. |
| Ark | Accepted | The project brand term for geographic distribution across independent sites, fault domains, and institutions. |
| Authority cell | Proposed | The FoundationDB authority domain that executes transaction logic and conflict checks for one or more ArkTxn key ranges. |
| BK-QCOW | Accepted | The BookKeeper-native qcow2 semantic block-volume engine. It preserves qcow2 concepts but stores state as immutable objects, mapping objects, roots, and commits. |
| BookKeeper | Accepted | Apache BookKeeper, used here as a site-local replicated append store for immutable payloads, manifests, and logs. |
| CAS | Accepted | Content-addressed storage. A storage mode where object identity derives from a content hash. |
| CDC | Accepted | Change data capture: a mechanism that emits committed database mutations for downstream processing. It is a generic term, not a synonym for FoundationDB Native CDC. |
| Chunk | Accepted | A bounded immutable byte range stored and replicated by ArkObj. |
| Clone | Accepted | A writable child rooted in a parent snapshot. Writes create new objects and shadow parent mappings. |
| Commit | Accepted | A durable record that makes a manifest, root, or mapping update visible. |
| Convergence | Accepted | Background progress from minimum durable placement toward the desired replica policy. |
| Data plane | Accepted | The Ark Fabric role that moves object payloads, log segments, replication traffic, and overlay packets across sites and WAN paths; it is implemented by ArkNet. |
| Deduplication domain | Accepted | Explicit tenant and encryption-key boundary within which identical content-addressed chunks may share physical storage. Cross-domain deduplication is disabled by default. |
| Desired sites | Accepted | The target number or set of sites that should eventually hold a copy or shard. |
| Durable head | Accepted | Highest contiguous ArkLog position known to satisfy the stream's minimum durability policy. |
| Edge | Accepted | A site-local service that terminates WAN protocols, authenticates requests, serves ranges, verifies data, caches, and mediates approved access to local BookKeeper and FoundationDB services. |
| Epoch | Accepted | A monotonically increasing ownership generation that fences stale writers for an ArkTxn range, ArkLog partition, or BK-QCOW volume. |
| Fan-in | Accepted | Reading data from multiple source sites into one client or edge. |
| File version | Accepted | A retained ArkFS metadata record that points to one file manifest and its file metadata at a specific version. |
| FoundationDB cell | Proposed | An independent site-local or region-local FoundationDB cluster participating in ArkTxn as an authority cell or hot replica. An authority cell may itself span primary, satellite, and secondary FoundationDB sites. |
| FoundationDB Native CDC | Experimental dependency | The experimental FoundationDB 8.0 durable named mutation-stream API. It is a future ArkTxn capture adapter, not the initial production capture path. |
| Ark Edge | Accepted | The edge service participating in the Ark Fabric data plane. |
| Ark Fabric | Accepted | The containing Ark platform. It includes ArkTxn, ArkLog, ArkObj, ArkNet, shared control components, site components, and service views. It is not a synonym for any one subsystem. |
| Ark Control Catalog | Accepted | Bootstrap-safe global control store for ArkTxn range ownership, epochs, transaction domains, site identity, policy roots, promotion fences, and ArkLog stream epochs. The first implementation is a dedicated FoundationDB deployment outside the routed application keyspace. |
| ArkTxn | Accepted | The Ark Fabric transaction subsystem: a geographically federated, strongly ACID ordered key-value layer. FoundationDB is its first engine; range ownership, nearby synchronous durability, ArkLog, and asynchronous hot replicas are ArkTxn behavior. |
| ArkLog | Accepted | The general Ark Fabric distributed append-only log subsystem for durable ordered history, replay, retention, and dissemination. It uses BookKeeper as its first active-log engine. |
| ArkObj | Accepted | The Ark Fabric immutable object subsystem. It stores chunks, manifests, and roots, verifies payloads, and enforces object durability and replica placement policy. It is a peer of ArkTxn, ArkLog, and ArkNet. |
| Ark Sites | Proposed | The site-connectivity project that supplies transport experiments, topology validation, and management work feeding ArkNet. |
| Ark scheduler | Accepted | A shared Ark Fabric control component that chooses source sites, target sites, replica placement, WAN paths, hedges, and chunk assignments within subsystem policy. |
| ArkNet | Accepted | The Ark Fabric network subsystem and data-plane implementation, using QUIC, optional MPQUIC, MASQUE CONNECT-IP, path inventory, telemetry, and scheduler policy across independent WAN paths. |
| ArkObj API | Accepted | The native internal interface of ArkObj for payload, manifest, lifecycle, and placement operations. It is not a separate subsystem or service view. |
| ArkFS | Proposed | A filesystem service view that uses ArkObj for file payloads and manifests, a metadata plane such as ArkTxn for hierarchy and versions, and ArkNet for WAN movement. |
| Hedged read | Accepted | A duplicate or alternate read issued after a request is slower than expected; the first valid response wins. |
| Corporate Ark | Proposed | Ark Fabric deployment operated by a large geographically distributed corporation across branch offices and corporate sites. |
| Hot replica | Proposed | An independent FoundationDB cluster that has materialized an ArkTxn range from ordered mutation segments and can serve eligible reads or become a promotion candidate. |
| Immutable object | Accepted | A stored byte sequence that is never updated in place. New writes create new objects. |
| Log plane | Proposed | The Ark Fabric layer responsible for ordered append streams, ArkLog mutation segments, replay, retention, and log compaction. |
| MASQUE CONNECT-IP | Proposed | HTTP/3 tunnel mechanism used by ArkNet when a general IPv4/IPv6 L3 overlay is required. |
| Manifest | Accepted | Metadata describing an object, file, S3 version, or volume mapping as references to immutable chunks or objects. |
| Matching ISP WAN connection point | Accepted | The labeled point inside an ISP routing well where that provider's data-center WAN connection attaches. Requests from the matching ISP may reach this point before the outer gateway and outside transit. |
| Metadata plane | Accepted | The strongly ordered state for names, roots, leases, policies, object versions, and service-specific metadata. |
| Minimum durable sites | Accepted | The independent site count or site set required before an operation may be acknowledged. |
| MPQUIC | Accepted | Multipath QUIC, used by ArkNet to schedule one logical connection across multiple network paths. |
| Multi-source read | Accepted | A read that fetches different chunks or ranges from multiple eligible replica sites. |
| Multipath | Accepted | Sending traffic between two logical endpoints across multiple network paths. |
| Mutation segment | Proposed | An immutable ordered ArkTxn replication unit containing committed mutations for a key range and owner epoch. |
| NBD | Accepted | Network Block Device, used as a compatibility block frontend for BK-QCOW. |
| OCI registry | Proposed | OCI Distribution API service view for container images and other OCI artifacts. ArkObj stores immutable blobs and manifests; ArkTxn owns repository and tag publication metadata. |
| Object plane | Accepted | The Ark Fabric role responsible for immutable chunks, manifests, roots, replicas, and object placement; it is implemented by ArkObj. |
| Object ID | Accepted | Stable logical identity for an immutable object or chunk. It must not expose mutable physical BookKeeper location. |
| Object manifest | Accepted | A manifest describing object length, chunk references, checksums, policy, generation, and replica information. |
| Placement policy | Accepted | Rules that decide where replicas or shards should be placed across fault domains. |
| qcow2 semantic compatibility | Accepted | Implementing qcow2 concepts such as COW mappings, snapshots, backing relationships, zero clusters, and dirty bitmaps without using a mutable `.qcow2` file as the native layout. |
| QUIC | Accepted | The secure UDP-based transport used for WAN data movement and stream multiplexing. |
| National Ark | Proposed | Ark Fabric deployment operated by a nation state across embassies, consulates, and other national sites. |
| Range owner | Proposed | The authority cell that may execute writes for an ArkTxn key range during a specific epoch. |
| Replica location | Accepted | Metadata describing which site or edge can serve a valid copy or shard of an object. |
| Replica placement catalog | Proposed | Presentation label for the ArkObj metadata that records the verified sites currently holding each chunk replica. It describes observed placement, not placement-policy intent, and is not the Ark Control Catalog or a separate subsystem. |
| Root | Accepted | An immutable versioned record naming a committed volume, filesystem, object, or snapshot state. ArkTxn owns mutable current-head pointers to roots. |
| Routing well | Accepted | Animation-only visual metaphor for the routed hop depth between subscriber clusters, access nodes, aggregation and regional routers, and an ISP gateway. It is not a standard network term or a literal physical topology. |
| S3-compatible API | Proposed | S3 protocol service view over ArkObj payloads and manifests, with bucket, key, and version metadata published through ArkTxn. |
| Service view | Accepted | A user-facing protocol or product surface, such as an S3-compatible API, OCI registry, BK-QCOW, ArkFS, CSI driver, or CDN, that consumes one or more Ark Fabric subsystems. |
| CSI driver | Proposed | Kubernetes storage integration that exposes BK-QCOW raw block or formatted filesystem volumes and, when ready, ArkFS-backed volumes through Container Storage Interface operations. It is not a storage subsystem. |
| Snapshot | Accepted | An immutable root reference retained for recovery, cloning, sharing, or history. |
| Storage class | Accepted | A user-visible durability, placement, convergence, and performance policy bundle. Initial classes are `ARK_REPLICATED`, `ARK_LOCAL_ASYNC`, and `ARK_SYSTEM`. |
| Stream | Accepted | Named ArkLog append namespace containing one or more independently ordered partitions. |
| Stream partition | Accepted | Independently ordered ArkLog unit with one authoritative writer epoch and its own sequence. |
| Subcluster | Accepted | A smaller allocation or mapping unit within a larger BK-QCOW cluster, useful for 4 KiB block changes inside larger objects. |
| Synchronous Ark durability | Proposed | The ArkTxn commit-path requirement that a transaction be durable in the authority cell's local and nearby failure-independent satellite transaction logs before client acknowledgement. |
| Transaction domain | Proposed | An ArkTxn grouping of key ranges that should stay in one authority cell because they commonly participate in the same transaction. |
| Transaction plane | Proposed | The Ark Fabric role responsible for range authority, ACID execution, transactional metadata, indexes, and leases; it is implemented by ArkTxn. |
| Transactional outbox | Accepted | ArkTxn capture record committed atomically with application mutations, then published idempotently to ArkLog. It is the initial production mutation-capture mechanism. |
| Two-stage durability | Accepted | The shared policy pattern where ArkObj, ArkLog, or ArkTxn acknowledges after its subsystem-specific minimum durability requirement and then continues toward desired replication or convergence. |
| ublk | Proposed | A high-performance Linux userspace block frontend that may become preferable to NBD for BK-QCOW. |
| WAN-native | Accepted | Designed around variable-latency, multi-site, multi-path wide-area networks rather than assuming one low-latency LAN cluster. |

## Naming Convention

The `Ark` prefix identifies Ark-owned subsystems and native interfaces.
Standards-based surfaces keep their established names: S3-compatible API, OCI
registry, and CSI driver. ArkFS and BK-QCOW are project-specific service
names. Do not add an `Ark` prefix to a standards-based interface merely to
make the service-view list look uniform.

## Appendix: Renamed Concepts And Aliases

This reference keeps earlier names and informal variants searchable without
putting them into current architecture explanations. `BlobAPI` was considered
for the ArkObj native interface, but is too generic and too narrow for its
manifest, lifecycle, and placement operations.

| Alias | Preferred Term | Note |
|---|---|---|
| BK QCOW | BK-QCOW | Use the hyphenated spelling in documentation. |
| BK-QCOW2 | BK-QCOW | The shorter form names the service view without tying it to binary qcow2 layout. |
| Geo Fabric | Ark Fabric | Deprecated pre-rebrand name. |
| Geo Object Fabric | ArkObj | Deprecated pre-rebrand name. |
| Ark Object Fabric | ArkObj | Deprecated former subsystem name; it confused a child subsystem with the containing Ark Fabric platform. |
| GeoBlob | ArkObj API | Deprecated pre-rebrand name. |
| ArkBlob | ArkObj API | Deprecated former name of the native interface; the API includes more than blob operations. |
| S3 API | S3-compatible API | Short label for the standards-based service view, not a new Ark-owned protocol. |
| GeoFS | ArkFS | Deprecated pre-rebrand name. |
| GeoFDB | ArkTxn | Deprecated pre-rebrand name. |
| GeoLog | ArkLog | Deprecated pre-rebrand name. |
| NDB | NBD | `NDB` appeared as a typo in the source discussion. |
| Ark object layer | ArkObj | Use the formal name for the shared substrate. |
| ArkFDB | ArkTxn | Deprecated intermediate name that tied the subsystem name to FoundationDB. |
| Ark Transport | ArkNet | Deprecated intermediate name; use ArkNet for the network subsystem and transport for the architectural role. |
| home-sites | Ark Sites | Current sibling repository path: `../home-sites`. `Ark Sites` is the proposed project name. |
| multicast parallelism | Application-level fanout or multi-source read | Use IP multicast only when discussing true network multicast. |
| shard owner | Range owner | Prefer `range owner` for ArkTxn because FoundationDB key ranges are the placement unit. |
| Matching ISP WAN handoff | Matching ISP WAN connection point | Technical alias retained for searchability. Use `WAN connection point` in viewer-facing explanations. |