Kaiba / System architectureRead the specification

FROM DEVICE TO FLEET

Provision with evidence.
Configure with intent.

A shared process for turning provisioned hardware into admitted fleet devices, then publishing a configuration through Kaiba Flow.

Each handoff carries a specific fact, a named owner and a clear acceptance gate. This guide connects those boundaries so each project can evolve around the same contracts.

Try the interactive workflow Read the process guide
10specified contracts
10contracts to define
01development integration slice

“Specified” means draft schemas and local fixtures exist. Production conformance remains open. This guide summarizes the authoritative specification.

01 / THE HANDOFFS

A pipeline built on explicit contracts

The main path begins with a provisioning observation and ends with durable publication. Component definitions feed both the editor and the resolver.

Dependencies, not a rigid sequence. Identity activation is part of the proposed production enrollment transaction. Early candidate evidence can support activation; final completion evidence follows it. Requiring final completion before activation would create a circular dependency.

Provision and report the observation

Specified

OWNER · PROVISIONING AUTHORITY

The provisioning project runs the physical workflow and retains its control state and independent audit. Its export reports what was observed about one exact transaction.

Accepts
Approved profile, transaction, exact physical target and scoped authority.
Produces
ProvisioningRecord with raw source state, revision, readiness claims and evidence references.
Consumer gate
Authenticate origin, enforce tenant and domain, verify authoritative evidence and current freshness. A successful lane outcome alone grants no fleet access.

Development anchor: security_applied still has both production and enrollment readiness set to false.

Bind the exact device identity

Specified

OWNER · REGISTRATION, CERTIFICATE & INVENTORY AUTHORITIES

Identity services assign the canonical logical identity and bind it to a particular provisioned instance, storage generation and credential tuple.

Accepts
Fresh bootstrap and operational-key proof, provisioning evidence and current identity policy.
Produces
DeviceBinding, exposing authoritative inventory state and lifecycle.
Consumer gate
A staged binding becomes active only after verification and atomic inventory activation. Hostnames, MAC addresses and intended names are correlation hints.

A replacement instance cannot inherit the old instance’s credentials or desired assignments.

Decide fleet participation

Contract deferred

OWNER · FLEET ADMISSION

Admission decides whether the exact instance can participate now and carries its platform constraints into configuration resolution.

Accepts
Current active binding, tenant authorization, qualified platform and fresh policy.
Produces
FleetTarget: instance, capabilities, restrictions, policy decision and freshness.
Consumer gate
Recheck participation when freezing a plan and before consequential actions. Historical eligibility does not override quarantine or revocation.

The development inbox exposes candidates with blockers. It does not issue admitted fleet targets.

Define the building blocks

Contract deferred

SIDE INPUT · COMPONENT OWNERS

Reviewed component definitions give the graphical editor and the resolver the same vocabulary. Both consume the same pinned component versions.

Accepts
A component definition and its reviewed implementation semantics.
Produces
ComponentContract: configuration schema, typed ports, compatibility, permissions, resolution behavior and health requirements.
Consumer gate
Agree these semantics before the editor or a compiler claims conformance.

Compose a configuration in Flow

Contract deferred

OWNER · KAIBA FLOW / AUTHORING

An operator connects typed components, configures values and selects the intended fleet scope. Flow captures declarative intent for resolution.

Accepts
Pinned component versions, user choices and scoped secret references.
Produces
ConfigurationRevision: an immutable graph snapshot, version pins and authoring provenance.
Consumer gate
Keep editable drafts separate from immutable revisions. Secret values must never enter graph records, browser bundles or build outputs.

The first Flow branch reads candidate observations. Graph authoring against shared contracts is a future slice.

Resolve exact scope, then review

Contract deferred

OWNER · RESOLVER; REVIEWED BY THE OPERATOR

The resolver combines the graph with admitted instances, platform constraints, baselines, group settings and allowed device overrides. Flow presents the resulting plan and findings.

Accepts
Immutable graph, component pins, selected targets, platform profiles and layered configuration.
Produces
DeploymentPlan: exact instances, effective inputs and value provenance, eligible/deferred/blocked targets, expected desired-state revisions, approvals, expiry and rollout policy.
Consumer gate
Conflicts at the same layer block the affected target. Platform security constraints remain locked. The operator reviews the exact eligible list and exclusions.

