# Ark Fabric Ontology

This ontology maps the main Ark Fabric concepts and relationships. It is a
working project knowledge document, not a complete formal schema.

## Concept Classes

| Concept | Type | Description |
|---|---|---|
| Ark | Brand concept | Project term for geographic distribution across independent sites, fault domains, and institutions. |
| Ark Fabric | Platform | Containing WAN-native platform that includes all Ark subsystems, shared components, site components, and service views. |
| ArkObj | Object subsystem | Included Ark Fabric subsystem for immutable objects, manifests, roots, and replicas. |
| ArkObj API | Subsystem API | Native internal interface of ArkObj for payload, manifest, lifecycle, and placement operations. |
| Service view | Interface layer | Product or protocol surface that consumes one or more Ark Fabric subsystems. |
| S3-compatible API | Standards-based service view | Object protocol surface backed by ArkObj payloads and ArkTxn namespace metadata. |
| OCI registry | Standards-based service view | OCI Distribution API surface for image and artifact manifests, blobs, repositories, and tags. |
| CSI driver | Standards-based integration | Kubernetes volume lifecycle interface over supported BK-QCOW or ArkFS capabilities. |
| Transaction plane | Control layer | Strongly ordered transactional substrate for metadata and indexes. |
| Log plane | Log layer | Ordered append, replay, retention, and mutation-segment substrate. |
| Object plane | Storage layer | Immutable chunk, manifest, root, replica, and object-placement substrate. |
| Metadata plane | Control layer | Strongly ordered service and namespace metadata. |
| Data plane | Transport layer | Payload transfer across sites and paths. |
| ArkNet | Network subsystem | Included Ark Fabric subsystem for WAN-native QUIC, MPQUIC, MASQUE CONNECT-IP, path inventory, telemetry, and overlays. |
| Ark Sites | Project / deployment subsystem | Site-connectivity project that supplies the transport lab and architecture feeding ArkNet. |
| Site | Fault domain | Independent location containing edge and local durability services. |
| Ark Edge | Site component | WAN-facing service that mediates local storage access. |
| BookKeeper cluster | Local durability component | Site-local replicated append store. |
| FoundationDB cell | Transaction component | Site-local or region-local FDB authority or replica cluster. |
| Ark Control Catalog | Global control component | Bootstrap-safe store for ArkTxn ownership, epochs, domains, site identity, policy roots, promotion fencing, and ArkLog stream epochs. |
| ArkTxn | Transaction subsystem | Included Ark Fabric subsystem providing a geographically federated, strongly ACID ordered key-value layer. FoundationDB is the first engine. |
| ArkLog | Log subsystem | Included Ark Fabric general append-only subsystem providing durable ordered history, replay, retention, and dissemination. BookKeeper is the first active-log engine. |
| CDC | Capture pattern | Change data capture mechanism that emits committed database mutations. |
| FoundationDB Native CDC | Experimental engine interface | Experimental FoundationDB 8.0 CDC interface and future ArkTxn capture adapter. |
| Transactional outbox | Capture record | Mutation record committed atomically with ArkTxn application changes and published idempotently to ArkLog. |
| Stream | Log namespace | Named ArkLog append namespace containing one or more partitions. |
| Stream partition | Ordering domain | Independently ordered ArkLog unit with one writer epoch. |
| Writer epoch | Authority generation | Monotonic fence for an ArkLog partition writer. |
| Durable head | Log watermark | Highest contiguous ArkLog position satisfying minimum site durability. |
| Log replica | Replica role | Site-local BookKeeper-backed copy of an ArkLog partition. |
| Mutation segment | Replication object | Immutable ordered mutation batch for an ArkTxn key range and epoch. |
| Range owner | Authority role | FoundationDB cell that executes writes for an ArkTxn key range and epoch. |
| Hot replica | Replica role | FoundationDB cell materialized from ArkTxn mutation segments. |
| Transaction domain | Placement concept | Group of key ranges that should share one authority cell. |
| National Ark | Deployment profile | Nation-state Ark Fabric deployment across embassies, consulates, and national sites. |
| Corporate Ark | Deployment profile | Corporate Ark Fabric deployment across branch offices and corporate sites. |
| Chunk | Storage object | Immutable byte range. |
| Manifest | Metadata object | References chunks, policy, checksums, and generation. |
| Root | Version object | Names a committed state. |
| File version | Version object | Names one ArkFS file state and references a file manifest. |
| Snapshot | Retained root | Immutable historical root. |
| Clone | Derived root | Writable child of a snapshot or parent root. |
| Placement policy | Policy | Rules for replica or shard location. |
| Deduplication domain | Security boundary | Tenant and encryption-key boundary within which chunks may share physical storage. |
| Ark scheduler | Control component | Chooses sites, paths, chunk assignment, and hedges. |

