@owlmeans/planning-postgres 0.1.18-rc.0

package/build/store/transitions.js

@@ -0,0 +1,164 @@
+import { CommitState, PlanningError, WorkcardConflict } from '@owlmeans/planning';
+import { cleanRecord, col, insertOf, pgFault, recordOf, UNIQUE_VIOLATION, whereOf } from '../sql.js';
+const clean = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+/** The portable criteria of a transition query — what a resource list reads the log with. */
+export const transitionCriteria = (where) => clean({
+    entityId: where.entityId,
+    card: where.card,
+    project: where.project,
+    seq: where.sinceSeq != null ? { $gt: where.sinceSeq } : undefined,
+    'commit.state': where.state,
+    action: where.action,
+});
+export const transitionOf = (row, sql) => recordOf(row, sql.tables.transition);
+export const readTransition = async (sql, id) => {
+    const spec = sql.tables.transition;
+    const rows = await sql.runner.query(`SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'id')} = $1`, [id]);
+    return rows[0] == null ? null : transitionOf(rows[0], sql);
+};
+export const readTransitionByKey = async (sql, entityId, key) => {
+    const spec = sql.tables.transition;
+    const rows = await sql.runner.query(`SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'entityId')} = $1 AND ${col(spec, 'key')} = $2`, [entityId, key]);
+    return rows[0] == null ? null : transitionOf(rows[0], sql);
+};
+/**
+ * The log of one card (or several) in `seq` order, as a fold reads it: this package's own statement,
+ * so it runs inside a fold's transaction. `size` bounds it (0 is no limit); `total` tells a bounded
+ * read that more remain.
+ */
+export const listTransitions = async (sql, where, size = 0) => {
+    const spec = sql.tables.transition;
+    const fixed = whereOf(spec, {
+        entityId: where.entityId,
+        card: where.card,
+        project: where.project,
+        action: where.action,
+    });
+    const params = [...fixed.params];
+    const clauses = [fixed.text];
+    if (where.sinceSeq != null) {
+        params.push(where.sinceSeq);
+        clauses.push(`${col(spec, 'seq')} > $${params.length}`);
+    }
+    if (where.state != null) {
+        params.push(where.state);
+        clauses.push(`(${col(spec, 'commit')}->>'state') = $${params.length}`);
+    }
+    const limit = size > 0 ? ` LIMIT ${Math.floor(size) + 1}` : '';
+    const rows = await sql.runner.query(`SELECT * FROM ${spec.qualified} WHERE ${clauses.join(' AND ')} ORDER BY ${col(spec, 'seq')}, ${col(spec, 'id')}${limit}`, params);
+    const items = rows.map(row => transitionOf(row, sql));
+    return size > 0 && items.length > size ? { items: items.slice(0, size), total: items.length } : { items, total: items.length };
+};
+export const commitTransition = async (sql, id, commit) => {
+    const spec = sql.tables.transition;
+    await sql.runner.query(`UPDATE ${spec.qualified} SET ${col(spec, 'commit')} = $2::jsonb WHERE ${col(spec, 'id')} = $1`, [id, JSON.stringify(clean(commit))]);
+};
+/**
+ * Allocate the next seq — a compare-and-set of `head` on the card row, stamping `headAt`. A card
+ * whose create has not folded yet has no row to count on: it allocates `max(seq) + 1` from the log
+ * and lets the unique `(card, seq)` index refuse a repeat.
+ *
+ * @throws {WorkcardConflict}
+ */
+export const allocateSeq = async (sql, card, expect, at) => {
+    const cards = sql.tables.card;
+    const head = col(cards, 'head');
+    const seq = col(cards, 'seq');
+    const guarded = expect != null;
+    const allocated = await sql.runner.query(`UPDATE ${cards.qualified} SET ${head} = COALESCE(${head}, ${seq}) + 1, ${col(cards, 'headAt')} = $2`
+        + ` WHERE ${col(cards, 'id')} = $1${guarded ? ` AND COALESCE(${head}, ${seq}) = $3` : ''} RETURNING ${head} AS head`, guarded ? [card, at, expect] : [card, at]);
+    if (allocated[0] != null) {
+        return Number(allocated[0].head);
+    }
+    const existing = await sql.runner.query(`SELECT COALESCE(${head}, ${seq}) AS head FROM ${cards.qualified} WHERE ${col(cards, 'id')} = $1`, [card]);
+    if (existing[0] != null) {
+        throw new WorkcardConflict(`${card}:expected:${expect}:head:${existing[0].head}`);
+    }
+    const last = await lastSeq(sql, card);
+    if (guarded && expect !== last) {
+        throw new WorkcardConflict(`${card}:expected:${expect}:head:${last}`);
+    }
+    return last + 1;
+};
+export const lastSeq = async (sql, card) => {
+    const spec = sql.tables.transition;
+    const rows = await sql.runner.query(`SELECT COALESCE(MAX(${col(spec, 'seq')}), 0) AS last FROM ${spec.qualified} WHERE ${col(spec, 'card')} = $1`, [card]);
+    return Number(rows[0]?.last ?? 0);
+};
+/** Give an allocation back when its append failed and nothing was allocated after it. */
+const releaseSeq = async (sql, card, seq) => {
+    const cards = sql.tables.card;
+    await sql.runner.query(`UPDATE ${cards.qualified} SET ${col(cards, 'head')} = $2 - 1 WHERE ${col(cards, 'id')} = $1 AND ${col(cards, 'head')} = $2`, [card, seq]);
+};
+/**
+ * The log port. `append` is idempotent on its id; a lost race on the key releases the allocation
+ * and answers `PlanningError('duplicate-key')` (the executor then answers the winner's receipt); a
+ * lost race on `(card, seq)` — an allocation the fold gave up for lost and filled with a failed
+ * placeholder — re-allocates once and lands after it, then refuses with `WorkcardConflict`.
+ */
+export const makeTransitionPort = (deps) => {
+    const insert = async (sql, transition) => {
+        const statement = insertOf(sql.tables.transition, transition, { tail: 'RETURNING *' });
+        const rows = await sql.runner.query(statement.text, statement.params);
+        return transitionOf(rows[0], sql);
+    };
+    const store = {
+        append: async (transition) => {
+            const sql = await deps.sql();
+            const indexes = await deps.indexes();
+            let current = {
+                ...transition, id: transition.id ?? deps.ids(), commit: transition.commit ?? { state: CommitState.Pending },
+            };
+            for (let attempt = 0;; attempt++) {
+                try {
+                    return await insert(sql, current);
+                }
+                catch (error) {
+                    const fault = pgFault(error);
+                    if (fault.code !== UNIQUE_VIOLATION) {
+                        await releaseSeq(sql, current.card, current.seq).catch(() => undefined);
+                        throw error;
+                    }
+                    if (fault.constraint === indexes.entityKey) {
+                        await releaseSeq(sql, current.card, current.seq);
+                        throw new PlanningError(`duplicate-key:${current.key}`);
+                    }
+                    if (fault.constraint === indexes.cardSeq) {
+                        if (attempt === 0 && current.seq > 1) {
+                            current = { ...current, seq: await allocateSeq(sql, current.card, null, deps.now()) };
+                            continue;
+                        }
+                        throw new WorkcardConflict(`${current.card}:seq:${current.seq}`);
+                    }
+                    const existing = await readTransition(sql, current.id);
+                    if (existing != null) {
+                        return existing;
+                    }
+                    throw error;
+                }
+            }
+        },
+        get: async (id) => await readTransition(await deps.sql(), id),
+        byKey: async (entityId, key) => await readTransitionByKey(await deps.sql(), entityId, key),
+        list: async (where, opts) => {
+            await deps.sql();
+            const sort = opts?.sort ?? (typeof where.card === 'string' ? ['seq'] : ['at', 'seq']);
+            const listed = await deps.resource().list(transitionCriteria(where), { ...opts, sort });
+            return { ...listed, items: listed.items.map(item => cleanRecord(item)) };
+        },
+        nextSeq: async (card, expect) => await allocateSeq(await deps.sql(), card, expect, deps.now()),
+        head: async (card) => {
+            const sql = await deps.sql();
+            const cards = sql.tables.card;
+            const rows = await sql.runner.query(`SELECT COALESCE(${col(cards, 'head')}, ${col(cards, 'seq')}) AS head FROM ${cards.qualified} WHERE ${col(cards, 'id')} = $1`, [card]);
+            return rows[0] != null ? Number(rows[0].head) : await lastSeq(sql, card);
+        },
+        commit: async (id, commit) => { await commitTransition(await deps.sql(), id, commit); },
+        purge: async (where) => {
+            await deps.sql();
+            return await deps.resource().purge(transitionCriteria(where));
+        },
+    };
+    return store;
+};
+//# sourceMappingURL=transitions.js.map

