@graview/core 0.1.0

package/dist/sync/types.d.ts

@@ -0,0 +1,125 @@
+import type { Author } from "../ops/types.js";
+/**
+ * How one node kind corresponds to one external resource.
+ *
+ * Declarative, the way a lens binds roles rather than field names: an app says
+ * "a block IS an event, and its start is `dtstart`", and the engine does the
+ * rest. No app writes per-field sync code, because per-field sync code is
+ * where two-way sync goes wrong — it is written once per field, drifts once
+ * per field, and fails silently once per field.
+ */
+export interface ResourceMapping {
+    /** The node kind on our side. */
+    readonly kind: string;
+    /** What the remote calls this thing. */
+    readonly resource: string;
+    /**
+     * Our field name → theirs. Only what is mapped is synced; anything else is
+     * ours alone and is never sent, which is the difference between syncing and
+     * replicating.
+     */
+    readonly fields: Readonly<Record<string, string>>;
+    /**
+     * Narrows which nodes of the kind participate. A household's shifts may
+     * belong on a calendar while its naps do not.
+     */
+    readonly match?: (node: Record<string, unknown>) => boolean;
+    /**
+     * Fields we will send but never accept back. Useful where the remote
+     * rewrites something on save — Google normalises a timezone — and echoing
+     * that back as "someone changed it" would start a loop.
+     */
+    readonly ours?: readonly string[];
+    /**
+     * Where the two systems disagree about REPRESENTATION, not about names.
+     *
+     * A mapping is a rename, plus this. The household example stores a block's start as
+     * minutes since midnight, and Google wants an RFC 3339 datetime; pretending
+     * a rename is enough is how a sync layer ships a field full of nonsense and
+     * finds out from a user. Keyed by OUR field name, both directions.
+     *
+     * `encode` also receives the node, because a conversion often needs a
+     * sibling field — minutes are meaningless without a date.
+     */
+    readonly encode?: Readonly<Record<string, (value: unknown, node: Record<string, unknown>) => unknown>>;
+    readonly decode?: Readonly<Record<string, (value: unknown) => unknown>>;
+}
+export interface SyncMapping {
+    /** Names the system, and appears as the author of every inbound change. */
+    readonly system: string;
+    readonly resources: readonly ResourceMapping[];
+}
+/** One thing the remote says changed. */
+export interface RemoteChange {
+    readonly resource: string;
+    /** The remote's own id. */
+    readonly id: string;
+    /**
+     * The remote's version of this record — an etag, a sequence number, a
+     * timestamp. This is what makes an echo recognisable, so a remote that has
+     * none cannot be synced two-way safely and the engine says so.
+     */
+    readonly version: string;
+    /** Absent when the record was deleted remotely. */
+    readonly fields?: Readonly<Record<string, unknown>>;
+    readonly deleted?: boolean;
+}
+/** One thing we want the remote to do. */
+export interface RemoteWrite {
+    readonly resource: string;
+    /** Absent when we are creating; the engine learns the id from the ack. */
+    readonly id?: string;
+    /** Our node id, so the ack can be matched back without guessing. */
+    readonly localId: string;
+    readonly fields?: Readonly<Record<string, unknown>>;
+    readonly deleted?: boolean;
+}
+/** What the remote did with a write, and the version it produced. */
+export interface RemoteAck {
+    readonly localId: string;
+    readonly id: string;
+    readonly version: string;
+    /** Set when the remote refused. The engine keeps the local state and says so. */
+    readonly error?: string;
+}
+/**
+ * The transport. Everything Google-specific, or Notion-specific, lives behind
+ * these three methods.
+ */
+export interface RemoteSystem {
+    readonly name: string;
+    /**
+     * Everything that changed since `cursor`, and a new cursor. A remote with
+     * no incremental API returns everything and a constant cursor; the engine
+     * still behaves, it just does more work.
+     */
+    pull(cursor?: string): Promise<{
+        readonly changes: readonly RemoteChange[];
+        readonly cursor: string;
+    }>;
+    push(writes: readonly RemoteWrite[]): Promise<readonly RemoteAck[]>;
+}
+/** What the engine remembers between runs. */
+export interface SyncState {
+    readonly cursor?: string;
+    /** Local id → what the remote knows about it. */
+    readonly links: Readonly<Record<string, RemoteLink>>;
+    /** Writes that have not reached the remote yet. */
+    readonly outbox: readonly RemoteWrite[];
+}
+export interface RemoteLink {
+    readonly resource: string;
+    readonly id: string;
+    /**
+     * The last version WE caused. An inbound change carrying this version is
+     * our own write coming back, and re-applying it is how a naive two-way sync
+     * starts a loop.
+     */
+    readonly version: string;
+    /** The mapped values as of that version, so a genuine conflict is detectable. */
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+export declare const EMPTY_SYNC_STATE: SyncState;
+/** The author every inbound change is attributed to. */
+export declare function systemAuthor(system: string): Author;
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

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

package/dist/sync/types.js

@@ -0,0 +1,6 @@
+export const EMPTY_SYNC_STATE = { links: {}, outbox: [] };
+/** The author every inbound change is attributed to. */
+export function systemAuthor(system) {
+    return { kind: "system", id: system };
+}
+//# sourceMappingURL=types.js.map

package/dist/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAoIA,MAAM,CAAC,MAAM,gBAAgB,GAAc,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAErE,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/temporal/effectivity.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * WHEN something is true, as a construct the framework owns rather than one
+ * each domain invents.
+ *
+ * Two apps arrived at the same idea from different directions. A household has
+ * agreements that come into force and later lapse, and blocks whose recurrence
+ * started in September. A club has a team you picked FOR a fixture — the
+ * eleven that were true on the fourteenth, not the eleven that are true now.
+ * Both are the same question: as of when?
+ *
+ * Left alone they would have become two constructs with different field names
+ * and slightly different edge semantics, and a lens or a rule that wanted to
+ * ask "was this true then" would have had to know which app it was in.
+ */
+/** A calendar day, `YYYY-MM-DD`. Not a timestamp: effectivity is a day question. */
+export declare const isoDate: z.ZodString;
+/**
+ * The fields a kind spreads into its own to become temporal.
+ *
+ * Half-open on purpose: `effectiveFrom` includes its day, `effectiveUntil`
+ * excludes it. That is the only convention under which two consecutive
+ * versions of a thing do not both hold on the day they change over, and
+ * getting it wrong is invisible until the one day of the year it matters.
+ */
+export declare const effectivity: {
+    effectiveFrom: z.ZodOptional<z.ZodString>;
+    effectiveUntil: z.ZodOptional<z.ZodString>;
+};
+export interface Effectivity {
+    readonly effectiveFrom?: string | undefined;
+    readonly effectiveUntil?: string | undefined;
+}
+/** Whether something holds on a given day. */
+export declare function isEffectiveOn(node: Effectivity, date: string): boolean;
+/** Whether something holds at any point in `[from, until)`. */
+export declare function isEffectiveBetween(node: Effectivity, from: string, until: string): boolean;
+/**
+ * A CHECKPOINT: a moment a selection is true as of.
+ *
+ * This is the construct the framework had avoided, and the reason to admit it
+ * is that the alternative is worse. A team picked for a fixture is a
+ * relationship between three things — this player, in this position, for this
+ * match — and a graph of nodes and edges has no ternary relation.
+ *
+ * The honest options were: a ternary relation (a new primitive, and every
+ * traversal, lens and rule learns about it), or a NODE standing for the moment,
+ * with ordinary binary edges to it. The second is what this is, and it is not
+ * a workaround: the moment is a real thing in the domain. A coach talks about
+ * "the team for Saturday" as an object — names it, changes it, compares it to
+ * last week's. Reifying it is admitting what was already true.
+ *
+ * A checkpoint is any node carrying `at`. What it means to be selected AS OF
+ * it is the app's business; what the framework guarantees is one shape.
+ */
+export declare const checkpoint: {
+    /** The day this checkpoint stands for. */
+    at: z.ZodString;
+};
+export interface Checkpoint {
+    readonly id: string;
+    readonly at: string;
+}
+/**
+ * The checkpoint in force on a day: the latest one at or before it.
+ *
+ * "In force" rather than "matching", because a selection made for the
+ * fourteenth is still what was true on the fifteenth if nobody has picked a
+ * new one — and a lookup that returned nothing on any day without its own
+ * checkpoint would make every question about a Tuesday unanswerable.
+ */
+export declare function checkpointOn<C extends Checkpoint>(checkpoints: readonly C[], date: string): C | undefined;
+/** Every checkpoint within `[from, until)`, in order. */
+export declare function checkpointsBetween<C extends Checkpoint>(checkpoints: readonly C[], from: string, until: string): readonly C[];
+//# sourceMappingURL=effectivity.d.ts.map

package/dist/temporal/effectivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectivity.d.ts","sourceRoot":"","sources":["../../src/temporal/effectivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,eAAO,MAAM,OAAO,aAEkC,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;CAGvB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAItE;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;IACrB,0CAA0C;;CAE3C,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC/C,WAAW,EAAE,SAAS,CAAC,EAAE,EACzB,IAAI,EAAE,MAAM,GACX,CAAC,GAAG,SAAS,CAIf;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,UAAU,EACrD,WAAW,EAAE,SAAS,CAAC,EAAE,EACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,EAAE,CAId"}

package/dist/temporal/effectivity.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+/**
+ * WHEN something is true, as a construct the framework owns rather than one
+ * each domain invents.
+ *
+ * Two apps arrived at the same idea from different directions. A household has
+ * agreements that come into force and later lapse, and blocks whose recurrence
+ * started in September. A club has a team you picked FOR a fixture — the
+ * eleven that were true on the fourteenth, not the eleven that are true now.
+ * Both are the same question: as of when?
+ *
+ * Left alone they would have become two constructs with different field names
+ * and slightly different edge semantics, and a lens or a rule that wanted to
+ * ask "was this true then" would have had to know which app it was in.
+ */
+/** A calendar day, `YYYY-MM-DD`. Not a timestamp: effectivity is a day question. */
+export const isoDate = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "expected YYYY-MM-DD");
+/**
+ * The fields a kind spreads into its own to become temporal.
+ *
+ * Half-open on purpose: `effectiveFrom` includes its day, `effectiveUntil`
+ * excludes it. That is the only convention under which two consecutive
+ * versions of a thing do not both hold on the day they change over, and
+ * getting it wrong is invisible until the one day of the year it matters.
+ */
+export const effectivity = {
+    effectiveFrom: isoDate.optional(),
+    effectiveUntil: isoDate.optional(),
+};
+/** Whether something holds on a given day. */
+export function isEffectiveOn(node, date) {
+    if (node.effectiveFrom && date < node.effectiveFrom)
+        return false;
+    if (node.effectiveUntil && date >= node.effectiveUntil)
+        return false;
+    return true;
+}
+/** Whether something holds at any point in `[from, until)`. */
+export function isEffectiveBetween(node, from, until) {
+    if (node.effectiveFrom && node.effectiveFrom >= until)
+        return false;
+    if (node.effectiveUntil && node.effectiveUntil <= from)
+        return false;
+    return true;
+}
+/**
+ * A CHECKPOINT: a moment a selection is true as of.
+ *
+ * This is the construct the framework had avoided, and the reason to admit it
+ * is that the alternative is worse. A team picked for a fixture is a
+ * relationship between three things — this player, in this position, for this
+ * match — and a graph of nodes and edges has no ternary relation.
+ *
+ * The honest options were: a ternary relation (a new primitive, and every
+ * traversal, lens and rule learns about it), or a NODE standing for the moment,
+ * with ordinary binary edges to it. The second is what this is, and it is not
+ * a workaround: the moment is a real thing in the domain. A coach talks about
+ * "the team for Saturday" as an object — names it, changes it, compares it to
+ * last week's. Reifying it is admitting what was already true.
+ *
+ * A checkpoint is any node carrying `at`. What it means to be selected AS OF
+ * it is the app's business; what the framework guarantees is one shape.
+ */
+export const checkpoint = {
+    /** The day this checkpoint stands for. */
+    at: isoDate,
+};
+/**
+ * The checkpoint in force on a day: the latest one at or before it.
+ *
+ * "In force" rather than "matching", because a selection made for the
+ * fourteenth is still what was true on the fifteenth if nobody has picked a
+ * new one — and a lookup that returned nothing on any day without its own
+ * checkpoint would make every question about a Tuesday unanswerable.
+ */
+export function checkpointOn(checkpoints, date) {
+    return [...checkpoints]
+        .filter((candidate) => candidate.at <= date)
+        .sort((a, b) => b.at.localeCompare(a.at))[0];
+}
+/** Every checkpoint within `[from, until)`, in order. */
+export function checkpointsBetween(checkpoints, from, until) {
+    return [...checkpoints]
+        .filter((candidate) => candidate.at >= from && candidate.at < until)
+        .sort((a, b) => a.at.localeCompare(b.at));
+}
+//# sourceMappingURL=effectivity.js.map

