# @graview/core

`@graview/core` is one of the 14 npm packages of Graview, a TypeScript framework that derives an app’s interface, permissions and agent tools from one declaration. The graph, the log, the schema and the checker. Everything a Graview app declares, and the CLI that verifies it.

```sh
pnpm add @graview/core
```

Entry points: `@graview/core`, `@graview/core/document`, `@graview/core/compiled`, `@graview/core/retry`, `@graview/core/describe`, `@graview/core/figures`, `@graview/core/scene`, `@graview/core/city`, `@graview/core/check`, `@graview/core/blocks`, `@graview/core/arrange`, `@graview/core/shown`, `@graview/core/record-boxes`, `@graview/core/head`, `@graview/core/revisions`, `@graview/core/csv`, `@graview/core/navigate`, `@graview/core/provenance`, `@graview/core/history`, `@graview/core/past`, `@graview/core/linked`, `@graview/core/tidying`, `@graview/core/catalog`, `@graview/core/jobs`, `@graview/core/devices`, `@graview/core/workflows`, `@graview/core/friction`, `@graview/core/css`, `@graview/core/learn`, `@graview/core/told`, `@graview/core/compose`, `@graview/core/composer`, `@graview/core/traits`, `@graview/core/subscriptions`, `@graview/core/markdown`, `@graview/core/words`, `@graview/core/seat`, `@graview/core/binding`, `@graview/core/publishing`, `@graview/core/field-sight`, `@graview/core/typing`, `@graview/core/search`, `@graview/core/forms`, `@graview/core/lines`, `@graview/core/json-schema`, `@graview/core/sync`, `@graview/core/import`, `@graview/core/snapshot`, `@graview/core/conformance`, `@graview/core/sqlite`, `@graview/core/scaffold`, `@graview/core/cli`, `@graview/core/testing`, `@graview/core/typed`, `@graview/core/document.schema.json`

## What it is

Everything a Graview app declares, and the checker that verifies it.

