Data Model

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The control plane uses a release-centric data model where governed assets flow through versioning, promotion, and release-state management. All entities use UUIDs as primary keys and support slug-based lookups where applicable.

The high-level hierarchy is:

Organization -> Namespace -> Workspace -> Workload -> Release -> Asset bindings

Assets can be workspace-scoped, shared across namespaces through explicit share grants, or platform-owned built-ins. Runtime execution always resolves a release for a workload/environment pair, then follows immutable bindings to the asset versions used for that execution.

Key Entities

GovernedAsset

A platform-managed asset such as a prompt template, knowledge base, model configuration, policy bundle, or orchestration flow.

• Has a unique slug for human-readable lookups
• Owns zero or more AssetVersion records
• Carries workspace and namespace scope for tenant isolation
• Uses asset_kind as the discriminator for schema and business-rule validation
• Tracks audit metadata (created/updated timestamps)

AssetVersion

An immutable snapshot of a governed asset at a point in time.

• Belongs to exactly one GovernedAsset
• Immutable after creation (append-only versioning)
• Contains the version payload (content, configuration, or reference)
• Tracks audit metadata

Workload

A registered workload/application that uses governed assets at runtime.

• Has a unique slug for identification
• Configured with runtime parameters and policy bindings
• Belongs to a workspace
• Participates in releases via ReleaseAssetBinding
• Tracks audit metadata

ReleaseRecord

A release that promotes a set of asset versions for use by consumer workloads.

• Follows the governed lifecycle (draft, review_ready, approved, active, superseded, rejected, retired)
• Groups one or more ReleaseAssetBinding entries
• Tracks audit metadata with state transition history

ReleaseAssetBinding

An immutable join that binds a specific asset version to a release and a workload.

• Links a ReleaseRecord, an AssetVersion, and a ConsumerWorkload
• Immutable after creation
• Represents the decision: “this workload uses this asset version in this release”

ConnectionInstance

A workspace-scoped configured connection. Connection instances reference connection definitions and secret bindings, but resolved connection reads do not expose secret values.

• Belongs to a workspace
• Names configuration and secret binding slots
• Is resolved by runtime paths through governed connection APIs

ExecutionRecord

A durable record of a workload execution.

• Captures workload, release, environment, actor subject, status, timing, and model config reference
• Links runtime traces and evidence back to the release-bound asset set
• Provides the anchor for pause/resume/snapshot and evidence views

Evidence and Audit Records

Evidence records capture runtime artifacts and governance evidence. Audit records capture control-plane governance mutations and authorization-sensitive events.

• Evidence is attached to execution and release context
• Governance audit rows are hash chained for tamper-evident review
• Sensitive values are redacted or referenced rather than embedded directly

MemoryEntry

Memory entries are workload/actor/session scoped records used by memory recall. When semantic recall is enabled, entries also carry embedding metadata and may be indexed by pgvector.

• Belongs to workload and actor context
• Supports retention, decay, and optional semantic recall behavior
• Remains subject to workspace and execution-subject checks

MemorySession

Each entry belongs to a MemorySession that stores the scope resolved from the active release-bound memory configuration. Semantic recall requires an exact match between the requested scope and this stored value before policy filtering or similarity ranking:

• workload scope may return entries written by either subject in the same authorized workload
• actor scope returns only the requesting actor’s actor-scoped entries
• session scope returns only the requesting actor and exact session-scoped entries; a session reference is required

Unknown scopes and session-scoped recalls without a session reference fail closed at the repository boundary.

Entity Relationships

Design Principles

• UUIDs as primary keys: all entities use UUID v4 for globally unique, non-sequential identifiers.
• Slug-based lookups: governed assets, workloads, namespaces, and workspaces support human-readable slug fields for API convenience.
• Immutable versioning: AssetVersion and ReleaseAssetBinding are append-only. Updates create new records rather than mutating existing ones.
• Audit trails: all mutable entities track created_at and updated_at timestamps via shared mixins (AuditMixin, ImmutableAuditMixin).
• Release-centric: the binding model ensures that asset-to-workload associations are always scoped to a specific release, enabling rollback and promotion.
• Workspace isolation: tenant-scoped reads require workspace context unless a platform path or explicit share grant allows visibility.
• Provider-neutral secrets: connection instances and secret bindings identify what the runtime may resolve; secret material stays in the configured backend.
• Evidence over inference: release, execution, evidence, and audit records preserve enough context to reconstruct what asset versions and decisions were active.

Lifecycle implications

Changing a prompt, model, policy, flow, knowledge base, memory config, or connection definition means creating a new asset version and binding it into a new release. Activating that release changes the runtime view for the workload; older executions remain tied to the release and asset versions they actually used.

Rollback follows the same model. Operators activate a release that points at a previously approved asset version set rather than mutating the currently active versions in place.