Group membership is resolved into exact instances. Later additions, replacements or edits require a new reviewed plan.

Publish the reviewed intent

Specified

OWNER · PUBLICATION AUTHORITY

Flow submits the exact reviewed plan. The authority checks current scope and durably records acceptance together with recoverable execution intent.

Accepts
PublishRequest: plan reference and digest, ordered eligible target tuples, expected revisions and a stable idempotency key. Authentication supplies actor and tenant.
Produces
Publication: immutable acceptance, authenticated actor, authorization reference and the exact accepted request.
Consumer gate
Validate the plan, approvals, current admission and every expected revision. Accept the whole reviewed eligible list or reject the request.

The UI can say “publication accepted.” A running configuration requires later execution evidence.

02 / THE COMMIT POINT

What the Publish button promises

Publication is the durable acceptance of exact reviewed intent. Its meaning stays stable even when execution is delayed or fails.

BEFORE ACCEPTANCE

Everything still matches

  • The plan’s version, digest and review remain valid.
  • Requested targets exactly equal its ordered eligible list.
  • Current admission, approvals and expected revisions pass.
AT ACCEPTANCE

Intent is recoverable

  • The request identity and accepted record are durable.
  • Execution intent survives a crash before dispatch.
  • The response identifies one stable publication.
If the response is lost: the caller’s outcome is unknown. Retry the identical request with the same idempotency key, or query its status. Changing the content under that key is a conflict; automatically making a new key risks duplicate intent.

After acceptance: separate facts and gates

These downstream contract formats remain deferred. The acceptance schema does not implement them.

FactRecordWhat it establishes
BuiltBuildResultComplete effective inputs map to exact artifacts and provenance.
AuthorizedAuthorizedReleaseA separate authority approves those artifact digests.
AssignedDesiredAssignmentAn exact instance receives an attempt after current policy and desired-state revision checks.
Observed & appraisedDeviceObservation
PolicyDecision		Sequenced device evidence is evaluated by an independent policy authority.
ConfirmedExecutionResultAttempt-correlated evidence supports the reported outcome.

A timeout never proves success. Unknown outcomes stop rollout expansion; offline targets remain deferred until a newly authorized attempt.

03 / OWNERSHIP

Projects meet at the boundary

These are logical responsibilities. Sharing a service or deployment does not combine authority, key custody or permissions.

THE SOURCE

kaiba-provisioning ↗

Physical workflow, control state, independent audit and the export adapter. It emits observations grounded in its own evidence.

THE AGREEMENT

kaiba-contracts ↗

Shared semantics, schemas, examples and conformance obligations. Each producer and consumer reviews changes here.

THE COORDINATION

kaiba-controller ↗

Today: a durable observation inbox and scoped read views. Future orchestration must consume identity, admission and publication decisions through their contracts.

THE OPERATOR EXPERIENCE

kaiba-flow

Candidate visibility and user intent. Future authoring, plan review and publication requests. Read credentials stay in its server adapter.

Identity, admission, build, signing and appraisal retain distinct authority roles. Their eventual deployment and repository layout remain open.

04 / IMPLEMENTATION SNAPSHOT

Start with the provisioning inbox

As reviewed on 12 September 2026. This first slice makes provisioning observations visible without granting enrollment, admission or publication privileges.

  1. Adapter patch

    Export from provisioning

    A read-only adapter exports immutable records and privately retained evidence. The tested patch lives in kaiba-controller; landing it in the provisioning repository remains pending.

  2. Development

    Retain and assess in the controller

    The development controller stores revisions and import outcomes durably, checks retained evidence and exposes scoped candidate/history APIs. Every candidate remains ineligible for production admission.

  3. Review branch

    Read observations in Flow

    The mvp/provisioning-inbox source branch adds candidate details, blockers, revision history and import history. It has an explicit rehearsal mode and a server-side controller adapter. The branch has not been deployed to the existing prototype.

  4. Next gates

    Earn the right to publish

    Implement live authority verification and fresh device binding, then admission. Define component, configuration and plan contracts before connecting graph authoring to real publication.

The experimental mapping is proposed in contracts PR #1. Retained evidence checks establish limited integrity; live authority verification and production qualification remain open. Flow branch snapshot: a5ef296.