- **Schema** — `defineNode` and `createSchema`. Zod is the single source of runtime validation, TypeScript types and JSON Schema.
- **Graph** — nodes and edges, with a tracked reader so a mutation records what it read as well as what it wrote.
- **Mutations** — `defineMutation`. Every change is a typed, named, describable act; nothing writes the graph directly. Each kind gets a derived `edit-<kind>` offering the fields no other act writes. Every act refuses an argument it does not take, naming those it does, and an act refused as asked throws an `ActRefusal` whose `reason` and `sentence` a host can show (`refusalOf` reads one): `refused` when the act's own rule says no, `invalid` for the call as sent.
- **Invariants** — rules that judge the graph and name the mutations that would repair them. That naming is the seam derived affordances ride on.
- **Operation log** — the graph is a fold over it. Author, intent, reads and writes on every op, which is what makes selective undo a dependency question rather than a stack.
- **Permissions** — a `Principal` is an `Author` with roles, so what the log blames is what the policy judged.
- **Files** — a record holds a picture, a video or a document the host stored (`imageField`, `videoField`, `fileField`; `"image"`, `"video"` and `"file"` in a document, and a list of any): a `FileValue`, its `href` a path on the host, uploaded through the page's `HostFiles` and drawn where the host serves it (`fileSrc`). A video's value may say its `poster`, its `duration` in seconds and its `captions` (a WebVTT file on the host), and is said "a 45-second video" (`videoWords`).
- **Theme** — the token contract, the two shipped palettes, and a contrast checker that measures a brand's palette before it ships. The rest of the look is data beside them — `SHAPE`, `TYPOGRAPHY` and `isoShade(scheme)`, resolved for a brand by `shapeOf` and `typographyOf` — so a page outside the app can dress as one without importing a stylesheet. A document's brand holds the rest of it too (FR-124): a logo and a page icon, judged by `svgProblem` and `markProblem` under the same rules as Graview Cloud's images; faces named from `SYSTEM_STACKS`, the system's own and `DOCUMENT_FONTS`, judged by `fontProblem`; and an accent that does not read as given is refused by `accentProblem` with the pair, its ratio and a shade that would pass (FR-126). Graview's own identity (the design kit, revision 03) is data too, and reaches an app only through these defaults: `GRAVIEW_COLORS` (En Dash navy and turquoise, paper, reading ink, muted text), `GRAVIEW_FACE` and `WEIGHTS` (Montserrat at 550, 450 and 600, named first in `TYPOGRAPHY` and never fetched), `LOGO_RULES`, and the shared-plane symbol as an inline currentColor SVG (`graviewSymbol`, the micro cut under 28 px by `symbolCut`). The shipped palettes are built on it; turquoise is in neither, since it is a point and a fill, never text.
- **`graview check`** — reads a declaration and reports what is wrong with it, in terms an agent can act on. In code it is `@graview/core/check`: `checkApp`, `describeApp`, the agent docs (`generateLlmsTxt`), and `compileDocument`, a document compiled and checked.
- **Documents** — `@graview/core/document`: a whole app as one JSON object, compiled by `compileDocumentWithoutCheck` into the same app `defineApp` declares and never run as code (`compileDocument` from `@graview/core/check` also asks the checker); `toDocument` writes an app back out. Rules say what must hold in a small, budgeted language (`expressionRule`). Every command that takes an entry takes `--document <file>`. A view's blocks resolve with `@graview/core/blocks`. A number field may say its range (`min`, `max`, `step`), which every form, tool and apply honors; an act's `connects` links from whichever end of the relation its subject is, `replaces` severs the links it supersedes and set the record at the other end (its "setsOther" key), and its "setsLinked" key carries a change to the records its subject is already linked to through a relation, judged by each far record's own edit. `editDocument`, `diffDocuments` and `planMigration` change a document and say what the change does to stored data. A host that compiles a document on its server hands the page `serializeCompiled(compiled)`, and the page builds the same app with `appFrom` or `appFromOrCompile` from `@graview/core/compiled`, which carries no compiler (the format is `graview-compiled@1`).
- **A document's shape, for an editor and a compiler** — every version ships `@graview/core/document.schema.json`, the document format as JSON Schema, written by the build from the shape the compiler reads. A document that says `"$schema": "./node_modules/@graview/core/dist/document.schema.json"` (or the version's own address, its `$id`) is checked as it is typed: an unknown key is underlined in the editor, not refused at run time. `@graview/core/typed` is the same document in TypeScript: `defineDocument` returns the JSON document unchanged, and a key the format does not have, an edge to a kind nobody declares, a glance or lifecycle field the kind lacks, a relation an act connects or a kind a rule is over that is not declared is a type error. `graview types <document> --out document.d.ts` writes a document's kinds, fields (an enum's options as a union) and relations as types, `TypesOf<typeof document>` derives the same from a `defineDocument`, and `typedReader<Types>(store)` reads a store through them (`reader.fieldOf(node, "status")`, `reader.edgesOf(node, "under")` and the rest), so a renamed field or relation fails `tsc` in the product that reads it.
- **A part that tries again** — `@graview/core/retry`, for a page only: `retryingImport(() => import("./part.js"))` is a loader that asks again after the import failed, with a URL of its own (`?retry=<n>`) where the engine keeps a failed module for the page's life, as Chromium and Firefox do. Never from a server's code: workerd refuses a script with a computed `import()` in it.
- **A snapshot file** — `@graview/core/snapshot`: `writeSnapshot(graph)` writes a header line (when it was made, records and links per kind, where each kind's lines are) and then a record per line; `readSnapshot(text, { kinds })` parses only the kinds asked for, `fetchSnapshot(url, { kinds })` fetches only their bytes, and an old `{ nodes, edges }` file still reads.
- **Two-way sync** — `@graview/core/sync`: `SyncEngine` over the op log, with a conflict policy (`report`, `theirs`, `ours`), resources the remote owns (`readonly`, refused here with their `because`), links seeded from a version field, and transports for Google Calendar and for a tool server over MCP (`mcpClient`, `mcpDoor`, `doorClient`, `mcpRemote`). The Google transport follows every page, starts a full resync when Google rejects the sync token, and asks `token({ refresh: true })` once when Google refuses an access token; `scripts/verify-google-calendar.mjs` proves it against a real test calendar (credentials from `~/.graview-google-test.env`, made once by `scripts/google-calendar-once.mjs`; `scripts/calendar-sync-demo.mjs` is the same by hand). A Notion database is a transport too (`notion`): one database, one kind, property to field by name or as declared, pulled by `last_edited_time` across every page of a query, pages made, set and archived, Notion's rate limit waited out, and a refused secret or an unshared database said as a sentence; `scriptedNotion()` is a Notion in memory to test against, and `scripts/verify-notion.mjs` proves the transport against a real workspace (`~/.graview-notion-test.env`; `--stub` against the scripted one). A document declares either as `connections.<name>` — a calendar, its fields and a color or tag filter, or a database and its properties; `read` or `both`, the conflict policy — judged by `graview check` and run by `graview serve` and `graview preview`; `connection(…)` builds its engine for any host.
- **A spreadsheet brought in** — `@graview/core/import`: `importRows(store, kind, rows, mapping, { by })` reads each cell by its field's type, links a cell to a record by its name, keeps every row that fits as one undoable batch `via: "import"`, and says each refused row in words; `previewImport` keeps nothing, `proposeMapping` offers a mapping from the header row, and `parseCsv` reads a CSV or a paste (`docs/import.md`).
- **The city** — `@graview/core/scene`: `sceneThumbnail` draws a document (or an app) as the Scene draws it from altitude — the same districts on the same map, in their hues — as one SVG string, with no DOM, for a host listing apps; `sceneDistricts` is the same answer as data. At a card's size, `fit: "content"` fits it to what stands: each district on its whole block from the same corner, cropped to the plots, with a few blocks no narrower than `minBuilding` pixels (16 by default) rather than a speck per record. Without counts — a live app with no snapshot — each district stands three blocks placed and raised by its kind's name, so every app still looks like itself. `size: "icon"` draws it as a tab's icon: 32 by 32, each district on its block in its hue with one block on it, readable at 16 pixels and about a kilobyte — a standalone SVG to serve as a favicon. A kind's figures are `@graview/core/figures`.
- **What is said, matched and listed after a page draws** (FR-179) — `@graview/core/search`: the one matcher (`search`, `actsOn`, `touchWeights`, `parseQuery`, `matchNode`), fetched when somebody first searches. `@graview/core/words`: a record read as a person reads it (`readableFields`, `pageSections`, `isLongText`, `describeNode`, `tellApart`), what an argument asks for (`argShape`, `describeArg`), an argument and a refusal in the record's words (`argumentWords`, `failureWords`) and `viaSaid`. `@graview/core/seat`: an act's answer as its seat may see it (`answerSeenBy`), the archive behind the undo horizon as a seat may see it (`archivedSeenBy`, a host's `HistoryHost.archived` answer), every place an app has (`placesOf`, `placesFrom`) and the order things are made in (`beginning`). Judging the arrangement (`arrangementFindings`) is `@graview/core/check`'s.
- **What a page loads first** — `@graview/core` and `@graview/core/document` hold only what a page draws with. The checker, the city, the figures and the block resolver are on the subpaths above because a bundler places a whole module in every chunk that can reach it: a hosted page imports both barrels up front, and would otherwise carry them before a face is fetched.
- **A view's CSS, read as a browser reads it** — `@graview/core/css`, on no page: the CSS tokenizer and parser, and the sanitizer over them (`sanitizeStylesheet`, `sanitizeStylesheets`, `sanitizeDeclarations`, `sanitizeValue`) that keeps of a stylesheet only what the open kit allows — the tables `CSS_PROPERTIES`, `CSS_FUNCTIONS`, `CSS_AT_RULES` and the rest, `url(#id)` on a paint alone, nothing that fetches — up to `OPEN_MAX_STYLESHEET` characters. It is the framework's one judge of CSS: `@graview/guest` draws a worker view's stylesheet through it, and the checker holds a document's own stylesheet for every view (`brand.views.css`) to it, so what passes is what a page draws.
- **A place's address** — `addressOf(place, { basePath })` spells a place from `placesOf` as the routed face links to it under a host's base path, `pathWithin` reads an address back, and `basePathOf` normalizes a base. A `search` hit says its own: a record, a kind's list or a place carries `address`, spelled the same way under the `basePath` it is given, and a seat finds only the records its sight lets it open.
- **The screens a device offers** — `@graview/core/devices`, on no page: the strip a fixed screen draws along its foot (`deviceScreensOf`: the declaration's `devices.screens`, else the home and the app's jobs, else its bar), the place a screen names (`screenPlaceOf`), and the checker's words for one it cannot offer (`deviceFindings`), held to `MOST_DEVICE_SCREENS` and `LONGEST_SCREEN_LABEL`. `@graview/pages/device` draws it.
- **Conformance** — `@graview/core/conformance`: fixtures a host runs against a version (`conformance()`) to prove it reads, compiles and derives the same.
- **A status board's moves** — `@graview/core/describe`: `columnReach` says which acts move a card to which column — the named steps that set the field to that column's value, or else an act told the value — and `columnMoves` the ones one seat may run on one record, its conditions judged.
- **What a declaration is made of** — `@graview/core/compose`, on no page: `traitsOf(document | app)` reads a declaration's traits in the closed vocabulary `TRAITS` (people who own things, a status that moves, money against a budget, …), each with the kinds, fields, rules, lenses and acts that carry it and one sentence, never off hand-written tags; `startingDocument({ base?, drop?, add?, name, purpose? })` composes a document from a template's parts and trait modules, each joined to the kind people see most, that compiles with no warning, and says what it took from where; beside `inferJobs` and `composeDesign`, which propose a declaration's jobs and one design whole.

```sh
npx graview create my-app          # a product on Graview, started (also: npm create graview)
npx graview check ./dist/domain/app.js
npx graview docs ./dist/domain/app.js
```

`create` writes the declaration split into domain and UI, a shell, a headless test and a CI workflow, initializes a repository, installs, and says what to do next. `--link <path>` consumes the framework from a sibling checkout by path instead of a registry — the only way that works until the packages are published — and refuses a framework that is not built. The generator behind it is `@graview/core/scaffold`, a pure function from a name and a first kind to a list of files, for a host that provisions apps.

## What it exports (438)

Read off the package's own barrel, so this is what is there today.

`accentProblem`, `actingAs`, `ActRefusal`, `actSpelledAs`, `actTitle`, `addressOf`, `AI_BRIDGE_PATH`, `allLabel`, `appLinkField`, `applySplice`, `AppTidying`, `ARCHIVED`, `archivedFrom`, `argumentsTaken`, `arrangedEntries`, `article`, `asBoundTo`, `askedArguments`, `askedFieldsOf`, `assertHead`, `assertReadable`, `assetSrc`, `attachFriction`, `AUTHOR_KINDS`, `authorKindOf`, `bareOp`, `basePathOf`, `BIND_PERSON`, `bindSchema`, `bindsOf`, `boundPeopleFor`, `brandFromAccent`, `brokenWords`, `capabilities`, `capabilitiesOf`, `checkBrandContrast`, `checkContrast`, `checkKitContrast`, `checkpoint`, `checkpointOn`, `checkpointsBetween`, `checkUndo`, `choiceWords`, `citedFieldsOf`, `colorsIn`, `compileMutation`, `composite`, `connectorHueColor`, `connectorKitFor`, `contrast`, `counted`, `coverageUnlinkedWords`, `createMemoryAdapter`, `createSchema`, `createSqlAdapter`, `createSqliteAdapter`, `createViewRegistry`, `DARK`, `darkGroundFor`, `DATE_VALUE`, `dateOn`, `dayAsRead`, `dayOf`, `dayOfMoment`, `dayOfMonthAsRead`, `daysAsRead`, `daySpanOf`, `dayZoneFor`, `DECISION_BRIDGE_PATH`, `declaredLenses`, `declareInstallation`, `DEFAULT_KIT`, `DEFAULT_LOCALE`, `defineApp`, `defineInvariant`, `defineMutation`, `defineNode`, `defOf`, `deriveArchiveMutations`, `derivedVia`, `deriveEditMutations`, `deriveMutations`, `deriveRemoveMutations`, `describeCapability`, `descriptionOf`, `diffSnapshots`, `DISPLAY_TRACKING`, `DOCUMENT_FONTS`, `documentSchemes`, `durationField`, `EDGE_FIELDS`, `edgeId`, `editMutationName`, `editVia`, `effectivity`, `emojiMark`, `emojiOf`, `emojiProblem`, `emojiSvg`, `EMPTY_DIFF`, `evaluate`, `excerpt`, `extendInvariants`, `extendMutations`, `familiesIn`, `faviconHref`, `FIDELITIES`, `FIELD_SIGHT`, `fieldInPassing`, `FieldRevisions`, `fieldsWritten`, `fieldsWrittenBy`, `fieldWords`, `fieldWriters`, `fileAt`, `fileField`, `fileKindOf`, `filesOf`, `fileSrc`, `foldPresence`, `fontProblem`, `FORMATS`, `formatStamp`, `FRAMEWORK_VERSION`, `FRESH_KEY`, `freshAddress`, `Graph`, `GRAPH_FINDING_CODES`, `GraphError`, `GRAVIEW_COLORS`, `GRAVIEW_FACE`, `graviewSymbol`, `GridSort`, `gridSortOf`, `gridSortProblem`, `groundProblem`, `groundReads`, `groundSchemes`, `headOf`, `hidesFrom`, `holdsValue`, `HOME_SLUG`, `HOST_ASSETS`, `hueFor`, `humanizeField`, `humanizeValue`, `imageField`, `inAskedOrder`, `INSTALLATION_MODULE`, `InvalidArguments`, `inverseOf`, `invert`, `inverted`, `isAppAddress`, `isAppLinkField`, `isArchived`, `isAutomated`, `isCurrent`, `isEffectiveBetween`, `isEffectiveOn`, `isEmptyDiff`, `isFileValue`, `isFocus`, `isImage`, `isInlineSvg`, `isLeftAlone`, `isLinkedTarget`, `isMadeRef`, `isoDate`, `isoShade`, `isoToday`, `isRepeat`, `isRepeatField`, `isShippedLens`, `isSystem`, `isSystemFamily`, `isUnset`, `isVideo`, `isVisitorAuthor`, `isWithheld`, `KEEP_LINK`, `KeepsSeat`, `keptSubscription`, `kindPath`, `kitVariables`, `labelOf`, `layer`, `layerProperty`, `LAYERS`, `layerVariables`, `LIGHT`, `Lineage`, `LINEAGE_BASIS_LIMIT`, `LINEAGE_EVIDENCE_LIMIT`, `LINEAGE_LIMIT`, `LINEAGE_MODEL_LIMIT`, `lineageOf`, `linkedReads`, `linkedRecordField`, `linkedRefOf`, `linkedRefsOf`, `linkedRelationOf`, `linkedRelations`, `linkedValue`, `LOCAL_BRIDGE_PATH`, `LOCAL_LAYERS`, `localeFor`, `LogHeadMovedError`, `LOGO_RULES`, `logoFor`, `logoOf`, `logoScheme`, `logSeenBy`, `luminance`, `made`, `markCites`, `markCollaborative`, `markdownField`, `markHref`, `markProblem`, `MAX_INLINE_SVG`, `meIn`, `memorySubscriptions`, `memoryViews`, `meOf`, `mintPersonId`, `minutesAsRead`, `MissingRecordError`, `MODULES_AUTHOR`, `momentAsRead`, `momentAtAGlance`, `monthAsRead`, `MOST_STANDING`, `motion`, `namedAuthors`, `nameInPassing`, `nameKey`, `nameOfAuthor`, `namesUnseen`, `nearestAct`, `NEVER_WRITTEN`, `NewerFormatError`, `nextExpiry`, `nextOccurrence`, `NO_KEPT_VIEWS`, `nodeRef`, `nodeRefArgs`, `nodeRefKinds`, `normalize`, `nounOf`, `numberAsRead`, `numbersSpelled`, `occurrences`, `offeredPlaces`, `ONE_FACE_LAYERS`, `onePerPicture`, `onPublish`, `openingOf`, `OperationLog`, `orderKinds`, `OVERVIEW_PATH`, `OVERVIEW_SLUG`, `pagesTitle`, `parseLinkedTarget`, `parseParticipant`, `PARTIAL_DAY`, `participantKey`, `passingShade`, `PastError`, `pathWithin`, `PermissionDeniedError`, `permits`, `permittedMutations`, `PERSON_SEAT`, `phoneField`, `placeField`, `placeLabel`, `placePath`, `placeSlug`, `placeTidying`, `PLAIN_WEIGHTS`, `pluralLabel`, `pluralOf`, `PRESENCE_TTL_MS`, `presenceName`, `presenceStands`, `PREVIEW_BATCH`, `primaryOf`, `PRIMITIVE_OPS`, `problemsMoved`, `profileOf`, `PROPOSE_CHANGES`, `ProposeChangesArgs`, `proposes`, `providerCan`, `PUBLISH`, `Publishing`, `readerSettings`, `readLinkedThrough`, `readsPublished`, `ReceiveError`, `recordFriction`, `recordPath`, `recordsOf`, `redact`, `REFUSAL_REASONS`, `refusalOf`, `REMOTE_PRESENCE_TTL_MS`, `REMOVED_VIEW_DAYS`, `removedLensName`, `removeMutationName`, `removeVia`, `repairPlan`, `repeatedBy`, `repeatField`, `repeatKey`, `requiredRolesOf`, `resolveKit`, `resolveModules`, `rolesOf`, `rolesWhoCould`, `RuleBudgetError`, `safeFileHref`, `samePicture`, `samePresence`, `sayIn`, `sayingIn`, `SCENE_LAYERS`, `sceneTitle`, `SchemaError`, `SCHEMES`, `SEARCH_UNASKED`, `seatLens`, `SeatLens`, `seatMark`, `seatPersonOf`, `seatsKept`, `seenBy`, `SeenOptions`, `sees`, `seesId`, `servesReaders`, `settableFields`, `sha256Hex`, `SHAPE`, `shapedRules`, `shapeOf`, `sharesItsName`, `SHIPPED_LENS_NAMES`, `SHIPPED_LENSES`, `sightedKinds`, `sightMayKeep`, `SignIn`, `signInInstead`, `snapshotHash`, `sortForGrid`, `spellingOf`, `sqlFromDatabase`, `SQLITE_TABLE_SHAPE`, `stackOf`, `Store`, `STUDIO_DOOR_PATH`, `subjectKindsOf`, `subscriberOf`, `subscriptionId`, `suggestionsMayWait`, `SuggestionVote`, `summarize`, `supportingKinds`, `svgProblem`, `symbolCut`, `SYSTEM_FONTS`, `SYSTEM_STACKS`, `takesAnId`, `tellTheWatchOfAPressRefusedByItsInput`, `tellTheWatchWhatIsUnseen`, `TEXT_PAIRS`, `textSize`, `tickEachDay`, `TIME_OF_DAY`, `timeAsRead`, `timeField`, `timeZoneFor`, `timeZoneProblem`, `touchedBy`, `touchesUnseen`, `TrackedReader`, `transformCaret`, `TYPE_TEXT`, `TYPOGRAPHY`, `typographyOf`, `UndoBlockedError`, `undoPrimitives`, `UnknownMutationError`, `unknownPrimitive`, `UnregisteredInvariantError`, `unseated`, `unseatedOp`, `unseatedSnapshot`, `UNSET`, `untilTheDayTurns`, `unwrittenFields`, `upgradeOp`, `upgradeSnapshot`, `validateGraph`, `validRepeat`, `VALUE_TYPES`, `videoField`, `videoWords`, `viewReference`, `violationKey`, `violationsTouching`, `VISITOR_PRESENCE_TTL_MS`, `Vote`, `VOTE_SUGGESTION`, `VotesOptions`, `walkKinds`, `weekdayAsRead`, `weekdayName`, `WEEKDAYS`, `WEIGHTS`, `whenAsRead`, `whyNot`, `WIRE_PROTOCOL`, `withArticle`, `WITHHELD_AUTHOR`, `WITHHELD_INTENT`, `withhold`, `withInverse`, `withMemoryRevisions`, `withValidProfile`, `wouldRun`, `Writers`, `writersOf`, `writesOf`, `writtenBy`, `z`, `zoneFor`

---

The graph, the log, the schema and the checker. Everything a Graview app declares, and the CLI that verifies it.

The page: https://graview.dev/docs/packages/core.html · Every Graview docs page, for a model: https://graview.dev/llms.txt