## Boundary Rules

* Ark Fabric contains ArkTxn, ArkLog, ArkObj, ArkNet, shared
  components, site components, and service views.
* Ark Fabric is not a peer of its included subsystems and must not be used as a
  behavioral comparator.
* ArkTxn owns transaction execution, range authority, and hot-replica placement
  intent.
* ArkLog owns durable ordered history, replay, retention, and segment
  dissemination.
* ArkObj owns immutable payloads, manifests, roots, replica validity, and
  object durability; ArkTxn owns mutable service names and publication heads.
* ArkNet owns cross-site sessions and WAN path use.
* The Ark Control Catalog owns bootstrap and global control state; ArkTxn owns
  service and application metadata.
* Service views consume subsystems; ArkTxn, ArkLog, ArkObj, and ArkNet are not
  service views. S3-compatible API, OCI registry, and CSI driver name external
  interface contracts; ArkFS and BK-QCOW name Ark-specific services.

```mermaid
flowchart TB
    Fabric["Ark Fabric"] -->|includes| FDB["ArkTxn"]
    Fabric -->|includes| Log["ArkLog"]
    Fabric -->|includes| Object["ArkObj"]
    Fabric -->|includes| Transport["ArkNet"]
    Fabric -->|includes| Catalog["Ark Control Catalog"]
    Fabric -->|includes| Scheduler["Ark scheduler"]
    Fabric -->|presents| Views["Service views"]

    FDB -->|publishes<br/>committed mutations| Log
    Catalog -->|authorizes<br/>ownership<br/>and epochs| FDB
    Catalog -->|authorizes<br/>stream writers| Log
    Object -->|uses| Transport
    Log -->|uses| Transport
    FDB -->|uses| Transport
    Views -->|may use| FDB
    Views -->|may use| Log
    Views -->|may use| Object
    Views -->|use for<br/>WAN traffic| Transport
```

## Primary Relationships

