@owlmeans/planning-postgres 0.1.18-rc.0

package/README.md

@@ -0,0 +1,88 @@
+# @owlmeans/planning-postgres
+
+A durable Postgres `PlanningStore` for `@owlmeans/server-planning`: projects, cards and
+specifications in one table, the append-only transition log, typed links, and data-defined card
+types and flows — four tables compiled from the planning record schemas by
+`@owlmeans/postgres-resource`. A write folds inline, in one transaction per card under a Postgres
+advisory lock; commits reach other processes over LISTEN/NOTIFY. Use it for a backend that keeps
+its planning data in Postgres; a Mongo deployment uses its own store, and tests and single-process
+tools the in-memory store of `@owlmeans/server-planning`.
+
+## Installation
+
+```sh
+bun add @owlmeans/planning-postgres@^0.1.18-rc.0
+```
+
+Peers: `pg`, `ajv`, `ajv-formats`.
+
+## Concepts
+
+- **Four resources, four tables** — `planning-card` (projects, cards and specifications, routed by
+  `kind`), `planning-transition` (the log), `planning-link` (relationships), `planning-schema`
+  (data-defined types and flows). Timestamps stay `text`, so ISO-8601 order is row order.
+- **Inline fold** — `project()` folds at once, inside one transaction under
+  `pg_advisory_xact_lock`; the settled events are delivered to waiters and `after` hooks only
+  after it commits.
+- **A gap is not a failure** — `nextSeq` and `append` are two round trips, so a fold waits for a
+  young gap and fills an old one with a failed `lost-allocation` placeholder.
+- **Every waiter heals** — a status read of a pending row older than `healAfterMs` folds its card
+  in the background; `recover()` folds what nobody is folding.
+- **Data-defined types and flows** — the store implements the schema port, so the planning facade
+  exposes `definitions`.
+
+## Usage
+
+```ts
+import { appendPostgres } from '@owlmeans/postgres'
+import { appendPostgresPlanning } from '@owlmeans/planning-postgres'
+
+appendPostgres(context)
+appendPostgresPlanning(context, { plugins: [libraryPlugin] })   // four resources + the service
+
+const planning = context.planning().for({ entityId, profileId })
+const receipt = await planning.execute({
+  card: { kind: 'project', type: 'library:branch', title: 'Riverside branch' },
+  action: 'create',
+}, { wait: true })
+```
+
+A generated target registers each piece from its own file instead — `resources/planning/card.ts`
+exporting `makeResource = makePlanningCardPostgres` (and `transition.ts`, `link.ts`, `schema.ts`),
+and `services/planning.ts` exporting `makeService = () => makePostgresPlanningService({ plugins })`.
+
+## API
+
+`makePlanningCardPostgres`, `makePlanningTransitionPostgres`, `makePlanningLinkPostgres`,
+`makePlanningSchemaPostgres` (and `make*Resource(alias, dbAlias?, serviceAlias?)`,
+`makePlanningPostgresResources`); `makePostgresPlanningStore`, `makePostgresPlanningService`,
+`appendPostgresPlanning`; `PostgresPlanningStore` (`fold`, `recover`, `close`);
+`DEFAULT_PLANNING_POSTGRES_LIMITS`, `RES_PLANNING_*`, `PLANNING_POSTGRES_STORE`;
+`PlanningPostgresError`; the table schemas `Planning*TableSchema`.
+
+## Common pitfalls
+
+- All four resources must be registered — the first call names the missing file.
+- `close()` the store when a process ends on its own: the LISTEN connection keeps it alive.
+- Do not aim `commits.subscribe` at hooks: `after` hooks run where the fold ran, once.
+
+## Related packages
+
+`@owlmeans/planning`, `@owlmeans/server-planning`, `@owlmeans/client-planning`,
+`@owlmeans/postgres-resource`, `@owlmeans/postgres`.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.41
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/planning-postgres",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-28T02:06:37.869Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "planning-postgres",
+      "category": "package-specific",
+      "file": "skills/planning-postgres/SKILL.md",
+      "canonicalPath": ".agents/skills/planning-postgres/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/planning-postgres/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: planning-postgres
+description: How to use @owlmeans/planning-postgres — the durable Postgres PlanningStore for @owlmeans/server-planning — the four resources (planning-card, planning-transition, planning-link, planning-schema) a target registers from resources/planning/*.ts, the service a target registers from services/planning.ts, the inline fold under a per-card advisory lock and its prelude, healing and recover(), the LISTEN/NOTIFY commit bus, the project purge, data-defined types and flows, the limits and the errors. Auto-invoked when wiring planning into a Postgres backend, touching a planning table, or diagnosing a planning commit that stays pending on Postgres.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/planning-postgres
+
+**Layer:** Infra extension
+**Install:** `"@owlmeans/planning-postgres": "^0.1.18-rc.0"` in `dependencies` (peers `pg`, `ajv`, `ajv-formats`)
+
+A `PlanningStore` of `@owlmeans/server-planning` on Postgres. It owns no planning semantics: every
+write still goes through the executor, every fold through `foldPending`, every query through
+`criteriaOf` — this package supplies four tables, the transaction a fold runs in, and the bus that
+carries commits between processes. It implements every port, the data-defined schema port
+included, so a facade over it has `definitions`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makePlanningCardPostgres` / `makePlanningTransitionPostgres` / `makePlanningLinkPostgres` / `makePlanningSchemaPostgres` | `ResourceMaker`s of the four tables, under the default aliases |
+| `makePlanningCardResource(alias?, dbAlias?, serviceAlias?)` (and the three twins), `makePlanningPostgresResources(aliases)` | The same resources under custom aliases |
+| `makePostgresPlanningService(opts?, alias?)` | The planning host service over a Postgres store — a target's `makeService()` |
+| `appendPostgresPlanning(ctx, opts?, alias?)` | The four resources (each unless present), the service and `ctx.planning()` in one call |
+| `makePostgresPlanningStore({ context, ...opts })` | The store alone; `fold(card)`, `recover(opts?)`, `close()` beside the ports |
+| `PlanningPostgresOptions` | `{ aliases?, bus?, limits?, ids?, now? }`; `PostgresPlanningServiceOptions` adds the service's own (`plugins`, `schemas`, `hooks`) |
+| `DEFAULT_PLANNING_POSTGRES_LIMITS` | `{ foldBatch: 500, gapGraceMs: 30_000, healAfterMs: 1_000, recoverAfterMs: 60_000, lockTimeoutMs: 10_000 }` |
+| `RES_PLANNING_CARD` · `RES_PLANNING_TRANSITION` · `RES_PLANNING_LINK` · `RES_PLANNING_SCHEMA`, `PLANNING_POSTGRES_STORE` | `planning-card` … `planning-schema`, `planning-postgres` |
+| `Planning*TableSchema` | The table schemas, derived from the planning record schemas |
+| `PlanningPostgresError` | `planning-postgres:<what>` — a fault (500) |
+| `planningChannel(qualified)`, `LOST_ALLOCATION` | The bus channel of a transition table; the cause of a gap's placeholder |
+
+## The four tables
+
+| Resource | Holds | Indexes |
+|---|---|---|
+| `planning-card` | projects, cards AND specifications (routed by `kind` at the query layer) | `(entityId, kind, type)`, `(parent, order)`, GIN `(parents)`, `(parent, status)`, `(entityId, intrinsic, updatedAt)`, GIN `(labels)`, `(entityId, parent, code) WHERE code IS NOT NULL`, `(parent, category) WHERE kind = 'specification'` |
+| `planning-transition` | the append-only log | UNIQUE `(card, seq)`, UNIQUE `(entityId, key) WHERE key IS NOT NULL`, `(project, at)`, `(at) WHERE (commit->>'state') = 'pending'` |
+| `planning-link` | typed edges | UNIQUE `(from, to, type)`, `(to, type)`, `(entityId, type)`, `(project)` |
+| `planning-schema` | data-defined types and flows, and one private `kind: 'head'` row per organization (its schema revision) | UNIQUE `("entityId", COALESCE(project, ''), kind, key)`, `(entityId, rev)` |
+
+- The DDL comes from `AnyWorkcardSchema`, `TransitionSchema`, `RelationshipSchema` and
+  `ScopedSchemaRecordSchema`. **Every timestamp stays `text`**: the `date-time` format would compile
+  to `timestamptz` and marshal through `Date`, which rewrites the ISO string a record carries and
+  breaks the lexicographic order `updatedSince`, `at` sorts and gap ages rely on. `seq`, `head`,
+  `revision` and `bodyChars` (and a schema record's `version` and `rev`) are `integer`; `body` is
+  `text`.
+- The card table carries one private column, `headAt` — when `head` last moved — that no read
+  ever returns.
+- A card list includes specifications only when it asks for `kind: 'specification'` or names a
+  `category` (`wantsSpecifications`, the memory store's own rule); a summary never counts them.
+- Every maker declares each index once, however often it runs.
+
+## Target wiring
+
+**Backs:** projects, cards and their documents as planning workcards — the transition log they are folded from, their links, and the card types and flows an application defines as data
+
+| Sub-project | Packages |
+|---|---|
+| backend | `@owlmeans/planning-postgres`, `@owlmeans/server-planning`, `@owlmeans/planning` |
+| common | `@owlmeans/planning` |
+| api | `@owlmeans/server-planning`, `@owlmeans/planning` |
+
+The service resolves its four resources by alias, so the registration order never matters. All
+four are required: the store keeps data-defined types and flows too, and a write reads their
+layer.
+
+```ts file=sources/backend/src/services/planning.ts
+import { makePostgresPlanningService } from '@owlmeans/planning-postgres'
+import type { Service } from '@owlmeans/context'
+import { PLANNING } from '__APP_SLUG__-common/planning'
+
+/**
+ * The planning service over Postgres — resolves its four resources
+ * (`resources/planning/{card,transition,link,schema}.ts`) by alias, so registration order never
+ * matters. The maker name is fixed — the generated service registry imports exactly this symbol.
+ */
+export const makeService = (): Service => makePostgresPlanningService({ plugins: [PLANNING] })
+```
+
+```ts file=sources/backend/src/resources/planning/card.ts
+import { makePlanningCardPostgres } from '@owlmeans/planning-postgres'
+import type { PlanningCardRecord, PlanningCardResource } from '@owlmeans/planning-postgres'
+import type { ResourceMaker } from '@owlmeans/resource'
+
+/**
+ * Projects, cards and their documents — one table (`planning-card`), routed by `kind` at the
+ * query layer. The maker is a thin wrapper: the schema and indexes are the package's own.
+ */
+export const makeResource: ResourceMaker<PlanningCardRecord, PlanningCardResource> =
+  (dbAlias, serviceAlias) => makePlanningCardPostgres(dbAlias, serviceAlias)
+```
+
+```ts file=sources/backend/src/resources/planning/transition.ts
+import { makePlanningTransitionPostgres } from '@owlmeans/planning-postgres'
+import type { PlanningTransitionResource } from '@owlmeans/planning-postgres'
+import type { Transition } from '@owlmeans/planning'
+import type { ResourceMaker } from '@owlmeans/resource'
+
+/** The append-only transition log (`planning-transition`) every card is folded from. */
+export const makeResource: ResourceMaker<Transition, PlanningTransitionResource> =
+  (dbAlias, serviceAlias) => makePlanningTransitionPostgres(dbAlias, serviceAlias)
+```
+
+```ts file=sources/backend/src/resources/planning/link.ts
+import { makePlanningLinkPostgres } from '@owlmeans/planning-postgres'
+import type { PlanningLinkResource } from '@owlmeans/planning-postgres'
+import type { Relationship } from '@owlmeans/planning'
+import type { ResourceMaker } from '@owlmeans/resource'
+
+/** Typed links between cards (`planning-link`) — one row per from, to and type. */
+export const makeResource: ResourceMaker<Relationship, PlanningLinkResource> =
+  (dbAlias, serviceAlias) => makePlanningLinkPostgres(dbAlias, serviceAlias)
+```
+
+```ts file=sources/backend/src/resources/planning/schema.ts
+import { makePlanningSchemaPostgres } from '@owlmeans/planning-postgres'
+import type { PlanningSchemaResource, PlanningSchemaRow } from '@owlmeans/planning-postgres'
+import type { ResourceMaker } from '@owlmeans/resource'
+
+/** Card types and flows defined as data (`planning-schema`), per organization and per project. */
+export const makeResource: ResourceMaker<PlanningSchemaRow, PlanningSchemaResource> =
+  (dbAlias, serviceAlias) => makePlanningSchemaPostgres(dbAlias, serviceAlias)
+```
+
+```ts file=sources/common/src/planning.ts
+import type { PlanningPlugin } from '@owlmeans/planning'
+
+/**
+ * This application's planning types and flows — see the `planning` skill for their shape. The
+ * backend's planning service registers it; a client that reads a model loads the same bundle from
+ * the server, so nothing else imports it.
+ */
+export const PLANNING: PlanningPlugin = {
+  name: 'app-planning',
+  schemas: {
+    flows: [
+      // owlmeans: add planning flows above this line
+    ],
+    types: [
+      // owlmeans: add planning types above this line
+    ],
+  },
+}
+```
+
+## A worked example
+
+The api binds the tree the shared package declares (an api's own `entrypoints.ts`, outside the
+wiring above); a hand-written backend may register everything in one call instead —
+`appendPostgres(context); appendPostgresPlanning(context, { plugins: [PLANNING] })`. A lending
+library's branches (projects) and books (cards):
+
+```ts
+// common: a lending library's branches (projects) and books (cards)
+export const PLANNING: PlanningPlugin = {
+  name: 'app-planning',
+  schemas: {
+    flows: [{
+      id: 'library:circulation', version: 1,
+      statuses: [
+        { key: 'shelved', intrinsic: IntrinsicStatus.Planned, initial: true },
+        { key: 'lent', intrinsic: IntrinsicStatus.InProgress },
+        { key: 'retired', intrinsic: IntrinsicStatus.Closed },
+      ],
+      transitions: [
+        { name: 'lend', from: ['shelved'], to: 'lent', explicit: true },
+        { name: 'return', from: ['lent'], to: 'shelved', explicit: true },
+      ],
+    }],
+    types: [
+      { type: 'library:branch', kind: WorkcardKind.Project, version: 1, fields: { type: 'object' },
+        flows: ['library:circulation'], specifications: [], cardTypes: ['library:book'], scopedCardTypes: true },
+      { type: 'library:book', kind: WorkcardKind.Card, version: 1, fields: { type: 'object' },
+        flows: ['library:circulation'], specifications: [] },
+    ],
+  },
+}
+export const planningProtocols = makePlanningProtocols({
+  base: { alias: 'library:planning', path: '/planning' }, guards: DEFAULT_GUARD, definitions: true,
+})
+
+// api: the protocol bindings
+...servePlanningEntrypoints(planningProtocols)
+```
+
+The first store call into a missing resource throws
+`PlanningPostgresError('resource-missing:planning-schema: add src/resources/planning/schema.ts')`,
+naming the file to add.
+
+## The fold
+
+`project()` folds inline — there is no queued mode. One fold is ONE transaction:
+
+1. `SET LOCAL lock_timeout` (`limits.lockTimeoutMs`), then `pg_advisory_xact_lock` on
+   `advisoryKey('planning:<qualified card table>:<card id>')`.
+2. **The prelude** walks the rows past `card.seq` (at most `foldBatch`): a FAILED row at the cursor
+   moves the cursor past it; the PENDING rows from the cursor on are the run the fold takes; a GAP
+   — a row past the expected seq, or `head > seq` with no row at all — is an append still in
+   flight while younger than `gapGraceMs` (the fold stops; the appender's own `project()` folds
+   it), and a lost allocation after that: a failed `lost-allocation` placeholder per missing seq.
+   `nextSeq` and `append` are two round trips, so without it a transient gap or an already-failed
+   row would turn the next write into a spurious `fold:out-of-order`.
+3. `foldPending` of `@owlmeans/server-planning` over a view of the ports bound to the transaction,
+   limited to that run, each transition's writes in a SAVEPOINT (`FoldOptions.unit`) — so a write
+   the database refuses fails that transition alone and the fold goes past it. Prelude and fold
+   repeat within the transaction until the log is folded or a young gap stops it.
+4. A `pg_notify` per settled event (no record).
+5. COMMIT — and only then the events reach the commit hub and the `after` hooks, in order, outside
+   the transaction and the lock. A hook may therefore write to the card it saw commit.
+
+A statement that fails outside a savepoint **poisons** the transaction: it is never committed
+(the "transaction is aborted" answers after it are not the cause — the first failure is). The
+fold is retried once; failing again, `failPending` fails the card's pending transitions in a fresh
+transaction, so no waiter hangs to its timeout. A lock that cannot be taken within
+`lockTimeoutMs` means another process is folding the card: nothing is failed, a heal follows.
+
+Allocation: `nextSeq` is a compare-and-set of `head` on the card row, stamping `headAt`; a card
+whose create has not folded counts `max(seq) + 1` from the log and the unique `(card, seq)` index
+refuses a repeat. A card write never lowers `head` (`GREATEST`) and never touches `headAt`; a write
+after the create is an UPDATE of a row that must still exist, so a card purged with its project is
+not resurrected by a fold that was already under way.
+
+## Healing and recovery
+
+- **Every waiter heals**: a status read of a pending row older than `healAfterMs` starts a
+  background fold of its card (try-lock, deduplicated per card).
+- `recover({ olderThanMs = recoverAfterMs, limit = 100 })` folds each card whose oldest pending
+  row is older than the threshold (the partial pending index), and runs once in the background on
+  the store's first use.
+- A lost allocation with no later row is released by the next fold of the card.
+
+## The commit bus
+
+`makeCommitHub` is the commit source; LISTEN/NOTIFY feeds it across processes. The channel is
+`planning_<16 hex>` of the qualified transition table, so two schemas in one database never hear
+each other. The frame is `{ p: <process id>, t: 'c', e: <CommitEvent without record> }`; a process
+ignores its own (`p`) — it delivered it itself, after its commit. LISTEN holds one dedicated
+`pg.Client` built from the pool's own configuration (no pool slot), opened on the first subscribe,
+wait or schema watch, reconnecting 1 s → 30 s; meanwhile the hub's poll ladder answers every
+waiter. A schema write sends `{ t: 's', e: <entityId> }` on the same channel. `bus: false` sends
+and hears nothing — waits poll, layers re-read the revision.
+
+## Data-defined types and flows
+
+`planning-schema` holds one record per `(organization, project layer, kind, key)`; a write is one
+transaction that bumps the organization's `head` row, writes under the compare-and-set on `version`
+(an INSERT for version 1, an UPDATE guarded on `version - 1` after) and NOTIFYs. `revision()` is a
+primary read of the head row, so the service's cached layers are never served stale. The rules —
+what may be defined, sealing, retiring — are `planning`'s and `server-planning`'s.
+
+## Purge
+
+A project's delete purges in the fold's own transaction (or, called directly, in one under the
+project's lock): a recursive walk over `parents @> ARRAY[id]` finds every doomed card, nested
+projects included; then links, transitions, the doomed projects' schema layers and the cards go,
+in that order. The project's own `delete` rows stay as its tombstone — a waiter still reads the
+delete committed.
+
+## Querying
+
+Lists, counts and summaries go through `@owlmeans/postgres-resource` (`criteriaToSql`), so a
+`WorkcardQuery` selects here what it selects in memory: `within` is `parents @> $1::varchar[]`,
+`labels` `&&`, `flows.<id>` / `fields.<key>` typed jsonb paths (a list is membership), `q` `ILIKE` +
+code prefix. A summary is one `countBy(parent, intrinsic)`. Paging is Postgres's — 100 rows unless
+`size` says otherwise.
+
+## Gotchas
+
+- `close()` the store in a process that should end on its own — the LISTEN connection keeps it
+  alive.
+- Two fold transactions of one card never run at once in a process (chained) or across processes
+  (the advisory lock); a heal that finds the lock taken yields.
+- A row appended by hand (`store.transitions.append`) is folded only by `project()`, a heal or
+  `recover()` — nothing watches the table.
+
+## Testing
+
+`bun test ./tests` — `schema.spec.ts` and `sql.spec.ts` need no database; `conformance.spec.ts`
+(the `@owlmeans/server-planning/conformance` cases), `fold.spec.ts`, `bus.spec.ts` and
+`sync.spec.ts` are gated on `POSTGRES_URL` (`postgresGate()`) and skip cleanly without it. Each spec
+file owns a throwaway schema (`makeSuite`); a fault is injected with a real trigger, never a mock.
+
+## Related
+
+- `server-planning` — the executor, `foldPending`/`failPending`, the commit hub, the conformance suite
+- `planning` — records, flows, scoped schemas, the query language
+- `postgres-resource` — the table compiler, `criteriaToSql`, `countBy`, `advisoryKey`
+- `postgres` — the connection service these resources resolve through
+- `marketing-consent-postgres` — the same resource-per-file wiring for another feature

package/build/consts.d.ts

@@ -0,0 +1,45 @@
+/** The four resource aliases — each is also the physical table name (sanitized). */
+export declare const RES_PLANNING_CARD = "planning-card";
+export declare const RES_PLANNING_TRANSITION = "planning-transition";
+export declare const RES_PLANNING_LINK = "planning-link";
+export declare const RES_PLANNING_SCHEMA = "planning-schema";
+/** The alias the store answers `PlanningStore.alias` with, and the service its placeholders name. */
+export declare const PLANNING_POSTGRES_STORE = "planning-postgres";
+export declare const DEFAULT_PLANNING_POSTGRES_LIMITS: Readonly<{
+    /** 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: 30000;
+    /** A pending row older than this makes every status read of it a heal: a background fold. */
+    healAfterMs: 1000;
+    /** What `recover()` folds by default: cards whose oldest pending row is older than this. */
+    recoverAfterMs: 60000;
+    /** `SET LOCAL lock_timeout` of a fold transaction, in milliseconds. */
+    lockTimeoutMs: 10000;
+}>;
+/** How many cards one `recover()` folds by default. */
+export declare const DEFAULT_RECOVER_LIMIT = 100;
+/** The cause and error of a failed placeholder written over a lost allocation. */
+export declare const LOST_ALLOCATION = "lost-allocation";
+/** Rounds (transactions) one `fold()` runs while a round reports more rows than `foldBatch`. */
+export declare const MAX_FOLD_ROUNDS = 16;
+/** Passes of prelude and fold one transaction runs — each over one run of consecutive pending rows. */
+export declare const MAX_FOLD_PASSES = 64;
+/** The private schema row that is an organization's monotonic schema revision. */
+export declare const SCHEMA_HEAD_KIND = "head";
+export declare const SCHEMA_HEAD_KEY = "head";
+/** Reconnect backoff of the LISTEN connection, doubling from the first to the last, in milliseconds. */
+export declare const BUS_BACKOFF: readonly [number, number];
+/** Postgres refuses a NOTIFY payload of 8000 bytes or more; a frame stays under this. */
+export declare const NOTIFY_PAYLOAD_MAX = 7900;
+/** The file a target adds for each resource — what a missing-resource error names. */
+export declare const PLANNING_RESOURCE_FILES: Readonly<{
+    card: "src/resources/planning/card.ts";
+    transition: "src/resources/planning/transition.ts";
+    link: "src/resources/planning/link.ts";
+    schema: "src/resources/planning/schema.ts";
+}>;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,kBAAkB,CAAA;AAChD,eAAO,MAAM,uBAAuB,wBAAwB,CAAA;AAC5D,eAAO,MAAM,iBAAiB,kBAAkB,CAAA;AAChD,eAAO,MAAM,mBAAmB,oBAAoB,CAAA;AAEpD,qGAAqG;AACrG,eAAO,MAAM,uBAAuB,sBAAsB,CAAA;AAE1D,eAAO,MAAM,gCAAgC;IAC3C,mGAAmG;;IAEnG;;;OAGG;;IAEH,6FAA6F;;IAE7F,4FAA4F;;IAE5F,uEAAuE;;EAEvE,CAAA;AAEF,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,kFAAkF;AAClF,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAEhD,gGAAgG;AAChG,eAAO,MAAM,eAAe,KAAK,CAAA;AAEjC,uGAAuG;AACvG,eAAO,MAAM,eAAe,KAAK,CAAA;AAEjC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,SAAS,CAAA;AACtC,eAAO,MAAM,eAAe,SAAS,CAAA;AAErC,wGAAwG;AACxG,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAA+D,CAAA;AAEjH,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,OAAQ,CAAA;AAEvC,sFAAsF;AACtF,eAAO,MAAM,uBAAuB;;;;;EAKlC,CAAA"}

package/build/consts.js

@@ -0,0 +1,45 @@
+/** 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 = Object.freeze([1_000, 30_000]);
+/** 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',
+});
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAA;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAA;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAA;AAChD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAA;AAEpD,qGAAqG;AACrG,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAA;AAE1D,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5D,mGAAmG;IACnG,SAAS,EAAE,GAAG;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM;IAClB,6FAA6F;IAC7F,WAAW,EAAE,KAAK;IAClB,4FAA4F;IAC5F,cAAc,EAAE,MAAM;IACtB,uEAAuE;IACvE,aAAa,EAAE,MAAM;CACtB,CAAC,CAAA;AAEF,uDAAuD;AACvD,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAExC,kFAAkF;AAClF,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEhD,gGAAgG;AAChG,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAA;AAEjC,uGAAuG;AACvG,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAA;AAEjC,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAA;AAErC,wGAAwG;AACxG,MAAM,CAAC,MAAM,WAAW,GAA8B,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAA8B,CAAA;AAEjH,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAEvC,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IACnD,IAAI,EAAE,gCAAgC;IACtC,UAAU,EAAE,sCAAsC;IAClD,IAAI,EAAE,gCAAgC;IACtC,MAAM,EAAE,kCAAkC;CAC3C,CAAC,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,10 @@
+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 declare class PlanningPostgresError extends ResilientError {
+    static typeName: string;
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,OAAuB,QAAQ,EAAE,MAAM,CAA0B;IAEjE,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF"}

package/build/errors.js

@@ -0,0 +1,13 @@
+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 {
+    static typeName = 'PlanningPostgresError';
+    constructor(message = 'error') {
+        super(PlanningPostgresError.typeName, `planning-postgres:${message}`);
+    }
+}
+ResilientError.registerErrorClass(PlanningPostgresError);
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IAChD,MAAM,CAAU,QAAQ,GAAW,uBAAuB,CAAA;IAEjE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,OAAO,EAAE,CAAC,CAAA;IACvE,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAA"}

package/build/index.d.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';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -0,0 +1,8 @@
+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';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/build/resource.d.ts

@@ -0,0 +1,32 @@
+import type { Relationship, Transition } from '@owlmeans/planning';
+import type { ResourceMaker } from '@owlmeans/resource';
+import type { PlanningCardRecord, PlanningCardResource, PlanningLinkResource, PlanningPostgresAliases, PlanningSchemaResource, PlanningSchemaRow, PlanningTransitionResource } from './types.js';
+/** The index names a table carries, by suffix — what the store matches a unique violation on. */
+export declare const planningIndexName: (alias: string, suffix: string) => string;
+/**
+ * `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 declare const makePlanningCardResource: (alias?: string, dbAlias?: string, serviceAlias?: string) => PlanningCardResource;
+/**
+ * `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 declare const makePlanningTransitionResource: (alias?: string, dbAlias?: string, serviceAlias?: string) => PlanningTransitionResource;
+/** `planning-link` — one row per `(from, to, type)`, read from either end, by type, and by project. */
+export declare const makePlanningLinkResource: (alias?: string, dbAlias?: string, serviceAlias?: string) => PlanningLinkResource;
+/**
+ * `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 declare const makePlanningSchemaResource: (alias?: string, dbAlias?: string, serviceAlias?: string) => PlanningSchemaResource;
+export declare const makePlanningCardPostgres: ResourceMaker<PlanningCardRecord, PlanningCardResource>;
+export declare const makePlanningTransitionPostgres: ResourceMaker<Transition, PlanningTransitionResource>;
+export declare const makePlanningLinkPostgres: ResourceMaker<Relationship, PlanningLinkResource>;
+export declare const makePlanningSchemaPostgres: ResourceMaker<PlanningSchemaRow, PlanningSchemaResource>;
+/** The four resources under the aliases a store resolves — what `appendPostgresPlanning` registers. */
+export declare const makePlanningPostgresResources: (aliases: PlanningPostgresAliases, dbAlias?: string, serviceAlias?: string) => [PlanningCardResource, PlanningTransitionResource, PlanningLinkResource, PlanningSchemaResource];
+//# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,oBAAoB,CAAA;AAKvE,OAAO,KAAK,EACV,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,sBAAsB,EAC/G,iBAAiB,EAAE,0BAA0B,EAC9C,MAAM,YAAY,CAAA;AAoBnB,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,UAAW,MAAM,UAAU,MAAM,KAAG,MAA4C,CAAA;AAE9G;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,WAC5B,MAAM,YAAgC,MAAM,iBAAiB,MAAM,KACzE,oBAeF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,WAClC,MAAM,YAAsC,MAAM,iBAAiB,MAAM,KAC/E,0BAWF,CAAA;AAED,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,WAC5B,MAAM,YAAgC,MAAM,iBAAiB,MAAM,KACzE,oBAWF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,WAC9B,MAAM,YAAkC,MAAM,iBAAiB,MAAM,KAC3E,sBASF,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC,kBAAkB,EAAE,oBAAoB,CACE,CAAA;AAE/F,eAAO,MAAM,8BAA8B,EAAE,aAAa,CAAC,UAAU,EAAE,0BAA0B,CACU,CAAA;AAE3G,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC,YAAY,EAAE,oBAAoB,CACQ,CAAA;AAE/F,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,iBAAiB,EAAE,sBAAsB,CACG,CAAA;AAEnG,uGAAuG;AACvG,eAAO,MAAM,6BAA6B,YAC/B,uBAAuB,YAAY,MAAM,iBAAiB,MAAM,KACxE,CAAC,oBAAoB,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,sBAAsB,CAKjG,CAAA"}