16.10 Goal views — a saved answer whose steps are planned

A view may declare goal: in place of cypher:. The world plans it, compiles it and pins the result; the view then runs that statement like any other view, so everything that runs views — by name, over MCP, in lenses, apps and watches — gets it unchanged.

# views/untracked-issues.yml — what a realm ships: the goal, and nothing the server writes
- name: UntrackedFromEmail
  description: Issues a customer's email raises that no open support case already tracks.
  params:
    email: { type: string, description: "The customer's email, as text." }
  goal: |
    MATCH (raisedBy:Attendee)-[:RAISED]->(untracked:Issue)
    WHERE NOT EXISTS { (untracked)-[:TRACKED_BY]->() }
    RETURN untracked.summary AS issue, untracked.severity AS severity, raisedBy.name AS person

Field	Written by	Meaning
goal	the author	The final read query, over facts as if they existed. Read by validation’s vocabulary, property and query-shape checks as a view’s cypher is.
params	the author	The plan’s inputs, typed by use (below).
compiled	the server, never the author	The statement the goal compiled to — what an invocation runs.
plan	the server, never the author	What compiled was planned from: a fingerprint of the goal text, and each chosen step’s name, kind and signature fingerprint.

Params are typed by use. A param a chosen step reads into ai.fromText is text; one a step keys or canonicalizes on spine L is an identity of L; one only filtered on is a value bound at invocation. A param binds the parameter of its own name — the compiled statement keeps the steps’ parameter names, so binding email to a step’s $notes would be invisible in the pin. A param nothing reads, or one read two ways, is refused, naming who reads what. A chosen step’s parameter the view does not declare is compiled in as that step’s default.

Compile, pin, run. Saving a goal view plans it as the saving principal, over the steps that principal may run, and stores compiled and plan beside it; the compiled statement is then checked as any view body is. Unreachable, tie and refused are save errors — the save names the missing fact, both rival plans, or the reasons, and nothing is written. An invocation runs compiled and never plans.

Replanning is explicit: a re-save, the MCP tool view_replan ({name} → {ok, compiled}, or {ok: false, error, details} naming the missing fact, the rivals or the refusal), or POST /api/v1/admin/kg/views/{name}/replan. Nothing replans a pinned goal view by itself.

Stale is refused, never silently redone. A pin records each chosen step’s signature — what it needs, makes, names and takes; not its body or cost, which the compiled statement already holds. Every invocation checks the pin against the invoking principal’s steps:

Found at invocation	Answer
the goal was never compiled in this world	refused: not compiled — replan it
the goal text changed since the pin	refused as stale
a pinned step was removed	refused as stale, naming the step
a pinned step’s signature changed	refused as stale, naming the step
a pinned step the invoking principal cannot run	refused as stale, without naming it (§16.7)

Each refusal is the caller’s to fix, answered as any invalid view argument is. The views listing carries the goal and a goalStatus — pinned, not compiled, or stale: <what moved> — which is the warning before anyone invokes it.

A goal view is an answer, not a step. It is never offered to a plan: its compiled statement makes what its own steps make, and offering it would tie every plan with itself.

A realm ships goal: alone; pins are per world. A goal is planned over the steps of the world it runs in — every installed realm’s views and rules — so the same realm can compile differently in two worlds. A pin written back into the realm would ship one world’s answer to every other, so each world keeps its own pins, written by the server. A world compiles a goal view it has never compiled when it is rebuilt — realm install, refresh or removal, world switch, all explicit acts — and never replans one it has already pinned. A view a user saves keeps its pin with it, written by the server; clients never edit it.

Realm validation plans each shipped goal view over the realm’s own views and DERIVE rules, and those of the realms validated beside it, read against the projected types, spines and producers they declare:

Found	Severity
unreachable, or refused	ERROR at the view’s goal
a shipped compiled: or plan:	ERROR — those fields are the server’s
a tie	WARNING — validation cannot price the deployment’s model reductions, so two plans the installing world tells apart may tie here; the world refuses a real tie when it compiles the view

Audience is not applied at validation: which steps a principal may plan through is decided per principal, when the world compiles.