Constants & Tunables (cheat sheet)
August 4, 2026 · View on GitHub
| Name | Value | Area |
|---|---|---|
MANIFEST_DIR | __manifest | manifest layout |
| Stream-token authority dataset | _stream_tokens.lance | RFC-026 graph-global current-token participant; only the exact witness selected by __manifest is authoritative |
| Trusted stream metadata column | __omnigraph_stream_v1$ | private nullable v9 base-row attribution; trailing $ is outside the .pg identifier grammar and public reflection/export omit it |
| Commit graph dirs (retired) | _graph_commits.lance / _graph_commit_actors.lance | retired in Phase B; lineage lives in __manifest (graph_commit / graph_head rows) since RFC-013 Phase 7. A graph this binary creates has neither. |
| Recovery audit dir | _graph_commit_recoveries.lance | internal exact record of completed crash-recovery actions; no public CLI query yet |
| BranchMerge logical data-transaction ceiling | MAX_BRANCH_MERGE_DATA_TRANSACTIONS = 1024 | maximum strict-insert/upsert/delete transactions one table may arm in a protocol_v4 chain; a larger plan fails before sidecar arm |
| Exact recovery history-scan ceiling | MAX_EFFECT_IDENTITY_SCAN_VERSIONS = 1026 | bounded schema-v9 transaction-history classification: 1,024 logical BranchMerge data transactions plus headroom for one allowed derived CreateIndex tail and one compensating Restore. Recovery can crash after the restore but before manifest publication, so both extra versions must remain classifiable; a longer history fails closed as unverifiable rather than causing an unbounded scan |
| Run branch prefix (legacy, removed) | __run__ | pre-v0.4.0 Run state machine; no longer a reserved name. A graph still carrying __run__* branches is sub-v4 and refused on open (rebuild via export/import). |
| Schema apply lock | __schema_apply_lock__ | schema apply |
| Manifest publisher retry budget | PUBLISHER_RETRY_BUDGET = 5 | manifest publish |
| Internal manifest schema version | INTERNAL_MANIFEST_SCHEMA_VERSION = 19 | strict RFC-026 strand. V19 preserves lifecycle-v3 and recovery-v15–v20 resume, maintenance, rebind, retirement, and DataBlock-correction families while activating token-schema-v3 terminal authority and recovery-v21. V18 and older graphs require export/init/load rebuild |
| Stream-token authority schema version | STREAM_TOKEN_AUTHORITY_SCHEMA_VERSION = 3 | current _stream_tokens.lance physical schema. V3 adds versioned DEAD_LETTERED evidence and fold attribution; historical token schemas are never reinterpreted under v19 |
| Stream-profile payload version | STREAM_PROFILE_PROTOCOL_VERSION = 2 | exact-equality wire gate on the v11 stream_profile singleton: profile_revision, bounded ReceiptChainRef, and strict `DISABLED |
| Stream-lifecycle payload version | STREAM_STATE_PROTOCOL_VERSION = 3 | exact-equality wire gate on v12 lifecycle rows: current binding/management/claim chain references, current binding/claim receipt IDs, authenticated WAL-tail authority, revisioned drain state, and exact sealed proof |
| Recovery-sidecar schema ceiling | SIDECAR_SCHEMA_VERSION = 21 | v21 activates DeadLetterFold and StreamAuthorityRetirementV2: conditional one-object creation, exact base/token participants, sole lifecycle/lineage publication, and exact three-disposition retirement. V20 remains exact StreamCorrection; v19 remains exact historical two-disposition StreamAuthorityRetirement; v18 remains exact hidden StreamRebind; v17 remains exact hidden StreamSealedOptimize; v16 remains exact hidden StreamSealedEnsureIndices; v15 remains exact hidden StreamResume. V14's correction/resume/retirement/ledger-maintenance/sealed-maintenance/rebind scaffolds remain frozen and fail closed. Recovery-v13 remains exactly StreamProfileChange; historical recovery-v10 enrollment and recovery-v12 lifecycle-v2 fold meanings are not reinterpreted |
| Keyed-write row ceiling | KEYED_WRITE_MAX_ROWS = 8192 | one Mutation/Load keyed table or one BranchMerge chunk; inclusive |
| Keyed-write Arrow-memory ceiling | KEYED_WRITE_MAX_BYTES = 33,554,432 (32 MiB) | accumulated Mutation/Load keyed input (including pending state plus a streamed mutation-update match set) or one BranchMerge row/upsert/delete-filter chunk; a single larger row is refused before sidecar arm. Stored update Blobs and keyed external-URI ranges/object sizes are charged before payload reads. The complete retained BranchMerge delete plan and operation-wide projected scalar validation delta are separately capped at the same value. Ordered scans request Lance's approximate 32-MiB batch target, then charge actual emitted batches before retaining them; the scanner target itself is not the hard budget. Overwrite retains external-reference semantics |
| Private RFC-026 B1 generation ceiling | 8,192 rows, 8,192 batches, 33,554,432 Arrow bytes | one no-roll MemWAL generation; the private seam refuses the next put before exceeding any bound |
| Private RFC-026 DataBlock detailed correction-view ceiling | 8,192 entries, 33,554,432 canonical bytes | while DRAINING, validator-contract v1 streams violations directly into a bounded collector. It switches deterministically from capped detailed canonical JSON to a one-entry-per-current-winner-key CORRECTION_VIEW_OVERFLOW projection when either bound is exceeded; the projection is ordered by raw UTF-8 logical key/token and hashed incrementally with domain-separated length framing (table key once), so no expanded JSON aggregate is retained. Overflow is a bounded terminal disposition, not an error |
| Private RFC-026 DataBlock show page ceiling | 256 entries, 268,435,456 complete serialized page bytes (256 MiB) | stopped/offline F3f inspection pagination. The byte cap includes the page envelope, cursor, JSON array framing, and commas; 256 MiB covers the sixfold worst-case JSON escaping of the 32-MiB acknowledged-generation envelope plus fixed correction-evidence fields. A valid single entry therefore always advances the opaque ordinal cursor |
| Private RFC-026 DataBlock correction request ceiling | 268,435,456 bytes (256 MiB) | block correct --plan checks file metadata and performs a limit-plus-one read before deserialization. The engine independently caps the compact serialized request and cumulatively charges every normalized REPLACE Arrow row plus canonical payload before the preparation pass repeats normalization. All three checks reuse B2's root preprocessing envelope and fail as typed resource limits before any correction effect |
| Private RFC-026 B1 resident-writer ceiling | 1 per graph root and table | evidence-qualified process-local worker admission; not a public throughput contract. B2 must requalify any higher multi-resident limit with an RSS cell |
| Private RFC-026 B1 aggregate Arrow reservation | 33,554,432 bytes (32 MiB) per graph root | cheap raw caller row/byte bounds reject obviously over-cap input before recovery I/O; raw-fit input then receives exact post-tombstone validation at that same pre-recovery boundary. After any recovery/authority prelude, the exact charge is recomputed and reserved against the aggregate before any same-key queue wait, shared admission, detached ownership, or cold claim; the permit transfers into the resident generation and remains charged through fold publication. Distinct from whole-process RSS |
| Private RFC-026 B2 canonical-payload ceiling | B2_MAX_CANONICAL_PAYLOAD_BYTES = 67,108,864 (64 MiB) per normalized row | bounded deterministic token-digest input; not a public request-body limit |
| Private RFC-026 F5 dead-letter object ceiling | MAX_STREAM_DEAD_LETTER_CANDIDATES = 8,192; MAX_STREAM_DEAD_LETTER_OBJECT_BYTES = 67,108,864 (64 MiB); DEAD_LETTER_RSS_DELTA_REMEASURE_BYTES = 201,326,592 (192 MiB, test evidence only) | one deterministic canonical NDJSON object per mixed/all-diverted fold. One-over the encoded-byte envelope installs durable operational DataBlock evidence before canonical-object creation, base-table effect, or current-token terminal-disposition transition; manifest/token-ledger state may move to persist the block. Verification/export retain nested payloads as bounded raw canonical JSON instead of recursively materializing serde_json::Value. F6b4's 2026-08-02 local macOS exact-cap run measured 8,192 candidates, 10,364,432 source-value bytes, 62,301,270 canonical-payload input bytes, exact 67,108,864-byte encoded length/capacity, 286,280 µs encode, 2,254,424 µs verify, and a 146,292,736-byte paired peak-RSS lift. The 192-MiB tripwire is not allocator admission, a quota, or an SLO |
| RFC-026 stopped/offline dead-letter page ceiling | 256 entries, 268,435,456 complete serialized page bytes (256 MiB); decoded cursor 4,096 bytes | bounded selected-current-token `cluster stream dead-letter list |
| Served export scan targets and chunk ceiling | initial 8,192-row estimate and approximate 33,554,432 decoded-Arrow-byte target; emitted chunks: hard 65,536-byte maximum | POST /graphs/{id}/export incrementally scans exact pinned Lance versions without whole-table collection. Lance's byte target overrides the row setting; neither setting is a hard limit, and Lance may emit a larger batch. Blob descriptor batches are explicitly sliced to one logical row before its complete Blob-property set is materialized. One row's Blob values and encoded JSON remain indivisible scratch before the row is split into strictly bounded independently owned transport chunks |
| Served export transport budget | 2 queued chunks; 262,144 bytes reserved per response queue envelope; 2,097,152 bytes process-wide; 250 ms reservation deadline; 1 nonwaiting immutable cut per graph root | each queue reservation accounts for two queued chunks, one producer chunk awaiting admission, and one consumer-current chunk; it is not the complete response or process RSS. At most eight reservations coexist process-wide. Saturation or an occupied graph cut returns typed HTTP 413 before success headers; the body and producer jointly retain the queue permit, and the cut remains in the producer or terminal frame until completion or disconnect unwinds both owners |
| Served graph-ingest authority precondition | strong opaque ETag / If-Match; one missing-token challenge, no automatic stale-token replacement | POST /graphs/{id}/stream/ingest derives the token from existing graph identity, accepted schema, streaming-profile revision, and fold delegation. Missing/stale checks finish before request-body polling and add no persisted authority |
| Served graph-ingest run coalescing | GRAPH_STREAM_RUN_MAX_COALESCE_DELAY = 50 ms | public observable, fixed maximum dwell while collecting more same-declaration rows after one non-full request run contains a complete row; new arrivals do not reset the deadline. Capacity, declaration change, and EOF still flush immediately. This is not an end-to-end acknowledgement SLO: storage, authority, and backpressure begin after submission and may add latency |
| Served graph-ingest request envelope | 1 request per actor; 2 per graph root; 134,217,728 reserved envelope bytes per request (268,435,456 root-wide); 8,192 retained result statuses; 33,554,432 bytes per input chunk and raw line | acquired only after an exact graph token and before body polling. The permit follows the detached request owner through any invoked tail; saturation is HTTP 413. These are process-memory/ownership admission bounds, not retained-storage quota or a promise that one request allocates the full reservation |
| Private RFC-026 B2 token-projection ceiling | B2_MAX_TOKEN_PROJECTION_ARROW_BYTES = 33,554,432 (32 MiB) | exact winning token projection and cumulative exact-authority lookup retention |
| Private RFC-026 B2 recovery-JSON ceiling | B2_MAX_TOKEN_RECOVERY_JSON_BYTES = 33,554,432 (32 MiB) | bounded token rows embedded in one stream-fold recovery sidecar; lifecycle-v3 recovery-v14 preserves the same logical token-plan bound |
| Maintenance concurrency | OMNIGRAPH_MAINTENANCE_CONCURRENCY=8 | optimize/cleanup |
| Graph index cache size | 8 (LRU) | runtime cache |
| Expand indexed-path frontier ceiling | OMNIGRAPH_EXPAND_INDEXED_MAX_FRONTIER=1024 | traversal |
| Expand indexed-path hop ceiling | OMNIGRAPH_EXPAND_INDEXED_MAX_HOPS=6 | traversal |
| Expand CSR-build cost factor | CSR_BUILD_FACTOR = 1.5 | traversal |
| Expand mode override | OMNIGRAPH_TRAVERSAL_MODE (indexed|csr; unset = cost-based auto) | traversal |
| Default body limit | 1 MB | HTTP server |
| Load (bulk-write) body limit | 32 MB | HTTP server (/load; shared by the deprecated /ingest alias) |
| Default embed provider/model | openai-compatible / openai/text-embedding-3-large | engine embedding |
| OpenAI-direct embed model | text-embedding-3-large | engine embedding |
| Gemini-direct embed model | gemini-embedding-2 | engine embedding |
| Embed deadline | OMNIGRAPH_EMBED_DEADLINE_MS=60000 | engine embedding |
| Embed timeout | OMNIGRAPH_EMBED_TIMEOUT_MS=30000 | engine embedding |
| Embed retries | OMNIGRAPH_EMBED_RETRY_ATTEMPTS=4 | engine embedding |
| Embed retry backoff | OMNIGRAPH_EMBED_RETRY_BACKOFF_MS=200 | engine embedding |
| LANCE memory pool default | 1 GB (raised in v0.3.0) | runtime |
Expand traversal dispatch. With OMNIGRAPH_TRAVERSAL_MODE unset, the engine
chooses the indexed (per-hop BTREE) vs CSR (whole-graph in-memory) path with a
cost model over cheap manifest counts (frontier size, |E|, source-vertex count,
hops) plus the index-coverage signal: the indexed path is preferred when its
frontier-relative work beats building the CSR (≈ when hops × frontier is a
small fraction of the source-vertex set), and CSR is preferred for dense/deep
traversals or when the BTREE coverage is degraded and a full scan would be paid
per hop. The two ceilings bound the initial dispatch frontier/hops (beyond
them CSR is always used); they are not a hard per-hop bound — the cost model
estimates total indexed work as ~hops × frontier × fanout, so dense fan-out is
priced toward CSR rather than capped mid-traversal. The override flag forces a path (the auto result is identical either way;
only the path differs).