| Subject | Relationship | Object |
|---|---|---|
| Ark Fabric | includes | ArkObj |
| Ark Fabric | includes | ArkTxn |
| Ark Fabric | includes | ArkLog |
| Ark Fabric | includes | ArkNet |
| Ark Fabric | includes | Ark Control Catalog |
| Ark Fabric | includes | Ark scheduler |
| Ark Fabric | presents | Service view |
| Ark Fabric | includes | Transaction plane |
| Ark Fabric | includes | Log plane |
| Ark Fabric | includes | Object plane |
| Ark Fabric | includes | Metadata plane |
| Ark Fabric | includes | Data plane |
| Ark Fabric | has-profile | National Ark |
| Ark Fabric | has-profile | Corporate Ark |
| ArkObj | implements | Object plane |
| ArkObj | stores | Chunk |
| ArkObj | stores | Manifest |
| ArkObj | stores | Root |
| ArkObj | uses | BookKeeper cluster |
| ArkObj | uses | ArkNet |
| ArkObj | uses | Placement policy |
| ArkObj | enforces | Deduplication domain |
| ArkObj | uses | Ark scheduler |
| ArkObj | exposes | ArkObj API |
| ArkObj | serves | S3-compatible API |
| ArkObj | serves | OCI registry |
| Transaction plane | implemented-by | ArkTxn |
| Metadata plane | implemented-by | ArkTxn |
| ArkTxn | uses | FoundationDB cell |
| ArkTxn | uses | ArkLog |
| ArkTxn | uses | ArkNet |
| ArkTxn | consults | Ark Control Catalog |
| ArkTxn | writes | Transactional outbox |
| Transactional outbox | feeds | ArkLog |
| FoundationDB Native CDC | may-feed | ArkLog |
| FoundationDB Native CDC | is-a | CDC |
| ArkTxn | assigns | Range owner |
| ArkTxn | preserves | Transaction domain |
| ArkTxn | manages | Hot replica |
| Log plane | implemented-by | ArkLog |
| ArkLog | stores | Mutation segment |
| ArkLog | contains | Stream |
| Stream | contains | Stream partition |
| Stream partition | fenced-by | Writer epoch |
| Stream partition | has | Durable head |
| Stream partition | replicated-as | Log replica |
| ArkLog | uses | BookKeeper cluster |
| ArkLog | consults | Ark Control Catalog |
| ArkLog | uses | Ark scheduler |
| ArkLog | uses | ArkNet |
| Service view | may-use | ArkObj |
| Service view | may-use | ArkObj API |
| Service view | may-use | ArkTxn |
| Service view | may-use | ArkLog |
| Service view | may-use | ArkNet |
| OCI registry | uses | ArkTxn |
| OCI registry | uses | ArkObj |
| CSI driver | uses | BK-QCOW |
| CSI driver | may-use | ArkFS |
| Metadata plane | names | Root |
| Manifest | references | Chunk |
| Root | references | Manifest |
| File version | references | Manifest |
| Snapshot | is-a | Root |
| Clone | depends-on | Snapshot |
| Clone | produces | Root |
| Site | contains | Ark Edge |
| Site | contains | BookKeeper cluster |
| Site | contains | FoundationDB cell |
| Site | may-contain | Log replica |
| Log replica | uses | BookKeeper cluster |
| Ark Control Catalog | uses | FoundationDB cell |
| Ark Edge | uses | BookKeeper cluster |
| Ark Edge | uses | FoundationDB cell |
| Ark Edge | participates-in | ArkNet |
| Data plane | implemented-by | ArkNet |
| ArkNet | uses | QUIC |
| ArkNet | may-use | MPQUIC |
| ArkNet | may-use | MASQUE CONNECT-IP |
| ArkNet | uses | Path inventory |
| ArkNet | produces | WAN telemetry |
| Ark Sites | validates | ArkNet |
| Ark scheduler | uses | Replica location |
| Ark scheduler | uses | WAN telemetry |
| Ark scheduler | produces | Chunk assignment |
| Placement policy | constrains | Replica location |
| Commit | publishes | Root |
| Garbage collection | starts-from | Root |

## Service View Relationships

| Service View | Relationship | Substrate Concept |
|---|---|---|
| S3-compatible API | maps bucket/key/version to | Object manifest |
| S3-compatible API | uses | Metadata plane |
| S3-compatible API | uses | Chunk |
| S3-compatible API | uses | ArkNet |
| S3-compatible API | supports | Multi-source read |
| S3-compatible API | supports | Application-level fanout |
| BK-QCOW | maps volume head to | Root |
| BK-QCOW | maps L1/L2 entries to | Object ID |
| BK-QCOW | uses | Epoch |
| BK-QCOW | produces | Snapshot |
| BK-QCOW | exposes | NBD |
| BK-QCOW | may-expose | ublk |
| BK-QCOW | uses | ArkObj |
| BK-QCOW | uses | ArkNet |
| ArkFS | maps file extents to | Manifest |
| ArkFS | maps file path to | File version |
| ArkFS | preserves | File version |
| ArkFS | maps filesystem state to | Root |
| ArkFS | uses | ArkObj |
| ArkFS | uses | ArkTxn |
| ArkFS | uses | ArkNet |
| OCI registry | maps repository/tag to | Manifest |
| OCI registry | maps layers to | Chunk |
| OCI registry | uses | ArkTxn |
| OCI registry | uses | ArkObj |
| CSI driver | uses | BK-QCOW |
| CSI driver | may-use | ArkFS |
| Backup service | maps backup point to | Root |
| CDN / HTTP view | serves | Range |
| Data lake view | serves | Range |

