@graview/core 0.1.0

package/LICENSE

@@ -0,0 +1,96 @@
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Copyright 2025-2026 En Dash Consulting

package/README.md

@@ -0,0 +1,35 @@
+# @graview/core
+
+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.
+- **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.
+- **Theme** — the token contract, the two shipped palettes, and a contrast
+  checker that measures a brand's palette before it ships.
+- **`graview check`** — reads a declaration and reports what is wrong with it,
+  in terms an agent can act on.
+
+```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, initialises 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.

package/dist/app.d.ts

@@ -0,0 +1,294 @@
+import type { ArrangementWords } from "./arrange.js";
+import type { InvariantDefinition } from "./invariants/types.js";
+import type { AnyMutationDefinition } from "./mutations/types.js";
+import type { Policy } from "./permissions/types.js";
+import type { Brand } from "./theme/types.js";
+import type { ModuleMap } from "./modules.js";
+import type { GraphSnapshot } from "./graph/types.js";
+import type { Primitive } from "./graph/primitives.js";
+import type { AnySchema } from "./schema/schema.js";
+import type { ViewRegistry } from "./views/types.js";
+/**
+ * Everything one application declares, in one object. `graview check` and
+ * the docs generator both read exactly this — an app that can be checked is
+ * an app whose whole surface is declared rather than assembled at runtime.
+ */
+/**
+ * A role bound to a node kind, an edge kind, or a field of one of the kinds
+ * another role already named.
+ *
+ * The third form arrived with the third lens. A board binds `slots` to a kind
+ * and `fill` to an edge, but `x` and `y` are FIELDS of whatever `slots` turned
+ * out to be — so the binding says which role supplies the kind, and the check
+ * can then verify the field actually exists on it. That is a stronger check
+ * than either of the first two shapes had.
+ */
+export type EntityBinding = {
+    readonly kind: string;
+} | {
+    readonly edge: string;
+}
+/**
+ * A RELATIONSHIP THAT RUNS THROUGH A NODE.
+ *
+ * One edge kind covers the relationships that are a bare edge —
+ * requirements↔deliverables, skills↔drills. It cannot express the ones
+ * where the relationship IS a thing with fields of its own: a concern is
+ * addressed by a practice, applied by a routine, which covers a ground.
+ * "Is this concern covered on this ground?" is a two-hop question with a
+ * node in the middle, and the node in the middle is not incidental — it is
+ * where the cadence and the season live.
+ *
+ * `path` is that walk, named by edge kind, from the COLUMN end to the ROW
+ * end. Each step follows an edge of that kind in either direction, because
+ * an edge has two readings and which one a domain declared is not the
+ * picture's business. The nodes passed through come back with the cell, so
+ * pressing "mosquitoes are covered in the Back Lawn" can show WHICH
+ * routine does it and when it next runs.
+ *
+ * Generalises well past one domain: controls↔risks through a policy,
+ * tests↔behaviours through a suite, staff↔shifts through a rota line.
+ * Wherever the relationship has attributes, it is a node.
+ */
+ | {
+    readonly path: readonly string[];
+} | {
+    readonly field: string;
+    readonly on: string;
+};
+export interface LensDeclaration {
+    readonly name: string;
+    readonly requiredRoles: readonly string[];
+    /**
+     * WHERE THE REUSE WAS PROVED — for a lens this app wrote.
+     *
+     * "Build it against a domain it was not designed for, and if you cannot
+     * write that test, say so plainly: you wrote a view" is the best
+     * instruction in `graview-lens` and the one nothing can check. The checker
+     * asks about every app-authored lens (`lens-authored-here`) precisely
+     * because it cannot know the answer — and a question that can only ever be
+     * acknowledged is one people learn to scroll past, which is what the note
+     * severity exists to avoid.
+     *
+     * So the declaration answers it. A path to the test that builds this lens
+     * in another domain quiets the note and appears in `graview describe`,
+     * where a reader can go and look. It is a claim the author makes, like
+     * every `description` here; what it buys is that the claim is written down
+     * next to the thing it is about, rather than remembered.
+     */
+    readonly provenBy?: string;
+    /** Defaults to `fields`, which is what every lens did before there were two. */
+    readonly binds?: "fields" | "entities";
+    /**
+     * What the picture opens arranged by, in the arrangement grammar —
+     * `{ group: "held-at", filter: "is:current" }` — so the checker can hold
+     * it to the bound kind's declaration and `describe` can say it. The lens
+     * options carry the same words to the picture (`arrangedBy`).
+     */
+    readonly arrangedBy?: ArrangementWords;
+    readonly bindings?: Readonly<Record<string, Readonly<Record<string, string>>>> | Readonly<Record<string, EntityBinding>>;
+}
+export interface GraviewApp<S extends AnySchema = AnySchema> {
+    readonly name: string;
+    readonly schema: S;
+    readonly mutations?: readonly AnyMutationDefinition<S>[];
+    readonly invariants?: readonly InvariantDefinition<S>[];
+    readonly views?: ViewRegistry<S, unknown>;
+    /**
+     * Roles a lens requires an app to bind, and what it binds them to.
+     *
+     * Two shapes, because there turned out to be two kinds of lens. A `fields`
+     * lens maps a KIND's own field names onto its roles — the timeline asks an
+     * app which of its fields are `start` and `end`. An `entities` lens maps
+     * roles onto whole kinds and edges — the coverage matrix asks which kind is
+     * the rows, which is the columns, and which edge fills a cell.
+     *
+     * The first shape was assumed to be the only one until a second lens
+     * existed, which is the usual way that assumption gets found.
+     */
+    readonly lenses?: readonly LensDeclaration[];
+    /**
+     * Who may run what. Declared on the app so `graview check` can read it —
+     * a mutation no role can ever run and a role that may do nothing are both
+     * mistakes in the declaration, findable before anyone meets a button they
+     * cannot press.
+     */
+    readonly policy?: Policy;
+    /**
+     * The name, the palette and the typography this installation wears.
+     *
+     * Declared so `graview check` can verify it: a custom palette can be wrong
+     * in ways nobody notices — a secondary colour that clears 4.5:1 on a dark
+     * ground and fails badly on paper — and contrast is a property the
+     * framework can measure rather than trust.
+     */
+    readonly brand?: Brand;
+    /**
+     * Named parts of the declaration a workspace can turn on and off.
+     *
+     * Declared on the app so `graview check` can hold the boundaries: a
+     * module naming a kind nobody declared, a requirement naming a module
+     * nobody wrote, or an always-on kind whose edge reaches into a module —
+     * a line that would dangle the moment someone turns that module off.
+     */
+    readonly modules?: ModuleMap;
+    /**
+     * The intelligence this installation runs on, declared.
+     *
+     * Three kinds share one seam: `graph` (structural derivations, no model),
+     * `llm` (a model behind one completion function), `external` (someone
+     * else's agent over the derived tool surface). `may` narrows a provider
+     * to named mutations — the allowlist `graview check` can verify and a
+     * hosted deployment can meter. "Add AI" is an entry here, never a second
+     * path to the store.
+     */
+    readonly intelligence?: readonly IntelligenceProviderDeclaration[];
+    /**
+     * The declaration's data-schema version, and the migrations that carry a
+     * stored graph forward through it.
+     *
+     * OP-LOG-NATIVE on purpose: a migration answers with primitives — the
+     * same vocabulary every other change speaks — so applying one is itself
+     * logged, attributed, and invertible (a patch carries its before). The
+     * `ship` engine runs them; `graview check` verifies the chain reaches
+     * this version with no gaps, because a migration discovered missing at
+     * deploy time is the most expensive place to discover it.
+     */
+    readonly version?: number;
+    readonly migrations?: readonly MigrationDeclaration[];
+    /**
+     * Settings that belong to the READER rather than to the installation.
+     *
+     * Text size, motion, anything else a person sets for themselves and keeps
+     * in their own browser. Declared here for the same reason everything else
+     * is: the profile pane draws exactly what the app declares, so adding a
+     * setting is a line in the declaration rather than a control somebody
+     * wires into a shell — and `graview check` can refuse one nothing could
+     * ever honour, which is a control that does nothing.
+     */
+    readonly settings?: readonly SettingDeclaration[];
+}
+/**
+ * One thing a reader may set for themselves.
+ *
+ * `honoured` is a CLOSED SET, and that is the point of declaring settings
+ * at all: the shell knows two ways to carry a person's answer to every
+ * surface at once, and a setting that names neither is a control nobody
+ * could act on. The checker says so before anybody meets it.
+ *
+ *   "root-font-size"  — a CSS length set on <html>. Every surface the
+ *                       framework draws is sized in `rem`, so one answer
+ *                       resizes the whole app, the routed face included,
+ *                       without a single component hearing about it.
+ *   "root-attribute"  — `data-graview-<name>` on <html>, for the theme's
+ *                       own CSS (and an app's) to read. How motion is
+ *                       carried: the stylesheet already honours the
+ *                       system's preference; this lets a person override it.
+ */
+export interface SettingDeclaration {
+    /** Kebab-case, unique in the app; becomes the storage key and the attribute. */
+    readonly name: string;
+    /** What a person is choosing, in their words. */
+    readonly title: string;
+    readonly description?: string;
+    readonly honoured: "root-font-size" | "root-attribute";
+    /** The answers, in order. At least two — one choice is not a setting. */
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** Where a reader who has never chosen starts. Must be one of the options. */
+    readonly initial: string;
+}
+export interface MigrationDeclaration {
+    readonly from: number;
+    readonly to: number;
+    readonly title: string;
+    /** Primitives that carry a `from`-shaped stored graph to `to`. */
+    readonly apply: (snapshot: GraphSnapshot) => readonly Primitive[];
+}
+/**
+ * THE FOUR DOORS a browser app has to a model.
+ *
+ *   "paste"  — a prompt to copy out and an answer to paste back. Works
+ *              everywhere, needs nothing, and is the floor every provider
+ *              should keep: a person with a model open in another tab.
+ *   "mcp"    — an assistant already holding the tool surface reaches in.
+ *   "key"    — the person's own key, typed into this browser. Whoever
+ *              declares this owes an answer about where the key lives.
+ *   "local"  — a process on this machine, spawned by the dev server and
+ *              called from the page. Free, private, and only ever there
+ *              while somebody is running the app from a terminal.
+ */
+export type IntelligenceReach = "paste" | "mcp" | "key" | "local";
+/**
+ * WHAT KIND OF THING ANSWERS.
+ *
+ *   "graph"    — the declaration itself: starter data and the repairs an
+ *                invariant already named. Keyless, always there.
+ *   "llm"      — a model reached through one completion function. Prose in,
+ *                prose out, proposals read out of the prose.
+ *   "external" — somebody's own agent, arriving over the derived tool
+ *                surface with its own model behind it.
+ *   "decision" — a model that answers TYPED questions and nothing else: a
+ *                Choice over named options, a Score over an ordered rubric,
+ *                a truth with a confidence. It writes no prose and cannot
+ *                propose an arbitrary call, so a chat seat must not offer
+ *                it, a field that wants filling should, and the checker
+ *                refuses it an act whose arguments it could not decide.
+ */
+export type IntelligenceKind = "graph" | "llm" | "external" | "decision";
+/** What a provider of some kind can be asked for. */
+export type IntelligenceCapability = "prose" | "decide" | "propose";
+/**
+ * The capabilities each kind serves, derived from the kind alone — so a
+ * surface asks whether a provider CAN before it offers one, rather than
+ * remembering which names talk.
+ */
+export declare function providerCan(provider: {
+    readonly kind: IntelligenceKind;
+}, capability: IntelligenceCapability): boolean;
+/**
+ * THE LADDER HAS TWO AXES, and this is the table that keeps a switch from
+ * lying about it. Prose is one axis — a Responder answers in it, and a
+ * decision provider has none. A decision is the other — which surface is
+ * this, does this practice address that concern — and it can be answered
+ * by the graph's own rules, by a decision provider exactly, or by a model
+ * with the whole parse-and-refuse layer behind it. A kind declares which
+ * it serves; a surface asks for a capability, never for a kind; and what a
+ * kind cannot serve falls down to the graph, which is keyless and always
+ * there.
+ */
+export declare function capabilitiesOf(kind: IntelligenceKind): readonly IntelligenceCapability[];
+/** What a capability is for, in a reader's words. */
+export declare function describeCapability(capability: IntelligenceCapability): string;
+export interface IntelligenceProviderDeclaration {
+    readonly name: string;
+    readonly kind: IntelligenceKind;
+    readonly description?: string;
+    /** Mutation names this provider may propose or call. Absent means all. */
+    readonly may?: readonly string[];
+    /**
+     * How words and photographs actually REACH this provider.
+     *
+     * A provider could be named and bounded and not reached: the declaration
+     * said what a model may do and nothing about how a person's photograph
+     * gets to it, so nothing derived from it could say either — a seat could
+     * not offer "send from here" or "copy the prompt" according to what was
+     * declared, the checker could not ask a keyed provider where its key
+     * lives, and the docs could not list the doors. Absent means the provider
+     * says nothing about its doors, which is what every app said until now.
+     */
+    readonly reach?: readonly IntelligenceReach[];
+    /**
+     * Where a `local` reach answers: the dev-server path the bridge serves.
+     *
+     * Named here so the same string is the checker's evidence that a local
+     * reach was actually wired, and the path `useLocalIntelligence()` probes.
+     */
+    readonly bridge?: string;
+    /** Where a `key` reach keeps the key, in the app's own words. */
+    readonly keyStorage?: string;
+}
+export declare function defineApp<S extends AnySchema>(app: GraviewApp<S>): GraviewApp<S>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -0,0 +1,49 @@
+/**
+ * The capabilities each kind serves, derived from the kind alone — so a
+ * surface asks whether a provider CAN before it offers one, rather than
+ * remembering which names talk.
+ */
+export function providerCan(provider, capability) {
+    return capabilitiesOf(provider.kind).includes(capability);
+}
+/**
+ * THE LADDER HAS TWO AXES, and this is the table that keeps a switch from
+ * lying about it. Prose is one axis — a Responder answers in it, and a
+ * decision provider has none. A decision is the other — which surface is
+ * this, does this practice address that concern — and it can be answered
+ * by the graph's own rules, by a decision provider exactly, or by a model
+ * with the whole parse-and-refuse layer behind it. A kind declares which
+ * it serves; a surface asks for a capability, never for a kind; and what a
+ * kind cannot serve falls down to the graph, which is keyless and always
+ * there.
+ */
+export function capabilitiesOf(kind) {
+    switch (kind) {
+        case "graph":
+            return ["decide", "propose"];
+        case "decision":
+            return ["decide"];
+        case "llm":
+        case "external":
+            return ["prose", "decide", "propose"];
+        default:
+            return [];
+    }
+}
+/** What a capability is for, in a reader's words. */
+export function describeCapability(capability) {
+    switch (capability) {
+        case "prose":
+            return "talks — answers in sentences";
+        case "decide":
+            return "decides — answers a typed question with a confidence";
+        case "propose":
+            return "proposes — offers calls to declared acts";
+        default:
+            return capability;
+    }
+}
+export function defineApp(app) {
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAoPA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,QAA6C,EAC7C,UAAkC;IAElC,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAsB;IACnD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC/B,KAAK,UAAU;YACb,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU;YACb,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QACxC;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAAC,UAAkC;IACnE,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,OAAO;YACV,OAAO,8BAA8B,CAAC;QACxC,KAAK,QAAQ;YACX,OAAO,sDAAsD,CAAC;QAChE,KAAK,SAAS;YACZ,OAAO,0CAA0C,CAAC;QACpD;YACE,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AA+BD,MAAM,UAAU,SAAS,CAAsB,GAAkB;IAC/D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/arrange.d.ts

@@ -0,0 +1,185 @@
+import type { AnySchema } from "./schema/schema.js";
+/**
+ * ARRANGEMENT IS A CAPABILITY OF THE DECLARATION, not of a view.
+ *
+ * Every surface that lists things arranges them, and each did it its own
+ * way or not at all: the list page grouped by an edge through a URL key of
+ * its own, the districts sorted by id, the board and the calendar took no
+ * sort, filter or group whatever. What a kind CAN be arranged by is already
+ * written down — its fields have types, its edges have far ends, its
+ * lifecycle names the past, the rules name what is flagged — so the offers
+ * are derived here once, headless, and the same string carries the chosen
+ * arrangement in a stop's fragment (`in.sort`, `in.filter`, `in.group`) and
+ * in a page's search, so an arranged picture is a link.
+ */
+export type SortDirection = "asc" | "desc";
+export interface Sort {
+    /** `label`, a field name, or an edge kind (by the far end's label). */
+    readonly by: string;
+    readonly direction: SortDirection;
+}
+/**
+ * One condition; a filter is the conjunction of several.
+ *
+ * `key` is a field name, an edge kind, or `is`. The value's grammar depends
+ * on the key: a boolean or enum field takes one of its values; a date field
+ * takes `before:<date>`, `after:<date>` or `on:<date>`; an edge takes a
+ * node id, `*` (tied to anything) or `none`; `is` takes `current`, `past`,
+ * `any`, `flagged` or `clear`. Anything else is dropped, not thrown.
+ */
+export interface Condition {
+    readonly key: string;
+    readonly value: string;
+}
+/** How wide a date group is. A year and a decade are what a catalogue of thirty years reads by. */
+export type DateBucket = "day" | "week" | "month" | "year" | "decade";
+export interface Grouping {
+    /** A field name or an edge kind. */
+    readonly by: string;
+    /** For a date field: how wide a group is. Day when unsaid. */
+    readonly bucket?: DateBucket;
+}
+export interface Arrangement {
+    readonly sort?: Sort;
+    readonly filter?: readonly Condition[];
+    readonly group?: Grouping;
+    /**
+     * Words to look for: a node stays when its label or any scalar field
+     * contains them, case aside. The narrowing a person types, beside the
+     * conditions a person picks — and the same matcher a search would use.
+     */
+    readonly query?: string;
+}
+export declare const NO_ARRANGEMENT: Arrangement;
+/** What a lens says to decline arrangement, wholly or a part at a time. */
+export type ArrangeOption = boolean | {
+    readonly sort?: boolean;
+    readonly filter?: boolean;
+    readonly group?: boolean;
+};
+/** Whether a lens offers a part, given what it declared. Everything is on unless declined. */
+export declare function arrangeAllows(option: ArrangeOption | undefined, part: "sort" | "filter" | "group"): boolean;
+export type OfferType = "text" | "number" | "date" | "boolean" | "choice";
+/** One thing a kind can be sorted, filtered or grouped by, in the declaration's own words. */
+export interface ArrangeOffer {
+    readonly key: string;
+    /** The words for it: the field's reading, the edge kind humanised, or the reserved word's sentence. */
+    readonly label: string;
+    readonly about: "label" | "field" | "edge" | "is";
+    readonly type?: OfferType;
+    /** For a choice field, its options; for `is`, its words; for an edge, nothing — the far ends are the graph's. */
+    readonly options?: readonly string[];
+    /** For a date field, how it may be bucketed when grouped. */
+    readonly buckets?: readonly DateBucket[];
+    /** For an edge: the kinds at the far end, and how it reads from this kind. */
+    readonly far?: readonly string[];
+}
+export interface Arrangeable {
+    readonly kind: string;
+    readonly sorts: readonly ArrangeOffer[];
+    readonly filters: readonly ArrangeOffer[];
+    readonly groups: readonly ArrangeOffer[];
+    /** The kind's natural order, when `fieldRoles.order` names one. */
+    readonly natural?: Sort;
+}
+/** The edges this kind takes part in, from either end, with how each reads from here. */
+export declare function edgesOf(schema: AnySchema, kind: string): readonly ArrangeOffer[];
+/**
+ * Whether a condition names one of a kind's RETIRED states — `status:demo`
+ * where demos are behind the horizon — which is asking for the past by
+ * name. The search box and the list page both left the past out for it and
+ * found nothing.
+ */
+export declare function asksForThePast(definition: {
+    readonly lifecycle?: {
+        readonly field: string;
+        readonly retired: readonly unknown[] | "date";
+    };
+} | undefined, conditions: readonly {
+    readonly key: string;
+    readonly value: string;
+}[]): boolean;
+/**
+ * What a kind can be arranged by, derived from its declaration alone.
+ *
+ * Sorts: the label, every field with a scalar type, every edge (by the far
+ * end's label). Filters: boolean and choice fields by value, date fields by
+ * before/after/on, every edge by a node or by having one at all, and `is`
+ * for the lifecycle and the standing. Groups: boolean and choice fields,
+ * date fields by day, week or month, and every edge by its far end. A field
+ * the declaration hides is not offered — an ordering key is not a thing a
+ * person groups by.
+ */
+export declare function arrangeable(schema: AnySchema, kind: string): Arrangeable;
+export interface ArrangementWords {
+    readonly sort?: string;
+    readonly filter?: string;
+    readonly group?: string;
+    readonly q?: string;
+}
+export declare function parseArrangement(words: ArrangementWords): Arrangement;
+export declare function formatArrangement(arrangement: Arrangement): ArrangementWords;
+/**
+ * Keeps only the parts a kind can actually be arranged by, and says which
+ * were dropped — a stale link names a field that was renamed, and the
+ * honest thing is to show the rest arranged and say what was ignored.
+ */
+export declare function admitArrangement(arrangement: Arrangement, offers: Arrangeable): {
+    readonly arrangement: Arrangement;
+    readonly dropped: readonly string[];
+};
+/** What arranging needs of a node: its identity. Fields are read off it by name. */
+export type ArrangeNode = {
+    readonly id: string;
+    readonly kind: string;
+};
+/**
+ * The little of a graph arranging needs, said structurally so a `Graph<S>`
+ * over any concrete schema fits — `GraphReader`'s generic `nodesOfKind`
+ * does not, once the kinds are literal.
+ */
+export interface ArrangeGraph {
+    getNode(id: string): ArrangeNode | undefined;
+    allNodes(): readonly ArrangeNode[];
+    out(id: string, kind?: string): readonly ArrangeNode[];
+    in(id: string, kind?: string): readonly ArrangeNode[];
+}
+export interface ArrangeContext {
+    readonly schema: AnySchema;
+    readonly graph: ArrangeGraph;
+    /** Node ids the rules currently implicate, for `is:flagged` and `is:clear`. */
+    readonly flagged?: ReadonlySet<string>;
+    /** For the lifecycle: today, as YYYY-MM-DD. */
+    readonly today?: string;
+}
+export interface ArrangedGroup<N extends ArrangeNode = ArrangeNode> {
+    /** Stable, sortable: the value, the date bucket's first day, the far end's id, or `` for none. */
+    readonly key: string;
+    /** The words for the group: a value as it reads, a date, a far end's label, or "No <reading>". */
+    readonly label: string;
+    readonly nodes: readonly N[];
+}
+export interface Arranged<N extends ArrangeNode = ArrangeNode> {
+    /** The nodes that passed the filter, in order. */
+    readonly nodes: readonly N[];
+    /** The same nodes, grouped when a grouping was asked; one unnamed group otherwise. */
+    readonly groups: readonly ArrangedGroup<N>[];
+    readonly grouped: boolean;
+}
+/** The first day of the bucket a date falls in, as YYYY-MM-DD; weeks start on Monday, in UTC. */
+export declare function bucketStart(date: string, bucket: DateBucket): string | undefined;
+/** Whether a node meets one condition of a filter. Search judges its `key:value` tokens with this too. */
+export declare function conditionHolds(ctx: ArrangeContext, node: ArrangeNode, condition: Condition): boolean;
+/**
+ * Whether the words find the node — search's own matcher, so a list's `q`
+ * and the Find box never disagree: every word the start of a word in the
+ * label or a readable field, case, diacritics and punctuation aside.
+ */
+export declare function matches(ctx: ArrangeContext, node: ArrangeNode, query: string): boolean;
+/**
+ * Filters, sorts and groups. The filter is a conjunction; the sort is
+ * stable; a grouping puts the group with nothing to say last. Nodes whose
+ * kind the context cannot describe are kept and sort by what they carry.
+ */
+export declare function arrange<N extends ArrangeNode>(nodes: readonly N[], arrangement: Arrangement, ctx: ArrangeContext): Arranged<N>;
+//# sourceMappingURL=arrange.d.ts.map