@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/content.js

@@ -0,0 +1,204 @@
+/**
+ * **The Content model half of the kernel** — the shared Content-axis field
+ * spreads and the base `content` resource, defined via
+ * `@thomasfosterau/effect-jsonapi`'s `Resource.make`.
+ *
+ * Ported from gardeneria's `packages/models/src/models/content.ts` (the
+ * three-state `Visibility`; website's copy is the older two-state one) and the
+ * timestamp / tombstone spreads of its `packages/models/src/utilities.ts`. A
+ * `#NNN` here names a gardeneria issue.
+ *
+ * Every spread is a plain `const` field map a Content subtype spreads into its
+ * own `Resource.make({ attributes })`, so one declaration drives the resource
+ * object, its documents and the create / update projections (the tri-state
+ * rule: a value sets, `null` clears a nullable column, `undefined` carries
+ * forward — declared on the descriptor, never re-spelled at a call site).
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/content
+ * @since 0.1.0
+ */
+import { Relationship, Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Schema from "effect/Schema";
+/**
+ * Visibility — the explicit access axis the publication policy reads,
+ * independent of soft-delete and the draft flag. Three states, because the
+ * kernel is multi-tenant:
+ *
+ * - `public` — anyone, signed in or not; the only state the KV read-through
+ *   cache may ever hold (`isPubliclyServeable` in `./publication`);
+ * - `followers` — the owner, the owner's followers (the follower seam in
+ *   `./subtype`), and the privileged rung;
+ * - `private` — the owner and the privileged rung only.
+ *
+ * The predicate lives in ONE place — `canViewOwned` in `./subtype` — and
+ * every read of an owned row goes through it. Content carries it on the
+ * Content branch's version row; owned Entity / File leaves carry the same
+ * column on their own version row, declared with
+ * {@link ownedVisibilityResourceFields}.
+ *
+ * @since 0.1.0
+ */
+export const Visibility = Schema.Literals(["public", "followers", "private"]);
+/**
+ * The two orthogonal Content-branch axes every Content subtype carries on its
+ * version row: `visibility` (three-state, above) and the binary `draft` flag
+ * (`PUB-009` / `PUB-010`). Both are required on the resource but optional to
+ * supply at create / update (a DB default applies, updates carry forward);
+ * neither is ever cleared.
+ *
+ * `Resource.attribute(schema, { create: "optional" })` is the
+ * required-on-resource, optional-at-both-inputs, never-cleared descriptor.
+ *
+ * @since 0.1.0
+ */
+export const contentVisibilityResourceFields = {
+    visibility: Resource.attribute(Visibility, { create: "optional" }),
+    draft: Resource.attribute(Schema.Boolean, { create: "optional" }),
+};
+/**
+ * The visibility / draft fields as **create-input** shapes (`Schema.optional`,
+ * non-null), for Content subtypes' hand-written `Create` structs — a form
+ * adapter passes `value | undefined`, which `createInput`'s strict
+ * `optionalKey` rejects, so the create struct is hand-written.
+ *
+ * @since 0.1.0
+ */
+export const contentVisibilityCreateFields = {
+    visibility: Schema.optional(Visibility),
+    draft: Schema.optional(Schema.Boolean),
+};
+/**
+ * The visibility axis alone, for **owned Entity / File leaves** (a garden, an
+ * organism, an image): they carry `visibility` on their own version row but
+ * no `draft` flag — a garden is not a draft of anything. Same descriptor as
+ * the Content pair: required on the resource, optional at both inputs, never
+ * cleared.
+ *
+ * @since 0.1.0
+ */
+export const ownedVisibilityResourceFields = {
+    visibility: Resource.attribute(Visibility, { create: "optional" }),
+};
+/**
+ * The version-chain timestamps every node-family resource carries:
+ * `createdAt` (the node's version-0 commit time) and `updatedAt` (its current
+ * version's), server-computed and present on the resource only
+ * (`readOnlyAttribute`), never accepted as command input.
+ *
+ * @since 0.1.0
+ */
+export const nodeTimestampResourceFields = {
+    createdAt: Resource.readOnlyAttribute(Schema.Date),
+    updatedAt: Resource.readOnlyAttribute(Schema.Date),
+};
+/**
+ * The soft-delete tombstone: `deletedAt` is present only on a tombstoned row
+ * (`resource: "optional"` — emitters omit the key entirely while live, #691)
+ * and is in no write projection. A tombstone is written by the chain's
+ * `delete` operation (`./version-chain`), never by an input.
+ *
+ * @since 0.1.0
+ */
+export const tombstoneResourceFields = {
+    deletedAt: Resource.attribute(Schema.Date, {
+        resource: "optional",
+        create: false,
+        update: false,
+    }),
+};
+/**
+ * The attribute spread every **reference-data** leaf carries: the two
+ * timestamps and the tombstone. Reference data has no visibility axis of its
+ * own — the corpus is publicly readable; a Content-branch reference leaf reads
+ * `visibility` off the branch row like every other Content subtype, and shows
+ * only a `public` row below the view-private rung.
+ *
+ * @since 0.1.0
+ */
+export const referenceLeafResourceFields = {
+    ...nodeTimestampResourceFields,
+    ...tombstoneResourceFields,
+};
+/**
+ * The attribute spread every **owned Content leaf** opens its attributes with:
+ * the timestamps, the tombstone, and the access axis —
+ * {@link referenceLeafResourceFields} plus {@link ownedVisibilityResourceFields}.
+ *
+ * `draft` is deliberately absent from THIS shared spread. The family that
+ * actually wants a bare boolean "come back and finish this later" flag
+ * declares it directly through {@link contentVisibilityResourceFields};
+ * folding it in here would put an unused, always-`false` `draft` attribute on
+ * every other owned Content leaf's wire contract. A leaf gated by a
+ * publication *stamp* (`publishedAt`, the axis `./publication` reads) carries
+ * that on its own row instead — a different axis from `draft`'s hard gate
+ * (#1118).
+ *
+ * @since 0.1.0
+ */
+export const ownedContentLeafResourceFields = {
+    ...referenceLeafResourceFields,
+    ...ownedVisibilityResourceFields,
+};
+/**
+ * The `owner` relationship every **owned** leaf carries — the account family
+ * the application supplies (its `users` resource) that owns the row.
+ *
+ * Server-assigned from the authenticated caller at creation and never
+ * re-parented: the operation layer stamps the owner from the viewer rather
+ * than from the payload (`stampOwner` in `./subtype`), so an application's
+ * hand-written create / update structs omit it. Spread into a leaf's
+ * `Resource.make({ relationships })` to opt in — the registry flags the same
+ * leaf `owned`, and the subtype factory's `access: { kind: "owned", … }`
+ * names the column the linkage reads.
+ *
+ * `Relationship.one`: every owned row has an owner. The target may still fail
+ * to resolve (deleting an account does not cascade to its rows); consumers
+ * degrade to a neutral label rather than erroring.
+ *
+ * Note that effect-jsonapi lists a `one` relationship as **required** in
+ * the generated `createPayload`; an application serving the generated payload
+ * strips the linkage at its handler seam. effect-jsonapi has no read-only
+ * linkage descriptor (effect-jsonapi#172 closed without one; 0.17.0 has
+ * none), and `tests/content.test.ts` pins the required linkage so the day one
+ * ships is visible.
+ *
+ * @since 0.1.0
+ */
+export const ownerRef = (owner) => ({
+    owner: Relationship.one(owner),
+});
+/**
+ * The base Content resource's attributes: the timestamps and the tombstone —
+ * exactly {@link referenceLeafResourceFields}, named for the resource that
+ * carries them so a subtype extending the base and a leaf spreading the
+ * fields declare the same wire shape.
+ *
+ * @since 0.1.0
+ */
+export const contentResourceAttributeFields = referenceLeafResourceFields;
+/**
+ * Build the base `content` resource with the application's own id brand
+ * (`makeContentResource(ContentId)`) — the shape {@link ContentResource}
+ * carries with the auto-derived `Resource.Id<"content">`. An application whose
+ * ids are branded hierarchically (a `PostId` that is also a `ContentId` and a
+ * `NodeId`) declares the base with its own brand so the two agree.
+ *
+ * @since 0.1.0
+ */
+export const makeContentResource = (id) => Resource.make("content", { id, attributes: contentResourceAttributeFields });
+/**
+ * The base Content resource with the auto-derived id (timestamps + soft-delete tombstone).
+ *
+ * @since 0.1.0
+ */
+export const ContentResource = Resource.make("content", {
+    attributes: contentResourceAttributeFields,
+});
+/**
+ * Lightweight `{ type, id }` reference to content.
+ *
+ * @since 0.1.0
+ */
+export const ContentRef = ContentResource.identifier;
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;AAQ9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAClE,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;CACzD,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CAC9B,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;CAC1D,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,SAAS,EAAE,QAAQ,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC;IAClD,SAAS,EAAE,QAAQ,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC;CAC1C,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE;QACzC,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,KAAK;KACd,CAAC;CACM,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,GAAG,2BAA2B;IAC9B,GAAG,uBAAuB;CAClB,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,GAAG,2BAA2B;IAC9B,GAAG,6BAA6B;CACxB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAA6B,KAAkB,EAAE,EAAE,CAAC,CAAC;IAC3E,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,2BAA2B,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAA6C,EAAY,EAAE,EAAE,CAC9F,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,8BAA8B,EAAE,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE;IACtD,UAAU,EAAE,8BAA8B;CAC3C,CAAC,CAAC;AASH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC,UAAU,CAAC"}

package/dist/documents.d.ts

@@ -0,0 +1,184 @@
+/**
+ * **Content-addressed documents** — the store seam a version row's document
+ * reference resolves through, the hash it is keyed by, and the field spread
+ * that carries the reference.
+ *
+ * A document (a ProseKit tree, in the apps) is stored once, keyed by a hash of
+ * its content, and a version row carries the hash rather than another full
+ * copy. Under an append-only chain that matters: history is never pruned
+ * (`VERSION-CHAIN-001`), so without content addressing every version of a long
+ * document would store the whole document again. The behavioural spec is
+ * `packages/database/src/documents.ts` in gardeneria and website (the
+ * `inline_documents` / `block_documents` writers) and the generated `hash_id`
+ * column of those tables.
+ *
+ * ## The invariant
+ *
+ * - **A stored document is never rewritten** (`DOC-001`). `put` stores a
+ *   document only when its hash is unseen and otherwise writes nothing; a
+ *   changed document is a new hash. So a hash a version row recorded always
+ *   reads back the exact document it was written with, and `restoreVersion`
+ *   restores the reference, never a copy. Only erasure (`./purge`) deletes a
+ *   document, once no version of any node references its hash.
+ *
+ * ## The seam
+ *
+ * Hashing is the store's job, not the kernel's: the apps derive the hash in
+ * Postgres and never re-derive it in JavaScript. The algorithm and the
+ * canonical serialisation a store must use are stated in the package README →
+ * Seams; {@link canonicalText} is that serialisation in JavaScript, for a
+ * store that doesn't run on Postgres. The kernel itself never hashes. The
+ * document type is a parameter; its schema and validation are the
+ * application's (prosekit-utilities), and pulpit never imports them.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/documents
+ * @since 0.1.0
+ */
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Effect from "effect/Effect";
+import type * as HashMap from "effect/HashMap";
+import type * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+/**
+ * A document's content hash as the kernel exchanges it: the 32-byte SHA-256
+ * digest as 64 lowercase hexadecimal characters (what gardeneria's
+ * `byteaToHex` renders a `bytea` hash as). A Postgres store keeps the 32 bytes
+ * in a `bytea` column and converts at its edge. The algorithm and the bytes it
+ * is taken over are the contract in the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export declare const DocumentHash: Schema.String;
+/**
+ * The {@link DocumentHash} string: 64 lowercase hexadecimal characters.
+ *
+ * @since 0.1.0
+ */
+export type DocumentHash = typeof DocumentHash.Type;
+/**
+ * What {@link DocumentStore.put} returns: the document's hash, and whether
+ * this call inserted it (`false` for a document already stored).
+ *
+ * @since 0.1.0
+ */
+export interface DocumentPut {
+    readonly hash: DocumentHash;
+    readonly inserted: boolean;
+}
+/**
+ * The content-addressed document store an application supplies (in
+ * production, a table per document family, keyed by the hash). `Document`
+ * is the application's document type; `E` is the store's own failure and `R`
+ * its requirements (a Drizzle store's `EffectDrizzleQueryError` and
+ * `CurrentTransaction`: like the chain store, it never opens a transaction).
+ *
+ * Every method fails only with the store's `E`, and applies no policy: a
+ * document is validated against the application's schema before it reaches
+ * `put`. Honours `DOC-001`: `put` never rewrites a stored document.
+ *
+ * @since 0.1.0
+ */
+export interface DocumentStore<Document, E, R> {
+    /**
+     * Store `document` if its hash is unseen and return the hash either way
+     * (`INSERT … ON CONFLICT DO NOTHING RETURNING`, then the hash), with
+     * `inserted: true` only when this call wrote the row (the `RETURNING`
+     * gave one back). Idempotent: a document already stored, or one equal to
+     * it under the canonical serialisation, writes nothing and returns the
+     * same hash with `inserted: false`. The hash is the store's to derive
+     * (README → Seams).
+     */
+    readonly put: (document: Document) => Effect.Effect<DocumentPut, E, R>;
+    /** The document stored at `hash`, or none. */
+    readonly get: (hash: DocumentHash) => Effect.Effect<Option.Option<Document>, E, R>;
+    /**
+     * One `hash = ANY($hashes)` read, never `hashes.length` sequential gets: the
+     * documents found, keyed by hash. A hash with no document is absent from
+     * the map.
+     */
+    readonly getMany: (hashes: ReadonlyArray<DocumentHash>) => Effect.Effect<HashMap.HashMap<DocumentHash, Document>, E, R>;
+}
+/**
+ * What an {@link onDocumentInsert} hook is shown: a document this `put`
+ * stored for the first time, and its hash.
+ *
+ * @since 0.1.0
+ */
+export interface DocumentInserted<Document> {
+    readonly hash: DocumentHash;
+    readonly document: Document;
+}
+/**
+ * The document store with a first-insert hook: its `put` runs `hook` after
+ * a `put` that inserted (`inserted: true`), and never after one that found
+ * the document already stored, so the hook runs once per document (an
+ * embedding job, in the apps). The hook runs in the `put`'s own
+ * transaction, so a failure (the store's `E`) fails the `put` and rolls
+ * the insert back with the caller's transaction; enqueue durable work as a
+ * row the same transaction writes (an outbox). `get` and `getMany` are the
+ * store's own.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { onDocumentInsert } from "@thomasfosterau/pulpit/documents";
+ * import { makeInMemoryDocumentStore } from "@thomasfosterau/pulpit/testing";
+ *
+ * const inserted: Array<string> = [];
+ * const store = onDocumentInsert(makeInMemoryDocumentStore<{ readonly text: string }>(), (event) =>
+ *   Effect.sync(() => {
+ *     inserted.push(event.document.text);
+ *   }),
+ * );
+ * await Effect.runPromise(Effect.andThen(store.put({ text: "hello" }), store.put({ text: "hello" })));
+ * deepStrictEqual(inserted, ["hello"]);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const onDocumentInsert: <Document, E, R>(store: DocumentStore<Document, E, R>, hook: (event: DocumentInserted<Document>) => Effect.Effect<void, E, R>) => DocumentStore<Document, E, R>;
+/**
+ * The canonical text of a JSON document, the bytes the {@link DocumentStore}
+ * hash contract (README → Seams → `DocumentStore`) takes SHA-256 over:
+ * PostgreSQL's `jsonb` text output, with object keys ordered shorter-first by
+ * UTF-8 byte length and then bytewise, `": "` after a key, `", "` between
+ * members and elements, only `"`, `\` and the control characters escaped, and
+ * numbers as `numeric` prints them (never with an exponent). A Postgres store
+ * never needs it (the database derives the hash from `document_jsonb::text`);
+ * a store that doesn't run on Postgres hashes the UTF-8 bytes of this text to
+ * reproduce the contract's hashes. The kernel's suite pins it to text and
+ * hashes taken from Postgres. Pure and total.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { canonicalText } from "@thomasfosterau/pulpit/documents";
+ *
+ * strictEqual(
+ *   canonicalText({ b: 1e21, aa: [true, null], a: "é" }),
+ *   '{"a": "é", "b": 1000000000000000000000, "aa": [true, null]}',
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const canonicalText: (value: Schema.Json) => string;
+/**
+ * The attribute spread for a version row's document reference: `key` carries
+ * the {@link DocumentHash} a {@link DocumentStore} returned from `put` (its `hash`).
+ * Required on the resource and at create; optional at update, where an absent
+ * key carries the previous version's reference forward (the tri-state rule),
+ * and never cleared. Spread into a leaf's `Resource.make({ attributes })`,
+ * once per document column (`...documentRef("title")`,
+ * `...documentRef("body")`).
+ *
+ * A document the leaf may omit is declared directly, as
+ * `Resource.attribute(Schema.NullOr(DocumentHash), { create: "optional" })`,
+ * so that `null` clears it.
+ *
+ * @since 0.1.0
+ */
+export declare const documentRef: <const Key extends string>(key: Key) => Record<Key, Resource.Attribute<Schema.String, true, "required", "optional", false>>;
+//# sourceMappingURL=documents.d.ts.map

package/dist/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE1D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,eAIxB,CAAC;AACF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;AAIpD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;IAC3C;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvE,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACnF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,KAChC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACnE;AAID;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACxC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,SACtC,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,QAC9B,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,KACrE,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAM7B,CAAC;AAwDH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,UAAW,MAAM,CAAC,IAAI,KAAG,MAWlD,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,CAAC,GAAG,SAAS,MAAM,OAAO,GAAG,wFACL,CAAC"}

package/dist/documents.js

@@ -0,0 +1,190 @@
+/**
+ * **Content-addressed documents** — the store seam a version row's document
+ * reference resolves through, the hash it is keyed by, and the field spread
+ * that carries the reference.
+ *
+ * A document (a ProseKit tree, in the apps) is stored once, keyed by a hash of
+ * its content, and a version row carries the hash rather than another full
+ * copy. Under an append-only chain that matters: history is never pruned
+ * (`VERSION-CHAIN-001`), so without content addressing every version of a long
+ * document would store the whole document again. The behavioural spec is
+ * `packages/database/src/documents.ts` in gardeneria and website (the
+ * `inline_documents` / `block_documents` writers) and the generated `hash_id`
+ * column of those tables.
+ *
+ * ## The invariant
+ *
+ * - **A stored document is never rewritten** (`DOC-001`). `put` stores a
+ *   document only when its hash is unseen and otherwise writes nothing; a
+ *   changed document is a new hash. So a hash a version row recorded always
+ *   reads back the exact document it was written with, and `restoreVersion`
+ *   restores the reference, never a copy. Only erasure (`./purge`) deletes a
+ *   document, once no version of any node references its hash.
+ *
+ * ## The seam
+ *
+ * Hashing is the store's job, not the kernel's: the apps derive the hash in
+ * Postgres and never re-derive it in JavaScript. The algorithm and the
+ * canonical serialisation a store must use are stated in the package README →
+ * Seams; {@link canonicalText} is that serialisation in JavaScript, for a
+ * store that doesn't run on Postgres. The kernel itself never hashes. The
+ * document type is a parameter; its schema and validation are the
+ * application's (prosekit-utilities), and pulpit never imports them.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/documents
+ * @since 0.1.0
+ */
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import * as Schema from "effect/Schema";
+// ── Vocabulary ────────────────────────────────────────────────────────
+/**
+ * A document's content hash as the kernel exchanges it: the 32-byte SHA-256
+ * digest as 64 lowercase hexadecimal characters (what gardeneria's
+ * `byteaToHex` renders a `bytea` hash as). A Postgres store keeps the 32 bytes
+ * in a `bytea` column and converts at its edge. The algorithm and the bytes it
+ * is taken over are the contract in the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export const DocumentHash = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/, {
+    description: "a SHA-256 document hash as 64 lowercase hexadecimal characters",
+}));
+/**
+ * The document store with a first-insert hook: its `put` runs `hook` after
+ * a `put` that inserted (`inserted: true`), and never after one that found
+ * the document already stored, so the hook runs once per document (an
+ * embedding job, in the apps). The hook runs in the `put`'s own
+ * transaction, so a failure (the store's `E`) fails the `put` and rolls
+ * the insert back with the caller's transaction; enqueue durable work as a
+ * row the same transaction writes (an outbox). `get` and `getMany` are the
+ * store's own.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { onDocumentInsert } from "@thomasfosterau/pulpit/documents";
+ * import { makeInMemoryDocumentStore } from "@thomasfosterau/pulpit/testing";
+ *
+ * const inserted: Array<string> = [];
+ * const store = onDocumentInsert(makeInMemoryDocumentStore<{ readonly text: string }>(), (event) =>
+ *   Effect.sync(() => {
+ *     inserted.push(event.document.text);
+ *   }),
+ * );
+ * await Effect.runPromise(Effect.andThen(store.put({ text: "hello" }), store.put({ text: "hello" })));
+ * deepStrictEqual(inserted, ["hello"]);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const onDocumentInsert = (store, hook) => ({
+    ...store,
+    put: (document) => Effect.tap(store.put(document), ({ hash, inserted }) => inserted ? hook({ hash, document }) : Effect.void),
+});
+// ── The hash contract ─────────────────────────────────────────────────
+const utf8 = new TextEncoder();
+/** A string's UTF-8 bytes as one character per byte, so that string order is byte order. */
+const byteString = (value) => String.fromCharCode(...utf8.encode(value));
+/** jsonb's key order: shorter UTF-8 byte length first, then bytewise. */
+const keyOrder = Order.combine(Order.mapInput(Order.Number, (key) => utf8.encode(key).length), Order.mapInput(Order.String, byteString));
+/**
+ * A number as Postgres `numeric` prints it: JavaScript's shortest round-trip
+ * digits, written positionally (`1e+21` → `1000000000000000000000`,
+ * `1.5e-7` → `0.00000015`), since `numeric` has no exponent form.
+ */
+const numericText = (value) => {
+    const shortest = String(value);
+    const match = /^(-?)(\d)(?:\.(\d+))?e([+-]\d+)$/.exec(shortest);
+    if (match === null)
+        return shortest;
+    const [, sign = "", lead = "", fraction = "", exponent = "0"] = match;
+    const digits = lead + fraction;
+    const point = 1 + Number(exponent);
+    if (point >= digits.length)
+        return sign + digits + "0".repeat(point - digits.length);
+    if (point <= 0)
+        return `${sign}0.${"0".repeat(-point)}${digits}`;
+    return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+};
+/** The short escapes jsonb's `escape_json` writes; every other control character is `\u00xx`. */
+const SHORT_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+};
+/** One character as jsonb's `escape_json` writes it: a short escape, `\u00xx` below U+0020, else itself. */
+const escapeCharacter = (character) => {
+    const code = character.charCodeAt(0);
+    return (SHORT_ESCAPES[character] ??
+        (code < 0x20 ? `\\u${code.toString(16).padStart(4, "0")}` : character));
+};
+/** A string literal as jsonb prints it: `"`, `\` and the control characters escaped, nothing else. */
+const stringText = (value) => `"${Arr.map(Arr.fromIterable(value), escapeCharacter).join("")}"`;
+/**
+ * The canonical text of a JSON document, the bytes the {@link DocumentStore}
+ * hash contract (README → Seams → `DocumentStore`) takes SHA-256 over:
+ * PostgreSQL's `jsonb` text output, with object keys ordered shorter-first by
+ * UTF-8 byte length and then bytewise, `": "` after a key, `", "` between
+ * members and elements, only `"`, `\` and the control characters escaped, and
+ * numbers as `numeric` prints them (never with an exponent). A Postgres store
+ * never needs it (the database derives the hash from `document_jsonb::text`);
+ * a store that doesn't run on Postgres hashes the UTF-8 bytes of this text to
+ * reproduce the contract's hashes. The kernel's suite pins it to text and
+ * hashes taken from Postgres. Pure and total.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { canonicalText } from "@thomasfosterau/pulpit/documents";
+ *
+ * strictEqual(
+ *   canonicalText({ b: 1e21, aa: [true, null], a: "é" }),
+ *   '{"a": "é", "b": 1000000000000000000000, "aa": [true, null]}',
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const canonicalText = (value) => {
+    if (value === null)
+        return "null";
+    if (Predicate.isBoolean(value))
+        return value ? "true" : "false";
+    if (Predicate.isNumber(value))
+        return numericText(value);
+    if (Predicate.isString(value))
+        return stringText(value);
+    if (Arr.isArray(value))
+        return `[${value.map(canonicalText).join(", ")}]`;
+    const members = Arr.sort(Record.toEntries(value), Order.mapInput(keyOrder, ([key]) => key));
+    return `{${members.map(([key, member]) => `${stringText(key)}: ${canonicalText(member)}`).join(", ")}}`;
+};
+// ── The field spread ──────────────────────────────────────────────────
+/**
+ * The attribute spread for a version row's document reference: `key` carries
+ * the {@link DocumentHash} a {@link DocumentStore} returned from `put` (its `hash`).
+ * Required on the resource and at create; optional at update, where an absent
+ * key carries the previous version's reference forward (the tri-state rule),
+ * and never cleared. Spread into a leaf's `Resource.make({ attributes })`,
+ * once per document column (`...documentRef("title")`,
+ * `...documentRef("body")`).
+ *
+ * A document the leaf may omit is declared directly, as
+ * `Resource.attribute(Schema.NullOr(DocumentHash), { create: "optional" })`,
+ * so that `null` clears it.
+ *
+ * @since 0.1.0
+ */
+export const documentRef = (key) => Record.singleton(key, Resource.attribute(DocumentHash));
+//# sourceMappingURL=documents.js.map

package/dist/documents.js.map

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