Glossary

Short definitions of the terms used across these docs. Terms that are also wire fields or error codes are set in code. Each links to the page that explains it in full.

Append field. A field that holds an ordered list of entries. You add entries and never change or remove them. Its version is the number of entries. See Field modes.

Author. The identity recorded on every write, such as apikey:ops-bot or sa:kagent/remediator. The gateway takes it from the credential on the connection. You cannot set it in a request body. See Scope and identity.

based_on. A list of {field, version} pairs you send with a write to say what your decision relied on. If any of them has changed, the write is rejected with STALE_PREMISE. See based_on.

Checkpoint. A JSON document an agent saves to record its progress on a record. It is stored per record and per role. Loading it returns the latest document plus every field that changed since it was saved. See Checkpoint and resume.

Claim. Taking a lease on a task field so other agents know you are working on it. Send renew: true to extend your lease and lease_seconds: 0 to release it. See Claims and leases.

Class. The template a record is created from. It lists the fields, the roles, how long records live, and the checkpoint rules. You write it as YAML, or as a SharedContext resource on Kubernetes. See The shared record.

CLASS_GONE. HTTP 410. The class has been deleted. Its records stay readable until they expire, but every write is rejected.

Evidence. Free text a writer attaches to say what the write is based on, such as a log line or a command’s output. The class can require it. The gateway checks that it is present, not that it is true.

expected_version. The version of a versioned field that you read before writing it. Send 0 to say the field must not exist yet. If it does not match the current version, the write is rejected with STALE.

Fence. A premise a writer declares to prove it still holds a claim. It names the task field and the version the writer’s claim returned. kslate checks it inside the write, so a write after a lost lease is refused with STALE_PREMISE. History stores it as kind: fence and blame prints (fence). See based_on.

Field. A named slot in a record. Each field has a mode, a value type, and its own version.

Gateway. The kslate process that agents talk to. It serves HTTP/JSON, gRPC and MCP and decides every request. The checks that have to be atomic run as SQL in one transaction: the version and lease compare-and-swaps, the based_on check and the checkpoint gate.

HELD. HTTP 409. You tried to claim a task that another identity holds and whose lease has not expired. The body tells you who holds it and until when.

History. The list of every write to a record, including rejected ones. Each row has the author, evidence, expected_version, premises and outcome. kslate history and kslate blame read it. See blame.

Identity provider. How the gateway turns a credential into an identity. apikey maps a bearer token to a name using a file. k8s-sa verifies a Kubernetes ServiceAccount token with the API server. oidc verifies a signed JWT against a listed issuer’s keys. mtls verifies the connection’s client certificate against a listed CA. --identity takes a comma-separated list and tries them in order. A credential none of them recognises gets UNAUTHENTICATED.

Identity strength. How well the writer’s credential was bound, as the gateway worked it out: pod-bound, sa-bound, issuer-declared or shared-secret. Stored on every write as identity_strength. See Identity strength.

Inferred premise. A premise the gateway works out for you. Read a record, then write to it with the same X-Kslate-Scope header within 15 minutes and no based_on. The gateway treats what you read as your premises. History marks these inferred: true.

Invocation. A JSON object of at most 1 KiB that a writer may attach to a write to say which call produced it. kslate stores it and returns it unchanged. It does not check it, and blame labels it writer-asserted.

Lease. How long a claim lasts. You set it with lease_seconds, or the class sets a default. The maximum is 86400 seconds. The gateway checks expiry when someone tries to claim, using the database clock.

minIdentityStrength. The weakest identity strength a class, or one field, accepts for a write. A write below it is refused with WEAK_IDENTITY.

Mode. How a field may be written: versioned, soft, append or task. See Field modes.

moved[]. The part of a STALE_PREMISE response that lists each premise that changed. Each entry shows the version you declared, the current version, and who wrote it.

Premise. One {field, version} pair that a write relied on. It may carry kind: fence (see Fence). See based_on.

Record. One instance of a class, named <class>/<id>. The first write to it creates it. It has a record_version that counts every write.

record_version. A counter on the record that goes up on every write to any field. Resume uses it to find what changed. Premises use field versions instead.

Rejection order. The fixed order in which the gateway runs its checks. If a request fails more than one, you get the first failure in that order. See the HTTP API.

Resume. Loading the latest checkpoint for a role, plus the changed_fields since it was saved. kslate resume on the CLI, or GET …/checkpoint on the wire.

Role. An entry in the class that maps identities to the fields they may read, write and claim. An identity that matches several roles gets all of their permissions.

Scope. The fields a role may read, write or claim. Reads outside scope are filtered out, or rejected with SCOPE_DENIED if you ask for them by name. Writes outside scope are rejected with SCOPE_DENIED.

Scope header. X-Kslate-Scope, the opaque value a caller puts on a read and a later write so the gateway can infer the write’s premises. It shares a word with role scope and nothing else. See Inferred premise.

Soft field. A field where the last write wins. You do not send expected_version. The gateway still records a version, evidence and premises.

STALE. HTTP 409. You wrote a versioned field with an expected_version that is no longer current. The body always gives you the current version, and gives the value, author, evidence, time and diff when your role may read the field.

STALE_PREMISE. HTTP 409. A premise you declared, or one the gateway inferred, has changed. The body describes the field you wrote and lists what moved in moved[].

Takeover. A claim that succeeds because the previous holder’s lease expired. The response includes took_over_from. History records it as op: takeover.

Task field. A field that tracks who is working on something. It has an owner and a lease_expires_at, and you write it only through claim.

Tombstone. The cached copy of a class that stays after the class is deleted. It is what lets the gateway answer CLASS_GONE and keep records readable.

TTL. ttl.after in the class. Records expire this long after they are created. An expired record is deleted along with its history, or saved as a snapshot if the class sets onExpire: archive.

Versioned field. A field with one current value. Every write must carry the version you read. Use it for fields where only one value can be true at a time.

WEAK_IDENTITY. HTTP 403. Your credential is weaker than the field’s minIdentityStrength. The body names required and presented.

Worker. The kslate process that deletes expired records, flags expired leases for metrics, and cleans up scoped reads. On Kubernetes it also runs the SharedContext controller.