@alineo-labs/schema 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,4 +1,127 @@
1
- # Temporary Holding Version
1
+ # @alineo-labs/schema
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
4
- If no other versions are published within 30 days, this package and version will be deleted.
3
+ The shapes of the system: the ledger envelope, every event definition, and the vocabulary all
4
+ of alineo's surfaces derive their names from.
5
+
6
+ **Types and Zod schemas only — no behaviour, no IO.** What _does_ something with these shapes
7
+ lives in [`@alineo-labs/ledger`](../ledger). The split is why `@alineo-labs/memory` can stop
8
+ depending on the whole sandbox runtime just to borrow two types.
9
+
10
+ Two entry points:
11
+
12
+ | Import | Contains | For |
13
+ | --------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
14
+ | `@alineo-labs/schema/types` | types only, no Zod in the graph | a package with no validator dependency that wants none |
15
+ | `@alineo-labs/schema` | the above, plus the Zod schemas and the event registry | anything validating at a boundary |
16
+
17
+ ## The vocabulary
18
+
19
+ ```bash
20
+ bun add @alineo-labs/schema
21
+ ```
22
+
23
+ ```ts
24
+ import { SUBJECTS, VERBS, isSubject, isVerb, parseName } from "@alineo-labs/schema";
25
+
26
+ parseName("agent_spawn", "_"); // → { subject: "agent", verb: "spawn" }
27
+ parseName("alineod_create_run", "_"); // → null
28
+ ```
29
+
30
+ ### Why this exists
31
+
32
+ One person meets the CLI, the SDK, the daemon's HTTP API, the MCP tools and the event stream.
33
+ Each of those was free to pick its own spelling, and each did — which is how `spawn` came to mean
34
+ "create a root agent" in the CLI and "create a child" in the SDK, and how `fork` came to mean
35
+ three different operations.
36
+
37
+ A glossary nobody can fail is a suggestion. These two lists are **data**, so CI can fail a name
38
+ instead of a reviewer having to catch it.
39
+
40
+ ## The shape of a name
41
+
42
+ | Surface | Pattern | Example |
43
+ | ---------- | ----------------------------- | ------------------------------------ |
44
+ | CLI | `alineo <verb> [args]` | `alineo spawn <parent> <child-spec>` |
45
+ | SDK method | the verb | `Alineo.spawn()`, `sb.checkpoint()` |
46
+ | SDK class | the subject | `Sandbox`, `Alineo` |
47
+ | HTTP | `/{subjects}/:id/{verb}` | `POST /agents/:agentId/steer` |
48
+ | MCP tool | `{subject}_{verb}` | `agent_spawn`, `run_start` |
49
+ | Event | `{subject}.{past-tense verb}` | `agent.spawned` |
50
+
51
+ Subjects are singular here; only HTTP pluralizes its collection segment.
52
+
53
+ ## What this package is not
54
+
55
+ It holds **no** event definitions, no Zod schemas and no wire types — only the words those are
56
+ built out of. The checks that enforce the lists live with the surfaces they police, so that a
57
+ surface cannot ship a name without also shipping the thing that would reject it.
58
+
59
+ ## Two names that needed a decision
60
+
61
+ Both were flagged when this package was written and settled when the MCP check landed:
62
+
63
+ - **the tool that reads a settled agent's output** is `result_get`, not `agent_result`.
64
+ `result` is a noun, so it belongs in `SUBJECTS` — and `agent_get` was already taken by the
65
+ agent's own view. A run's records (`event`, `result`, `transcript`) were on the wire long
66
+ before they were written down here.
67
+ - **`init`** has no subject at all. It is named for the verb alone, exactly as `alineo init`
68
+ is on the CLI — so a bare verb is a legal tool name, not an exception to the pattern.
69
+
70
+ ## The envelope
71
+
72
+ One record shape an event takes, whichever layer emitted it:
73
+
74
+ ```ts
75
+ interface LedgerEnvelope<T, D> {
76
+ v: 1;
77
+ ts: number;
78
+ type: T; // "agent.spawned", "exec.completed"
79
+ runId?: string;
80
+ agentId?: string;
81
+ turnId?: string; // reserved; nothing generates turn ids yet
82
+ causedBy?: EventRef; // the decision this fact followed from
83
+ durable?: DurableRef; // { aggregate, seq, version } — present once persisted
84
+ data: D;
85
+ }
86
+ ```
87
+
88
+ Mostly a formalisation rather than an invention: alineod's ledger row is already five of these
89
+ eight fields. Before it, the same idea was written three ways — the SDK's `LedgerEntry`
90
+ (ordered by timestamp), alineod's row (ordered by `seq`), and the harness's bare
91
+ `{ type, ...fields }` stream — and a consumer reading one run end to end had to know all three.
92
+
93
+ **`seq` sits under `durable`, not at the top level.** A monotone sequence needs a single
94
+ writer for whatever it counts within, and there are two writers here in different processes.
95
+ So the writer assigns it at persist time, scoped to an aggregate: the run for alineod, the
96
+ sandbox session for the SDK.
97
+
98
+ ## Events
99
+
100
+ ```ts
101
+ import { defineEvent } from "@alineo-labs/schema";
102
+
103
+ export const AgentSpawned = defineEvent({
104
+ type: "agent.spawned",
105
+ durable: true,
106
+ version: 1,
107
+ schema: z.object({ agentId: z.string().nullable() /* … */ }),
108
+ });
109
+ ```
110
+
111
+ One definition, three readers: the writer checks `durable` to decide whether to persist, a
112
+ reader uses `schema` to validate, and CI uses `type`. `defineEvent` refuses a name that is not
113
+ `<subject>.<past_tense_verb>`, a subject outside `SUBJECTS`, or a type defined twice.
114
+
115
+ Events are namespaced **by subject, not by the layer that emits them** — `agent.spawned`, not
116
+ `alineod.agent_spawned`. Someone reading one mixed stream needs to know what an event is
117
+ _about_, not which process produced it.
118
+
119
+ That settles three collisions for free: `run_started` meant both a workflow run and a swarm run
120
+ (now `workflow.started` and `run.started`); `agent_start` meant both a harness session beginning
121
+ and an alineod agent's lifecycle (now `session.started` and `agent.spawned`); and three
122
+ checkpoint-ish events collapse to two, with `snapshot` folding into
123
+ `sandbox.checkpoint_created` because that is what it always recorded.
124
+
125
+ `renames.ts` maps the old flat names to the new ones. It is **dated and deletable** — it exists
126
+ for a one-time store migration, not as a permanent alias table, and goes once no deployed
127
+ database predates the rename.