Skip to content

Commit ea58cda

Browse files
myobiemyobie
authored
docs(vrs): add source-linked language index (#68)
* docs(vrs): add source-linked language index * docs(vrs): refresh ontology proof links
1 parent 853b90b commit ea58cda

1 file changed

Lines changed: 158 additions & 0 deletions

File tree

‎docs/vrs/ontology.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# st2 language
2+
3+
This is a small disambiguation index, not a behavioral specification. Each
4+
canonical term links to the source that owns its meaning. Follow that source
5+
for behavior, lifecycle, ordering, and wire or file formats.
6+
7+
st2 inherits agent-authoring language from the
8+
[canonical Agent Spec](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification).
9+
Terms without an independent authority are deliberately absent.
10+
11+
## Canonical language
12+
13+
### agent
14+
15+
The actor st2 models.
16+
17+
Authority: [Agent Spec overview](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification);
18+
[R10 agent-only identity](requirements.md#L98-L99)
19+
20+
### agent declaration
21+
22+
The authored KDL representation of one agent.
23+
24+
Authority: [Agent Spec discovery and declaration shape](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host);
25+
[R02 canonical KDL](requirements.md#L36-L45)
26+
27+
### agent runtime
28+
29+
A running instance of an agent declaration.
30+
31+
Authority: [declared runtime vision](vision.md#L16-L26);
32+
[`AgentSpec` runtime model](../../crates/agent-spec/src/spec.rs#L24-L50)
33+
34+
### agent task
35+
36+
A terminal-backed or terminal-free unit declared for an agent.
37+
38+
Authority: [Agent Spec task contract](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#compact-and-explicit-tasks);
39+
[`Task`](../../crates/agent-spec/src/spec.rs#L121-L148)
40+
41+
### agent identity
42+
43+
The bare `identity` value of an agent declaration. It is not a claim of
44+
fleet-wide uniqueness.
45+
46+
Authority: [`AgentSpec::identity`](../../crates/agent-spec/src/spec.rs#L24-L50);
47+
[Agent Spec identity rules](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host)
48+
49+
### bus ID
50+
51+
The host-qualified agent address `<host>.<identity>`.
52+
53+
Authority: [`AgentSpec::bus_id`](../../crates/agent-spec/src/spec.rs#L203-L211);
54+
[Agent Spec bus identity](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host)
55+
56+
### catalog
57+
58+
The selected folder containing agent declarations and catalog-backed state.
59+
60+
Authority: [Agent Spec catalog boundary](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#discovery-identity-and-host);
61+
[catalog selection](../../src/main.rs#L867-L927)
62+
63+
### catalog root
64+
65+
The filesystem path selected as the catalog for a command.
66+
67+
Authority: [catalog path resolution](../../src/main.rs#L867-L927)
68+
69+
### root agent
70+
71+
The agent assigned host-local health observation, recovery, and escalation.
72+
73+
Authority: [R04 root supervision](requirements.md#L51-L54);
74+
[vision](vision.md#L21-L22)
75+
76+
### control plane
77+
78+
The replaceable `st2 up` process that reconciles host-local work.
79+
80+
Authority: [R11 control-plane replacement safety](requirements.md#L83-L88);
81+
[`up_loop`](../../src/run.rs#L1440-L1452)
82+
83+
### declared supervisor
84+
85+
The agent reference carried by a declaration for supervisory routing.
86+
87+
Authority: [`AgentSpec::supervisor`](../../crates/agent-spec/src/spec.rs#L24-L50);
88+
[Agent Spec field](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#complete-declaration-shape)
89+
90+
### presence
91+
92+
The agent-authored availability signal read from catalog-backed state.
93+
94+
Authority: [`status::State`](../../src/status.rs#L24-L45);
95+
[R08 catalog observability](requirements.md#L92-L95)
96+
97+
### session state
98+
99+
st2's runtime observation of whether a task record is alive.
100+
101+
Authority: [`reconcile::Session`](../../src/reconcile.rs#L16-L26)
102+
103+
### reconciliation
104+
105+
Comparing declared host-local work with observed runtime state to produce a
106+
plan.
107+
108+
Authority: [`reconcile`](../../src/reconcile.rs#L1-L10);
109+
[reconcile pass](../../src/run.rs#L1007-L1017)
110+
111+
### materialization
112+
113+
Rendering catalog-declared content into an agent workspace.
114+
115+
Authority: [`materialize_catalog`](../../src/materialize.rs#L837-L850)
116+
117+
### message
118+
119+
A durable addressed record in an agent inbox or archive.
120+
121+
Authority: [`message::Message`](../../src/message.rs#L26-L46)
122+
123+
### DING
124+
125+
The terminal notification that makes an agent aware of unread messages.
126+
127+
Authority: [DING module contract](../../src/ding/mod.rs#L1-L14)
128+
129+
## Collision rules
130+
131+
- Qualify **root** as [root agent](requirements.md#L51-L54) or
132+
[catalog root](../../src/main.rs#L867-L927). Bare *root* does not identify
133+
which concept is meant.
134+
- Qualify **supervisor** as [control plane](requirements.md#L83-L88) or
135+
[declared supervisor](../../crates/agent-spec/src/spec.rs#L24-L50).
136+
- Use [presence](../../src/status.rs#L24-L45) for the agent-authored signal and
137+
[session state](../../src/reconcile.rs#L16-L26) for runtime liveness. Avoid
138+
bare *agent status* when either could be meant.
139+
- Use [agent identity](../../crates/agent-spec/src/spec.rs#L24-L50) for the bare
140+
value and [bus ID](../../crates/agent-spec/src/spec.rs#L203-L211) for the
141+
host-qualified address.
142+
- Use [message](../../src/message.rs#L26-L46) for the durable record and
143+
[DING](../../src/ding/mod.rs#L1-L14) for its terminal notification.
144+
145+
## Avoid
146+
147+
**seat** is not canonical st2 language. Choose by meaning: [agent](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#canonical-agent-specification)
148+
for the actor, [agent declaration](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#complete-declaration-shape)
149+
for the catalog entry, and [agent runtime](vision.md#L16-L24) for a running
150+
instance. For admission, use an already-authoritative admission term only if
151+
one exists; this index does not canonize one.
152+
153+
The rejected word remains visible as design leakage in
154+
[issue #52](https://github.com/compoundingtech/st2/issues/52),
155+
[draft PR #55](https://github.com/compoundingtech/st2/pull/55), and one
156+
[Agent Spec phrase](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md#free-authoring-gate).
157+
Those references are evidence of recurrence, not authorities for a new st2
158+
concept.

0 commit comments

Comments
 (0)