## BK-QCOW Concept Map

```mermaid
flowchart TD
    Volume[Volume] --> Head[Volume Head]
    Head --> Root[Root]
    Root --> L1[L1 Mapping]
    L1 --> L2[L2 Mapping]
    L2 --> OID[Object ID]
    OID --> Chunk[Immutable Chunk]
    Snapshot[Snapshot] --> Root
    Clone[Clone] --> Snapshot
    Clone --> CloneRoot[Clone Root]
    Commit[Commit] --> Head
    Epoch[Epoch] --> Commit
```

BK-QCOW contrasts with binary qcow2. It keeps qcow2 semantics but does not use
a mutable `.qcow2` file as the native physical representation.

## S3 Concept Map

```mermaid
flowchart TD
    Bucket[Bucket] --> Key[Key]
    Key --> Version[Object Version]
    Version --> Manifest[Object Manifest]
    Manifest --> ChunkA[Chunk]
    Manifest --> ChunkB[Chunk]
    Manifest --> ChunkC[Chunk]
    Policy[Placement Policy] --> Manifest
    Metadata[Metadata Plane] --> Version
```

S3 object visibility is controlled by metadata-plane pointer changes. A new
object version is visible only after its manifest references durable chunks.

## ArkFS Concept Map

```mermaid
flowchart TD
    Path[File Path] --> FileVersion[File Version]
    FileVersion --> FileManifest[File Manifest]
    FileManifest --> ChunkA[Chunk]
    FileManifest --> ChunkB[Chunk]
    FileManifest --> ChunkC[Chunk]
    Directory[Directory Node] --> Path
    Root[Filesystem Root] --> Directory
    Snapshot[Snapshot] --> Root
```

ArkFS hierarchy is metadata. File version history is preserved by retaining
file versions and the manifests they reference until retention policy permits
garbage collection.

## ArkTxn Concept Map

```mermaid
flowchart TD
    Catalog[Ark Control Catalog] --> KeyRange[Key Range]
    KeyRange[Key Range] --> RangeOwner[Range Owner]
    KeyRange --> TransactionDomain[Transaction Domain]
    RangeOwner --> FDBAuthority["FoundationDB<br/>Authority Cell"]
    FDBAuthority --> SatelliteLogs["Satellite<br/>Transaction Logs"]
    FDBAuthority --> Outbox[Transactional Outbox]
    FDBAuthority -. "future adapter" .-> CDC[FoundationDB Native CDC]
    Outbox --> ArkLog[ArkLog]
    CDC -.-> ArkLog
    ArkLog --> Segment[Mutation Segment]
    Segment --> HotReplica[Hot Replica]
    Policy[Hierarchical Policy] --> KeyRange
    Epoch[Epoch] --> RangeOwner
```

ArkTxn is active-active across ranges but single-primary per range and epoch.
Hot replicas materialize ordered mutation segments and may be promoted after
they catch up to the durable head.

## ArkLog Concept Map

```mermaid
flowchart TD
    Catalog[Ark Control Catalog] --> Stream[Stream]
    Stream --> Partition[Stream Partition]
    WriterEpoch[Writer Epoch] --> Partition
    Partition --> Record[Ordered Record]
    Record --> Segment[Immutable Segment]
    Segment --> BK["BookKeeper<br/>Active Storage"]
    Segment --> Replica[Log Replica]
    Replica --> DurableHead[Durable Head]
    Segment -. "closed archive" .-> Object[ArkObj]
    Replica --> Net[ArkNet]
```

