@kernhq/module-quire 0.2.0

package/README.md

@@ -0,0 +1,71 @@
+# Module template
+
+Copy this to start a Kern module. It is a working module: a `Note` entity with list, create and
+delete, its own Postgres schema, row-level security, permissions, events, and a test that refuses to
+let the contract and the router drift apart.
+
+The fastest way to copy it correctly is not to copy it by hand:
+
+```bash
+cd repos/modules
+pnpm new-module crm          # generates this package *and* its half in the app
+```
+
+Read the rest of this file if you are doing it by hand, or if you want to know what the generator
+wrote.
+
+## What is in here
+
+| File | What it is |
+|---|---|
+| `src/contract.ts` | Zod models, the oRPC contract, events, permission keys, capabilities. Imported by both halves, so no Node code. |
+| `src/server/schema.ts` | Drizzle tables in `mod_<id>`. |
+| `src/server/_impl.ts` | The router. Separate from `index.ts` so the test can walk it without a kernel. |
+| `src/server/index.ts` | `defineServerModule` — schema, migrations, router, subscriptions. |
+| `src/client/index.ts` | The typed API client and module logic. **Ships as source.** |
+| `src/module.test.ts` | Contract-to-router parity and the authorisation guard. Keep it. |
+| `migrations/0000_init.sql` | Generated by `pnpm db:generate`. |
+| `migrations/0001_rls.sql` | Hand-written. Never generated. |
+
+## Copying it by hand
+
+Each of these has been got wrong before.
+
+1. **`package.json`** — set `name` to `@kernhq/module-<id>`, and **delete `"private": true`**. A
+   private package is skipped silently by changesets: the commit lands, CI is green, and nothing
+   publishes.
+2. **`files`** must cover every directory `./client` reaches — `src/client` *and* `src/contract`.
+   The client ships as source, so a re-export the tarball omits breaks the consumer and nothing
+   local notices, because the workspace resolves the file the package does not ship.
+   `pnpm check:pack` catches it.
+3. **The id agrees in four places**: `MODULE_ID`, `moduleSchema('<id>')`, `schemaFilter` in
+   `drizzle.config.ts`, and every permission and event prefix.
+4. **Version comes from the package**, never a literal: `packageVersion(import.meta.url)`. A literal
+   is not bumped by a release — chat once shipped as 0.2.0 while telling every admin it was 0.1.0,
+   and that literal is what `workspace_modules.installed_version` recorded.
+5. **Write the RLS migration.** `pnpm db:generate` will not. Copy `0001_rls.sql` and change the
+   table names; `rlsPolicySql` from `@kernhq/kernel` emits the same text.
+6. **Host it.** A module nothing imports is invisible: its tests pass, it publishes, and every call
+   404s. Add it to `featureModules` in the `core` repo's `src/service.ts`, or to whichever service
+   should hold it.
+7. **Register the client** in the app's `src/lib/modules/registry.ts`.
+
+## What a module can contribute
+
+The server half declares tables, migrations, a router, `procedures` other modules call through
+`kernel.call()`, `jobs`, `subscriptions`, search indexers and lifecycle hooks.
+
+The client half — the manifest in the app — declares `nav`, `commands`, `settingsPages`, `widgets`
+for the dashboard, and `sidebar` for the column beside the rail. Read the `kern-widget` skill before
+writing a widget, and `kern-module` for the whole sequence.
+
+## Before you call it done
+
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+pnpm check:pack        # the tarball contains what ./client imports
+pnpm check:versions    # the manifest version matches package.json
+```
+
+Then use it through the interface, signed in, with the module enabled for a workspace. A module that
+has never served a request is not finished, whatever the type-checker says.

package/dist/client/rank.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fractional indexing for `Page.position`.
+ *
+ * Copied from the tracker's `rank.ts` rather than imported: modules do not depend on one another,
+ * and a pure algorithm is the one thing worth duplicating. Keep them in step if either changes.
+ *
+ * A page tree must survive concurrent edits: two people dragging different pages at the same time
+ * should not have to renumber anything. Each page therefore carries a short string key, and moving
+ * one between two siblings only mints a new key strictly between its neighbours — no other row is
+ * touched, and the result sorts with a plain string comparison.
+ *
+ * The alphabet is ordered by code point (digits, uppercase, lowercase) so lexicographic order and
+ * numeric order agree, which is what `ORDER BY position` in Postgres relies on.
+ */
+/** True when `rank` only uses the rank alphabet and has no trailing zero (the canonical form). */
+export declare function isValidRank(rank: string): boolean;
+/**
+ * A key strictly between `before` and `after`. Pass `null` for an open end: `rankBetween(null, first)`
+ * puts an item at the top of the list, `rankBetween(last, null)` at the bottom.
+ */
+export declare function rankBetween(before: string | null, after: string | null): string;
+/** First rank in an empty list. */
+export declare function initialRank(): string;
+/**
+ * `count` evenly spread ranks, for seeding a list. Cheaper and tidier than calling `rankBetween`
+ * repeatedly, which would bias every new key towards the end.
+ */
+export declare function rankSequence(count: number): string[];
+/** Ascending comparator for anything carrying a `rank`. */
+export declare function byRank(a: {
+    rank: string;
+}, b: {
+    rank: string;
+}): number;
+/**
+ * The rank an item needs to land at `targetIndex` of `ordered` (the list it is being dropped into,
+ * already excluding the dragged item).
+ */
+export declare function rankForIndex(ordered: Array<{
+    rank: string;
+}>, targetIndex: number): string;
+//# sourceMappingURL=rank.d.ts.map

package/dist/client/rank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.d.ts","sourceRoot":"","sources":["../../src/client/rank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CA8B/E;AAED,mCAAmC;AACnC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQpD;AAED,2DAA2D;AAC3D,wBAAgB,MAAM,CAAC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI1F"}

package/dist/client/rank.js

@@ -0,0 +1,97 @@
+/**
+ * Fractional indexing for `Page.position`.
+ *
+ * Copied from the tracker's `rank.ts` rather than imported: modules do not depend on one another,
+ * and a pure algorithm is the one thing worth duplicating. Keep them in step if either changes.
+ *
+ * A page tree must survive concurrent edits: two people dragging different pages at the same time
+ * should not have to renumber anything. Each page therefore carries a short string key, and moving
+ * one between two siblings only mints a new key strictly between its neighbours — no other row is
+ * touched, and the result sorts with a plain string comparison.
+ *
+ * The alphabet is ordered by code point (digits, uppercase, lowercase) so lexicographic order and
+ * numeric order agree, which is what `ORDER BY position` in Postgres relies on.
+ */
+const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const BASE = DIGITS.length;
+const indexOfDigit = (ch) => {
+    const i = DIGITS.indexOf(ch);
+    if (i < 0)
+        throw new Error(`invalid rank character: ${JSON.stringify(ch)}`);
+    return i;
+};
+/** True when `rank` only uses the rank alphabet and has no trailing zero (the canonical form). */
+export function isValidRank(rank) {
+    if (rank.length === 0)
+        return false;
+    for (const ch of rank)
+        if (!DIGITS.includes(ch))
+            return false;
+    return !rank.endsWith(DIGITS[0]);
+}
+/**
+ * A key strictly between `before` and `after`. Pass `null` for an open end: `rankBetween(null, first)`
+ * puts an item at the top of the list, `rankBetween(last, null)` at the bottom.
+ */
+export function rankBetween(before, after) {
+    const lo = before ?? '';
+    const hi = after ?? '';
+    if (lo && hi && lo >= hi) {
+        throw new Error(`rankBetween expects before < after, got ${JSON.stringify(lo)} >= ${JSON.stringify(hi)}`);
+    }
+    let prefix = '';
+    // once the digit we keep is strictly below the upper bound's digit, the rest of `hi` cannot
+    // constrain us any more and we are free to use the whole alphabet
+    let free = hi === '';
+    for (let i = 0;; i++) {
+        const da = i < lo.length ? indexOfDigit(lo[i]) : -1;
+        const db = free ? BASE : i < hi.length ? indexOfDigit(hi[i]) : 0;
+        /**
+         * An absent lower bound is digit 0, not "below 0".
+         *
+         * Digit 0 can never be the last digit of a key: nothing sorts strictly between `''` and `'0'`,
+         * so a key ending in 0 leaves no room to insert in front of it. Treating the absent bound as -1
+         * makes the midpoint of (nothing, '2') come out as '0', and the next insertion at the front then
+         * looks for a key below '0', finds none, and appends a digit for ever — a loop inside a request
+         * handler that allocates until the process dies. Reaching it takes five insertions at the top of
+         * the same list.
+         */
+        const low = da >= 0 ? da : 0;
+        if (db - low > 1)
+            return prefix + DIGITS[Math.floor((low + db) / 2)];
+        prefix += DIGITS[low];
+        if (!free && low < db)
+            free = true;
+    }
+}
+/** First rank in an empty list. */
+export function initialRank() {
+    return rankBetween(null, null);
+}
+/**
+ * `count` evenly spread ranks, for seeding a list. Cheaper and tidier than calling `rankBetween`
+ * repeatedly, which would bias every new key towards the end.
+ */
+export function rankSequence(count) {
+    const out = [];
+    let prev = null;
+    for (let i = 0; i < count; i++) {
+        prev = rankBetween(prev, null);
+        out.push(prev);
+    }
+    return out;
+}
+/** Ascending comparator for anything carrying a `rank`. */
+export function byRank(a, b) {
+    return a.rank < b.rank ? -1 : a.rank > b.rank ? 1 : 0;
+}
+/**
+ * The rank an item needs to land at `targetIndex` of `ordered` (the list it is being dropped into,
+ * already excluding the dragged item).
+ */
+export function rankForIndex(ordered, targetIndex) {
+    const before = targetIndex > 0 ? (ordered[targetIndex - 1]?.rank ?? null) : null;
+    const after = targetIndex < ordered.length ? (ordered[targetIndex]?.rank ?? null) : null;
+    return rankBetween(before, after);
+}
+//# sourceMappingURL=rank.js.map

package/dist/client/rank.js.map

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

package/dist/contract/capabilities.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Sub-features a workspace can switch off inside this module.
+ *
+ * Only the foundation exists today, and it is `required` — always on, never offered as a switch — so
+ * that the optional ones arriving later have something to depend on. A capability is not a second
+ * permission system: a permission asks whether this *person* may do something, a capability asks
+ * whether this *workspace* has the feature at all, and a procedure behind a disabled one answers
+ * `notFound` rather than `forbidden`, because a surface the workspace never enabled is not being
+ * withheld — it is not there.
+ *
+ * Planned, each of which is a real "different customers want different amounts of this": databases,
+ * public publishing, blogs and page analytics. They are declared when the feature lands, not before:
+ * a switch that does nothing is worse than no switch.
+ */
+export declare const quireCapabilities: readonly {
+    id: string;
+    label: string;
+    dependsOn: string[];
+    defaultEnabled: boolean;
+    level: 3 | 1 | 2;
+    required: boolean;
+    description?: string | undefined;
+}[];
+/**
+ * Which procedures belong to which capability, as data.
+ *
+ * Declared rather than inferred, because a missing `requiresCapability` is invisible: the procedure
+ * type-checks, the tests pass, and the only symptom is that a workspace which switched the feature
+ * off can still call it. `module.test.ts` reads this and fails when a procedure named here is not
+ * carrying the extra middleware.
+ *
+ * Everything Quire offers today belongs to the module as a whole, so this is empty.
+ */
+export declare const quireCapabilityProcedures: Record<string, readonly string[]>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/contract/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;GAO5B,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAM,CAAA"}

package/dist/contract/capabilities.js

@@ -0,0 +1,35 @@
+import { defineCapabilities } from '@kernhq/contracts';
+/**
+ * Sub-features a workspace can switch off inside this module.
+ *
+ * Only the foundation exists today, and it is `required` — always on, never offered as a switch — so
+ * that the optional ones arriving later have something to depend on. A capability is not a second
+ * permission system: a permission asks whether this *person* may do something, a capability asks
+ * whether this *workspace* has the feature at all, and a procedure behind a disabled one answers
+ * `notFound` rather than `forbidden`, because a surface the workspace never enabled is not being
+ * withheld — it is not there.
+ *
+ * Planned, each of which is a real "different customers want different amounts of this": databases,
+ * public publishing, blogs and page analytics. They are declared when the feature lands, not before:
+ * a switch that does nothing is worse than no switch.
+ */
+export const quireCapabilities = defineCapabilities([
+    {
+        id: 'pages',
+        label: 'Spaces and pages',
+        description: 'The page tree itself',
+        required: true,
+    },
+]);
+/**
+ * Which procedures belong to which capability, as data.
+ *
+ * Declared rather than inferred, because a missing `requiresCapability` is invisible: the procedure
+ * type-checks, the tests pass, and the only symptom is that a workspace which switched the feature
+ * off can still call it. `module.test.ts` reads this and fails when a procedure named here is not
+ * carrying the extra middleware.
+ *
+ * Everything Quire offers today belongs to the module as a whole, so this is empty.
+ */
+export const quireCapabilityProcedures = {};
+//# sourceMappingURL=capabilities.js.map

package/dist/contract/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;IAClD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,kBAAkB;QACzB,WAAW,EAAE,sBAAsB;QACnC,QAAQ,EAAE,IAAI;KACf;CACF,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsC,EAAE,CAAA"}

package/dist/contract/events.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+/** `<module>.<entity>.<action>`. Anything that emits one declares it here. */
+export declare const quireEvents: {
+    readonly spaceCreated: import("@kernhq/contracts").EventDef<"quire.space.created", z.ZodObject<{
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    readonly spaceUpdated: import("@kernhq/contracts").EventDef<"quire.space.updated", z.ZodObject<{
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    readonly spaceArchived: import("@kernhq/contracts").EventDef<"quire.space.archived", z.ZodObject<{
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+        archived: z.ZodBoolean;
+    }, z.core.$strip>>;
+    readonly pageCreated: import("@kernhq/contracts").EventDef<"quire.page.created", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    readonly pageUpdated: import("@kernhq/contracts").EventDef<"quire.page.updated", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    readonly pageMoved: import("@kernhq/contracts").EventDef<"quire.page.moved", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+        parentId: z.ZodNullable<z.ZodUUID>;
+    }, z.core.$strip>>;
+    readonly pageArchived: import("@kernhq/contracts").EventDef<"quire.page.archived", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+        archived: z.ZodBoolean;
+    }, z.core.$strip>>;
+    readonly pageTrashed: import("@kernhq/contracts").EventDef<"quire.page.trashed", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    readonly pageRestored: import("@kernhq/contracts").EventDef<"quire.page.restored", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    /** The page and its descendants are gone; anything holding a reference should drop it. */
+    readonly pageDeleted: import("@kernhq/contracts").EventDef<"quire.page.deleted", z.ZodObject<{
+        pageId: z.ZodUUID;
+        spaceId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+        pageIds: z.ZodArray<z.ZodUUID>;
+    }, z.core.$strip>>;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/contract/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/contract/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,8EAA8E;AAC9E,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAatB,0FAA0F;;;;;;;CAElF,CAAA"}

package/dist/contract/events.js

@@ -0,0 +1,18 @@
+import { defineEvent, Id, WorkspaceId } from '@kernhq/contracts';
+import { z } from 'zod';
+const page = z.object({ pageId: Id, spaceId: Id, workspaceId: WorkspaceId });
+/** `<module>.<entity>.<action>`. Anything that emits one declares it here. */
+export const quireEvents = {
+    spaceCreated: defineEvent('quire.space.created', z.object({ spaceId: Id, workspaceId: WorkspaceId })),
+    spaceUpdated: defineEvent('quire.space.updated', z.object({ spaceId: Id, workspaceId: WorkspaceId })),
+    spaceArchived: defineEvent('quire.space.archived', z.object({ spaceId: Id, workspaceId: WorkspaceId, archived: z.boolean() })),
+    pageCreated: defineEvent('quire.page.created', page),
+    pageUpdated: defineEvent('quire.page.updated', page),
+    pageMoved: defineEvent('quire.page.moved', page.extend({ parentId: Id.nullable() })),
+    pageArchived: defineEvent('quire.page.archived', page.extend({ archived: z.boolean() })),
+    pageTrashed: defineEvent('quire.page.trashed', page.extend({ count: z.number().int().nonnegative() })),
+    pageRestored: defineEvent('quire.page.restored', page),
+    /** The page and its descendants are gone; anything holding a reference should drop it. */
+    pageDeleted: defineEvent('quire.page.deleted', page.extend({ pageIds: z.array(Id) })),
+};
+//# sourceMappingURL=events.js.map

package/dist/contract/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/contract/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAChE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAA;AAE5E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,YAAY,EAAE,WAAW,CAAC,qBAAqB,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrG,YAAY,EAAE,WAAW,CAAC,qBAAqB,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACrG,aAAa,EAAE,WAAW,CACxB,sBAAsB,EACtB,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAC3E;IACD,WAAW,EAAE,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC;IACpD,WAAW,EAAE,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC;IACpD,SAAS,EAAE,WAAW,CAAC,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpF,YAAY,EAAE,WAAW,CAAC,qBAAqB,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxF,WAAW,EAAE,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACtG,YAAY,EAAE,WAAW,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACtD,0FAA0F;IAC1F,WAAW,EAAE,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7E,CAAA"}

package/dist/contract/index.d.ts

@@ -0,0 +1,6 @@
+export * from './capabilities.js';
+export * from './events.js';
+export * from './models.js';
+export * from './permissions.js';
+export * from './router.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA"}

package/dist/contract/index.js

@@ -0,0 +1,6 @@
+export * from './capabilities.js';
+export * from './events.js';
+export * from './models.js';
+export * from './permissions.js';
+export * from './router.js';
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA"}

package/dist/contract/models.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_quire` and every event. */
+export declare const MODULE_ID = "quire";
+/**
+ * How a space decides who may see it before any binding is consulted.
+ *
+ * `open` — every member of the workspace may read it.
+ * `restricted` — members may find it and see its name, and need a binding to read a page.
+ * `private` — only people with a binding know it exists at all.
+ */
+export declare const SpaceVisibility: z.ZodEnum<{
+    open: "open";
+    restricted: "restricted";
+    private: "private";
+}>;
+export type SpaceVisibility = z.infer<typeof SpaceVisibility>;
+export declare const Space: z.ZodObject<{
+    id: z.ZodUUID;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    key: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    visibility: z.ZodEnum<{
+        open: "open";
+        restricted: "restricted";
+        private: "private";
+    }>;
+    homepageId: z.ZodNullable<z.ZodUUID>;
+    createdBy: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "UserId", "out">>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type Space = z.infer<typeof Space>;
+/**
+ * What a page *is*, which decides what a reader sees.
+ *
+ * `page` — has a published version and a draft. Everyone editing shares one live document; a reader
+ * without edit rights, and every public URL, is served the last published version instead. This is
+ * what a documentation site is made of.
+ * `live` — always live, like a shared note. There is no draft and no unpublished-changes state;
+ * versions still accumulate so history and restore work the same way.
+ * `database` — the page *is* a database. Its own body is the description above the view.
+ */
+export declare const PageKind: z.ZodEnum<{
+    page: "page";
+    live: "live";
+    database: "database";
+}>;
+export type PageKind = z.infer<typeof PageKind>;
+export declare const Page: z.ZodObject<{
+    id: z.ZodUUID;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    spaceId: z.ZodUUID;
+    parentId: z.ZodNullable<z.ZodUUID>;
+    position: z.ZodString;
+    kind: z.ZodEnum<{
+        page: "page";
+        live: "live";
+        database: "database";
+    }>;
+    title: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    coverUrl: z.ZodNullable<z.ZodString>;
+    publishedVersionId: z.ZodNullable<z.ZodUUID>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    createdBy: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "UserId", "out">>;
+    updatedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "UserId", "out">>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    deletedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type Page = z.infer<typeof Page>;
+/** A page in the sidebar tree: enough to draw a row, and nothing that costs a join. */
+export declare const PageNode: z.ZodObject<{
+    id: z.ZodUUID;
+    parentId: z.ZodNullable<z.ZodUUID>;
+    position: z.ZodString;
+    kind: z.ZodEnum<{
+        page: "page";
+        live: "live";
+        database: "database";
+    }>;
+    title: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    hasChildren: z.ZodBoolean;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type PageNode = z.infer<typeof PageNode>;
+export declare const Ok: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+//# sourceMappingURL=models.d.ts.map

package/dist/contract/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/contract/models.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,yGAAyG;AACzG,eAAO,MAAM,SAAS,UAAU,CAAA;AAEhC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;EAA4C,CAAA;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;iBAoBhB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;;;;EAAuC,CAAA;AAC5D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAE/C,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;iBAwBf,CAAA;AACF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA;AAEvC,uFAAuF;AACvF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;iBASnB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAE/C,eAAO,MAAM,EAAE;;iBAAoC,CAAA"}

package/dist/contract/models.js

@@ -0,0 +1,82 @@
+import { Id, Timestamp, UserId, WorkspaceId } from '@kernhq/contracts';
+import { z } from 'zod';
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_quire` and every event. */
+export const MODULE_ID = 'quire';
+/**
+ * How a space decides who may see it before any binding is consulted.
+ *
+ * `open` — every member of the workspace may read it.
+ * `restricted` — members may find it and see its name, and need a binding to read a page.
+ * `private` — only people with a binding know it exists at all.
+ */
+export const SpaceVisibility = z.enum(['open', 'restricted', 'private']);
+export const Space = z.object({
+    id: Id,
+    workspaceId: WorkspaceId,
+    /** unique per workspace; it is what appears in the URL */
+    key: z
+        .string()
+        .min(2)
+        .max(48)
+        .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, 'lowercase letters, digits and dashes'),
+    name: z.string().min(1).max(120),
+    description: z.string().max(2000),
+    /** a Lucide icon name, or an emoji */
+    icon: z.string().max(64).nullable(),
+    visibility: SpaceVisibility,
+    /** the page shown when somebody opens the space; null until one is set */
+    homepageId: Id.nullable(),
+    createdBy: UserId.nullable(),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+    archivedAt: Timestamp.nullable(),
+});
+/**
+ * What a page *is*, which decides what a reader sees.
+ *
+ * `page` — has a published version and a draft. Everyone editing shares one live document; a reader
+ * without edit rights, and every public URL, is served the last published version instead. This is
+ * what a documentation site is made of.
+ * `live` — always live, like a shared note. There is no draft and no unpublished-changes state;
+ * versions still accumulate so history and restore work the same way.
+ * `database` — the page *is* a database. Its own body is the description above the view.
+ */
+export const PageKind = z.enum(['page', 'live', 'database']);
+export const Page = z.object({
+    id: Id,
+    workspaceId: WorkspaceId,
+    spaceId: Id,
+    parentId: Id.nullable(),
+    /**
+     * A fractional index, not an integer. Moving one page between two others must not renumber its
+     * siblings: two people reordering at once would then write different numbers for the same rows.
+     */
+    position: z.string().min(1).max(256),
+    kind: PageKind,
+    title: z.string().max(300),
+    icon: z.string().max(64).nullable(),
+    coverUrl: z.string().max(2048).nullable(),
+    /** the version a reader without edit rights sees; null while a `page` has never been published */
+    publishedVersionId: Id.nullable(),
+    /** whether the live document has changed since `publishedVersionId` was written */
+    hasUnpublishedChanges: z.boolean(),
+    createdBy: UserId.nullable(),
+    updatedBy: UserId.nullable(),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+    archivedAt: Timestamp.nullable(),
+    deletedAt: Timestamp.nullable(),
+});
+/** A page in the sidebar tree: enough to draw a row, and nothing that costs a join. */
+export const PageNode = z.object({
+    id: Id,
+    parentId: Id.nullable(),
+    position: z.string(),
+    kind: PageKind,
+    title: z.string(),
+    icon: z.string().nullable(),
+    hasChildren: z.boolean(),
+    archivedAt: Timestamp.nullable(),
+});
+export const Ok = z.object({ ok: z.literal(true) });
+//# sourceMappingURL=models.js.map

package/dist/contract/models.js.map

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