GroundPlane is the shared lower infrastructure workspace for the nshkr platform core.
It holds the reusable lower primitives that sit underneath outer_brain,
Citadel, jido_integration, and app_kit.
GroundPlane should stay boring, small, and generic. If a concept mentions a product, provider, workflow engine, connector, model, runtime lane, or policy decision, it probably belongs higher in the stack. GroundPlane is the place for values that every owner can reuse without inheriting someone else's semantics.
all ranked repos
-> ground_plane primitive packages
-> ids, refs, leases, fences, checkpoints, persistence policy,
generic Postgres helpers, generic projection helpers
Higher repos use these contracts to describe durable handoff and restart boundaries. GroundPlane does not know what a Codex run, Linear issue, policy pack, operator review, or semantic turn means.
- shared contracts and state vocabulary
- Postgres transaction, outbox, inbox, and checkpoint helpers
- generic projection publication helpers
- generic persistence profile and debug-capture posture
- adaptive execution fences when they remain ref-only lower primitives
ground_plane_contractsground_plane_execution_fencingground_plane_persistence_policyground_plane_persistence_policy_data_extensionground_plane_postgresground_plane_projection
ground_plane_persistence_policy owns the pure profile contract for
persistence tier selection, debug capture level selection, store capability
descriptors, partition dimensions, and bounded debug taps. Its built-in default
profile is :mickey_mouse: memory-only, no restart durability claim, no
Postgres, no Temporal, no object storage, no external network dependency, no
live provider credential dependency, and no debug sidecar dependency.
Workspace root established. The internal packages are intentionally small and generic.
Maintainers should read Code Smell Remediation before changing persistence policy contracts, store capability constructors, false/nil value semantics, fence values, or epoch compatibility policy.
Active packages:
core/ground_plane_contracts: lower shared IDs, refs, leases, fences, checkpoints, and state vocabulary.core/execution_fencing: ref-only adaptive execution fences for endpoint leases, resource-pool leases, replay epochs, promotion epochs, router artifact epochs, and revoked candidate artifacts.core/persistence_policy: pure profile contracts for storage tier, debug capture level, store capabilities, partition dimensions, and bounded debug taps.core/persistence_policy_data_extension: generic data persistence-profile extension points that still avoid higher-layer semantics.core/ground_plane_postgres: generic Postgres transaction and outbox/inbox helpers.core/ground_plane_projection: generic projection publication helpers.examples/projection_smoke: composition proof for the packages.
Recent work added long-running execution fencing, persistence-policy packages, persistence posture docs, credential lease fabric primitives, revoked-lease restart fencing, and dependency-source/Weld gates.
The Synapse governed-effect lift uses GroundPlane only for reusable boundary
protocol primitives. GroundPlane.BoundaryProtocol.CommandEnvelope is the
canonical serializable command envelope for cross-plane effect requests, and
GroundPlane.Boundary.Codec provides deterministic encode/hash support for
integrity checks. GroundPlane still does not own effect lifecycle, authority
policy, product status, connector dispatch, or diagnostic lane semantics.
The NSHKR cleanup pass hardened GroundPlane.Boundary.Codec as the canonical
boundary encoder for stack-significant hashes. Boundary metadata now rejects
raw/raw_* fields and common credential, authorization, session, and token
keys before encoding. Higher owners should pass refs, hashes, leases, and
bounded envelopes through GroundPlane codecs rather than serializing raw
payloads or secret-shaped maps.
The cross-stack proof that consumes these primitives is owned by StackLab:
cd /home/home/p/g/n/stack_lab
MIX_ENV=test mix stack_lab.synapse.staged_live.v1 --jsonBefore adding a new primitive, check that it can be named and tested without depending on product language or mechanism-specific behavior. Good examples are lease expiry, fence epoch, checkpoint ref, projection publish receipt, and storage capability descriptor. Bad examples are "Linear issue state", "Codex turn policy", "operator review status", or "Temporal workflow retry"; those belong in source/runtime/product owners that understand their meaning.
flowchart TD
Contracts["GroundPlane<br/>contracts"] --> IDs["IDs<br/>refs"]
Contracts --> Leases["Leases<br/>fences"]
Contracts --> Checkpoints["Checkpoints"]
Contracts --> Persistence["Persistence<br/>policy"]
Persistence --> Store["Store<br/>capabilities"]
Persistence --> Debug["Debug<br/>taps"]
Postgres["Postgres<br/>helpers"] --> Outbox["Outbox<br/>inbox"]
Projection["Projection<br/>helpers"] --> Receipts["Publish<br/>receipts"]
flowchart LR
OuterBrain["OuterBrain"] --> Primitives["GroundPlane<br/>primitives"]
Citadel["Citadel"] --> Primitives
Jido["Jido<br/>Integration"] --> Primitives
AppKit["AppKit"] --> Primitives
Primitives --> Rule["No product<br/>semantics"]
flowchart TD
Profile["Profile<br/>selection"] --> Tier["Storage<br/>tier"]
Tier --> Capability["Store<br/>capability"]
Capability --> Debug["Debug<br/>capture"]
Debug --> Partition["Partition<br/>dimensions"]
Partition --> Receipt["Receipt<br/>refs"]
Capability --> Reject["Unsupported<br/>selection"]
flowchart LR
Need["Shared<br/>need"] --> Primitive["Primitive<br/>contract"]
Primitive --> Ids["IDs<br/>refs"]
Primitive --> Leases["Leases<br/>fences"]
Primitive --> Checkpoints["Checkpoints"]
Need --> Semantic["Semantic<br/>concept"]
Semantic --> Higher["Higher<br/>owner"]
The project targets Elixir ~> 1.19 and Erlang/OTP 28.
mix ciThe welded ground_plane_contracts artifact is tracked through the prepared
bundle flow:
mix release.prepare
mix release.track
mix release.archivemix release.track updates the orphan-backed
projection/ground_plane_contracts branch so downstream repos can pin a real
generated-source ref before any formal release boundary exists.
Workspace docs cover the overview, layout, contracts, Postgres helpers, and projection helpers.
MIT. Copyright (c) 2026 nshkrdotcom.
Temporal runtime development is managed from /home/home/p/g/n/mezzanine
through the repo-owned just workflow. Do not start ad hoc Temporal processes
or rely on the temporal CLI as the implementation runbook.
Temporal runtime development is managed from /home/home/p/g/n/mezzanine through the repo-owned just workflow, not by manually starting ad hoc Temporal processes.
Use:
cd /home/home/p/g/n/mezzanine
just dev-up
just dev-status
just dev-logs
just temporal-uiExpected local contract: 127.0.0.1:7233, UI http://127.0.0.1:8233, namespace default, native service mezzanine-temporal-dev.service, persistent state ~/.local/share/temporal/dev-server.db.
See docs/persistence.md for tiers, defaults, adapters, unsupported selections, config examples, restart claims, durability claims, debug sidecar behavior, redaction guarantees, migration or preflight behavior, and no-bypass scope when applicable.
GroundPlane is the primitive substrate. It owns reusable refs, ids, leases, fences, checkpoints, persistence policy, Postgres helpers, and projection helpers that higher repos can consume without inheriting product or provider semantics.
Read these repo-specific guides before adding primitives:
Operational rules:
- Public interfaces are owned by
core/ground_plane_contracts,core/execution_fencing,core/persistence_policy,core/persistence_policy_data_extension,core/ground_plane_postgres, andcore/ground_plane_projection. - GroundPlane may not own product names, provider names, workflow-engine behavior, connector behavior, model behavior, or policy decisions.
- Provider vocabulary is documentation-only when describing forbidden higher semantics. Primitive code should be nameable without product/provider words.
- GroundPlane does not own live-provider commands. If a higher proof command
using GroundPlane primitives reaches GitHub or Linear, the higher owner must
prefix that command with
~/scripts/with_bash_secrets. - Local development uses
mix ci, package-local tests, and release artifact commands when contract artifacts change. - Evidence is emitted through package tests, projection smoke examples, persistence posture docs, Weld/release tracking, StackLab primitive proofs, and downstream artifact receipts.
Chassis Evolution and the Host Daemon consume
GroundPlane.Boundary.Codec.encode!/1,
GroundPlane.Contracts.Fence, and
GroundPlane.Contracts.Checkpoint for Ring 0 envelopes, idempotency keys,
rollback points, receipt hashes, and restart-safe handoff. Chassis uses those
primitives to prove that a deployment, candidate swap, model materialization,
or tensor reload request can be encoded deterministically without carrying
unsafe process terms, raw credentials, or mutable runtime state as authority.
The Chassis usage is documented in
../j/jido_brainstorm/nshkrdotcom/docs/20260529/chassis_impl/0520_ground_plane_and_boundary_contracts_spec.md.
Chassis is a consumer, not a re-implementer. GroundPlane owns generic codec, fence, checkpoint, lease, persistence, and projection primitives; Chassis binds those primitives to spatial-plane receipts and substrate lifecycle without adding product, provider, workflow, or policy semantics to GroundPlane.