05 / CONTRACT CATALOG

One vocabulary across the system

Generated from the repository’s contract catalog at build time. Specified contracts have draft schemas and record-local fixtures; deferred contracts describe required boundaries with wire formats still to agree.

ContractProducer → consumerRequired meaningCoverage
ProvisioningRecordProvisioning → identity/admissionObserved outcome, posture, readiness claims and authoritative evidenceSpecified
DeviceBindingInventory → relying services/admissionExact canonical identity/instance/credential binding and lifecycle snapshotSpecified
WorkloadBindingMembership registry → SPIFFE relying servicesCanonical workload identity, active enrollment instance and per-request permission; unadopted additive 0.5 draftSpecified
DNSWorkloadAuthorizationFleet registry → DNS controllerTransient response binding one authorization query to current workload membership and assigned DNS name; not a durable record or bearer grantSpecified
PilotAdoptionRecordProvisioning → pilot admissionExisting-device observations and separately retained qualification gapsSpecified
PilotPolicyPolicy authority → pilot admission/relying servicesExact two-target cohort, issuer, audience, permissions and validitySpecified
PilotAdmissionDecisionPolicy authority → pilot admissionExact adoption/policy approval or denial and accepted gapsSpecified
PilotDeviceBindingInventory → pilot relying servicesRestricted pilot tuple and lifecycle, without full qualificationSpecified
FleetTargetAdmission → resolver/controllerTenant, instance, platform and capability references, policy decision, freshness and restrictionsDeferred
ComponentContractComponent owner → editor/resolver/adapterVersioned schema, typed ports, compatibility, permissions, resolution semantics and health requirementsDeferred
ConfigurationRevisionAuthoring → resolverImmutable graph, pinned components, secret references and authoring provenanceDeferred
DeploymentPlanResolver → reviewer/publication/executionExact instances, effective input digests, value provenance, conflicts, exclusions, expected revisions and rollout policyDeferred
PublishRequestUser client → publication authorityExact plan and expected desired-state versions, with a retry identitySpecified
PublicationPublication authority → execution/UIDurable acceptance of exact intent, actor and authorization decisionSpecified
BuildResultBuilder → release authorizationExact input-to-artifact mapping, compiler/lockfile/source versions and provenanceDeferred
AuthorizedReleaseRelease authority → assignment/verifierApproved artifact digests, platform, delegation, epoch, validity and recovery classDeferred
DesiredAssignmentController → deviceInstance, desired version, release digest, expected base, attempt and leaseDeferred
DeviceObservationDevice → controller/appraisalSequenced boot/attempt/release observations and separate health dimensionsDeferred
PolicyDecisionAppraisal → controller/verifierEvidence binding, policy version, freshness, result and reasonsDeferred
ExecutionResultController → UI/auditAttempt-correlated result supported by observations and policy decisionsDeferred

06 / SHARED GUARANTEES

What every handoff preserves

01

Exact identity

Logical device, provisioned instance, storage generation and credential tuple are separate identities. Replacement creates a new boundary.

02

Immutable evidence

Record revisions are immutable. Structured records use RFC 8785 digests; evidence digests bind exact retained bytes. A URI is a locator.

03

Current authority

Authenticate origin and enforce tenant, domain, freshness and current policy. Possessing a valid record or digest grants no authority.

04

Explicit configuration

Preserve field provenance through platform constraints, tenant baseline, group settings and allowed device overrides. Equal-layer conflicts block.

05

Stable retries

Repeat the same logical operation with the same identity. Conflicting content is rejected. Lost responses remain unknown until reconciled.

06

Scoped secret references

Keep private keys, tokens and secret values out of shared records, public artifacts, graphs and Nix outputs. Pass scoped references only.

Read the common rules

07 / KEEP GOING

From guide to specification

The Markdown specifications and JSON schemas in this repository are the authority. This page is an explanatory guide; it does not change contract semantics or release status.

System specificationPipeline, authority ownership and global invariants ↗Conformance & examplesSchema checks, record-local checks and runtime obligations ↗Adoption checklistProducer and consumer gates before claiming support ↗Change the contractsCompatibility, review and shared ownership ↗Source baselinePinned upstream decisions and design provenance ↗Why publication is durable intentThe decision behind the acceptance boundary ↗