ArkLog assigns order within a stream partition and writer epoch. Local
BookKeeper replication protects each site, minimum-site durability advances the
durable head, and desired replicas converge through ArkNet. Closed segments may
be archived in ArkObj without moving the active append path there.

## ArkNet Concept Map

```mermaid
flowchart LR
    Client[Client or Edge] --> Scheduler[Ark Scheduler]
    Scheduler --> SiteA[Site A Edge]
    Scheduler --> SiteB[Site B Edge]
    Scheduler --> SiteC[Site C Edge]
    SiteA --> BKA[BookKeeper A]
    SiteB --> BKB[BookKeeper B]
    SiteC --> BKC[BookKeeper C]
    Scheduler --> Telemetry[WAN Telemetry]
    Scheduler --> Policy[Placement Policy]
    Scheduler --> Transport[ArkNet]
    Transport --> QUIC[QUIC]
    Transport --> MPQUIC[MPQUIC]
    Transport --> MASQUE[MASQUE CONNECT-IP]
```

The scheduler is above transport connections. It chooses eligible source sites
and target sites first, then path scheduling can use QUIC or MPQUIC within each
site connection.

## Durability Relationships

| Subject | Relationship | Object |
|---|---|---|
| Minimum durable sites | gates | Client acknowledgement |
| Desired sites | drives | Convergence |
| Commit | requires | Durable referenced chunks |
| File version | requires | Durable referenced chunks |
| ArkTxn commit | requires | Local FDB durability |
| ArkTxn commit | requires | Synchronous Ark durability |
| ArkTxn commit | atomically-includes | Transactional outbox |
| ArkLog append | requires | Ordered-log minimum durability |
| Minimum durable sites | advances | Durable head |
| Hot replica | consumes | Mutation segment |
| Placement policy | requires | Independent fault domains |
| Ark scheduler | optimizes | Predicted completion time |
| Repair | restores | Desired placement |
| Compaction | preserves | Object ID |
| Compaction | changes | Physical BookKeeper location |

## External Neighbor Concepts

OCI registry and CSI relationships use the
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md),
[Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/),
and [CSI specification](https://github.com/container-storage-interface/spec),
reviewed 2026-10-06. These are external interface contracts, not additional
Ark Fabric subsystems.

| Project Concept | External Neighbor | Relationship |
|---|---|---|
| BK-QCOW | qcow2 | Implements compatible semantics, not native binary layout |
| BK-QCOW | NBD | Exposes compatibility block frontend |
| BK-QCOW | ublk | May expose high-performance Linux block frontend |
| ArkObj | S3 | Provides storage substrate for S3-compatible service |
| ArkObj | OCI registry | Provides content-addressed blob substrate |
| CSI driver | Container Storage Interface | Implements Kubernetes volume lifecycle operations for supported services |
| ArkNet | QUIC | Uses stream-oriented secure transport |
| ArkNet | MPQUIC | May use multipath scheduling |
| ArkNet | MASQUE CONNECT-IP | May use HTTP/3 packet tunneling for L3 overlays |
| Local durability | Apache BookKeeper | Uses site-local append and replication substrate |
| Metadata plane | FoundationDB | Uses FDB as the first ArkTxn engine for strongly ordered service metadata |
| Transaction plane | FoundationDB | Uses FDB as the first local ACID authority and hot-replica engine |
| ArkTxn | FoundationDB regions | Uses similar satellite-log durability pattern at authority-cell level |
| ArkTxn | FoundationDB Native CDC | May adopt the experimental interface as a future capture adapter |
| ArkLog | Apache BookKeeper | Uses BookKeeper as the first active ordered append engine |