---
title: "Kodama concepts and lifecycles"
description: "Learn Kodama’s domain model: tenant ownership, work-item revisions, Git workspaces, immutable runs, attempts, artifacts, human gates and deployments."
canonical_url: https://optimi.com/en/docs/kodama/concepts
md_url: https://optimi.com/en/docs/kodama/concepts.md
last_updated: 2018-10-20
---

# Concepts and lifecycles

Kodama keeps **business intent, source work, execution and human decisions** in
separate records. Understanding those boundaries prevents a successful command
from being mistaken for a reviewed or delivered business outcome.

## Ownership: factory, tenant and project

A **factory** is one installation. A **tenant** is an organization within it,
owning projects and memberships. A **project** groups related work, repository
settings, pipeline definitions, configuration and delivery environments.

Tenant and project ownership accompany records, API routes, events, artifacts
and runtime identities. Knowing an ID does not grant access to its resource.
The customer organizations inside an application produced by Kodama are
**application tenants**; they are distinct from factory tenancy.

In standalone operation, OIDC establishes the person’s identity and local
memberships establish authorization. The fixed roles compose through bindings:

| Role | Main responsibility |
| --- | --- |
| `admin` | Membership, project settings and credential management |
| `analyst` | Specifications and acceptance criteria |
| `engineer` | Technical edits, workspaces, runs and deployment |
| `reviewer` | Human gate decisions and business completion |
| `viewer` | Authorized read-only access |

An administrator is not automatically a reviewer. A workload receives
attempt-scoped actions rather than a human role. A valid access token still
needs a current binding for the requested operation.

## Work items describe the intended outcome

A **work item** contains a kind, title, specification, acceptance criteria and
business state. Stories, tasks and defects are actionable; an epic groups work.
A card is a board representation of a work item, and a plan belongs in its
specification rather than in a separate planning resource.

The business lifecycle is:

**Business work has its own lifecycle**

![Work moves from backlog to ready, active, review and done. Rework and reopening return to active; unfinished work can be cancelled.](/diagrams/kodama/work-lifecycle-en.svg)

*A successful pipeline provides evidence. It does not decide the business state of the work item.*

Every entry to `active` checks WIP capacity. A blocked item remains in its state
and continues to consume its active slot. Dependencies describe business
prerequisites; they differ from a pipeline’s step dependencies. An unmet work
prerequisite prevents admission to active work.

Entering review requires an identified candidate and applicable evidence.
Completion is an explicit reviewer action against that subject and the current
requirements. Human gates within a pipeline have their own lifecycle: approving
a gate does not automatically move the work item to `done`.

## Resource version versus content revision

These two numbers answer different questions:

| Value | Changes when | Used for |
| --- | --- | --- |
| `version` | Any resource mutation | Optimistic concurrency through `If-Match` or CLI `--if-version` |
| `contentRevision` | Specification or acceptance criteria change | Pinning the requirements a run or review evaluates |

A transition can increment `version` while leaving `contentRevision` unchanged.
A run pins the content revision it was admitted against. Editing requirements
does not rewrite historical runs or gate decisions; a new run evaluates the
new requirements. After a version conflict, read the resource and history before
deciding whether your intended edit still applies.

## Workspaces preserve source continuity

A **workspace** is the durable logical source context paired with an actionable
work item. Its states are `provisioning`, `available` and `archived`. Its branch
and accepted commit live in Git; its ownership and publication records live in
PostgreSQL. A running container’s filesystem is disposable scratch.

- A **checkpoint** is a committed revision retained for recovery or later work.
- A **candidate** is the commit proposed for review and delivery.
- Each attempt uses a private clone; it does not share a writable filesystem
  with another attempt.
- Readers use a pinned commit. `workspace.access: read` forbids publication,
  while allowing build-tool scratch changes inside the clone.
- Writers are ordered. Publication compares the expected remote branch tip
  before moving it, a Git compare-and-swap operation.

A human push that moves the branch can therefore cause a publication conflict
instead of being overwritten. A lost push response requires inspecting the
remote ref before releasing the writer slot. Deleting a Pod is not proof that
its publication settled. Archive and restore operate on the same workspace;
they do not erase retained commits.

## Definitions, runs, steps and attempts

A **pipeline definition** is an immutable version of a directed acyclic graph.
Registration validates the document and stores a canonical digest. Registering
identical content returns the existing version.

A **run** executes one definition with pinned inputs, source commit, content
revision and applicable configuration. A **step run** tracks one node of the
graph. A **step attempt** is one execution of an executable node; an allowed
retry creates another attempt rather than rewriting the first.

| Resource | Persisted states |
| --- | --- |
| Run | `queued`, `running`, `succeeded`, `failed`, `cancelled` |
| Step | `pending`, `running`, `succeeded`, `failed`, `skipped`, `cancelled` |
| Attempt | `running`, `succeeded`, `failed`, `cancelled` |
| Gate | `pending`, `approved`, `rejected` |
| Deployment | `pending`, `running`, `succeeded`, `failed` |

Waiting, cancellation requests, timeouts and uncertain external effects are
represented through reasons and timestamps. They are not additional status
values. A cancellation request can be accepted while the run is still running;
observe it until settlement.

## Agents, evidence and gates

An **agent profile** is an immutable selection of harness image, instructions,
model, tools and supported limits. The agent step expands into ordinary runtime
execution. Models and tools must be approved by the project and supported by the
installation’s qualified wrapper catalogue. A profile cannot create authority
that the installation does not grant.

An **artifact** is a retained output such as a report, trace or log.
**Evidence** is the artifact and provenance used to evaluate a particular
candidate or deployment. A successful exit code without required outputs can
still fail result finalization.

A **gate** requests one human decision about an identified subject. That subject
binds source, content revision, definition and evidence, plus deployment
configuration when applicable. The decision is immutable. Current reviewer
authority and subject applicability are checked again before approval is
consumed. A gate waits in the database without reserving a running container.

An agent reporting `needs_input` fails with a recorded question. After clarifying
the specification, start a new run; there is no implicit conversation continuation.
Likewise, an approved gate or a passing QA result never marks business work done.

## Two meanings of environment

**`KODAMA_ENV`** selects the process’s adapter set: `development`, `test` or
`production`. A **delivery environment** is a named project target, such as a
preview or staging namespace, with scoped configuration and credentials.

A **deployment** records the target, source, image digest, configuration and
execution outcome. A **preview** is a temporary deployment. Expiry requests
cleanup through the delivery lifecycle; it does not erase the deployment’s
history or its evidence.

Next: **[Architecture](/en/docs/kodama/architecture)** and the
**[developer workflow](/en/docs/kodama/developer-guide)**.