graview-linked-records

graview-linked-records is one of Graview's 31 authoring skills: instructions an AI coding assistant such as Claude Code or Codex reads before it changes a Graview app. What it teaches: Link a record in one Graview app to a record in another app — a relation whose target is another app's kind, read there as whoever is looking, walked by computed fields and rules, its far changes kept in this app's history — and verify it with graview check and by opening it as a viewer who may not see the other app.

Installed into a project by graview skills install ., and read by whichever assistant is working beside you.

The skill

Link a record in another app

A relation usually goes to a kind of the same app. When the thing lives in an app of its own — a purchase scenario that buys a house kept in the house app — the relation goes THERE: its target is @ + the other app's address + / + its kind. Linking picks a record in that app; the other app is never changed. What the far record is, and whether this viewer may see it, is the host's to say, every time, as the viewer.

Do this

  1. Declare the relation to the other app's kind. In a document:

``json "scenario": { "fields": { "name": { "type": "string", "required": true }, "budget": { "type": "number", "format": "money" } }, "edges": { "forHouse": { "to": ["@nick/house/house"], "cardinality": "one", "description": "the house this scenario buys" } } } ``

The address is the one an app-link field would hold: @owner/app, the id the host knows the app by (@app_kf5eydr9z58jzf/house), or its https address (@https://example.com/a/house/house). Every target names ONE app; mix in a kind of this app, a second app, an inverse or appendOnly, and the check refuses it in a sentence. In TypeScript the link is a field it is kept in: forHouse: linkedRecordField("@nick/house/house").optional() ({ cardinality: "many" } for several). A host that changes a document by edits sends {"op": "add-relation", "kind": "scenario", "relation": "forHouse", "to": ["@nick/house/house"], "cardinality": "one"}, refused by the same finding codes; the studio makes one with its act for linking another app's records.

  1. Let the record's own edit link one. The link is kept on the record that links, as the far kind and its id — "house:h1", or a list — so the derived edit-scenario sets it, undoes it, logs it and hides it from a seat a sight keeps it from, like any field. The faces draw a picker that lists what the host finds there for this viewer; an agent finds the value with find_linked and passes it to the edit. A declared act may not connects it or set it (act-linked).
  1. Walk it by name. forHouse.listPrice reads the far record's field, in a computed field, a view's block or a rule:

``json "computed": { "price": { "expr": "forHouse.listPrice", "label": "Asking price" } }, "rules": { "within-budget": { "over": "scenario", "when": "budget != null", "require": "forHouse.listPrice <= budget" } } ``

It is read AS THE VIEWER: a field they may not see there reads as nothing. A link they may not open, or not read yet, is said, never thrown — the computed value says why it has none, and a rule that would fail without it is "could not be judged" rather than broken. out('forHouse') does not walk it (rule-linked).

  1. Show it. A record's page and the scene's record panel draw the far record with its own card — label, describe line, a glance at its fields, its app's name — and { "field": "forHouse" } in a card names it. Pressing it opens it in its own app through the host. A viewer who may not open that app sees "linked record (no access)" and nothing of it.
  1. Hand the host's reader in. The host implements LinkedRecords and passes it where it passes resolveApp (mount, <Embed>, GraviewProvider, PagesApp) as linkedRecords: `resolve(ref, viewer) answers { address, kind, id, label, describe?, card?, fields, href?, app? }, { denied: true } or null; find({ address, kinds, query, limit }, viewer) the records it may link; open(ref, viewer)`, optional, opens one in place. `linkedRecordsOver({ "@nick/house": { store, name, opens, href } }) from @graview/core/linked` is that host over stores in memory — tests and a host holding both apps use it as is. When the far record changes there, the host calls recordLinkedChange(store, { ref, fields, app }): one op per linking record, authored by the far app, naming what changed and none of its values, so Activity and the record's history say it.

Then find out whether it worked

pnpm build && npx graview check ./app.gdd.json
npx graview describe ./app.gdd.json   # "Linked from other apps" says each relation and how to link one

Report the actual output. What it catches here: linked-target, linked-mixed, linked-apps, linked-inverse, linked-append-only, act-linked, rule-linked. Then open a record that links one as a viewer the host refuses that app, and confirm the page says "linked record (no access)" and shows nothing of it — not its name, not a value worked out from it.

What the check cannot see

  • Whether the other app exists, has that kind, or lets this viewer in: the host answers that, every time, and nothing in the document can.
  • Whether a far field the expression names (listPrice) is one the other app has: a field it lacks, or hides from this viewer, reads as nothing.
  • Whether linking across apps was the right shape at all. If both kinds change together and the same people keep them, one app with a local relation is simpler.