Workspace Declaration
A chant.workspace.json at the top of a repository makes it a workspace: a directory of members of declared kinds (#2524 D1, D2). Only this file creates a workspace. chant never infers one, and a project without it stays at level 0, where nothing changes (#2525). chant workspace init proposes one from the projects already in the repository, and chant workspace ls lists what it declares.
The repository is the workspace’s database (ws-074, #3158). The declaration, the record files the kinds it names hold and the ledgers on chant/lifecycle are every durable fact about the workspace, and a tool such as hud or studio changes them only through chant’s commands. A tool may keep a cache or an index, never a fact the repository doesn’t have.
The format is JSON so that any reader can list the members without running TypeScript. The JSON Schema ships in @intentius/chant at src/workspace/declaration.schema.json, with the $id https://intentius.io/chant/schemas/workspace/declaration/v1/chant.workspace.schema.json. chant validates the file against it on every read.
Example
Section titled “Example”This is the declaration the chant repository commits, shortened:
{ "name": "chant", "schema": 1, "members": [ { "name": "docs", "dir": "docs", "kind": "other", "because": "an npm package with no chant project" }, { "name": "lexicon-aws", "dir": "lexicons/aws", "kind": "other", "because": "an npm workspace package with no chant project" }, { "name": "core", "dir": "packages/core", "kind": "other", "because": "an npm workspace package with no chant project" }, { "name": "examples", "kind": "examples", "glob": "examples/*" }, { "name": "lexicon-examples", "kind": "examples", "glob": "lexicons/*/examples/*" }, { "name": "fixtures", "kind": "examples", "glob": ["test/forgejo-preview-e2e", "test/leftness"] } ]}The file
Section titled “The file”| Name | Dialect |
|---|---|
chant.workspace.json | strict JSON |
chant.workspace.jsonc | JSON with // and /* */ comments and trailing commas |
Having both in one directory is an error (declaration-ambiguous). Duplicate keys are an error in either dialect.
chant finds the file by walking up from the current directory to the git root, the first directory holding .git, and it checks the git root too. The nearest declaration wins, so a command inside a nested workspace reads the inner one. Outside a git repository only the current directory is checked. The walk that finds a project’s chant.config.ts is unchanged and never looks at the declaration.
Top-level fields
Section titled “Top-level fields”| Field | Required | Value |
|---|---|---|
name | yes | The workspace’s name, in the name grammar. With a git revision it identifies the workspace to readers. |
schema | yes | 1, the only format version so far. |
members | yes | An array of members and example groups, in the order readers list them. |
minReader | no | The oldest chant version that may read the file, such as "0.81.0". An older chant refuses it with reader-too-old. |
scope | no | repo, the default, or org for an org workspace, which holds only repo members. It was added in chant 0.124.47. |
pins | no | An array of pins. |
checks | no | Severities for the declaration checks, keyed by WSP id: error, warning, info or off. |
records | no | The workspace’s own record kinds, each { "kind": "<path>" } with the path from the workspace root. It was added in chant 0.86.0. |
hosts | no | The hosts boxes run on, each with the port range its boxes share. It was added in chant 0.91.0. |
diagrams | no | The workspace’s own diagram artifacts, each pinned to the renderer its render was made with. It was added in chant 0.91.0. |
changes | no | The forward coverage check of chant workspace check --changes: severity (off, warn or fail, default warn) and ignore, globs over file paths from the workspace root whose changes need no record, such as lockfiles and generated output. It was added in chant 0.92.0. |
writeScope | no | Who may write what: for each principal class, the members whose files it may write and the record kinds it may write, with which verbs. See Write scope and agent sessions. It was added in chant 0.101.0. |
agents | no | The agent sessions, each bound to one member or several. See Write scope and agent sessions. It was added in chant 0.101.0, and a session’s members in chant 0.105.0. |
identity | no | Who a person-attributed record or gate approval may name, and which gates pass only on a signed approval. See Identity. It was added in chant 0.102.0. |
ci | no | Which of the branch’s commits passed CI, as green. See CI. It was added in chant 0.108.0. |
retention | no | How long chant lifecycle gc keeps stored change sets, releases and run event files. See Retention. It was added in chant 0.124.29. |
metrics | no | The failure window chant workspace metrics counts a failed deploy in, new in chant 0.124.29. See Metrics. |
security | no | The security groups the workspace opts into, new in chant 0.124.33. See Security. |
quorum | no | How many agree verdicts besides the decider’s a record needs, as an integer from 0. chant workspace records reports each record’s quorum against it, and it applies to every record kind with a reviews list. The default is 2. It was added in chant 0.86.0, so a declaration that sets it should set minReader to "0.86.0". |
$schema, $comment | no | Editor hints and notes. chant ignores them. |
x-... | no | Any field whose name starts with x-, for people and other tools. Allowed on every object in the file. status --json and ls --json print them back, as written, on the object of their output that the declaration holds them on (#3595), so a tool reads what it wrote without parsing the file. |
Any other field is refused. A field added later within schema 1 is optional. A declaration that uses one should set minReader to the first chant that knows it, so an older chant reports reader-too-old and doesn’t misread the file.
Members
Section titled “Members”A member is an object with name, dir and kind. A member of kind repo has repo in place of dir.
| Field | Required | Value |
|---|---|---|
name | yes | The member’s name, in the name grammar. Frozen once the member deploys. |
dir | yes, except for repo | Its directory relative to the workspace root, with / separators. "." is the root member. A repo member has none. |
kind | yes | How to read it: chant, workspace, repo, design, other, or a kind a pinned package supplies. |
repo | for repo | The other repository’s workspace: url, the pinned rev and, optionally, workspace. See Repo members and org workspaces. Only a repo member has it. |
roles | no | Roles the member plays. Each is a role name, or { "name": "...", "path": "..." } with a path inside the member. |
generated | no | The files a command writes in the member, with the command that writes each (see Generated files). |
links | no | The member links this member reads, each { "member": "...", "output": "..." }. |
outputs | no | For a member of kind other, design or a kind from a package, the outputs it exposes to links. A chant member’s outputs are read from its source instead. |
fields | no | Values for the fields its kind declares, such as an app member’s health path (#3151). Each is a string, integer or boolean, or an object of those for a field the kind declares as an object. A field left out takes the kind’s default. chant workspace check fails a field the kind doesn’t declare, or a value of the wrong type, with WSP005. It was added in chant 0.103.0. |
records | no | The record kinds the member holds, each { "kind": "<path>" } with the path from the member’s directory. It was added in chant 0.86.0. |
diagrams | no | The diagram artifacts this member holds. It was added in chant 0.91.0. |
box | no | The member is a box, or holds a box’s declarations: the capabilities it reaches through a broker, each with its broker and scope. It was added in chant 0.91.0. |
upstream | no | Where an embedded member’s files come from. Versions live in the lock, not here. |
because | for other | Why the member is there. |
travel | no | true when the member goes with an export. chant workspace export takes only members that set it. It was added in chant 0.101.0. |
acceptWorkspaceGates | no | true lets an approval of a workspace gate stand in for this member’s own gates, when its digest covers the plan the member’s run reached the gate with. Only the declaration at base counts. It was added in chant 0.124.47. |
suppress | no | Declaration checks turned off for this member, each { "check": "WSP009", "because": "..." }. See severity and suppression. |
These kinds are built in, besides design and the group kind examples.
| Kind | The directory holds |
|---|---|
chant | a chant project, with chant.config.ts or chant.config.json directly in it |
workspace | a nested workspace with its own declaration. The outer workspace never runs commands or writes inside it, except chant workspace export into a member with the role export. chant workspace graph reads it read-only, through its own chant workspace graph |
repo | nothing in this repository: the member names another repository’s workspace. See below |
other | anything chant does not read. because is required |
A pinned package can supply more kinds, as data at its ./workspace-kinds subpath. Workspace Kinds describes the format, which packages are read, and how chant decides when several kinds’ probes claim one directory. A member whose kind no built-in or pinned package supplies is listed with the reason unknown-kind, and chant workspace check fails on it.
A member’s directory leaves the root project, and discovery at the root skips it (#2527). The member’s own commands cover it, and chant workspace build runs them for every member (#2537). chant workspace init lists these directories before it writes.
Repo members and org workspaces
Section titled “Repo members and org workspaces”A member of kind repo names another repository’s workspace by URL and pinned revision (#3168). It is read only through that repository’s own read contract, its chant workspace graph at the revision, the way a nested workspace member is read, and chant never writes there.
{ "name": "acme", "schema": 1, "minReader": "0.124.47", "scope": "org", "members": [ { "name": "payments", "kind": "repo", "repo": { "url": "https://github.com/acme/payments", "rev": "9f2c4e1d0b7a6c5e4f3a2b1c0d9e8f7a6b5c4d3e" } }, { "name": "platform", "kind": "repo", "repo": { "url": "git@github.com:acme/platform.git", "rev": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "workspace": "infra" } } ]}repo field | Required | Value |
|---|---|---|
url | yes | Where git fetches the repository from: an https, ssh or file URL, a local path (from the workspace root), or git@host:org/repo. It must carry no password or token (WSP016); git’s own credential helpers supply access |
rev | yes | The pinned revision, a full commit id. A branch or tag is not a pin |
workspace | no | The workspace root inside that repository, from its git root. Defaults to "." |
A repo member has no directory here, so it takes no part in placement. chant workspace ls lists it with dir @repo/<name>, a marker that names no directory, and its repo object. build, lint and audit skip it with kind-not-run. chant workspace graph fetches the revision into the user’s cache and folds the other repository’s graph in, with that repository’s own member list under the member’s nested. chant workspace check never fetches.
An org workspace sets scope to org and holds only repo members, one per repository of the org. chant workspace check fails any other member or example group with WSP013. A warden generates the declaration from its policy, or checks one against the forge: it writes the org’s repository list to a file and runs chant workspace check --forge-repos <file>, which reports a repository the forge has and the declaration lacks (WSP014) and one the declaration names that the forge no longer has (WSP015). chant reads the list and never asks the forge itself.
Member links
Section titled “Member links”A member link says that one member reads an output of another (#2524 D6, #2539, ws-008). The consumer states it once and names the producer and the output.
{ "name": "acme", "schema": 1, "members": [ { "name": "shared", "dir": "infra/shared", "kind": "chant" }, { "name": "web", "dir": "services/web", "kind": "chant", "links": [{ "member": "shared", "output": "ClusterArn" }] }, { "name": "legacy", "dir": "legacy", "kind": "other", "because": "a queue created by hand", "outputs": ["QueueUrl"] } ]}| Field | Required | Value |
|---|---|---|
member | yes | The producer, another member of this workspace. An example group can’t be one. |
output | yes | The producer’s output. It is matched exactly, the way deploy matches it. |
kind | no | The link kind: output, the default, or telemetry (below). Any other value fails closed. |
protocol | no | For a telemetry link, the OTLP protocol the consumer sends: grpc, http/protobuf or http/json. Any other link kind refuses it (WSP098). |
The outputs a producer exposes depend on its kind.
| Kind | Exposes |
|---|---|
chant | The names its source passes to output(ref, "Name"), and each export const name = stackOutput(ref). chant reads the TypeScript without running it. A lexicon can add outputs for its own declarations: a sql member exposes each table and view as <schema>.<table> and each column as <schema>.<table>.<column> (below). |
workspace | Nothing. Links name the outer workspace’s own members, and a nested workspace’s links stay its own. |
other | What the entry lists in outputs. |
| a kind from a package | What the kind lists in its outputs, plus what the entry lists. |
chant workspace check resolves every link in source and never reaches the network. A link whose output the producer no longer exposes fails, so renaming an output fails the check for every consumer that links to it. When chant can’t read all of a chant producer’s outputs without running its code, such as an output whose name is computed, a link to a name it didn’t find is kept and reported as unresolved.
Lexicon outputs
Section titled “Lexicon outputs”A lexicon can report outputs for its own declarations, through the workspaceOutputs plugin hook (#3931). In the sql lexicon a Postgres member exposes public.orders for a table and public.orders.customer_id for its column, and a ClickHouse member analytics.events and analytics.events.user_id. The naming rules and a worked example are in Tables and Columns as Workspace Outputs.
{ "name": "app", "dir": "app", "kind": "other", "because": "reads the database", "links": [{ "member": "db", "output": "public.orders.customer_id" }] }chant workspace check reads these outputs by folding the member’s source under the build’s sandbox, so no member code runs. A file of the lexicon’s that does not fold leaves the member’s outputs incomplete, and a link to a name the check did not find is unresolved rather than missing. When the source records a rename, such as a sql -- previously: customer_id comment, a link to the old name is told the new one. chant workspace graph lists the outputs in its exports, with a renamed output’s old names in previously.
Joins nobody wrote down are inferred. Each parameter of a chant member, written export const name = new Parameter(...), is matched to the other members’ outputs by the core function joinKey(). That function ignores case and punctuation. An inferred join is labelled exact when the names are equal and folded when they differ only in case or punctuation, so clusterArn joins ClusterArn as folded. A parameter that matches outputs of two producers is reported as ambiguous and joins neither. A declared link from the same consumer to one of the matched outputs replaces the inferred join, and writing one down is how an inferred join becomes declared.
Telemetry links
Section titled “Telemetry links”A telemetry link says that a member sends its telemetry to the collector of another (#2558, D22 of #2524, ws-060). The service is the consumer and the member that declares the collector is the producer. output names a pipeline id (traces, traces/backend) or an exporter id (otlphttp/backend) in the producer’s collector, which the otel lexicon reports for chant workspace graph (#2559).
{ "name": "app", "dir": "app", "kind": "other", "because": "...", "links": [{ "member": "delivery", "output": "traces", "kind": "telemetry", "protocol": "http/protobuf" }] }The graph command, chant workspace graph, checks the link in its links section and gives it one of four statuses. It is resolved when the producer’s collector has that pipeline or exporter. It is missing when the collector doesn’t, or when the producer declares no collector. With a protocol, a pipeline must have a receiver that speaks it and an exporter must speak it itself, and a mismatch is invalid with a reason that lists what the target speaks. A target whose definition states no protocols leaves the link unresolved. A resolved row also says whether the target is a pipeline or an exporter.
Because chant workspace check reads source and runs no member, it can’t read a collector, and so a telemetry link stays unresolved there (WSP094) while the graph resolves it. A declaration that uses a telemetry link sets minReader to 0.101.0 or newer, since an older chant refuses the link kind.
Record kinds
Section titled “Record kinds”The declaration names the workspace’s record kinds, so a reader never has to guess which kind files exist (#2680). A member lists the kinds it holds in its records. Kinds whose records belong to no one member, such as a decisions directory at the root, go in the top-level records. The reference workspace declares its decision kind that way, and its design member declares the review-session kind with the design kinds of #3148. In this example the design member holds a kind of its own too:
{ "name": "studio", "schema": 1, "minReader": "0.86.0", "members": [ { "name": "design", "dir": "design", "kind": "design", "records": [{ "kind": "notes/note.kind.mjs", "name": "notes" }] } ], "records": [{ "kind": "decisions/decision.kind.mjs" }]}| Field | Required | Value |
|---|---|---|
kind | yes | The kind file: a module that exports recordKind (Record kinds). The path is relative to the member’s directory, or to the workspace root in the top-level list, and it stays inside it. A path is declared once across the file. |
name | no | The name readers show for the kind, in the kind-name grammar. Without it, the kind file’s own recordKind.name. A name is given once across the file. |
Readers take the top-level list first. The members’ lists follow in file order.
| Command | Uses the declared kinds |
|---|---|
chant workspace ls | lists them, with each kind file’s name, or the reason it can’t be loaded |
chant workspace check | fails with WSP115 when a kind file is missing or doesn’t load as a record kind. The check is fixed, so it can’t be turned down or suppressed |
chant workspace records | reads every one of them when --kind is not given |
chant workspace graph --intent | reads every one of them, and runs each one’s commit joins, when --kind is not given |
--kind still overrides the declaration in records and graph --intent. A kind file is looked for in the tree read, which is the revision under --at. It is loaded from the working tree, the way a --kind file is. A declaration that uses records should set minReader to "0.86.0". An older chant then reports reader-too-old, where it would otherwise refuse the field as unknown.
Write scope and agent sessions
Section titled “Write scope and agent sessions”writeScope says who may write what, per member and per record kind, for each principal class (#2548, ws-067). agents names the agent sessions, each bound to one member or several (ws-101). Without them nothing is restricted.
{ "name": "studio", "schema": 1, "minReader": "0.101.0", "members": [ { "name": "app", "dir": "app", "kind": "other", "because": "a Node server" }, { "name": "design", "dir": "design", "kind": "design", "records": [{ "kind": "sessions/session.kind.mjs" }] } ], "records": [{ "kind": "decisions/decision.kind.mjs" }], "writeScope": { "agent": { "records": { "decision": ["new", "review"] } }, "runner": { "members": ["app"], "records": { "decision": ["review"] } } }, "agents": [{ "name": "app", "member": "app", "principals": ["app-bot@example.com"] }]}writeScope has an entry for each class it restricts: human, agent, runner, service, or a domain class a pinned package supplies, such as reviewer (#3080, see principal classes from a package). A class with no entry isn’t restricted. A declaration that names a domain class sets minReader to 0.102.0 or newer.
| Field | Value |
|---|---|
members | The members whose files the class may write, by name, or "*" for every path. Without it, every path. A path in no member, such as chant.workspace.json at the root, is in scope only under "*". The agent entry takes no members: a session writes only the members it is bound to. |
records | Kind names, as the kind file’s recordKind.name or the name the declaration gives it, each with the verbs the class may write it with: new, amend, review and close. A kind left out can’t be written at all. Without records, every kind in reach with every verb. |
protected | Paths the class may not write, even inside a member it may. Each entry is a glob from the workspace root, or { "path", "except" } for a JSON file the class may change only in what except names: a top-level key, or a JSON Pointer starting with /, where a * token matches every key or array index at its level (#3308). An entry covers the files it matches and everything under a directory it matches, so "box" covers box/ops/guard.mjs. The agent entry takes it too. Added in chant 0.102.0 (#3146). |
A kind a member declares is in reach when that member is. The workspace’s own kinds, from the top-level records, are in every writer’s reach, so an agent bound to app can propose a decision that lives at the root. A record is never deleted under a restricted scope.
protected is how a factory keeps a build away from what it must not change (#3146, ws-077). A builder bound to the root member could otherwise write the declaration, the box’s own Ops and the release config:
"writeScope": { "agent": { "records": { "work": ["new", "amend"], "proposal": ["new"] }, "protected": ["steward", "delivery/.chant", "delivery/chant.config.ts", { "path": "chant.workspace.json", "except": ["diagrams"] }] }}A record file is judged by records, never by protected: leave a record kind out of records, or narrow its verbs, to keep a builder off it. check --changes reports a write to a protected path with write-scope-protected. For an entry with except, it parses the file before and after the commit, and the change is in scope when the two differ only in those top-level keys and the values those pointers match. { "path": "chant.workspace.json", "except": ["/members/*/box/listing"] } keeps the declaration protected and lets a box’s listing change, which is what chant workspace box listing set writes. chant workspace agent --json lists a session’s protected paths, so a factory’s guard can apply the same list to a build’s diff before anything is committed.
Each entry in agents is a session:
| Field | Required | Value |
|---|---|---|
name | yes | The session’s name, unique among agents, in the name grammar. |
member | one of member and members | The one member the session is bound to: a declared member, not an example group. |
members | one of member and members | The members the session is bound to, when it writes in more than one, each a declared member. Added in chant 0.105.0 (#3505). |
principals | no | Principals that write only as this session. A commit attested by one, or a write whose by names one, is judged as the session. A principal is listed by one session at most. |
A writer’s class comes from the role grants in the trust policy at base. A principal holding the agent role is in the agent class. One holding runner is a runner and one holding service a service, tried in that order. Then each domain class the pins supply is tried, in pin order, by the role it names. Anyone else is human. While writeScope names a class no pinned package supplies, a writer judged human might be in it, so its writes are refused with write-scope-class-unknown. A write that names a session is in the agent class. Naming a session only ever narrows what the writer may do, so chant honours a session name it can’t verify.
| Where | How the session is named | What happens outside scope |
|---|---|---|
chant workspace records new, amend, review and close, and the MCP record tools | the CHANT_AGENT environment variable, set by whatever runs the agent | refused with write-scope-member, write-scope-kind, write-scope-class-unknown or agent-unknown; nothing is written |
chant workspace check --changes | a Chant-Agent: <name> commit trailer, or an attested principal a session lists | a finding for each path, and the check fails |
All three read writeScope and agents from the declaration at base (origin/HEAD, main or master, or the range’s base for check --changes), with the trust policy read there too. An agent can’t widen its own scope by editing its copy of the declaration, and an edit to the declaration by a writer restricted to members is itself out of scope. A writer with no entry can still edit both blocks, so chant workspace verify treats a commit that changes writeScope or agents as a protected write when the declaration at base has either. It needs a signature by a signer the policy at base lists, or by an admin when the admin role is granted (#3079). On a developer machine this detects; run in CI with an attestation policy at base, the principal is the signer the policy trusts (ws-002).
A session bound to several members may write the files of any of them and the records of kinds any of them or the workspace declares; its scope is their union, and writeScope.agent applies to all of it. A factory whose builds write an app and also record their evidence in a design member declares one session over both (arugula-salad/studio#402), where a session bound to app alone would fail every build with write-scope-member:
"agents": [ { "name": "factory", "members": ["app", "design"] }, { "name": "planter-chat", "member": "app" }]A declaration that uses members needs a minReader of 0.105.0 or higher, since an older chant does not know the field. chant workspace agent <name> prints what a session reloads from: its members, its scope and the spec. chant workspace ls --json lists the sessions bound to each member in its agents, read from the same declaration, so a tool that starts an agent for a member reads the names there (#3615).
Identity
Section titled “Identity”A record’s by, decided_by, reviewer or answerer, and a gate approval’s --actor, name a person. chant never signs a person in (ws-052). The surface that does (hud, studio’s planter, behold) maps the session to one of these principals and passes it to chant’s write commands (#3163, ws-080):
| Form | Written as | What vouches for it |
|---|---|---|
| forge identity | github:<login>, gitlab:<login>, or <forge>@<host>:<login> for forgejo, gitea or a self-hosted github or gitlab, such as forgejo@codeberg.org:alice | The surface that signed the person in through the forge. chant records it as given, folding case. |
| signer | a principal .chant/allowed_signers lists at base, often the person’s forge identity, or one with a passkey under passkeys in .chant/trust.json | A seal made with --sign by a key listed for that principal, or a signature made elsewhere and brought with --signature (below), verified against the signers and passkeys at base. |
| role holder | a principal holding the agent, runner or service role at base, or listed by a declared agent session | The role grant at base. Not a person. |
| name | anything else, such as a hud roster name or $USER | Nothing. |
The role grants in .chant/trust.json and the signers file name people by the same string, so github:alice is one person in a record, in the key list and in a principal class.
"identity": { "attribution": "identified", "gates": { "ship": { "class": "operator", "quorum": { "count": 2 } }, "rollback": {} }}| Field | Value |
|---|---|
attribution | any, the default, takes any name. identified refuses a name: records new, amend and review, points answer and chant approve refuse a --by, author field, answerer or --actor that is not a forge identity, a signer or a role holder, with principal-unidentified. |
gates | Gates by name. A gate of that name, in any member, Op or component, counts only an approval sealed with chant approve --sign by a key the signers file at base lists for its approver, or signed elsewhere with such a key or a passkey .chant/trust.json lists and brought with chant approve --signature. With class, the approver must also be in that class, read from the role grants at base. A class no pinned package supplies lets nothing through. Without a signers file at base, nothing passes. The gate named release also says who may cut a release: chant release cut then needs --sign, by an actor in its class. |
gates.<gate>.quorum | The approval rules an Op gate of that name takes, in place of the Op’s own approval.quorum (#4324). One rule or a list, each { targets?, count, roles? } as in Approval Rules: count distinct people, roles read from .chant/trust.json at base, targets globs over the run’s environment. notAuthor is refused with declaration-invalid, since an Op gate has no author to judge by. Absent, the Op’s own quorum applies. A chant older than 0.124.47 refuses the field, so set minReader to at least that version when you use it. |
gates.<gate>.policy, .mode, .context | The rest of an Op gate’s approval block, read at base the way quorum is (#4404). policy is the policy set object the owning lexicon’s helper renders (the cedar lexicon’s gatePolicy()): kind, lexicon, name, version (the digest of text) and text. mode is log-only or enforce. context is an object of strings, numbers, booleans and lists of strings. Each replaces the Op’s field. A context key here wins over the Op’s, and a key only the Op sets, such as a step output the run computes, still reaches the policy. A field this entry leaves out is read from the Op, which the change being run can edit, and WSP153 names the gates that still rely on that. A chant older than 0.124.49 refuses the fields, so set minReader to at least that version when you use them. |
Both are read from the declaration at base, so a change can’t loosen its own rule. A run reads a gate’s quorum, policy, mode and context at base too (packages/core/src/op/local-executor.ts:768, called with the rule at base from :833). A pull request that lowers the quorum in its Op or in this file still needs the quorum on the base branch. A run, chant workspace status and chant approve all apply gates. chant approve refuses an approval the rule would not count before writing it, and a run or status leaves out any such approval already on the ledger, so a hud invite link alone can’t clear the gate. status --json marks such a gate with signed.
An approval for a gate under gates is made like this, in the member’s directory, with a key the signers file lists for github:alice:
chant approve web ship --env prod --plan <digest> --actor github:alice --sign ~/.ssh/id_ed25519The seal is an ssh signature in the chant-gate namespace over the op or component, the gate, the environment, the plan digest, the approver and the time, so it can’t be moved to another plan or gate.
An approval of a gate that resumes (Resuming at the approved gate, #3947) also carries the digest of the checkpoint its run stored. Its seal is version 2: the signature covers one more line, checkpoint <digest>, after the others, and the seal records version: 2. Changing or removing the digest then stops the seal verifying, so the step outputs a resumed run carries on with are the ones the approver signed for. An approval with no checkpoint digest is sealed as before.
Approvals signed outside chant
Section titled “Approvals signed outside chant”--sign needs the key on the machine running chant. A platform that collects the approval somewhere else, such as a phone with a passkey or a device key on another machine, has the person sign the same statement and hands chant the signature (#4646):
chant approve web ship --env prod --actor github:alice --statement > statement.json# the platform has github:alice sign the statement's bytes, then:chant approve web ship --env prod --actor github:alice --at <timestamp> --signature signature.json--statement runs the checks an approval runs, records nothing, and prints a chant-gate-statement/v1 document whose JSON Schema ships in the package as @intentius/chant/gate-statement.schema.json. Its text is the statement and statement is the same bytes in base64: the lines the seal above signs, joined by LF with no final newline.
<op or component><gate><environment, or empty><plan digest, or empty><approver><timestamp>relayed-by <principal> (only when --relayed-by is given)checkpoint <digest> (only when the gate resumes; seal version 2)binding <text> (only when --binding is given; seal version 3)The statement fixes the time, timestamp, which --at must repeat with the same --actor, --relayed-by, --plan, --env and --binding. A time before the gate’s pending fact or more than five minutes ahead is refused. digest is sha256: and the bytes’ SHA-256 in hex, and challenge is the same hash in base64url with no padding.
The platform can have the same signature cover something of its own with --binding <text> (#4697), such as the id of the deploy the approval is for and when the approval stops being good for it:
chant approve web ship --env prod --actor github:alice --binding "deploy dep_42 until 2026-11-01T12:00:00Z" --statement > statement.jsonchant approve web ship --env prod --actor github:alice --binding "deploy dep_42 until 2026-11-01T12:00:00Z" --at <timestamp> --signature signature.jsonThe statement then ends with binding <text>, after any checkpoint line, and the document’s binding holds the text. The seal is version 3 and records version: 3, and the resolution line keeps the text as binding. Changing or removing it stops the seal verifying, in a run, in chant workspace status, in @intentius/chant/gate-decision and in the seal check, as with every other line. Chant reads nothing in it: the binding is one line of printable text, at most 512 UTF-8 bytes, with no control, format or separator characters and no leading or trailing space, and anything else is refused before the statement is printed. Checking what it says, such as whether the deploy id matches or the time has passed, is the platform’s job. --sign takes --binding too and signs it the same way. An approval without a binding signs what it signed before and its seal stays version 1 or 2. Chant 0.124.64 and newer write and check a binding. An older chant leaves the line out of what it checks, so it finds a version 3 seal doesn’t verify and counts nothing for it.
--signature <file>, or - for stdin, takes either of these:
- An ssh signature over the bytes in the
chant-gatenamespace (ssh-keygen -Y sign -n chant-gate -f <key>), checked against the keys the signers file at base lists for--actor. A device key that is an ssh key, or a security key (sk-ssh-ed25519,sk-ecdsa-sha2-nistp256), signs this way. The seal recorded is the one--signwould have made. - A WebAuthn assertion from
navigator.credentials.getwithchallengeas its challenge, as JSON:{ "id", "clientDataJSON", "authenticatorData", "signature" }, each base64url, or aPublicKeyCredential’stoJSON()with the last three underresponse. It is checked against a passkey.chant/trust.jsonat base lists for--actor.
A passkey is listed under passkeys in .chant/trust.json:
{ "schema": 1, "passkeys": [ { "principal": "github:alice", "id": "<credential id, base64url>", "publicKey": "<DER SubjectPublicKeyInfo, base64url>", "rpId": "control.example.com", "origins": ["https://control.example.com"] } ]}publicKey is what AuthenticatorAttestationResponse.getPublicKey() returns at registration. Ed25519 (EdDSA), P-256 (ES256) and RSA (RS256) keys verify. The check follows WebAuthn level 2 for what a ledger line can be checked for. The client data’s type is webauthn.get, its challenge is the statement’s, its origin is one of origins, and it isn’t cross-origin. The authenticator data’s rpIdHash is SHA-256 of rpId, and its user-present and user-verified flags are both set. The signature over the authenticator data followed by SHA-256 of the client data verifies with publicKey. The signature counter isn’t checked. Listing a passkey is a change to the trust config, a protected write. As with ssh seals, nothing counts unless the signers file exists at base, so a workspace whose people sign only with passkeys keeps an empty one.
A signature that doesn’t verify for --actor is refused before anything is written, whether or not the gate is under gates. A passkey’s seal on the resolution line is { "kind": "webauthn", "signer", "key", "signature", "clientDataJSON", "authenticatorData" }, with the credential id as key, version: 2 when it signs a checkpoint and version: 3 when it signs a binding. An ssh seal has no kind. A run, chant workspace status, @intentius/chant/gate-decision and the seal check read either kind against the policy at base, so anyone can check the approval again offline. Chant 0.124.63 and newer write and read passkeys and passkey seals. An older chant reads a trust config with passkeys as invalid, which turns attestation off, and counts no passkey seal toward a gate.
A gate that lists an old name as an alias (Renaming a gate, #3949) counts an approval recorded under that name only when it passes the new gate’s identity.gates rule. The seal is checked against the op, gate, time and checkpoint digest it was signed under, which the carried line keeps in carriedFrom. A rename therefore doesn’t break a seal. chant build refuses a gate whose alias identity.gates names when the gate has no entry of its own, or lacks the alias’s class (OPS017).
ci.green says which commits passed CI (#3573, ws-103). chant ci tick tags each passing commit, and people and tools read the newest one from git with chant ci last-green, without asking the forge.
"ci": { "green": { "branch": "main", "window": "24h", "phases": { "lint": ["lint"], "build": ["build", "clippy"], "e2e": ["e2e (*)"], "macos": { "runs": ["macos (test)", "macos (webkit)"], "skipped": "pass" } }, "require": ["lint", "build", "e2e", "macos"] }}| Field | Required | Value |
|---|---|---|
branch | yes | The branch whose first-parent commits are tagged, or a list of branches (#4325). With a list, the tick judges each one, and the first is the trunk that readers and release cut use when they are not told a branch. List a branch that ci.branches routes members to, so it gets a green verdict and can release. A string reads as it always did. Older chant refuse a list, so set minReader with it. |
window | no | How far back a tick looks, by committer time, as minutes, hours or days such as 90m or 7d. The default is 24h. |
phases | yes | Phases by name. Each is a list of check-run name patterns, or { "runs": [...], "skipped": "pass", "build": "newest" }. In a pattern, * stands for any run of characters, and the pattern must match the whole name. build is every or newest, described below; read by chant 0.124.33 and newer, so set minReader with it. |
require | yes | The phases a commit must pass to be tagged green. Each must be declared under phases. |
preMerge | no | The phases that must pass before the branch moves, such as the quick checks a pull request runs (#4168). Each must be declared under phases. The trunk-curated workflow needs at least one. |
mergeQueue | no | true when the branch takes changes through GitHub’s merge queue (#4644): ci workflow adds merge_group to the phases’ workflows and writes chant-merge-queue.yml, whose chant-verdict job the ruleset requires. See a merge queue. Needs minReader 0.124.61 or newer. { "retries": <n> } in place of true (0 to 5) re-runs a failed job’s workflow run up to <n> times before the group fails (#4729); it needs minReader 0.124.70 or newer. |
notify | no | Who chant ci tick tells, as an Op waves spec’s notify (#4645): ci.red, ci.culprit and ci.green, each once; and ci.quarantine-passed from the quarantine’s scheduled run. Needs minReader 0.124.61 or newer. staleAfter, a number of hours, adds ci.stale when the branch has had no green commit that long, once per red stretch (#4678); it needs minReader 0.124.63 or newer. |
lanes | no | Green lanes by name (#4662), each { "require": [...] } naming declared phases. A commit that passes a lane’s phases gets ci/green-<lane>/<sha>, and a lane-green commit that later fails one gets ci/revoked-<lane>/<sha>, from the same tick and the same runs as require. A lane’s name is lowercase letters, digits and dashes. Needs minReader 0.124.61 or newer. |
quarantine | no | Known-flaky tests the phases’ runners leave out (#4677): { "maxDays": 14, "phases": { "<phase>": [{ "test", "file", "issue", "until", "why" }] } }. Each phase must be declared, until is the last day the test stays out (YYYY-MM-DD, UTC), and file is for a runner that names a test by its file and title, such as Playwright. chant ci quarantine filter prints each runner’s filter, chant ci quarantine report reads the scheduled run, and filter and chant ci quarantine check fail when an entry is past its until or more than maxDays (14 by default) out. See quarantine. Read by chant 0.124.63 and newer, so set minReader with it. |
signedSince | no | The full sha of the first commit on branch whose tags must be signed. A tag on it or on any commit that is not a strict first-parent ancestor of it counts only with a statement signed by a runner key; a tag on an ancestor counts unsigned. A sha that names no commit in the clone is refused with declaration-invalid. Absent, every tag counts. See signed tags. Read by chant 0.124.28 and newer, so set minReader with it. |
source | no | Where the tick reads each phase’s results: checks, the default, reads the forge’s check runs, and runs reads chant’s own Op runs on chant/lifecycle (#4044). With runs, a phase’s patterns match Op names, a run counts for the commit its record names as gitSha, and only a run signed by a runner key counts. See chant runs as the status source. Read by chant 0.124.28 and newer, so set minReader with it. |
With "source": "runs", read each check run below as the latest signed run of an Op the pattern matches, which passes when it ended ok. A phase passes when every check run its patterns match finished with success, judged by each run’s latest attempt. A run that finished as skipped passes only in a phase with "skipped": "pass", which suits a job that a path filter runs on some commits only. The default, fail, never lets a skipped run pass. A run still queued or in progress, or a pattern that no run matches yet, leaves the commit undecided. A run that was cancelled or went stale leaves its phase unbuilt, which is neither a pass nor a failure (#4169). A commit is green when every required phase passes, and it fails as soon as one of them fails.
A phase’s build says which commits it runs on (#4169). every, the default, runs it on each first-parent commit. newest runs it on the newest commit when a runner frees, so a merge does not have to start it. Under newest:
- A commit with no run of the phase, below a newer commit that has one, is unbuilt, covered by the newer commit.
- When the newest commit the phase ran on is red, the tick bisects the unbuilt commits back to the last one the phase passed on. It asks for one build per tick with a
ci/build/<sha>tag: the commit halfway when more than four are left, otherwise the one just below the red. The first red commit found is the culprit, and it and every commit after it name it. - Only a commit the phase ran on can go green, so a release is cut from a built commit.
chant ci run --at <sha>asks for a build of a commit you choose.
Under either value, a failed run is run again once before the commit counts red, and chant ci workflow writes the triggers and concurrency of the workflows holding a phase that sets build. A phase without build leaves its workflows as they are.
The result is kept as two kinds of annotated tag. chant makes each one once, and never moves or deletes either.
| Tag | Made when | Its annotation |
|---|---|---|
ci/green/<sha> | a commit passes every required phase | the time, and each required phase’s runs |
ci/revoked/<sha> | a commit with a green tag later fails a required phase, as a re-run that went red does | the phase, the run that failed, and the time |
A revoked commit doesn’t go green again by itself. Deleting its ci/revoked/<sha> tag by hand makes it count as green again, since its green tag is still there.
With signedSince, the annotation also holds the statement a runner key signed, and every reader ignores and reports a tag outside the ancestry of signedSince without a valid one (#4031).
The tick also keeps one record per commit it judges, _ci/<sha>.json on chant/lifecycle (#4169), so a commit with no tag still says what happened to it. It rewrites a record only when what it says changes.
| Field | Value |
|---|---|
state | green or red, following the tags and the failed phases, else unbuilt or pending |
phases | each required phase’s verdict, build and runs, with reason (cancelled, superseded, retrying, requested, request-unserved or aged-out), coveredBy for a superseded phase and culprit once a bisect finds one |
failure | the first required phase that failed, and its run |
retried | the runs asked to run again, so each is asked once |
request | the ci/build/<sha> tag waiting on the commit, and whether a workflow was started at it |
A commit that leaves the window still pending is rewritten unbuilt, for the reason aged-out. ci list and ci last-green show the records, and the release preflight says why each newer commit was passed over.
Report URL
Section titled “Report URL”ci.reportUrl says where the pull-request jobs copy their reports and events, and where chant ci run keeps the run index (#4160). A reader such as behold then finds the index at <reportUrl>/runs/index.json from the declaration, with no URL of its own to configure.
"ci": { "reportUrl": "s3://acme-chant-reports/prod"}The value takes the same forms as --report-url. Those are s3://<bucket>/<prefix>, gs://<bucket>/<prefix>, az://<account>/<container>/<prefix> and file://<directory>, with an absolute directory. Any other value, an https:// URL included, is refused with declaration-invalid at /ci/reportUrl, since no job can upload there. A trailing slash is dropped. chant build --pr-loop, chant ci run, chant ci serve and chant ci runs use it when --report-url is not given, and the flag wins when it is. chant workspace ls --json prints it as ci.reportUrl. The field can stand without green. Read by chant 0.124.32 and newer, so set minReader with it, and set it to 0.124.55 or newer when the value is a gs:// or az:// one (#4554).
Stage hooks
Section titled “Stage hooks”ci.hooks holds the stage hooks the pull-request jobs run (#4288). The shape is an Op waves spec’s hooks: before.observe, before.plan, after.plan, after.gate, before.apply and after.apply, each a list of { command, name?, onFailure?, perRun?, targets? }. A member’s own ci.hooks run after the top level’s. apply.runBy is refused with declaration-invalid at /ci/hooks (packages/core/src/workspace/declaration.ts:1201). The jobs read the block at base, as Hooks on Pull-Request Jobs describes. A declaration with ci.hooks needs chant 0.124.41 or newer to read it. The check list holds the hooks a product’s check job runs through chant ci check before any plan, where onFailure: "approve" and {plan} are refused (#4556), and a declaration that uses it sets minReader to 0.124.55 or newer.
Branches and labels
Section titled “Branches and labels”ci.branches maps a branch to globs over member names, and ci.labels maps a pull request label the same way (#4292). See route members to branches.
"ci": { "branches": { "release": ["prod-*"] }, "labels": { "plan:prod": ["prod-*"] }}| Field | Value |
|---|---|
branches | A member a branch’s globs match applies from that branch alone: its pull-request pipeline targets it, and its record and apply jobs plan nothing on a push to another branch. A member no glob matches applies from every branch the map leaves out. A member two branches match is refused with declaration-invalid. |
labels | When a pull request carries one of the labels, its plan jobs plan only the members those labels match. The record and apply jobs never read labels, so a label never gates. |
Each glob list holds at least one glob, and x- keys are ignored. chant 0.124.41 is the first reader of both fields; set minReader to it when you use one.
ci.locks says when a pull request takes its target locks (#4293). The locks live in _locks/<gate>.json on chant/lifecycle, under the member’s prefix in a workspace member.
"ci": { "locks": "plan"}| Value | Who takes the locks |
|---|---|
apply | the pull request’s apply, and chant lock by hand |
plan | the same, and a lock job that runs chant lock --stage plan after the plan job |
Under either value, chant components pr-apply refuses with locked when another open pull request holds a component it reaches, and applies nothing. A lock whose pull request merged or closed reads as released. With no ci.locks, pr-apply reads no locks. pr-apply takes the field from the declaration at base, so a pull request cannot turn its own locks off. Lock the Targets a Pull Request Reaches sets it up. chant reads the field from 0.124.41, so a declaration that sets it needs minReader 0.124.41 or newer.
Lock grain
Section titled “Lock grain”ci.lockGrain says what one apply holds while it applies (#4552). It sits beside ci.locks at the top level of ci, and a member may set its own in its ci block, which wins.
"ci": { "locks": "apply", "lockGrain": "resource"}| Value | What an apply holds |
|---|---|
target | The target’s own row where its lexicon names one: stack <project>/<stack> for stock Pulumi, root <root> for Terraform, tofu and Terragrunt. The apply waits for it in the ledger’s queue, oldest commit first, up to the job’s timeout (Two pushes at once). Elsewhere nothing of its own, and the engine’s lock keeps two applies of one target apart. Target locks name components. |
resource | A lease on one row per resource the plan changes, taken before anything applies and released when the apply ends. Under ci.locks, a pull request locks those row keys in place of its component names, so two pull requests that change different resources of one stack can both apply before merge. |
repo | One apply at a time in the repository. The apply waits in the queue for the repo row, which meets every other row. The pull-request pipeline also keeps it: one concurrency group on GitHub, one resource group on GitLab, and the lock tag refs/tags/chant-apply-lock on Forgejo. A waves file carries none of these. |
Absent, each member takes its lexicon’s default:
| Engine | Default | Row keys |
|---|---|---|
| choudoufu | resource | estate <estate> <address>, or root <root> <address> for a root with no estate; the same for a moved instance’s previous address; object <id> for anything but a create |
| plunge | resource | urn <urn> for each changed resource, the root stack’s URN included when its outputs change; object <id> for update, replace and delete; a single stack <project>/<stack> row in place of the URN rows when a component may register resources only at apply |
| Terraform, tofu, Terragrunt | target | root <root>, waited for; resource is refused by name |
| stock Pulumi | target | stack <project>/<stack>, waited for; resource is refused by name, since nothing in a stock stack’s state is per resource |
SQL (sql-migrate, sql-apply) | target | none: resource is refused by name, since an environment’s migrations apply in chain order under its own lock, a KeeperMap row on ClickHouse and a session advisory lock on Postgres |
One file per gate holds the rows for the whole workspace: _locks/rows/<gate>.json at the root of chant/lifecycle, never under a member’s prefix. Two members that act on one object therefore meet on its row. The format is the one terragucci’s apply rows used. A take is all or nothing. A holder may carry a beat, a time its run’s side process writes every CHANT_LOCK_BEAT seconds while it applies (#4660). Such a holder is judged by its beat alone: its rows are taken over once the beat is older than CHANT_LOCK_BEAT_STALE seconds (default 600), and never before. For a holder with no beat, when the forge says its run finished, its rows are taken over, and so are the rows of a lease older than CHANT_LOCK_STALE seconds (default 7200; terragucci’s TG_LOCK_STALE is read as an alias). A stack row and every urn row of that stack hold each other. On the resource grain a row another run holds stops the apply with exit 5 (held), naming that run. On the target and repo grains the apply waits in the file’s waiting list until the row is free and no older commit waits for it, and gives up with exit 5 (LockWaitTimeoutError) after CHANT_LOCK_WAIT seconds, which a waves job sets five minutes under its timeout.
Every apply takes the lease on this grain (#4594). chant components pr-apply and an op wave with a capability step lease the rows their plan already holds. chant run --components, chant components fan-out, promote, rollback and redeploy plan each step before it applies, lease that plan’s rows, then apply the plan they leased for. Components that plan and apply as one group lease every member’s rows in one take, and under --wave-gate a wave leases the rows of the plans its gate approved. A pull request environment’s apply leases as pr-apply does. A round that pr-apply plans after an upstream applies leases its own rows before it applies, and a held row stops that round with exit 5. All of these read the rows file of the pull-request loop’s gate, pr-apply, unless an op wave’s job passes another. An apply on merge and an apply before merge thus share one file. Outside a git work tree run, fan-out and promote take no lease, since no ledger is there to hold rows. Like ci.locks, the grain comes from the declaration at base, so a change cannot pick its own. A pulumi-up step that sets lockGrain takes that grain instead. ci.lockGrain needs a minReader of 0.124.55 or newer.
Policy
Section titled “Policy”ci.policy names the policy engine the pull-request jobs run over the change set (#4294). Its settings are those the table in Policy at the Gate lists. Any other key is refused with declaration-invalid at /ci/policy, and so are outcomes and allow_unattended, since no rule lets a plan apply with nobody approving it (packages/core/src/gate-policy.ts:293). The jobs read the block and the policy directory at base, as Policy at the Gate describes. A declaration that sets it needs a minReader of 0.124.41 or newer, since an older chant refuses it. The source and packs settings (#4613) need a minReader of 0.124.55 or newer (CI_POLICY_SOURCE_FLOOR). The install setting (#4774) needs a minReader of 0.124.77 or newer (POLICY_ENGINE_INSTALL_FLOOR).
Cloud identities
Section titled “Cloud identities”ci.identity.cloud gives the pull-request jobs a plan identity and an apply identity per cloud (#4296). See plan and apply as separate cloud identities.
"ci": { "identity": { "cloud": { "aws": { "rules": [{ "environments": ["prod"], "plan": "arn:aws:iam::111111111111:role/prod-plan", "apply": "arn:aws:iam::111111111111:role/prod-apply" }] } } }}| Key | What it holds |
|---|---|
aws | Its identities are role ARNs. It takes rules, and may set region (default us-east-1), audience (default sts.amazonaws.com) and an emulator’s endpoint. |
gcp | Its identities are service account emails. It takes provider, the workload identity provider’s name, and rules, and may set audience (default https://iam.googleapis.com/<provider>), stsEndpoint and iamEndpoint. |
azure | Its identities are client ids. It takes tenantId and rules, and may set subscriptionId, audience (default api://AzureADTokenExchange), authority, and database (#4572), which also trades for an Azure Database for PostgreSQL token in AZURE_DATABASE_ACCESS_TOKEN and needs a minReader of AZURE_DATABASE_TOKEN_FLOOR. |
pulumi | Pulumi Cloud access tokens (#4549). Its identities are team:<name>, user:<login>, organization or organization:admin. It takes organization and rules, and may set audience (default urn:pulumi:org:<organization>) and apiUrl (default https://api.pulumi.com). Needs a minReader of 0.124.55 or newer. See preview and up with separate Pulumi Cloud tokens. |
rules[] | Each rule has a plan and an apply identity and may set environments and members globs. The first rule that matches the pipeline’s environment and member wins. |
rules[].targets | Target globs inside the member, such as Terraform roots (#4332): * within one / segment, ** across segments, ? one character. A target takes the first rule that covers its environment, member and target. A Terraform root matches by its key in terraform.roots or by its directory relative to the project. The plan job trades for every plan identity the member’s targets take, and an Op wave applies in one job per apply identity. See give targets their own identities. |
rules[].name | The name of the apply job group the rule’s targets form, lowercase letters, digits, - and _. Default: from the first target glob. |
A rule that plans as an identity any rule applies as is refused with declaration-invalid at that rule (packages/core/src/workspace/declaration.ts:1257). Keys starting with x- are skipped, and a declaration that sets the block needs chant 0.124.41 or newer as its minReader, or 0.124.45 or newer when a rule sets targets or name.
Pull request environments
Section titled “Pull request environments”ci.prEnvironment gives each open pull request an environment, pr-<n>, derived from a template environment (#4298). See an environment per pull request.
"ci": { "prEnvironment": { "template": "staging", "ttl": "72h" }}| Field | Value |
|---|---|
template | The declared environment of the project that pr-<n> takes its endpoint from, unless a pr-* entry declares one. Required. |
ttl | How long the environment lives after its last apply, as 90m, 72h or 7d, and 72h when absent. chant components pr-env sweep tears down one whose TTL passed. |
teardown | A command that tears down what no lexicon does, such as a Terraform root’s copy (#4330). command is its argv, with {env}, {pr} and {stage} filled in. name labels its outcomes, teardown when absent. lexicons names the lexicons it tears down in place of. pr-env down and pr-env sweep run it after the ownership check, without the forge token variables. See tear down what no lexicon does. Needs minReader 0.124.45 or newer. |
The jobs take the block from the declaration at the pull request’s base, which keeps a change from naming its own template or TTL. Releases come from green commits, so a release never targets a pull request’s environment. A declaration that uses the block needs minReader set to 0.124.42 or newer, the first chant that reads it.
Retention
Section titled “Retention”retention sets how long chant lifecycle gc keeps each kind of stored record (#4036). A kind or field left out keeps its default. gc takes the block from the declaration at base, the way identity is taken.
"retention": { "changeSets": { "days": 30 }, "releases": { "days": 30, "keep": 20 }, "runEvents": { "days": 7, "keep": 50 }}| Kind | Where it is kept | days default | keep default |
|---|---|---|---|
changeSets | _change-sets/<digest>.json on chant/lifecycle | 14, counted from when it was stored or last named by a gate fact | does not apply |
releases | _releases/<digest>.json on chant/lifecycle, with the templates only they name | 14, counted from the newest cut | 10 per member |
runEvents | <git-common-dir>/chant/run-events/<run>.jsonl on each host | 14, counted from the last write | 100 |
days and keep are whole numbers from 0. A release is kept while it is promotable: cut within days, or among the newest keep releases of its member, and its commit has no ci/revoked tag. The policy never lets go of a release an environment runs, of what a pending gate binds, or of a change set a gate names with a kept release; What is never pruned lists the rules. The ledgers are never pruned. A declaration with retention sets minReader to 0.124.29 or newer.
Metrics
Section titled “Metrics”metrics sets how chant workspace metrics counts a failed deploy (#4039).
"metrics": { "failureWindowDays": 14 }failureWindowDays is the number of days after a deploy in which a revocation of the commit it deployed, or a rollback of the environment from it, counts the deploy as failed. It is a whole number from 1 to 365, and the default is 7. workspace metrics takes it from the declaration in the working tree. Older chant releases refuse the block, which is why its minReader floor is 0.124.29.
Workflow
Section titled “Workflow”ci.workflow names a prescribed delivery workflow, trunk-curated, trunk-curated+apply-on-merge or apply-before-merge (#4168, #4301). apply-before-merge is trunk-curated with one more path: a person may apply an open pull request’s plan from its head under its gate, once it is approved, mergeable, undiverged and green. It needs minReader 0.124.42 or newer, and Apply a Pull Request Before It Merges sets it up. At the top level it covers every member that builds with chant. A member’s own "ci": { "workflow": ... } wins over it. chant ci init writes it, and chant workspace check reports what a member under it still lacks as WSP151. The requirements are on CI Workflows.
Security
Section titled “Security”Every security feature is opt-in (#4168). With no security field, chant stays quiet about a feature the workspace has not turned on: no refusal and no warning. security lists groups, each turning on the features one use case needs. It goes at the top level, for every member, or on a member entry, for that member; a member runs under both lists.
"security": ["verified-releases", "supply-chain"]| Group | What it turns on |
|---|---|
verified-releases | chant release publish refuses a release none of whose cuts carries a signature that verifies against .chant/allowed_signers at base, unless --allow-unsigned, and chant components promote --release and rollback --release refuse a release chant release verify does not pass. |
supply-chain | A publish with no OIDC token warns on stderr, and a publish target with no SBOM source is refused with publish-sbom-missing. |
who-ran-it | chant ci tick refuses to run without a runner key, so every tag it makes is signed. |
review-rules | chant components pr-apply counts an approval only from someone who approved the pull request on the forge and never from its author, as --require-review does, and chant build --pr-loop writes the flag into the apply job. |
isolated-runners | chant ci run apply, and so chant ci serve, refuses to start without a provisioner’s runner-start statement for the job, as --require-runner-start does. chant build --pr-loop writes the flag into the apply job. |
Each feature also turns on alone: a release gate in identity.gates, --require-provenance, --require-review, --require-runner-start, ci.green.signedSince. A group is read at base, as the release gate is. Each name may appear once in a list, and an unknown name is refused. chant workspace check reports what a declared group still lacks as WSP161 to WSP165 warnings (security features). A chant older than 0.124.33 refuses security, so set minReader to at least that version when you use it.
Diagrams
Section titled “Diagrams”The declaration names the workspace’s diagram artifacts, so hud and other readers can list and draw them without guessing which file is a diagram’s source and which is its render, or which renderer made it (#2764). Studio’s docs/diagrams/*.d2 rendered by docs/diagrams/render.sh is the motivating case: a .d2 source beside the .svg render.sh writes, pinned to an exact D2 release and a fixed set of flags. Like record kinds, a diagram that belongs to no one member goes in the top-level diagrams, and a member names the ones it holds in its own diagrams. chant never runs the renderer, on any command (ws-052): it only records the pin, so a reader that has that renderer installed can reproduce the render, and chant workspace check can compare a content hash instead of re-rendering.
{ "name": "studio", "schema": 1, "minReader": "0.91.0", "members": [ { "name": "docs", "dir": "docs", "kind": "other", "because": "the docs site" } ], "diagrams": [ { "name": "architecture", "title": "Studio architecture", "source": "docs/diagrams/architecture.d2", "render": "docs/diagrams/architecture.svg", "renderer": { "tool": "d2", "version": "0.9.0", "args": ["--layout=elk", "--theme=0", "--pad=40", "--omit-version"] }, "sourceHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ]}| Field | Required | Value |
|---|---|---|
name | yes | The diagram’s name, in the name grammar. Unique across the declaration. |
title | yes | Shown above the diagram. |
source | no | The source file, from the workspace root, with / separators. Null, the default, for an SVG with no source. |
render | yes, except for mermaid and excalidraw | The rendered image, from the workspace root, with / separators. A mermaid or excalidraw diagram may leave it out or set it to null. |
renderer | yes | The renderer the render was made with: tool (d2, mermaid, graphviz or excalidraw), version (the exact release, such as "0.9.0") and args, the arguments passed before the input and output paths. For mermaid and excalidraw, version is the release of the library the reader draws with, such as "11.4.1". |
sourceHash | no | sha256 hex of the source’s bytes when the render was last produced from it. With it, chant workspace check fails (WSP133) when the source’s bytes now hash to something else: the render is stale for its source. Without it, or without a source, the render is never checked for drift. For a mermaid or excalidraw diagram with no render, it pins the source itself. |
mermaid and excalidraw diagrams are drawn by the reader. Each needs a source and may name no render: hud draws a .mmd source with the mermaid release renderer.version names, and opens an .excalidraw file (Excalidraw’s JSON scene format) as an editable canvas. An excalidraw entry may still name an exported SVG for pages that can’t draw the scene. For either tool, sourceHash pins the source itself. Declarations with a render-less entry need chant 0.96.0 or newer to read them, and should set minReader to match.
{ "name": "request-flow", "title": "Request flow", "source": "docs/diagrams/request-flow.mmd", "renderer": { "tool": "mermaid", "version": "11.4.1" }}{ "name": "whiteboard", "title": "Whiteboard", "source": "docs/diagrams/whiteboard.excalidraw", "renderer": { "tool": "excalidraw", "version": "0.18.0" }}Unlike a generated file or a record kind, a diagram’s source and render are workspace-root-relative wherever they are declared: a diagram’s files need not sit inside the directory of the member that declares it.
| Command | Uses the declared diagrams |
|---|---|
chant workspace ls | lists every one, flattened across the workspace and its members into one diagrams array, each with the member that declares it |
chant workspace check | fails with WSP131 when a named source doesn’t exist, WSP132 when a named render doesn’t exist, and, when the entry records a sourceHash, WSP133 when the source’s hash no longer matches it |
The example above sets minReader for that reason: without it, a chant older than 0.91.0 meets an unknown diagrams field and refuses the whole file, rather than naming the version gap with reader-too-old.
A box holds no credential (#2726). Each capability it needs from outside, such as inference, Fountain or a third-party API, goes through a broker. The broker is a runtime, such as a lobby or a door. It holds the real credential, swaps the box’s own token for it, and allows only what the declared scope allows. chant never runs a broker (ws-052). The declaration states the capabilities and their scopes, chant workspace check checks that the box holds no credential, and the broker reads the scopes from chant workspace status --json. What a broker answers for each capability, and the suite that checks one, is the broker protocol (#3164).
The member that holds the box’s declarations carries a box block:
{ "name": "chaff", "schema": 1, "minReader": "0.91.0", "members": [ { "name": "spec", "dir": "spec", "kind": "chant", "box": { "capabilities": [ { "name": "fountain", "broker": "lobby", "scope": ["agent", "vault", "conversations", "sandboxes"] }, { "name": "inference", "broker": "lobby", "scope": ["agent"] } ] } } ]}| Field | Required | Value |
|---|---|---|
capabilities | no | Each capability the box reaches outside itself. None when omitted. |
intent | no | The id of the decision record that says what the box is for. See Intent. |
services | no | The services the box runs under its supervisor. See Services. |
factory | no | What the box builds, how a build is checked, which member declares the builder agents and where a finished build is published. See Factory. |
listing | no | What the box shows of itself on a home site that lists boxes. See Listing. |
publisher | no | The command that publishes the box’s work, which an orchestrator such as studio supplies. See Publisher. |
ship | no | How the box ships its staged work to its own site: the Op, its gate, the environment it records releases in, and the bookkeeping paths. See Ship. |
capabilities[].name | yes | The capability, in the kind-name grammar, such as inference or fountain. A box names each capability once. |
capabilities[].broker | no | What brokers it, such as lobby or door. It may be a member of this workspace or a runtime outside it, as a planted box’s lobby is. Without it the capability is unbrokered, and chant workspace check fails with WSP122. |
capabilities[].scope | no | The parts of the box’s own that the broker lets it reach. The broker enforces the words, and chant records them. For Fountain these are agent (start conversations with its own agent), vault (attach its own vault), and conversations and sandboxes (its own). |
A box built from the fountain lexicon’s Box also declares { "name": "fountain-callback", "broker": "fountain", "scope": ["owner"] } (#2780). The pinned fountain spec gives a sandbox a callback token scoped to its owner unless the conversation asks for none (managoat/fountain#2497), and a Box runs with it. The entry records that token, so the declaration doesn’t claim a box with no credential while the machine holds one, and it sits beside any fountain capability a lobby brokers for the same box.
The block goes in the workspace declaration and not in the box’s TypeScript. check and status read the declaration without running member code, and a broker reads the read contract. A lexicon’s own box type, such as the fountain lexicon’s Box composite or chaff’s Box, keeps describing the machine. The declaration adds what the box may reach and through what.
| Command | Uses the box block |
|---|---|
chant workspace check | reads every file in the member’s directory and fails with WSP121 (box-credential-declared) on a literal secret. It fails with WSP122 (box-capability-unbrokered) on a capability that names no broker, and with WSP125 (box-fountain-callback-undeclared) when a member that builds a fountain Box doesn’t declare fountain-callback. It fails with WSP126 (box-intent-unknown) when the intent names no decision record, and warns with WSP127 (box-intent-unconstrained) when that record’s constrains names no member or path of this workspace at all |
chant workspace status --json | lists each member’s box, with every capability’s name, broker and scope, the box’s intent, its services, its factory, its listing, its publisher and its ship, and whether the workspace is plantable |
chant workspace graph --json | prints each member’s factory and listing as box, and plantable, read at the revision --at names |
Set minReader to "0.91.0" or newer when the file has a box block, so an older chant reports reader-too-old instead of an unknown field.
Intent
Section titled “Intent”A new box starts as a question, and its first answer is what the box is for (#2850). That answer is a decision record, so every reader of the box sees the same answer: the intent graph and hud as much as the runtime that plants it. The box block names the record’s id in intent, and chant looks for it among the records of every declared record kind named decision:
{ "name": "fern", "dir": "fern", "kind": "other", "because": "a box planted from a question", "box": { "intent": "box-001" }}The record starts proposed with a null choice. It holds the question and its options, and its constrains names member:fern. records new writes it from a JSON file of its fields:
chant workspace records new decisions/decision.kind.mjs --from box-001.json --prefix box --by alexThe person who answers the question decides the record with records amend. The fields given with --set set the choice, decided_by and decided_on, and move the state to decided:
echo '{ "state": "decided", "choice": { "option": "a", "reason": "A review queue for the design team." }, "decided_by": "sam", "decided_on": "2026-09-26" }' \ | chant workspace records amend box-001 --kind decisions/decision.kind.mjs --set -status --json reports the record under the member’s box.intent as { id, state, question, choice, answer, decided_by, decided_on, approved }, before and after it is decided. answer is the label of the options[] entry choice.option names, or null while none is chosen (#2855). approved says whether the state counts as decided, by the decision kind’s approval ranks, so a reader holds work on it without keeping its own list of states (#3609). check fails when no decision record has the id (WSP126), and warns when the record’s constrains names no member or path of this workspace at all: no member: entry for a declared member and no path: entry at, above or inside one’s directory (WSP127). The member it names need not be the box’s own: a box one member runs can be what a decision naming another member constrains, such as the app the box runs when the box block sits on the box’s steward (#2857). With the box’s own member constrained, graph --intent fern shows the decision for the box’s files. Set minReader to "0.94.0" or newer when a box block has an intent.
Services
Section titled “Services”A box runs its processes as services under a supervisor: sprite-env on a sprite, or a stand-in with the same command line elsewhere. The box block lists them in services (#2880), so a reader of status --json has them before anything observes the box, and the fly lexicon keeps them running from the same list:
{ "name": "box", "dir": "box", "kind": "other", "because": "the box's steward and its Ops", "box": { "services": [ { "name": "app", "cmd": "${HOME}/box/run-app.sh", "duration": "3s", "health": "http://127.0.0.1:5173/health" }, { "name": "door", "cmd": "${HOME}/box/run-door.sh", "needs": ["app"], "httpPort": 8080, "duration": "2s" }, { "name": "site", "cmd": "${HOME}/box/run-site.sh", "health": "http://127.0.0.1:3300/health", "optional": true } ] }}| Field | Required | Value |
|---|---|---|
services[].name | yes | The service’s name in the supervisor, in the kind-name grammar. A box names each service once. |
services[].cmd | yes | The command the supervisor runs. It is split on whitespace, with no quoting or other shell syntax: the first word is the executable (sprite-env services create --cmd) and the rest its arguments (--args, comma-separated, so an argument can’t hold a comma). Each ${VAR} in it is expanded from the environment of the process that applies the list, word by word, so the declaration holds no machine path. A command that needs a shell belongs in a script. |
services[].needs | no | Services of the same block that start first (--needs). |
services[].httpPort | no | The port the supervisor routes the sprite’s URL to (--http-port). One service of a box at most sets it. |
services[].duration | no | How long the service must stay up after a create or start, such as 3s (--duration). Without one, the create passes --no-stream and returns once the service is defined. |
services[].health | no | A URL that answers 200 while the service works. Without one, the supervisor’s state decides. |
services[].optional | no | true for a service something else creates by name, such as a site a release Op makes. An apply creates it only when its only names it, and an observer skips it while the supervisor has no such service. |
The services also follow rules the schema can’t state. Each needs entry names a service of the same block, and the needs form no cycle. A block gives each name once, and one service at most sets httpPort. A declaration that breaks one can’t be read (declaration-invalid), so check fails with WSP001.
The fly lexicon reads the list with box: true, from the box block of the member whose directory holds the working directory. spriteServicesObserve({ box: true }) observes the services for a ConvergeOp, spriteServiceRestart({ box: true }) restarts one and waits for its health, and spriteApplyServices({ box: true }) creates and replaces them through sprite-env services. A full apply (no only) also deletes each service the supervisor has that the block does not declare, so a service dropped from the list stops running; prune: false keeps them. chant reads services from 0.95.0 on, and a declaration that has them needs minReader of "0.95.0" or higher.
Factory
Section titled “Factory”A box’s factory turns a work item into a change: a builder agent edits the members the factory builds, a check gives the verdict, and a finished build is published as a pull request (#3146, ws-077). The factory block declares it, so any orchestrator, a studio or a fountain steward, reads the same facts from status --json:
{ "name": "steward", "dir": "steward", "kind": "chant", "box": { "services": [{ "name": "app", "cmd": "node ${HOME}/box/app/steward/preview.mjs" }], "factory": { "builds": ["studio"], "check": { "run": "npm run --silent check && npm test --silent", "kind": "test" }, "checks": "checks", "builders": "steward", "publish": { "repo": "arugula-salad/studio", "base": "main", "branchPrefix": "box/" } } }}| Field | Required | Value |
|---|---|---|
builds | yes | The members the factory builds, each a declared member of any kind: an app, a chant member, a Terraform estate. A work item a person asks for constrains member: and the first of them. |
check | no | The command whose exit code is a build’s verdict, run from the workspace root after the work item’s own checks: a string, or { "run", "kind" }. kind says what the command is, one of test, build, lint, plan and conformance, and is test for a string. |
checks | no | The directory, from the workspace root, where a builder writes the check for its work item. Without it the orchestrator chooses. |
builders | no | The member that declares the builder agents, such as the one whose agents/ holds them. |
tiers | no | Which builder agent builds at which tier: a list of { "tier", "agent", "kinds", "session" } (#3152, ws-094). See Builder tiers. Added in chant 0.103.0. |
publish | no | Where a finished build goes: { "repo", "base", "branchPrefix", "head", "forge" }. The branch <branchPrefix><work item id> is pushed and a pull request opened on repo (owner/name) against base, the repository’s default branch when omitted. branchPrefix is chant/work/ when omitted, the work lease’s own branch. head is a fork (owner/name) the branch is pushed to instead, so the pull request comes from <head owner>:<branch>; a runtime that publishes from each contributor’s own fork supplies that per contributor. forge is github. A template can’t name the repo of each box planted from it, so it leaves publish out, and whoever plants the box sets it with chant workspace box factory set (#3600). |
The factory is opt-in (#3174): a workspace with no factory is held to nothing here. It needs no box services and no app, so an infra workspace can declare one whose builds names its estate members and whose check is a plan, and run it on a fountain steward. There is one factory per declaration, and its builds and builders name only declared members; a second factory or an unknown name stops the read with declaration-invalid, which check reports as WSP001. What a build may not change goes in writeScope.agent.protected.
The reference workspace ships three profiles that show the opt-in at work: ideation declares records and a stub app with no factory, app declares the factory over an app member that runs as the box’s service, and infra declares a factory over an estate member with no app and no box services. chant workspace init --profile copies one.
Builder tiers
Section titled “Builder tiers”A work item has a tier, from its own tier field or the slice-tier decision point’s answer, in the vocabulary its work kind declares in work.tier.tiers (work items). The factory’s tiers say which agent builds each tier, so an orchestrator resolves the tier from the spec instead of from metadata only it reads, such as studio’s studio/role and studio/tier on its Agents (#3152).
"factory": { "builds": ["app", "network"], "builders": "delivery", "tiers": [ { "tier": "small", "agent": "builder-small" }, { "tier": "medium", "agent": "builder-medium" }, { "tier": "large", "agent": "builder-large" }, { "tier": "small", "agent": "infra-small", "kinds": ["terraform"], "session": "infra" } ]}| Field | Required | Value |
|---|---|---|
tier | yes | The tier, a word of the work kind’s work.tier.tiers. |
agent | yes | The builder agent’s name, as the builders member declares it, such as a fountain Agent in its agents/. |
kinds | no | The member kinds the agent builds at this tier, such as app or terraform. An entry without kinds builds the tier for every kind no other entry of the tier names. |
session | no | A declared agent session the builder writes as, so its write scope is that session’s. An infra builder bound to an estate member edits the estate and leaves applies to the gates. |
A tier has at most one entry without kinds and at most one per kind, tiers needs builders, and a session names a declared session; otherwise the read stops with declaration-invalid. For each member in builds and each tier, status --json prints the agent that builds it in builderFor. The entry for the member’s kind wins over the tier’s default.
Listing
Section titled “Listing”A box can show itself on a home site that lists boxes, with a title, a line and a cover picture. The listing is configuration of the box, so it lives in the declaration and a change to it is reviewed like any other (#3154, ws-074):
"box": { "listing": { "published": true, "title": "Fern", "line": "A garden planner for a small allotment", "cover": "box/cover.png" }}| Field | Required | Value |
|---|---|---|
published | no | Whether the box is listed. true when omitted: a box is listed unless its owner takes it out. |
title | no | One line of at most 60 characters. "" when omitted, and a reader then shows a name of its own. |
line | no | One line of at most 140 characters saying what the box is. "" when omitted. |
cover | no | A PNG, JPEG or WebP picture of the box, as a file from the workspace root. status and graph print its sha256, so a reader can cache it by hash. |
A title or line with a control character, such as a newline, can’t be read. Since factory and listing are new in chant 0.102.0, a box block with either needs minReader at "0.102.0" or later.
A tool such as hud changes the listing with chant workspace box listing set, which edits only these fields and copies a cover picture in, rather than editing the declaration itself (#3308).
Publisher
Section titled “Publisher”A box’s work leaves the box through its publisher. The publisher applies a built work item to the box’s checkout and opens a pull request on factory.publish’s repo when one is named. It also sends the records a person kept uncommitted. The orchestrator does that work, so the box block names the command it supplies (#3165, ws-088):
"box": { "publisher": "node box/ops/factory/publish.mjs"}chant splits the command into words as a shell splits plain words, where quotes group and a backslash escapes. No shell runs it, so $HOME and ~ reach the program as written. A surface calls chant workspace box publish rather than running the command. chant then runs it from the workspace root with a JSON request on stdin and checks the commit it made for the apply record of ws-075. status --json prints it under the member’s box, or null. A chant older than 0.103.0 refuses the field, so set minReader to "0.103.0" when you add it.
The people working on a box see its working tree at once, and everyone else sees the app as it was last shipped, until a person ships the staged work. ship names the Op in the box member that does it (ws-100):
"box": { "ship": { "op": "release", "gate": "ship", "env": "box", "bookkeeping": ["decisions", "work", "answers"] }}| Field | Required | Value |
|---|---|---|
op | yes | The Op in the box member that ships, as chant run takes it. Its own steps commit the staged tree as one commit by the person shipping, with a Chant-Record trailer for each work item it lands, then release that commit to the box’s site, stopping at gate, and record the release in env’s release ledger. |
gate | no | The gate the Op stops at for a person’s approval, which is ship when the field is left out. |
env | no | The environment whose release ledger, under the box member, the Op records each release in, which is box when the field is left out. |
bookkeeping | no | Path prefixes from the workspace root whose changes never count as waiting to ship, such as the record directories; with none, every change counts. |
chant runs none of those steps itself. A surface offers Ship when the field is set, and it runs chant run <op> in the member’s directory with the person’s principal in CHANT_SHIP_BY, and approves the gate as for any Op. chant workspace status --json prints it under the member’s box, with serving, the latest release in env’s ledger, and pending, the files that differ between that commit and the working tree, bookkeeping left out. A declaration that uses ship needs a minReader of "0.104.0" or later, because older readers refuse the field.
Replicate
Section titled “Replicate”Uncommitted records, work branches and kept attempts sit on a box’s disk until someone commits and pushes. replicate names where chant pushes it, so a box that is lost or reclaimed loses none of it (#3172, ws-085):
"box": { "replicate": { "remote": "mirror", "refs": ["work", "kept", "wip", "ledger"], "on": ["save", "release"], "every": "10m" }}| Field | Required | Value |
|---|---|---|
remote | no | The git remote to push to, by name. origin when omitted. A box holds no credential, so the host adds the remote, such as a bare mirror on the machine, with the credential it brokers. |
refs | no | What goes: work (the branches under chant/work/), kept (refs/chant/kept/...), wip (the snapshots under refs/chant/wip/<branch>, uncommitted records included) and ledger (chant/lifecycle). All four when omitted. |
on | no | When chant pushes on its own: save, after each chant workspace wip save, and release, after a work lease is released. Both when omitted. [] leaves every push to wip push. A record write never pushes, because chant’s record writes never run git. |
every | no | How often the host runs chant workspace wip push on a schedule of its own, such as 10m. chant runs no scheduler. |
At most one box block declares replicate, since a checkout’s work in progress goes to one remote. chant pushes each ref under its own name and never forces a push. status --json prints the policy under the member’s box, and its top-level replication says how far each ref is from the remote. replicate is read from chant 0.103.0 on, so minReader must be at least "0.103.0" where it is used.
Plantable
Section titled “Plantable”A host that plants a repo as a box, such as a studio’s planter, needs exactly one box to run. status --json and graph --json say whether the workspace is plantable: exactly one member’s box block declares services. plantable.box names that member, and plantable.reason says why not otherwise: box-none or box-several. Being plantable isn’t a check. A records-only workspace, or an infra workspace with a factory and no box services, is a valid workspace that a planter declines.
Isolation
Section titled “Isolation”Several boxes on one machine can collide on ports, state paths and cookies. When two boxes keep hud’s identity in one file, they share one owner (arugula-salad/studio#39). A browser scopes a cookie to a host and not to a port. So when two boxes set one cookie name on one hostname, signing into one signs you out of the other. The box block states the box’s isolation, and chant derives the values from the box’s identity (#2727). A runtime that plants or starts boxes reads them from chant workspace status --json instead of choosing its own.
{ "name": "lobby", "schema": 1, "minReader": "0.91.0", "hosts": [ { "name": "local", "ports": { "from": 7100, "to": 7999, "perBox": 20 } } ], "members": [ { "name": "fern", "dir": "boxes/fern", "kind": "chant", "box": { "host": "local", "slot": 0, "ports": { "app": 0, "door": 1, "proxy": 2, "inject": 3 }, "state": { "HUD_IDENTITY_PATH": "hud/identity.json", "HUD_DB_PATH": "hud/events.db" }, "cookies": ["hud_session", "chaff_door"], "capabilities": [{ "name": "inference", "broker": "lobby", "scope": ["agent"] }] } }, { "name": "moss", "dir": "boxes/moss", "kind": "chant", "box": { "host": "local", "slot": 1, "ports": { "app": 0, "door": 1 } } } ]}A host is one machine reached under one hostname. Everything a box could collide on belongs to its host, so chant workspace check compares boxes with the other boxes on their host and never across hosts. A box that runs on a machine of its own, such as a Fountain sandbox, is the only box on its host.
| Host field | Required | Value |
|---|---|---|
name | yes | The host’s name, in the name grammar, unique among hosts. |
ports | yes | { "from", "to", "perBox" }: the range boxes on the host take their ports from, inclusive, and the size of each box’s block. |
stateRoot | no | Where boxes on the host keep state, starting with an environment reference that the runtime expands on the machine. The default is ${XDG_STATE_HOME}/chant/boxes. |
| Box block field | Required | Value |
|---|---|---|
host | with slot | The host the box runs on, one of hosts. A block without it declares no isolation. |
slot | with host | The box’s number on its host, from 0. Its ports come from the slot’s block. |
ports | no | Each port the box listens on, as a name and its offset in the block, from 0 to perBox - 1. |
state | no | State the box keeps outside its checkout, as a name and a path relative to the box’s state directory. The name is usually the environment variable the runtime sets, such as HUD_IDENTITY_PATH. |
cookies | no | The session cookie names the box’s runtimes set, such as hud_session. |
ports, state and cookies need a host. A box’s identity is its host, the member’s name and its slot. The values follow from those and the host’s declaration, and from nothing else:
| Value | Derived as | fern above |
|---|---|---|
| port block | from + slot * perBox to from + (slot + 1) * perBox - 1 | 7100 to 7119 |
port p | the block’s first port plus p’s offset | door is 7101 |
| state directory | <stateRoot>/<member name> | ${XDG_STATE_HOME}/chant/boxes/fern |
| state entry | the state directory, then the entry’s path | HUD_IDENTITY_PATH is ${XDG_STATE_HOME}/chant/boxes/fern/hud/identity.json |
cookie c | <c>_<member name> | hud_session_fern |
The same declaration gives the same values on every machine. Adding a box changes no other box’s values, and neither does removing or moving one. chant leaves the environment reference in a state path for the runtime to expand. It never reads the machine, and it listens on no port. Distinct names give distinct state paths and cookie names, since a member name has no _, so ports are the value two boxes can share by mistake: two boxes on a host with one slot.
Some mistakes stop the read with declaration-invalid. A box may only name a declared host, and its slot’s block has to end at or before the host’s to. Each offset is below perBox, and a host name is used once. chant workspace check then reports what the boxes resolve to:
| Id | Code | Fails when |
|---|---|---|
WSP123 | box-isolation-collision | two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset. Two state entries in one box may name one file, as hud and a door that reads hud’s identity do |
WSP124 | box-isolation-literal | a host’s stateRoot is a literal machine path, such as /Users/..., ~/... or anything under $HOME, or a box’s state entry is absolute, starts with ~ or an environment reference, or has a .. segment |
Both are fixed errors, and each finding carries its code.
Example groups
Section titled “Example groups”An entry with "kind": "examples" is an example group (ws-051). It covers projects that exist as examples or test fixtures in one line.
| Field | Required | Value |
|---|---|---|
name | yes | The group’s name, in the name grammar. |
kind | yes | examples |
glob | yes | A glob, or an array of globs, over directories relative to the workspace root |
suppress | no | Declaration checks turned off for this group, as for a member |
Each directory a glob matches that holds a chant project is built and linted by the workspace commands. A match holds a project when a chant.config.ts or chant.config.json sits in it or up to four levels below it, or when its own package.json depends on @intentius/chant or a chant lexicon. Matches that hold none are left alone.
A group has no ledger, no releases and no links, and its matches are never members of their own. A match may sit inside a member’s directory, as lexicons/aws/examples/lambda-api sits inside the lexicon-aws member. That member’s build and lint then leave the match to the group.
| Glob syntax | Matches |
|---|---|
*, ? | within one path segment |
** | any number of directories |
[...] | one character from a set |
A wildcard never enters node_modules or a directory whose name starts with ..
Generated files
Section titled “Generated files”A member lists the files a command writes in its generated array (#2541, D14 of #2524). Each entry names the file, the command that regenerates it and, optionally, what the command reads. chant workspace check fails when a listed file differs from what its generator writes, and the lineage lock classes the same files generated.
{ "name": "api", "dir": "services/api", "kind": "chant", "generated": [ { "path": "ci/pipeline.yml", "generator": "chant build ci --lexicon github -o ci/pipeline.yml", "sources": ["services/api/src/pipeline.ts"] }, { "path": "skills/chant-aws/SKILL.md", "generator": "chant update", "handWritten": { "because": "we trim the skill for this service" } } ]}| Field | Required | Value |
|---|---|---|
path | yes | The file, relative to the member’s directory. It may not sit inside another member’s directory, and a member lists a path once. |
generator | yes | The command line that writes the file. It runs in the member’s directory with no shell, so pipes and redirections are refused. |
sources | no | Files or directories the generator reads, relative to the workspace root, since a generator often reads other members. Each must exist. |
handWritten | no | { "because": "..." } marks a file kept by hand. The check reports it with the reason and never runs its generator, and the lock classes it owned. |
When the generator passes -o or --output with the entry’s path, the check points that flag at a temporary file. Otherwise the generator writes in place, and the check puts the git working tree back afterwards.
chant registers some files without an entry. The files chant update rewrites are implicit generated entries of every chant member, and an entry for the same path takes their place, which is how a member keeps a skill by hand.
| File | Class |
|---|---|
skills/*/SKILL.md | generated, by chant update |
.mcp.json | seed, written once at init |
.chant/types/ | ignored, since it is gitignored |
Root CI files that forges read from fixed paths, such as .github/workflows/, sit outside the member that generates them. Their exemption comes with #2542 (ws-042). Until then an entry’s path stays inside its member.
The workspace, its members and its groups are all named the same way.
| Rule | Detail |
|---|---|
| Grammar | ^[a-z0-9][a-z0-9-]{0,39}$, for member names, group names and the workspace name |
| Unique | across every entry in members, members and groups together |
| Reserved | _workspace and _members, which ledger paths use; the grammar already rules them out |
Placement
Section titled “Placement”These rules keep every directory owned by one entry at most.
| Rule | Error |
|---|---|
A dir or glob stays inside the workspace: no leading /, no . or .. segments, no \ | declaration-invalid |
| No two members share a directory | placement-invalid |
Only the root member "." contains other members | placement-invalid |
| A group match is never a member’s directory and never contains one | placement-invalid |
A group match never sits inside a nested workspace member | placement-invalid |
| No two groups match the same directory | placement-invalid |
The last three depend on what the globs match, so they are checked when the groups are expanded, on every chant workspace ls.
A pin names the toolchain or a plugin that reads the workspace.
| Shape | Fields |
|---|---|
| an npm package | package and version (an exact version), optional integrity |
| a local plugin | path inside the workspace, optional integrity |
A pin of @intentius/chant names the root’s chant, which is the chant that reads the declaration (which chant reads it). The workspace commands of any other chant version hand themselves to it when it is installed at the root, and refuse with root-chant-required when it isn’t.
integrity is a Subresource Integrity digest such as sha256-.... chant records pins and lists them in chant workspace ls --json. Member kinds come only from pinned packages, which chant reads as data and never imports (Workspace Kinds).
Integrity of a plugin pinned by path
Section titled “Integrity of a plugin pinned by path”A path pin with integrity is checked whenever chant loads kinds from it: the directory’s content hash must equal integrity, or chant reads nothing from the plugin, and chant workspace check reports WSP002 on the pin with the value it expected and the one it computed (ws-065). chant workspace pin <path> prints the value to put there. A pin with no integrity is not checked.
| Covered | Left out |
|---|---|
| every regular file under the directory, at any depth, by its bytes and its path from the directory | anything inside a node_modules or .git directory |
The value is sha256-, sha384- or sha512- and the base64 of that algorithm over a manifest with one line per file, <hex digest of the file> <path>, sorted by path. A file path is hashed by its bytes. A symbolic link inside the directory makes the check fail, since it can point outside the plugin. The hash is of the working tree, so build output or untracked files inside the directory change it: pin a directory that holds only committed files.
The check covers kinds read from a path pin. It doesn’t cover a package pin’s integrity, which names a registry tarball and is still not recomputed, or the record kind files named in records, which have no integrity field. The declaration is read from the working tree, so a change that edits a plugin and its pin together passes: the pin guards a plugin edited on its own.
Ledgers
Section titled “Ledgers”chant records each lifecycle fact on the orphan branch chant/lifecycle, and keeps operator leases in refs beside it. A member writes all of them under its own directory on that one branch (#2538, #2524 D7). In the table, <ledger> is the top of the branch for a project with no declaration, and _members/<member>/ for a member. The paths are chant’s storage rather than a contract, so read the facts with the CLI.
| Store | Path |
|---|---|
| Release records | <ledger><env>/releases.jsonl |
| Release status (deprecated, yanked, restored) | <ledger><env>/release-status.jsonl (#4596) |
| State snapshots | <ledger><env>/<lexicon>.json, with a <stack>__ prefix for a project with several stacks |
| Accepted observation baseline | <ledger><env>/observation-baseline.json |
| Op run records | <ledger><env>/runs__<op>.jsonl |
| Converge tick records | <ledger><env>/converge.jsonl |
| Gate facts, pending and resolved | <ledger>_gates/<op>.jsonl |
| Each apply that ran under an approval, and how it ended | <ledger>_gates/<op>/applied.jsonl |
| The attachment a gated request carries, such as a migration’s proof | <ledger>_gates/<op>/requests/<digest>.json (#4551) |
| One record for each environment a pull request has opened | <ledger>_pr-envs/records.jsonl |
| Build manifests | <ledger>_builds/<digest>.json |
| Stored change sets | <ledger>_change-sets/<digest>.json, pruned by retention |
| Releases, their cuts and template bytes | <ledger>_releases/<digest>.json, <ledger>_releases/cuts.jsonl and <ledger>_releases/templates/<digest>.txt; the release files and templates are pruned by retention |
| Operator leases | the ref refs/chant/lease/<ledger><op> |
chant looks up from a project’s directory to the git root for a declaration. The entry that owns the directory decides the ledger.
| The project is | Its ledger |
|---|---|
| a project with no declaration above it (level 0) | the top of the branch, byte for byte as before |
the root member ".", or a directory no member owns | the top of the branch |
| a match of an example group, since a group has no ledger | the top of the branch |
| any other member | _members/<member>/ |
a member of a nested workspace held by the outer member platform | _members/platform/_members/<member>/ |
A project with no declaration loads no workspace code for this lookup. When a declaration exists but can’t be read, a ledger write fails with the read error instead of guessing the member. There is still one branch, so pushing it and refusing a stale push work as before. One commit can write the ledgers of several members.
A run started with chant run --no-record, or with CHANT_NO_RECORD=1 in its environment, writes none of these (#3955). Its writes build commits in memory that the process drops when it ends. The branch ref doesn’t move and nothing is pushed to the remote, so a lease ref stays in the checkout. Reads in the same process see the run’s own writes, and a gate step fails because no approval can be recorded or spent. The chant run reference has the details.
The branch is fetched from and pushed to origin, or the first remote when there is no origin. Set CHANT_LIFECYCLE_REMOTE=<name> to use another remote, for a checkout whose origin is not where the ledger lives (#4647). Every read and write of the ledger uses it: the fetch, the push and the retry after a refused push, the remote-tracking ref refs/remotes/<name>/chant/lifecycle that the push’s lease reads, and the lease, lock and snapshot refs pushed beside the branch. A name the repository has no remote by fails the fetch and the push with a message naming it; chant never falls back to origin for it. An empty value counts as unset. --no-record is unchanged and pushes nothing anywhere.
Receipts written by an effect() step are not on the branch. They live wherever the lexicon stores them, named by ownership.stack and environment, so distinct stacks keep members’ receipts apart.
Declaring a project as a member changes where it writes from then on. chant does not copy the records the project already wrote at the top of the branch. A project with history that becomes the root member "." keeps reading it.
The first chant that writes member paths is 0.81.0. A member whose own toolchain resolves an older chant keeps writing the top of the branch. Two checks cover this, and chant workspace check reports them. Neither can be turned down or suppressed.
| Id | Fails when |
|---|---|
WSP071 | two chant members set the same ownership.stack. Markers carry no member name, so the stack keeps members’ resources apart. A member with no stack stamps no marker and isn’t compared. chant workspace init proposes a distinct stack for each member |
WSP072 | two members that write the top of the branch share an environment name, taken from environments and a literal ownership.env. The root member writes there, and so does a member on a chant older than 0.81.0 |
Errors
Section titled “Errors”A declaration that can’t be read is never treated as empty. Every error names the file, and a parse or schema error names its line and column.
declaration-invalid: chant.workspace.json:9:7: unknown field "dependsOn"; only fields named x-... may be added| Code | Cause |
|---|---|
declaration-missing | no declaration between the directory and the git root |
declaration-ambiguous | both chant.workspace.json and chant.workspace.jsonc exist |
declaration-unparseable | not valid JSON, or not valid JSONC for .jsonc |
declaration-invalid | doesn’t match the schema, or repeats a name |
placement-invalid | breaks a placement rule |
reader-too-old | minReader is newer than this chant |
root-chant-required | the declaration pins another chant, which isn’t installed at the root |
chant workspace ls --json reports the same codes with the location (Output). Every code is in the closed list of the read contract.