package/dist/temporal/effectivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectivity.js","sourceRoot":"","sources":["../../src/temporal/effectivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC;KACrB,MAAM,EAAE;KACR,KAAK,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa,EAAE,OAAO,CAAC,QAAQ,EAAE;IACjC,cAAc,EAAE,OAAO,CAAC,QAAQ,EAAE;CACnC,CAAC;AAOF,8CAA8C;AAC9C,MAAM,UAAU,aAAa,CAAC,IAAiB,EAAE,IAAY;IAC3D,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,GAAG,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IAClE,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,IAAI,IAAI,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAChC,IAAiB,EACjB,IAAY,EACZ,KAAa;IAEb,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACpE,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,EAAE,EAAE,OAAO;CACZ,CAAC;AAOF;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAyB,EACzB,IAAY;IAEZ,OAAO,CAAC,GAAG,WAAW,CAAC;SACpB,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,CAAC;SAC3C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAChC,WAAyB,EACzB,IAAY,EACZ,KAAa;IAEb,OAAO,CAAC,GAAG,WAAW,CAAC;SACpB,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,IAAI,SAAS,CAAC,EAAE,GAAG,KAAK,CAAC;SACnE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,63 @@
+import { type GraviewApp } from "./app.js";
+import type { GraphSnapshot } from "./graph/types.js";
+/**
+ * A DECLARATION BUILT TO BE AWKWARD.
+ *
+ * The framework derives an interface from a declaration, so the framework's
+ * correctness IS the derivation's correctness — and the derivation was only
+ * ever tested against the three apps in this repository, all of which have
+ * four or five kinds, short plurals, no chain worth the name, and people who
+ * are not part of the domain. A second product with ten kinds found thirty
+ * of the consequences in an afternoon, and every one of them was the same
+ * sentence: this holds for the examples and stops just past them.
+ *
+ * So: a generator of the shapes the examples never had, and properties
+ * asserted over the derivations rather than screenshots taken of three apps.
+ * It ships rather than hiding in a test directory because a PRODUCT wants it
+ * too — a lens claiming to be reusable can be built against this, and an
+ * app's own views can be held to the same properties as the framework's.
+ *
+ * Nothing here is random. A generated declaration is a pure function of its
+ * options, so a property that fails names a shape rather than a seed.
+ */
+export interface AwkwardOptions {
+    /** How many domain kinds. The examples have four; real domains have ten. */
+    readonly kinds?: number;
+    /**
+     * Whether each kind's creating act needs the one before it — the chain
+     * that makes a blank installation a queue rather than a menu.
+     */
+    readonly chain?: boolean;
+    /** Include the installation's kinds, and an edge from the domain to a person. */
+    readonly people?: boolean;
+    /** A kind nothing creates: the catalogue that arrives with the data. */
+    readonly unreachable?: boolean;
+    /** Plural length. Long ones are what a district row actually has to hold. */
+    readonly plurals?: "short" | "long";
+}
+/**
+ * An app of the shape a real product has: several kinds, a chain between
+ * them, people in the domain, and a kind nothing can make.
+ */
+export declare function awkwardApp(options?: AwkwardOptions): GraviewApp;
+/**
+ * Three of every kind, joined to nothing, every field filled with the least
+ * interesting value that parses.
+ *
+ * It is the state a real installation passes through on its second
+ * afternoon — some ground named, some concerns raised, none of it joined up
+ * — and it is the state that breaks anything written while looking at a
+ * finished graph.
+ */
+export interface AwkwardGraphOptions {
+    readonly per?: number;
+    /**
+     * Values for fields this cannot guess — a discriminated union, a tuple
+     * with a meaning. Keyed `kind.field`, and each is offered to the field's
+     * own schema like any other candidate, so a wrong one is a refusal here
+     * rather than a mystery three layers down.
+     */
+    readonly fill?: Readonly<Record<string, unknown>>;
+}
+export declare function awkwardGraph(app: GraviewApp, options?: number | AwkwardGraphOptions): GraphSnapshot;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAMtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACrC;AA6CD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,cAAmB,GAAG,UAAU,CAuEnE;AA6CD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,MAAM,GAAG,mBAAwB,GAAG,aAAa,CA+BvG"}

