diff --git a/docs/vrs/ontology.md b/docs/vrs/ontology.md new file mode 100644 index 0000000..08f1476 --- /dev/null +++ b/docs/vrs/ontology.md @@ -0,0 +1,158 @@ +# st2 language + +This is a small disambiguation index, not a behavioral specification. Each +canonical term links to the source that owns its meaning. Follow that source +for behavior, lifecycle, ordering, and wire or file formats. + +st2 inherits agent-authoring language from the +[canonical Agent Spec](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification). +Terms without an independent authority are deliberately absent. + +## Canonical language + +### agent + +The actor st2 models. + +Authority: [Agent Spec overview](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification); +[R10 agent-only identity](requirements.md#L98-L99) + +### agent declaration + +The authored KDL representation of one agent. + +Authority: [Agent Spec discovery and declaration shape](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host); +[R02 canonical KDL](requirements.md#L36-L45) + +### agent runtime + +A running instance of an agent declaration. + +Authority: [declared runtime vision](vision.md#L16-L26); +[`AgentSpec` runtime model](../../crates/agent-spec/src/spec.rs#L24-L50) + +### agent task + +A terminal-backed or terminal-free unit declared for an agent. + +Authority: [Agent Spec task contract](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#compact-and-explicit-tasks); +[`Task`](../../crates/agent-spec/src/spec.rs#L121-L148) + +### agent identity + +The bare `identity` value of an agent declaration. It is not a claim of +fleet-wide uniqueness. + +Authority: [`AgentSpec::identity`](../../crates/agent-spec/src/spec.rs#L24-L50); +[Agent Spec identity rules](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host) + +### bus ID + +The host-qualified agent address `.`. + +Authority: [`AgentSpec::bus_id`](../../crates/agent-spec/src/spec.rs#L203-L211); +[Agent Spec bus identity](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host) + +### catalog + +The selected folder containing agent declarations and catalog-backed state. + +Authority: [Agent Spec catalog boundary](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host); +[catalog selection](../../src/main.rs#L867-L927) + +### catalog root + +The filesystem path selected as the catalog for a command. + +Authority: [catalog path resolution](../../src/main.rs#L867-L927) + +### root agent + +The agent assigned host-local health observation, recovery, and escalation. + +Authority: [R04 root supervision](requirements.md#L51-L54); +[vision](vision.md#L21-L22) + +### control plane + +The replaceable `st2 up` process that reconciles host-local work. + +Authority: [R11 control-plane replacement safety](requirements.md#L83-L88); +[`up_loop`](../../src/run.rs#L1440-L1452) + +### declared supervisor + +The agent reference carried by a declaration for supervisory routing. + +Authority: [`AgentSpec::supervisor`](../../crates/agent-spec/src/spec.rs#L24-L50); +[Agent Spec field](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#complete-declaration-shape) + +### presence + +The agent-authored availability signal read from catalog-backed state. + +Authority: [`status::State`](../../src/status.rs#L24-L45); +[R08 catalog observability](requirements.md#L92-L95) + +### session state + +st2's runtime observation of whether a task record is alive. + +Authority: [`reconcile::Session`](../../src/reconcile.rs#L16-L26) + +### reconciliation + +Comparing declared host-local work with observed runtime state to produce a +plan. + +Authority: [`reconcile`](../../src/reconcile.rs#L1-L10); +[reconcile pass](../../src/run.rs#L1007-L1017) + +### materialization + +Rendering catalog-declared content into an agent workspace. + +Authority: [`materialize_catalog`](../../src/materialize.rs#L837-L850) + +### message + +A durable addressed record in an agent inbox or archive. + +Authority: [`message::Message`](../../src/message.rs#L26-L46) + +### DING + +The terminal notification that makes an agent aware of unread messages. + +Authority: [DING module contract](../../src/ding/mod.rs#L1-L14) + +## Collision rules + +- Qualify **root** as [root agent](requirements.md#L51-L54) or + [catalog root](../../src/main.rs#L867-L927). Bare *root* does not identify + which concept is meant. +- Qualify **supervisor** as [control plane](requirements.md#L83-L88) or + [declared supervisor](../../crates/agent-spec/src/spec.rs#L24-L50). +- Use [presence](../../src/status.rs#L24-L45) for the agent-authored signal and + [session state](../../src/reconcile.rs#L16-L26) for runtime liveness. Avoid + bare *agent status* when either could be meant. +- Use [agent identity](../../crates/agent-spec/src/spec.rs#L24-L50) for the bare + value and [bus ID](../../crates/agent-spec/src/spec.rs#L203-L211) for the + host-qualified address. +- Use [message](../../src/message.rs#L26-L46) for the durable record and + [DING](../../src/ding/mod.rs#L1-L14) for its terminal notification. + +## Avoid + +**seat** is not canonical st2 language. Choose by meaning: [agent](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification) +for the actor, [agent declaration](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#complete-declaration-shape) +for the catalog entry, and [agent runtime](vision.md#L16-L24) for a running +instance. For admission, use an already-authoritative admission term only if +one exists; this index does not canonize one. + +The rejected word remains visible as design leakage in +[issue #52](https://github.com/compoundingtech/st2/issues/52), +[draft PR #55](https://github.com/compoundingtech/st2/pull/55), and one +[Agent Spec phrase](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#free-authoring-gate). +Those references are evidence of recurrence, not authorities for a new st2 +concept.