package/build/store/transitions.js.map

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

package/build/types.d.ts

@@ -0,0 +1,72 @@
+import type { BasicContext } from '@owlmeans/context';
+import type { ProjectionStore, Relationship, RelationshipStore, SchemaStore, ScopedSchemaRecord, SpecificationStore, Transition, TransitionStore, Workcard } from '@owlmeans/planning';
+import type { PostgresResource } from '@owlmeans/postgres-resource';
+import type { BindablePlanningStore, CommitHub, FoldResult, PlanningServiceOptions } from '@owlmeans/server-planning';
+import type { DEFAULT_PLANNING_POSTGRES_LIMITS } from './consts.js';
+export type PlanningPostgresLimits = {
+    -readonly [K in keyof typeof DEFAULT_PLANNING_POSTGRES_LIMITS]: number;
+};
+/** The resource aliases the store resolves its four tables by. */
+export interface PlanningPostgresAliases {
+    card: string;
+    transition: string;
+    link: string;
+    schema: string;
+}
+export interface PlanningPostgresOptions {
+    aliases?: Partial<PlanningPostgresAliases>;
+    /**
+     * NOTIFY every settled commit and schema write on the store's channel, and LISTEN for other
+     * processes' (default `true`). `false` leaves a waiter to its poll and a reader to the revision.
+     */
+    bus?: boolean;
+    limits?: Partial<PlanningPostgresLimits>;
+    /** Card and transition ids. */
+    ids?: () => string;
+    /** ISO-8601 timestamps. */
+    now?: () => string;
+}
+export interface PostgresPlanningStoreOptions extends PlanningPostgresOptions {
+    /** The context the four resources are registered on — read at call time, never at construction. */
+    context: () => BasicContext<any> | undefined;
+}
+/** A card row: the record, plus the allocation bookkeeping no caller ever sees. */
+export interface PlanningCardRecord extends Workcard {
+    /** When `head` last moved — how old a gap in the card's log is. Private to the store. */
+    headAt?: string;
+}
+/** A schema row: a record, or the private per-organization revision counter (`kind: 'head'`). */
+export type PlanningSchemaRow = Omit<ScopedSchemaRecord, 'kind'> & {
+    kind: ScopedSchemaRecord['kind'] | 'head';
+};
+export interface PlanningCardResource extends PostgresResource<PlanningCardRecord> {
+}
+export interface PlanningTransitionResource extends PostgresResource<Transition> {
+}
+export interface PlanningLinkResource extends PostgresResource<Relationship> {
+}
+export interface PlanningSchemaResource extends PostgresResource<PlanningSchemaRow> {
+}
+export interface PostgresPlanningStore extends BindablePlanningStore {
+    transitions: TransitionStore;
+    cards: ProjectionStore;
+    specs: SpecificationStore;
+    links: RelationshipStore;
+    commits: CommitHub;
+    schemas: SchemaStore;
+    /**
+     * Fold what is pending for one card — one transaction under its advisory lock, the settled
+     * events delivered after the commit.
+     */
+    fold: (cardId: string) => Promise<FoldResult>;
+    /** Fold every card whose oldest pending row is older than `olderThanMs`. Answers how many. */
+    recover: (opts?: {
+        olderThanMs?: number;
+        limit?: number;
+    }) => Promise<number>;
+    /** Release the LISTEN connection and stop healing. */
+    close: () => Promise<void>;
+}
+export interface PostgresPlanningServiceOptions extends Omit<PlanningServiceOptions, 'store'>, PlanningPostgresOptions {
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,KAAK,EACV,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EACrG,UAAU,EAAE,eAAe,EAAE,QAAQ,EACtC,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EACV,qBAAqB,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EACrE,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAA;AAEnE,MAAM,MAAM,sBAAsB,GAAG;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,OAAO,gCAAgC,GAAG,MAAM;CAAE,CAAA;AAE/G,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAC1C;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IACxC,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,mGAAmG;IACnG,OAAO,EAAE,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;CAC7C;AAED,mFAAmF;AACnF,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAClD,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;CAAE,CAAA;AAEhH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB,CAAC,kBAAkB,CAAC;CAAI;AACtF,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB,CAAC,UAAU,CAAC;CAAI;AACpF,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB,CAAC,YAAY,CAAC;CAAI;AAChF,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB,CAAC,iBAAiB,CAAC;CAAI;AAEvF,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,WAAW,EAAE,eAAe,CAAA;IAC5B,KAAK,EAAE,eAAe,CAAA;IACtB,KAAK,EAAE,kBAAkB,CAAA;IACzB,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,SAAS,CAAA;IAClB,OAAO,EAAE,WAAW,CAAA;IACpB;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAC7C,8FAA8F;IAC9F,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7E,sDAAsD;IACtD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,8BAA+B,SAAQ,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,EAAE,uBAAuB;CAAI"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@owlmeans/planning-postgres",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "description": "A durable Postgres PlanningStore for @owlmeans/server-planning — cards, the transition log, links and data-defined types and flows as four tables, an inline fold under a per-card advisory lock, and a LISTEN/NOTIFY commit bus.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 12 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/basic-ids": "^0.1.18-rc.34",
+    "@owlmeans/context": "^0.1.18-rc.32",
+    "@owlmeans/error": "^0.1.18-rc.36",
+    "@owlmeans/planning": "^0.1.18-rc.11",
+    "@owlmeans/postgres-resource": "^0.1.18-rc.37",
+    "@owlmeans/resource": "^0.1.18-rc.36",
+    "@owlmeans/server-planning": "^0.1.18-rc.13"
+  },
+  "peerDependencies": {
+    "ajv": "*",
+    "ajv-formats": "*",
+    "pg": "*"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/postgres": "^0.1.18-rc.38",
+    "@owlmeans/server-context": "^0.1.18-rc.37",
+    "@owlmeans/test": "^0.1.18-rc.32",
+    "@owlmeans/test-integration": "^0.1.18-rc.29",
+    "@types/bun": "^1.4.0",
+    "@types/pg": "^8.20.4",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "nodemon": "^3.1.14",
+    "pg": "^8.22.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,54 @@
+/** The four resource aliases — each is also the physical table name (sanitized). */
+export const RES_PLANNING_CARD = 'planning-card'
+export const RES_PLANNING_TRANSITION = 'planning-transition'
+export const RES_PLANNING_LINK = 'planning-link'
+export const RES_PLANNING_SCHEMA = 'planning-schema'
+
+/** The alias the store answers `PlanningStore.alias` with, and the service its placeholders name. */
+export const PLANNING_POSTGRES_STORE = 'planning-postgres'
+
+export const DEFAULT_PLANNING_POSTGRES_LIMITS = Object.freeze({
+  /** The most log rows one fold transaction reads and applies; the rest follow in the next round. */
+  foldBatch: 500,
+  /**
+   * How long a gap in a card's log — a seq allocated with no row yet — is an append still in
+   * flight. Older, it is a lost allocation: the fold writes a failed placeholder and goes on.
+   */
+  gapGraceMs: 30_000,
+  /** A pending row older than this makes every status read of it a heal: a background fold. */
+  healAfterMs: 1_000,
+  /** What `recover()` folds by default: cards whose oldest pending row is older than this. */
+  recoverAfterMs: 60_000,
+  /** `SET LOCAL lock_timeout` of a fold transaction, in milliseconds. */
+  lockTimeoutMs: 10_000,
+})
+
+/** How many cards one `recover()` folds by default. */
+export const DEFAULT_RECOVER_LIMIT = 100
+
+/** The cause and error of a failed placeholder written over a lost allocation. */
+export const LOST_ALLOCATION = 'lost-allocation'
+
+/** Rounds (transactions) one `fold()` runs while a round reports more rows than `foldBatch`. */
+export const MAX_FOLD_ROUNDS = 16
+
+/** Passes of prelude and fold one transaction runs — each over one run of consecutive pending rows. */
+export const MAX_FOLD_PASSES = 64
+
+/** The private schema row that is an organization's monotonic schema revision. */
+export const SCHEMA_HEAD_KIND = 'head'
+export const SCHEMA_HEAD_KEY = 'head'
+
+/** Reconnect backoff of the LISTEN connection, doubling from the first to the last, in milliseconds. */
+export const BUS_BACKOFF: readonly [number, number] = Object.freeze([1_000, 30_000]) as readonly [number, number]
+
+/** Postgres refuses a NOTIFY payload of 8000 bytes or more; a frame stays under this. */
+export const NOTIFY_PAYLOAD_MAX = 7_900
+
+/** The file a target adds for each resource — what a missing-resource error names. */
+export const PLANNING_RESOURCE_FILES = Object.freeze({
+  card: 'src/resources/planning/card.ts',
+  transition: 'src/resources/planning/transition.ts',
+  link: 'src/resources/planning/link.ts',
+  schema: 'src/resources/planning/schema.ts',
+})

package/src/errors.ts

@@ -0,0 +1,15 @@
+import { ResilientError } from '@owlmeans/error'
+
+/**
+ * A fault of the Postgres planning store — a missing resource, a fold transaction that could not
+ * commit. Messages start with `planning-postgres:`; it declares no HTTP status (a fault answers 500).
+ */
+export class PlanningPostgresError extends ResilientError {
+  public static override typeName: string = 'PlanningPostgresError'
+
+  constructor(message: string = 'error') {
+    super(PlanningPostgresError.typeName, `planning-postgres:${message}`)
+  }
+}
+
+ResilientError.registerErrorClass(PlanningPostgresError)

package/src/index.ts

@@ -0,0 +1,9 @@
+export type * from './types.js'
+
+export * from './consts.js'
+export * from './errors.js'
+export * from './schemas.js'
+export * from './resource.js'
+export * from './sql.js'
+export * from './store/index.js'
+export * from './service.js'

package/src/resource.ts

@@ -0,0 +1,133 @@
+import type { Relationship, Transition } from '@owlmeans/planning'
+import { getDeclaration, makePostgresResource, PgIndexMethod, pgIdentifier } from '@owlmeans/postgres-resource'
+import type { PgIndexSpec, PostgresResource } from '@owlmeans/postgres-resource'
+import type { ResourceMaker, ResourceRecord } from '@owlmeans/resource'
+import { RES_PLANNING_CARD, RES_PLANNING_LINK, RES_PLANNING_SCHEMA, RES_PLANNING_TRANSITION } from './consts.js'
+import {
+  PlanningCardTableSchema, PlanningLinkTableSchema, PlanningSchemaTableSchema, PlanningTransitionTableSchema,
+} from './schemas.js'
+import type {
+  PlanningCardRecord, PlanningCardResource, PlanningLinkResource, PlanningPostgresAliases, PlanningSchemaResource,
+  PlanningSchemaRow, PlanningTransitionResource,
+} from './types.js'
+
+type IndexList = Array<[suffix: string, spec: PgIndexSpec]>
+
+/**
+ * Declare the indexes a maker owns — each only once. The declaration is keyed by alias at module
+ * scope, so a maker that runs twice (a target's maker wrapping this one, a spec) re-declaring an
+ * index would make the compiler warn about a duplicate on every boot.
+ */
+const declareIndexes = <T extends ResourceRecord>(resource: PostgresResource<T>, alias: string, indexes: IndexList): void => {
+  const table = pgIdentifier(alias)
+  const declared = getDeclaration(alias).indexes
+  for (const [suffix, spec] of indexes) {
+    const name = `${table}_${suffix}`
+    if (!declared.some(index => index.name === name)) {
+      resource.index(name, spec)
+    }
+  }
+}
+
+/** The index names a table carries, by suffix — what the store matches a unique violation on. */
+export const planningIndexName = (alias: string, suffix: string): string => `${pgIdentifier(alias)}_${suffix}`
+
+/**
+ * `planning-card` — projects, cards and specifications in ONE table, routed by `kind` at the query
+ * layer. Indexes follow the reads: a list by kind and type, children in order, membership
+ * (`parents`, GIN), a board by status, the intrinsic state by recency, labels (GIN), a code within
+ * its parent, and a slot's documents.
+ */
+export const makePlanningCardResource = (
+  alias: string = RES_PLANNING_CARD, dbAlias?: string, serviceAlias?: string
+): PlanningCardResource => {
+  const resource = makePostgresResource<PlanningCardRecord, PlanningCardResource>(alias, dbAlias, serviceAlias)
+  resource.schema = PlanningCardTableSchema
+  declareIndexes(resource, alias, [
+    ['entity_kind_type', { columns: ['entityId', 'kind', 'type'] }],
+    ['parent_order', { columns: ['parent', 'order'] }],
+    ['parents', { columns: ['parents'], method: PgIndexMethod.Gin }],
+    ['parent_status', { columns: ['parent', 'status'] }],
+    ['entity_intrinsic', { columns: ['entityId', 'intrinsic', 'updatedAt'] }],
+    ['labels', { columns: ['labels'], method: PgIndexMethod.Gin }],
+    ['code', { columns: ['entityId', 'parent', 'code'], where: '"code" IS NOT NULL' }],
+    ['slot', { columns: ['parent', 'category'], where: `"kind" = 'specification'` }],
+  ])
+
+  return resource
+}
+
+/**
+ * `planning-transition` — the append-only log. `(card, seq)` is the arbiter of allocation, a key is
+ * unique per organization, a project's history reads by time, and the pending rows by age (what
+ * `recover()` scans).
+ */
+export const makePlanningTransitionResource = (
+  alias: string = RES_PLANNING_TRANSITION, dbAlias?: string, serviceAlias?: string
+): PlanningTransitionResource => {
+  const resource = makePostgresResource<Transition, PlanningTransitionResource>(alias, dbAlias, serviceAlias)
+  resource.schema = PlanningTransitionTableSchema
+  declareIndexes(resource, alias, [
+    ['card_seq', { columns: ['card', 'seq'], unique: true }],
+    ['entity_key', { columns: ['entityId', 'key'], unique: true, where: '"key" IS NOT NULL' }],
+    ['project_at', { columns: ['project', 'at'] }],
+    ['pending', { columns: ['at'], where: `("commit"->>'state') = 'pending'` }],
+  ])
+
+  return resource
+}
+
+/** `planning-link` — one row per `(from, to, type)`, read from either end, by type, and by project. */
+export const makePlanningLinkResource = (
+  alias: string = RES_PLANNING_LINK, dbAlias?: string, serviceAlias?: string
+): PlanningLinkResource => {
+  const resource = makePostgresResource<Relationship, PlanningLinkResource>(alias, dbAlias, serviceAlias)
+  resource.schema = PlanningLinkTableSchema
+  declareIndexes(resource, alias, [
+    ['edge', { columns: ['from', 'to', 'type'], unique: true }],
+    ['inbound', { columns: ['to', 'type'] }],
+    ['entity_type', { columns: ['entityId', 'type'] }],
+    ['project', { columns: ['project'] }],
+  ])
+
+  return resource
+}
+
+/**
+ * `planning-schema` — data-defined types and flows, one row per `(organization, project layer,
+ * kind, key)`, plus each organization's private revision row (`kind: 'head'`).
+ */
+export const makePlanningSchemaResource = (
+  alias: string = RES_PLANNING_SCHEMA, dbAlias?: string, serviceAlias?: string
+): PlanningSchemaResource => {
+  const resource = makePostgresResource<PlanningSchemaRow, PlanningSchemaResource>(alias, dbAlias, serviceAlias)
+  resource.schema = PlanningSchemaTableSchema
+  declareIndexes(resource, alias, [
+    ['scope', { unique: true, expression: `"entityId", COALESCE("project", ''), "kind", "key"` }],
+    ['rev', { columns: ['entityId', 'rev'] }],
+  ])
+
+  return resource
+}
+
+export const makePlanningCardPostgres: ResourceMaker<PlanningCardRecord, PlanningCardResource> =
+  (dbAlias, serviceAlias) => makePlanningCardResource(RES_PLANNING_CARD, dbAlias, serviceAlias)
+
+export const makePlanningTransitionPostgres: ResourceMaker<Transition, PlanningTransitionResource> =
+  (dbAlias, serviceAlias) => makePlanningTransitionResource(RES_PLANNING_TRANSITION, dbAlias, serviceAlias)
+
+export const makePlanningLinkPostgres: ResourceMaker<Relationship, PlanningLinkResource> =
+  (dbAlias, serviceAlias) => makePlanningLinkResource(RES_PLANNING_LINK, dbAlias, serviceAlias)
+
+export const makePlanningSchemaPostgres: ResourceMaker<PlanningSchemaRow, PlanningSchemaResource> =
+  (dbAlias, serviceAlias) => makePlanningSchemaResource(RES_PLANNING_SCHEMA, dbAlias, serviceAlias)
+
+/** The four resources under the aliases a store resolves — what `appendPostgresPlanning` registers. */
+export const makePlanningPostgresResources = (
+  aliases: PlanningPostgresAliases, dbAlias?: string, serviceAlias?: string
+): [PlanningCardResource, PlanningTransitionResource, PlanningLinkResource, PlanningSchemaResource] => [
+  makePlanningCardResource(aliases.card, dbAlias, serviceAlias),
+  makePlanningTransitionResource(aliases.transition, dbAlias, serviceAlias),
+  makePlanningLinkResource(aliases.link, dbAlias, serviceAlias),
+  makePlanningSchemaResource(aliases.schema, dbAlias, serviceAlias),
+]

package/src/schemas.ts

@@ -0,0 +1,84 @@
+import {
+  AnyWorkcardSchema, PlanningSchemaKind, RelationshipSchema, ScopedSchemaRecordSchema, TransitionSchema,
+} from '@owlmeans/planning'
+import type { Relationship, Transition } from '@owlmeans/planning'
+import type { JSONSchemaType } from 'ajv'
+import { SCHEMA_HEAD_KIND } from './consts.js'
+import type { PlanningCardRecord, PlanningSchemaRow } from './types.js'
+
+type Properties = Record<string, Record<string, unknown>>
+
+const propertiesOf = (schema: object): Properties =>
+  structuredClone((schema as { properties: Properties }).properties)
+
+const requiredOf = (schema: object): string[] => [...((schema as { required?: string[] }).required ?? [])]
+
+/**
+ * An ISO-8601 timestamp stays TEXT. The record's `format: 'date-time'` would compile to
+ * `timestamptz` and marshal through `Date` — which changes the string a record carries and breaks
+ * the lexicographic order every `updatedSince`, `at` sort and gap age relies on.
+ */
+const timestamp = (property: Record<string, unknown>): Record<string, unknown> => {
+  const { format: _format, ...rest } = property
+  return { ...rest, pg: { type: 'text' } }
+}
+
+const integer = (property: Record<string, unknown>): Record<string, unknown> => ({ ...property, pg: { type: 'integer' } })
+
+const tableSchema = <T>(properties: Properties, required: string[]): JSONSchemaType<T> => ({
+  type: 'object', properties, required, additionalProperties: false,
+}) as unknown as JSONSchemaType<T>
+
+const cardProperties = propertiesOf(AnyWorkcardSchema)
+
+/**
+ * `planning-card`: projects, cards and specifications in one table — derived from
+ * `AnyWorkcardSchema`, plus the private `headAt` column. `seq`/`head`/`revision`/`bodyChars` are
+ * `integer`, `body` is `text`, every timestamp is `text`.
+ */
+export const PlanningCardTableSchema = tableSchema<PlanningCardRecord>({
+  ...cardProperties,
+  createdAt: timestamp(cardProperties.createdAt),
+  updatedAt: timestamp(cardProperties.updatedAt),
+  closedAt: timestamp(cardProperties.closedAt),
+  seq: integer(cardProperties.seq),
+  head: integer(cardProperties.head),
+  revision: integer(cardProperties.revision),
+  bodyChars: integer(cardProperties.bodyChars),
+  body: { ...cardProperties.body, pg: { type: 'text' } },
+  headAt: { type: 'string', nullable: true, pg: { type: 'text' } },
+}, requiredOf(AnyWorkcardSchema))
+
+const transitionProperties = propertiesOf(TransitionSchema)
+
+/** `planning-transition`: the append-only log, derived from `TransitionSchema`. */
+export const PlanningTransitionTableSchema = tableSchema<Transition>({
+  ...transitionProperties,
+  seq: integer(transitionProperties.seq),
+  at: timestamp(transitionProperties.at),
+}, requiredOf(TransitionSchema))
+
+const linkProperties = propertiesOf(RelationshipSchema)
+
+/** `planning-link`: typed edges, derived from `RelationshipSchema`. */
+export const PlanningLinkTableSchema = tableSchema<Relationship>({
+  ...linkProperties,
+  createdAt: timestamp(linkProperties.createdAt),
+}, requiredOf(RelationshipSchema))
+
+const schemaProperties = propertiesOf(ScopedSchemaRecordSchema)
+
+/**
+ * `planning-schema`: data-defined types and flows, derived from `ScopedSchemaRecordSchema`. `kind`
+ * also admits the private `head` row an organization's revision is counted in; `project` is `text`
+ * so the uniqueness expression `COALESCE("project", '')` stays one type.
+ */
+export const PlanningSchemaTableSchema = tableSchema<PlanningSchemaRow>({
+  ...schemaProperties,
+  kind: { type: 'string', enum: [...Object.values(PlanningSchemaKind), SCHEMA_HEAD_KIND] },
+  project: { ...schemaProperties.project, pg: { type: 'text' } },
+  version: integer(schemaProperties.version),
+  rev: integer(schemaProperties.rev),
+  createdAt: timestamp(schemaProperties.createdAt),
+  updatedAt: timestamp(schemaProperties.updatedAt),
+}, requiredOf(ScopedSchemaRecordSchema))