You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
AuditEntry represents a write event recorded in the audit log.
Every config mutation (SetField, SetFields, RollbackToVersion) creates
one or more audit entries atomically with the config change.
Human-readable description explaining this specific value. Only populated when include_description(s) is true in the request.
ConfigVersion
ConfigVersion represents a point-in-time snapshot of configuration changes.
Each write operation (SetField, SetFields, RollbackToVersion) creates a new
config version. Versions store only the changed fields (delta storage) — the
full config at any version is the union of all deltas up to that version.
DependentRequiredEntry encodes one cross-field requirement: when the
trigger field has a non-null value, every dependent field path must also
have a non-null value. This is the proto wire form of JSON Schema 2020-12
dependentRequired, which uses a map<path, list<path>> shape — proto
maps cannot hold repeated values directly, so we use a repeated list of
entries.
For enum fields: the specific subset of values that are locked (not editable by admin). If empty, the entire field is locked.
Schema
Schema represents a configuration schema template.
Schemas define the allowed fields and their types for tenant configurations.
Each schema is versioned — updates create new immutable versions.
Machine identifier for this schema, used in API calls, URLs, and code. Must be a unique slug: lowercase alphanumeric and hyphens, 1-63 characters, matching a-z0-9?. See info.title for a display name.
Cross-field "B required when A present" rules. Each entry declares one trigger field whose presence (non-null value) makes a list of dependent field paths required (also non-null). Equivalent to JSON Schema 2020-12 dependentRequired, scoped to schema-level cross-field requirement. Lint-checked at ImportSchema time (every path must reference a real field; trigger may not appear in its own dependents). Enforced at every config write against the post-merge snapshot.
Cross-field rule expressions reserved for future Common Expression Language (CEL) evaluation. Stored on the schema and round-tripped through ImportSchema/GetSchema; the runtime engine ships separately (see issue #76). Reserving the key in v0.1.0 of the schema spec avoids a breaking meta-schema change later.
SchemaContact
SchemaContact contains contact information for a schema owner.
OAS: Contact Object
SchemaInfo contains optional metadata about a schema's ownership and context.
Optional organizational metadata for a schema.
Schema.description lives on Schema itself (not here) because it's a
first-class field used in every listing, while these are optional extras.
OAS: Info Object
ValidationRule encodes one cross-field rule expressed in Common
Expression Language (CEL). Reserved in v0.1.0 of the schema spec — the
parser accepts and persists rules, but the engine that compiles and
evaluates them ships separately (see issue #76 / .agents/context/cel-validation.md).
Rules are scoped to a path prefix: an empty path means a schema-wide
rule; a non-empty path anchors the rule to a group for documentation
and UI grouping (the binding namespace itself always exposes every
field via self, regardless of path).
The CEL expression source. Lint at ImportSchema in v0.1.0 only checks that the string is non-empty; CEL compilation happens in Phase 2 once the engine ships.
Optional severity hint. Reserved values: "error" (default — write rejected) and "warning" (write accepted, surfaced for UI). v0.1.0 only validates the value is empty or one of the reserved set; the warning path is not yet enforced.
AuditService provides read-only access to the change history and usage
statistics for tenant configurations.
Write events are recorded automatically by the ConfigService whenever
configuration values are modified (atomically with the config change).
Usage statistics are tracked asynchronously via batched read counters.
GetUnusedFields returns field paths that have not been read since the given time. Useful for identifying configuration fields that may be safe to deprecate.
Config-format spec version to emit (e.g. "v1"). When omitted, defaults to the highest version the server supports. The server returns InvalidArgument if the requested version is not registered.
The target version to rollback to. The full config at this version is copied into a new version (the current version number + 1). The target version itself is not modified.
Optimistic concurrency control: the checksum from a previous GetField/GetConfig response. If provided and the field's current checksum doesn't match, the request fails with ABORTED. This prevents lost updates when multiple actors modify the same field concurrently.
Field updates to apply. All updates are applied atomically in a single config version. If any update fails validation (checksum, field lock), no changes are committed.
Resume the stream from this config version (inclusive). When set, the server replays all changes at versions >= start_version before streaming live events. Use snapshot_version + 1 to close the gap between a GetConfig snapshot and the live subscription.
A configuration change event. Delivered via Redis Pub/Sub internally.
ImportMode
ImportMode controls how imported values interact with existing config.
Name
Number
Description
IMPORT_MODE_UNSPECIFIED
0
Unspecified defaults to merge behavior.
IMPORT_MODE_MERGE
1
Merge: update fields from YAML that differ, keep runtime overrides for fields not in the YAML.
IMPORT_MODE_REPLACE
2
Replace: full replace — all fields from YAML are set, fields not in YAML are not carried forward. Runtime overrides are wiped.
IMPORT_MODE_DEFAULTS
3
Defaults: only set fields that have no value yet. Fields that already have a value are skipped regardless of the YAML content.
ConfigService
ConfigService manages configuration values, versions, and real-time subscriptions.
Configuration is stored per-tenant using delta versioning: each write creates a
new version containing only the changed fields. The full config at any version is
the union of all deltas up to that version (latest value per field wins).
Read operations are cached in Redis. Write operations are atomic: the config
version, values, and audit log entry are committed in a single database transaction.
Read operations.
Reads are served from Redis cache when possible. Setting include_descriptions
bypasses the cache and reads directly from the database.
RollbackToVersion creates a new version with the same values as the target version. This does not delete intermediate versions — it creates a new version that copies the target's values.
Subscribe opens a server-streaming connection that pushes ConfigChange events whenever the tenant's configuration is modified. The stream remains open until the client disconnects or the server shuts down.
Schema-format spec version to emit (e.g. "v1"). When omitted, defaults to the highest version the server supports. The server returns InvalidArgument if the requested version is not registered.
YAML-encoded schema (spec_version v1). Includes schema name, description, version, and all field definitions with OAS-style constraint naming. Server-generated fields (id, checksum, published, created_at) are excluded.
YAML-encoded schema (spec_version v1). Must include spec_version, name, and fields.
Import uses full-replace semantics: - If no schema with this name exists: creates a new schema with version 1. - If a schema exists and fields differ from latest: creates the next version. - If a schema exists and fields are identical: returns AlreadyExists error.
Imported versions are created as drafts (unpublished) unless auto_publish is true. The version field in the YAML is informational — the server assigns the next version number automatically. |
| auto_publish | bool | | When true, the imported version is automatically published after creation. If the schema already exists and fields are identical (AlreadyExists), this has no effect. |
SchemaService manages configuration schemas, tenants, and field-level locking.
Schemas define the allowed fields and their types for tenant configurations.
Each schema is versioned — updates create new immutable versions that must be
published before tenants can use them.
ImportSchema creates a schema (or new version) from YAML. Full-replace semantics: the YAML defines the complete field set. Returns AlreadyExists if the imported fields are identical to the latest version.