package/dist/testing.js

@@ -0,0 +1,194 @@
+import { z } from "zod";
+import { defineApp } from "./app.js";
+import { declareInstallation } from "./installation.js";
+import { bindSchema } from "./bind.js";
+import { nodeRef } from "./mutations/node-ref.js";
+import { createSchema } from "./schema/schema.js";
+import { defineNode } from "./schema/define-node.js";
+/* Plurals of the length a real domain has. The district row breaks on these
+   and never on "Jobs", which is why the examples never found it. */
+const LONG = [
+    ["responsibility", "Responsibilities"],
+    ["consideration", "Considerations"],
+    ["practicality", "Practicalities"],
+    ["arrangement", "Arrangements"],
+    ["requirement", "Requirements"],
+    ["observation", "Observations"],
+    ["preparation", "Preparations"],
+    ["description", "Descriptions"],
+    ["measurement", "Measurements"],
+    ["instruction", "Instructions"],
+    ["expectation", "Expectations"],
+    ["certification", "Certifications"],
+    ["qualification", "Qualifications"],
+    ["recommendation", "Recommendations"],
+];
+const SHORT = [
+    ["zone", "Zones"],
+    ["bed", "Beds"],
+    ["tool", "Tools"],
+    ["job", "Jobs"],
+    ["note", "Notes"],
+    ["run", "Runs"],
+    ["plot", "Plots"],
+    ["crew", "Crews"],
+    ["kit", "Kits"],
+    ["bay", "Bays"],
+    ["dock", "Docks"],
+    ["lane", "Lanes"],
+    ["yard", "Yards"],
+    ["gate", "Gates"],
+];
+/** A name for kind number `index`, and the plural a district has to draw. */
+function named(index, plurals) {
+    const words = plurals === "long" ? LONG : SHORT;
+    const [singular, plural] = words[index % words.length];
+    const suffix = index >= words.length ? String(index) : "";
+    return { kind: `${singular}${suffix}`, plural: `${plural}${suffix}` };
+}
+/**
+ * An app of the shape a real product has: several kinds, a chain between
+ * them, people in the domain, and a kind nothing can make.
+ */
+export function awkwardApp(options = {}) {
+    const count = Math.max(1, options.kinds ?? 10);
+    const plurals = options.plurals ?? "long";
+    const people = options.people ?? true;
+    const installation = declareInstallation({ roles: ["keeper", "helper"], admin: "keeper", required: true });
+    const names = Array.from({ length: count }, (_, index) => named(index, plurals));
+    const definitions = names.map(({ kind, plural }, index) => defineNode(kind, {
+        fields: z.object({ label: z.string() }),
+        plural,
+        ...(index === 0 && people
+            ? {
+                edges: {
+                    "kept-by": { to: ["user"], description: "who looks after it", inverse: "what they keep" },
+                },
+            }
+            : {}),
+    }));
+    const catalogue = options.unreachable
+        ? [defineNode("almanac", { fields: z.object({ label: z.string() }), plural: "Almanacs" })]
+        : [];
+    const schema = createSchema([
+        ...definitions,
+        ...catalogue,
+        ...(people ? [...installation.kinds] : []),
+    ]);
+    const { defineMutation } = bindSchema(schema);
+    const acts = names.map(({ kind }, index) => {
+        const needs = options.chain !== false && index > 0 ? names[index - 1].kind : undefined;
+        return defineMutation(`add-${kind}`, {
+            title: `Add ${kind}`,
+            /* Well-formed in every way but its SHAPE: a fixture that trips the
+               checker on its own carelessness proves nothing about the shapes it
+               exists to test. */
+            description: `Adds ${kind} to the graph.`,
+            creates: [kind],
+            /* A real chain: the argument is a nodeRef, which is what makes the
+               act unofferable until something exists to point it at. */
+            input: needs
+                ? z.object({ label: z.string(), [`${needs}Id`]: nodeRef([needs]) })
+                : z.object({ label: z.string() }),
+            apply(ctx, args) {
+                ctx.addNode({ id: ctx.freshId(String(args["label"]), kind), kind, label: args["label"] });
+            },
+        });
+    });
+    return defineApp({
+        name: "awkward",
+        schema: schema,
+        mutations: [...acts, ...(people ? installation.mutations : [])],
+        ...(people
+            ? {
+                modules: installation.modules,
+                policy: installation.withPolicy({
+                    roles: ["keeper", "helper"],
+                    grants: [
+                        {
+                            roles: ["keeper"],
+                            mutations: "*",
+                            describe: "The keeper keeps all of it.",
+                        },
+                    ],
+                }),
+            }
+            : {}),
+    });
+}
+/** A graph with `per` of each kind the app declares, and the edges between them. */
+/**
+ * A VALUE THAT PARSES, found rather than known.
+ *
+ * The first version of this filled three field names it had met — `email`,
+ * `roles`, `status` — which was enough for the fixtures it was written
+ * beside and enough for nothing else. The first real product to reach for
+ * it got `zone 0 does not match what zone declares`, because a zone has a
+ * surface and nobody had told this about surfaces.
+ *
+ * So it asks. Each candidate is offered to the field's own schema and the
+ * first one accepted is used, which means a kind can declare whatever it
+ * likes — an enum, a date, a tuple of numbers — without this having to
+ * have heard of it. `undefined` goes first so an optional field stays
+ * unset: the awkward graph should be the SPARSEST one that parses, not the
+ * fullest.
+ */
+function parseable(field, hint) {
+    const schema = field;
+    if (typeof schema?.safeParse !== "function")
+        return { found: false };
+    const entries = schema.def?.entries;
+    const enumerated = entries && typeof entries === "object" ? Object.values(entries) : [];
+    const candidates = [
+        undefined,
+        ...enumerated,
+        hint,
+        "2026-05-04",
+        `${hint}@example.test`,
+        1,
+        0,
+        true,
+        [],
+        [hint],
+        {},
+        { x: 0.5, y: 0.5 },
+        null,
+    ];
+    for (const candidate of candidates) {
+        if (schema.safeParse(candidate).success)
+            return { found: true, value: candidate };
+    }
+    return { found: false };
+}
+export function awkwardGraph(app, options = {}) {
+    const { per = 3, fill = {} } = typeof options === "number" ? { per: options, fill: {} } : options;
+    const nodes = [];
+    for (const kind of app.schema.kinds) {
+        const definition = app.schema.tryDefinition(kind);
+        const shape = (definition?.fields.shape ?? {});
+        for (let index = 0; index < per; index += 1) {
+            const node = { id: `${kind}-${index}`, kind, label: `${kind} ${index}` };
+            for (const [name, field] of Object.entries(shape)) {
+                if (name === "id" || name === "kind" || name === "label")
+                    continue;
+                const given = fill[`${kind}.${name}`];
+                const answer = given === undefined
+                    ? parseable(field, `${kind}-${index}`)
+                    : field.safeParse(given).success
+                        ? { found: true, value: given }
+                        : { found: false };
+                if (!answer.found) {
+                    throw new Error(given === undefined
+                        ? `awkwardGraph cannot fill ${kind}.${name}: none of the values it knows how to offer were accepted. ` +
+                            `Pass one it cannot guess as fill: { "${kind}.${name}": … }.`
+                        : `awkwardGraph was given a fill for ${kind}.${name} that ${kind} does not accept.`);
+                }
+                if (answer.value !== undefined)
+                    node[name] = answer.value;
+            }
+            nodes.push(node);
+        }
+    }
+    return { nodes: nodes, edges: [] };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

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

package/dist/theme/contrast.d.ts

@@ -0,0 +1,47 @@
+import { type ThemeTokens } from "./types.js";
+/** Straight sRGB, 0–255, with alpha 0–1. */
+export interface Rgba {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/** sRGB back to HSL, so a colour can be moved in lightness and stay itself. */
+export declare function rgbToHsl(colour: Rgba): {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare function hsl(h: number, s: number, l: number): Rgba;
+/**
+ * Every colour a token value mentions.
+ *
+ * A gradient is not one colour and pretending otherwise is how a check passes
+ * on a value it never looked at. `bar` and `float` are gradients in both
+ * built-in schemes; a pair drawn on one owes its contrast against the WORST
+ * stop, because that is where the text will be at some point along it.
+ */
+export declare function coloursIn(value: string): Rgba[];
+/** One colour laid over another, straight alpha. */
+export declare function composite(over: Rgba, under: Rgba): Rgba;
+export declare function luminance(colour: Rgba): number;
+/** WCAG 2.1 contrast ratio, 1 to 21. */
+export declare function contrast(a: Rgba, b: Rgba): number;
+export interface ContrastFinding {
+    readonly ink: string;
+    readonly on: string;
+    readonly where: string;
+    readonly ratio: number;
+    readonly requires: number;
+    /** Set when a value could not be read at all, rather than read and failed. */
+    readonly unreadable?: string;
+}
+/**
+ * Every text pair in a palette, measured.
+ *
+ * Returns the failures AND the unreadable values. A token this cannot parse
+ * is reported rather than skipped: silently passing a value nobody looked at
+ * is exactly the failure mode a contrast check exists to prevent.
+ */
+export declare function checkContrast(tokens: ThemeTokens): readonly ContrastFinding[];
+//# sourceMappingURL=contrast.d.ts.map

package/dist/theme/contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../../src/theme/contrast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,4CAA4C;AAC5C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAuCD,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAiB1E;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzD;AA0BD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAW/C;AAED,oDAAoD;AACpD,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI,CAKvD;AAOD,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAI9C;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAGjD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,eAAe,EAAE,CAyC7E"}