agentopology 0.2.5 → 0.4.0

package/spec/grammar.md

@@ -43,6 +43,30 @@ template-var     = [A-Z] [A-Z0-9_-]*
 
 **Rule:** Quote strings. Don't quote identifiers, numbers, or booleans.
 
+**Rule: one field per line.** Key-value fields are newline-separated. Writing two
+on one line makes the first key take the rest of the line as its value:
+
+```
+# WRONG — `model` becomes the string "sonnet retry: 3"
+agent a { model: sonnet retry: 3 }
+
+# RIGHT
+agent a {
+  model: sonnet
+  retry: 3
+}
+```
+
+This is not a parser limitation to route around — some unquoted values are
+legitimately multi-token (`on-fail: fallback reviewer`), so whitespace could not
+separate fields without ambiguity. V90 rejects the collapsed form, in `meta` and in every node block.
+
+**Exception:** free-prose fields (`description`, `role`, `generates`,
+`termination`) are exempt once their quotes have been stripped by the parser,
+because a colon in English is ordinary — `description: "Demo: agent pipeline"`.
+Where quotes survive parsing the check is still sharp: one well-formed quoted
+token followed by more content means a field was eaten.
+
 ### Composite Types
 
 ```ebnf
@@ -207,6 +231,7 @@ perm-enum       = perm-identifier
 | `fan-out` | Parallel slices |
 | `event-driven` | Pub-sub |
 | `human-gate` | Human approval points |
+| `brain` | Agent-maintained, Obsidian-portable markdown knowledge graph |
 
 ---
 
@@ -346,7 +371,7 @@ scale-field     = 'mode' ':' ('auto' | 'fixed' | 'config')
 | `role` | identifier | no | -- | Maps to a role defined in the `roles` block |
 | `model` | model-id | yes | -- | LLM model identifier (e.g., `opus`, `gpt-4o`, `gemini-pro`) |
 | `permissions` | perm-enum | no | `autonomous` | Permission mode |
-| `prompt` | block | no | -- | Inline agent instructions (multi-line text block) |
+| `prompt` | block | no | -- | Inline agent instructions (multi-line text **block**). A key-value `prompt: "path"` is NOT valid on an agent — that form belongs to `skill` — and is rejected by V89. |
 | `phase` | number | no | -- | Pipeline position (ordering by numeric value) |
 | `tools` | tool-list | no | all | Tool allowlist |
 | `disallowed-tools` | tool-list | no | `[]` | Explicit deny-list |
@@ -360,6 +385,7 @@ scale-field     = 'mode' ':' ('auto' | 'fixed' | 'config')
 | `behavior` | `advisory` / `blocking` | no | `blocking` | Advisory never blocks flow |
 | `memory` | name-list | no | `[]` | Store IDs this agent can access (V35) |
 | `retrieval` | identifier | no | -- | Retrieval strategy ID for memory queries (V35) |
+| `custodian-of` | name-list `{ does: name-list }?` | no | -- | Store IDs this agent **maintains** (not just reads). The primitive behind the `brain` pattern. Optional `does:` declares maintenance verbs (e.g. `link, tag, index, dedupe`). Refs validated by V88. |
 | `skills` | name-list | no | `[]` | Skills to preload |
 | `mcp-servers` | name-list | no | `[]` | MCP servers available |
 | `background` | boolean | no | `false` | Run in background |
@@ -531,7 +557,7 @@ store-field     = 'type' ':' store-type
                 | lifecycle-block
                 | backend-config-block
 store-type      = 'semantic' | 'episodic' | 'procedural' | 'entity'
-                | 'graph' | 'user' | 'session' | 'temporal'
+                | 'graph' | 'user' | 'session' | 'temporal' | 'brain'
 scope-enum      = 'agent' | 'user' | 'session' | 'org' | 'global'
 isolation-enum  = 'strict' | 'soft' | 'none'
 backend-enum    = 'lancedb' | 'sqlite-vec' | 'chroma' | 'kuzu' | 'falkordb'
@@ -639,10 +665,12 @@ memory {
 | `description` | string | no | -- | Human-readable purpose |
 | `scope` | scope-enum | no | -- | Access scope (V32 warning if omitted) |
 | `isolation` | isolation-enum | no | -- | Isolation level between scopes |
-| `backend` | backend-enum | yes | -- | Storage backend (V30 enum check) |
+| `backend` | backend-enum | yes | -- | Storage backend (V30 enum check). For `type: brain`, defaults to `files` and is exempt from the enum check (V81). |
 | `path` | string | no | -- | File system path for local backends |
 | `connection` | secret-string | no | -- | Connection URI for remote backends (V34) |
 | `extraction` | extraction-enum | no | -- | Entity/fact extraction method |
+| `format` | string | no | -- | File format/convention for file-native stores. For `brain`, typically `obsidian` ([[wikilinks]], #tags, YAML frontmatter) — a promise the store round-trips as a real Obsidian vault. |
+| `sources` | sources-block | no | -- | **Presentation only** — provenance styling for the brain graph view. Maps a note's `source:` frontmatter to a color/icon. Visualizer-only; bindings ignore it. See below. |
 | `embedding` | embedding-block | no | -- | Embedding configuration (V31 warning if omitted for semantic/episodic/procedural) |
 | `index` | index-block | no | -- | Index/collection configuration |
 | `ingestion` | ingestion-block | no | -- | Data ingestion configuration |
@@ -654,6 +682,30 @@ memory {
 
 **`backend-config`:** A passthrough block for backend-specific key-value pairs not covered by the standard fields. Stored as `Record<string, unknown>` on the AST. Same pattern as `ProviderDef.extra`.
 
+**The `brain` store type (file-native).** A `brain` store is the file-native memory primitive behind the `brain` pattern: a folder of Obsidian-format markdown where the graph is a *projection* of the files, not a separate database. It is deliberately backend-less — its `backend` defaults to `files` and is exempt from the backend-enum check (V81), it needs no embedding (V82), and it compiles to direct file access (no MCP server). Edges come from inline `[[wikilinks]]` and `#tags`; backlinks are computed. Because the format is Obsidian, a `brain` store round-trips as a real Obsidian vault — agents build it, a human opens it in Obsidian for the graph view, and an existing vault becomes an agent-readable brain with zero migration. Heavyweight stores (`semantic`, `graph`, `entity`) remain available as an opt-in power-up alongside a brain. See `docs/company-brain-design.md`.
+
+**Custody (`custodian-of`).** Custody is the one new primitive the brain pattern needs. `memory:` grants an agent *read* access to a store; `custodian-of:` makes the agent *responsible for the store's upkeep* — wiring dropped files into the graph (resolving mentions into `[[wikilinks]]`, assigning `#tags`, updating index/hub notes, flagging ghost nodes and duplicates). The optional `does:` sub-list declares the maintenance verbs as visible architecture (like an optional type annotation); omitting it lets the agent infer its duties from its prompt. The verb *names* are language vocabulary; *how* each verb is performed well is an implementation/skill concern, not part of the spec. V88 validates that every `custodian-of` reference resolves to a declared store and warns when custody targets a non-brain store.
+
+**Provenance styling (`sources`).** A presentation-only sub-block on a brain store that colors the graph view by where each note came from. Each named entry maps a source key (matching a note's `source:` frontmatter, stamped by its ingester) to a `color` (hex) and/or `icon` (a file path):
+
+```
+store brain {
+  type: brain
+  path: "brain/"
+  sources {
+    gmail {
+      color: "#EA4335"
+      icon: "./logos/gmail.svg"
+    }
+    slack {
+      color: "#4A154B"
+    }
+  }
+}
+```
+
+This is **strictly cosmetic and affects only the `visualize-brain` rendering** — it never touches ingestion, agents, files, or binding output. Bindings emit nothing for it; delete it and the brain behaves identically (the graph just falls back to category coloring). The language stores **no image bytes** — only the path string; the visualizer reads the icon file at generate-time and inlines it as a `data:` URI, keeping the output a single self-contained HTML file. When a node's `source` matches a `sources` key, it is colored/iconed accordingly; otherwise it falls back to category-based coloring (person/org/topic inferred from tag namespaces).
+
 **Local vs remote backends:** Backends `lancedb`, `sqlite-vec`, `sqlite`, `kuzu`, and `chroma` are local-first (use `path`). Backends `pinecone`, `qdrant`, `pgvector`, `neo4j`, `mongodb`, and `falkordb` are remote (require `connection`, V34).
 
 ##### `embedding` sub-block

package/spec/validation.md

@@ -665,40 +665,108 @@ agent researcher {
 
 ## Summary Table
 
+All 92 rules, generated from `src/parser/validator.ts` so the spec cannot drift
+from the implementation. Rules V8, V12, V23, V24, V89 and V90 are collected at
+**parse time** — the misuse they catch leaves no trace in the AST — and surfaced
+through the validator like any other rule.
+
+`error` fails `agentopology validate` with exit 1. `warning` reports and exits 0.
+
 | Rule | Severity | Description |
 |------|----------|-------------|
-| V1 | error | Unique names — all agent, action, and gate names must be globally unique |
-| V2 | error | No keyword names — names cannot match reserved keywords |
-| V3 | error | Flow resolves — every flow reference must be a declared node |
-| V4 | error | No orphans — every agent must appear in flow or have `invocation: manual` |
-| V5 | error | Outputs exist — `[when x.y]` must reference a declared output |
-| V6 | error | Bounded loops — every back-edge must have `[max N]` |
-| V7 | error | Model required — every agent and orchestrator must have a model |
-| V8 | error | Imports resolve — import paths must point to existing files |
-| V9 | error | Actions handled — flow actions must appear in `orchestrator.handles` |
-| V10 | warning | Prompts exist — prompt blocks should not be empty |
-| V11 | error | Reads/writes consistent — data dependencies must match flow order |
-| V12 | error | Edge attribute order — must be `[when, max, per]` |
-| V13 | error | Gate placement — `after` and `before` must reference declared nodes |
-| V14 | error | Tool exclusivity — cannot have both `tools` and `disallowed-tools` |
-| V15 | error | Exhaustive conditions — conditional edges must cover all output values |
-| V16 | error | API key env vars — provider `api-key` must use `${ENV_VAR}` syntax |
-| V17 | error | Single default provider — at most one provider may be default |
-| V18 | warning | Model in provider — agent models should exist in a provider's list |
-| V19 | error | Unique provider names — no duplicate provider names |
-| V20 | error | Schedule job references — jobs must reference declared nodes; cron/every exclusive |
-| V21 | error | Interface secret detection — sensitive fields must use `${ENV_VAR}` syntax |
-| V22 | warning | Fallback chain models — fallback models should exist in a provider's list |
-| V23 | warning | Duplicate sections — singleton sections should appear at most once |
-| V24 | warning | Unknown memory sub-blocks — only known sub-blocks are expected |
-| V25 | warning | Bounce-back advisory — `on-fail: bounce-back` is advisory on CLI bindings |
-| V26 | error | Action kind enum — must be external, git, decision, inline, or report |
-| V27 | warning | Agent permissions enum — should be a recognized permission mode |
-| V28 | error | Metering format enum — must be json, jsonl, or csv |
-| V29 | warning | Metering pricing enum — should be a recognized pricing model |
-| V30 | error | Store backend enum — must be lancedb, sqlite-vec, chroma, kuzu, falkordb, mongodb, pinecone, qdrant, pgvector, neo4j, or sqlite |
-| V31 | warning | Embedding recommended — embedding should be present for semantic, episodic, and procedural stores |
-| V32 | warning | Store scope recommended — every store should have a scope field |
-| V33 | error | Retrieval sources resolve — retrieval sources must reference declared store IDs |
-| V34 | error | Connection required for remote backends — pinecone, qdrant, pgvector, neo4j, mongodb, falkordb require connection |
-| V35 | error | Agent memory/retrieval references — agent memory and retrieval fields must reference valid IDs |
+| V1 | error | All agent, action, and gate names must be globally unique |
+| V2 | error | No name may match a reserved keyword |
+| V3 | error | Every node referenced in flow must be a declared agent, action, or gate |
+| V4 | error | Every agent must appear in flow unless it has `invocation: manual` or is a group member |
+| V5 | error/warning | Every `[when x.y]` must reference a declared output |
+| V6 | error/warning | Every back-edge must have `max N` |
+| V7 | error/warning | Every agent and orchestrator must have a model |
+| V8 | error/warning | Import references should resolve (warning only -- we cannot check the filesystem) |
+| V9 | error/warning | Every action referenced in flow must appear in orchestrator.handles |
+| V10 | error/warning | Prompt content should not be empty if a prompt block is declared |
+| V11 | error | If agent A writes X and agent B reads X, a path A -> B must exist in flow |
+| V12 | error | Edge attribute order must be [when, max, per] |
+| V13 | error | Gate `after` and `before` must reference declared nodes |
+| V14 | error | `tools` and `disallowed-tools` cannot both appear on the same agent |
+| V15 | error/warning | When a node has ONLY conditional outgoing edges, the conditions must |
+| V16 | error/warning | `api-key` must be a `${...}` env-var reference (no literal secrets) |
+| V17 | error/warning | At most one provider may have `default: true` |
+| V18 | error/warning | Every model referenced by an agent should exist in at least one provider's models list |
+| V19 | error/warning | Provider names must be unique |
+| V20 | error/warning | Every schedule job must reference a declared agent or action; cron and every are mutually exclusive |
+| V21 | error/warning | Interface webhook/auth values containing literal secrets (not `${ENV_VAR}`) should error |
+| V22 | error/warning | Every model in a fallback-chain should exist in at least one provider's models list |
+| V23 | error/warning | Duplicate top-level singleton sections |
+| V24 | error/warning | Unknown sub-blocks in the `memory` section |
+| V25 | error/warning | `on-fail: bounce-back` enforcement depends on the gate's `after` target |
+| V26 | error/warning | `action.kind` must be one of the allowed values |
+| V27 | error/warning | `agent.permissions` should be one of the known values |
+| V28 | error/warning | `metering.format` must be one of the allowed values |
+| V29 | error/warning | `metering.pricing` should be one of the known values |
+| V30 | error | Validate `timeout` format is a valid duration string (matches /^\d+[smhd]$/) |
+| V31 | error | Validate `on-fail` is one of: halt, retry, skip, continue, or starts with "fallback " |
+| V32 | error | If `on-fail: fallback <id>`, validate that the referenced agent exists |
+| V33 | error | Validate retry block fields (backoff enum, interval format, non-retryable is list) |
+| V34 | error | Validate `temperature` is between 0 and 2 (on agents and defaults) |
+| V35 | error | Validate `thinking` is one of: off, low, medium, high, max |
+| V36 | error | Validate `output-format` is one of: text, json, json-schema |
+| V37 | error | Validate `log-level` is one of: debug, info, warn, error |
+| V38 | error | Validate `max-tokens` is a positive integer |
+| V39 | error | Validate `join` is one of: all, any, all-done, none-failed, or N-of-M |
+| V40 | error | Error edge target must be a declared node |
+| V41 | error | `[race]` is only valid on fan-out edges (node has multiple outgoing edges) |
+| V42 | error | `[tolerance]` format is valid (integer or percentage string matching /^\d+%?$/) |
+| V43 | error | `[wait]` format is a valid duration string (reuse timeout validation pattern) |
+| V44 | error | Topology-level `error-handler` must reference a declared node |
+| V45 | error | Topology-level `timeout` must be a valid duration string |
+| V46 | error | Schema type names must be valid (primitive, array of X, enum, or ref) |
+| V47 | error | Schema `ref` names must resolve to a declared schema in the top-level `schemas` block |
+| V48 | error/warning | Validate `observability.level` is one of: debug, info, warn, error |
+| V49 | error/warning | Validate `observability.exporter` is one of: otlp, langsmith, datadog, stdout, none |
+| V50 | error/warning | Validate `observability.sample-rate` is between 0 and 1 (inclusive) |
+| V51 | error/warning | When `sensitive` is used with a literal string (not a `${...}` env var |
+| V52 | error | Validate that secret URI schemes are one of the supported providers |
+| V53 | error | Param type must be one of: `string`, `number`, `boolean` |
+| V54 | error | Interface entry and exit must reference declared node ids |
+| V55 | error | No two imports may share the same alias |
+| V56 | error | Import source must be a syntactically valid path (starts with `./`, |
+| V57 | error | Validate circuit-breaker fields — threshold must be a positive integer, |
+| V58 | error/warning | `compensates` must reference a declared agent node |
+| V59 | error | Human node `on-timeout` must be one of: halt, skip, or start with "fallback " |
+| V60 | error/warning | When `join` uses quorum syntax `N-of-M`, validate: |
+| V61 | error/warning | Validate `[weight N]` edge attributes: |
+| V62 | error/warning | `[reflection]` is only valid on back-edges (edges that form cycles) |
+| V63 | error | `members` in a group node must reference declared agent nodes |
+| V64 | error | `speaker-selection` must be one of: auto, round-robin, random, manual |
+| V65 | error | `max-rounds` must be a positive integer |
+| V66 | error/warning | `rate-limit` must match N/unit where N >= 1 and unit is sec\|min\|hour\|day |
+| V67 | error/warning | checkpoint `backend` must be one of the known values |
+| V68 | error/warning | checkpoint `strategy` must be one of the known values, |
+| V69 | error/warning | replay requires strategy "every-node"; max-history must be a positive |
+| V70 | error | All artifact IDs in the artifacts block must be unique |
+| V71 | error | depends-on, produces, and consumes must reference declared artifact IDs |
+| V72 | error | Artifact dependency graph must be acyclic |
+| V73 | error/warning | Registry package names must match `[a-z0-9-]+(/[a-z0-9-]+)*` |
+| V74 | error/warning | Registry package version must be valid semver or "latest" |
+| V75 | error/warning | If sha256 is present on an import, it must be a valid 64-char hex string |
+| V76 | error/warning | Variant ids must be unique within each agent |
+| V77 | error/warning | Variant weights must sum to approximately 1.0 (within 0.01 tolerance) |
+| V78 | error/warning | `encrypted` values must match SOPS envelope format ENC[METHOD,data:BASE64] |
+| V79 | error/warning | provider auth.type must be one of the known auth types |
+| V80 | error/warning | OIDC and OAuth2 auth types require an issuer field |
+| V81 | error/warning | StoreNode.backend must be one of the known values |
+| V82 | error/warning | When StoreNode.type is "semantic", "episodic", or "procedural", |
+| V83 | error/warning | Every store should have a scope defined. Warning level |
+| V84 | error | Every source in RetrievalNode.sources must match a store ID in ast.stores |
+| V85 | error | Remote backends (pinecone, neo4j, qdrant, pgvector) require a connection field |
+| V86 | error | Every ID in AgentNode.memory must match a store ID in ast.stores |
+| V87 | error/warning | `orchestrator.delegation` must be "subagent" or "inline" |
+| V88 | error/warning | Every store in an agent's `custodian-of` must reference a declared store |
+| V89 | error | `agent.prompt` must be a `prompt { }` block, not a `prompt: "path"` key-value pair (the string form belongs to `skill`) |
+| V90 | error | A field value must not swallow the next field — fields are one per line (`spec/grammar.md` §2) |
+| V91 | error | A required field must not be satisfied by a parser-injected placeholder — `meta.version` and `orchestrator.model` are required, and their sentinels (`0.0.0`, `unknown`) satisfied every downstream check |
+| V92 | error | An edge's attributes go in ONE bracket, comma-separated — `[when ...] [max N]` produced a condition string containing brackets, silently |
+
+> Sections above document the first 35 rules with worked examples. The rest are
+> single-line entries here plus their doc comment in the source. Adding an
+> example section for a rule is always welcome.