@thomasfosterau/pulpit 0.0.0-stage → 0.1.0

package/src/publication.ts

@@ -0,0 +1,225 @@
+/**
+ * **The publication axis, the moderation state, and the cache serveability
+ * policy.**
+ *
+ * Ported from gardeneria's `packages/database/src/publication.ts`
+ * (`isPublished` / `isNotPublished` / `publishedFilter`) and the
+ * `isPubliclyServeable` gate of its `apps/api/src/cache.ts`, with its tests
+ * (`apps/api/tests/resource-cache-readthrough.test.ts`). A `#NNN` here names
+ * a gardeneria issue.
+ *
+ * ## Published means stamped AND arrived
+ *
+ * A publication stamp (`publishedAt`) is a datetime the author controls, so
+ * an author may set a FUTURE one, and that is what scheduling is (#1121): the
+ * row exists, it is stamped, and it is not out yet. `IS NOT NULL` and "live"
+ * are therefore different predicates, and every reader of the axis gets the
+ * two-part answer from here. The unpublished predicate is the exact
+ * complement — an owner's "unpublished" list is their drafts AND their
+ * scheduled rows. In SQL the clock is the database's (`now()`, one per
+ * query); the list filter node carries that contract (`./filter`).
+ *
+ * ## The serveability policy (`CACHE-AUTH-005`)
+ *
+ * The KV read-through cache is populated by writes — a privileged editor's
+ * save included — so it CAN hold a resource only some viewers may read, and
+ * it serves anonymous readers. {@link isPubliclyServeable} is the gate on
+ * both of its paths (serving a hit, and populating on a miss, where a
+ * non-serveable resource is evicted so a `public → private` flip
+ * self-purges). **The rule: every publication axis the operation layer
+ * gates on must be present in the cached attributes AND pass.** A present
+ * axis whose value is not exactly the serveable literal is refused; an absent
+ * axis means the resource does not ride it — except where the family's
+ * options say absence is itself a refusal:
+ *
+ * - `owned` — an owned family whose `visibility` attribute is absent refuses:
+ *   the projection dropped the one attribute that decides who may see the
+ *   row, and reading that as public is a fail-open (#1096, #1092);
+ * - `publishGated` — a family gated by its stamp refuses a missing,
+ *   unparseable or future `publishedAt`. A leaf that declares `./subtype`'s
+ *   live pointer is one: its live view supplies the stamp, and its
+ *   handlers write the cache only from the anonymous (live) read
+ *   (pulpit#46).
+ *
+ * What the predicate structurally cannot express is a gate that depends on
+ * state outside the cached resource (a comment's inherited target gate,
+ * #1475); a family with one closes it on the write path (evict on the
+ * target's mutation) with the cache TTL floor as the backstop.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/publication
+ * @since 0.1.0
+ */
+
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { always, and, gt, lte, notPublished, published, type ListFilter } from "./filter.ts";
+
+/**
+ * A moderated family's review state (`PUB-005`): only `approved` is
+ * serveable from the cache. A `pending` / `rejected` row is still readable by
+ * its author at the operation layer — it is refused from the cache because
+ * only SOME viewers may read it.
+ *
+ * @since 0.1.0
+ */
+export const ModerationState = Schema.Literals(["pending", "approved", "rejected"]);
+/**
+ * The {@link ModerationState} literal union: `"pending" | "approved" | "rejected"`.
+ *
+ * @since 0.1.0
+ */
+export type ModerationState = typeof ModerationState.Type;
+
+/**
+ * Stamped, and the stamp has arrived at `now`.
+ *
+ * @since 0.1.0
+ */
+export const isPublishedAt = (publishedAt: Option.Option<Date>, now: Date): boolean =>
+  Option.exists(publishedAt, (stamp) => stamp.getTime() <= now.getTime());
+
+/**
+ * Not out at `now`: unstamped, or stamped in the future — the exact complement of {@link isPublishedAt}.
+ *
+ * @since 0.1.0
+ */
+export const isNotPublishedAt = (publishedAt: Option.Option<Date>, now: Date): boolean =>
+  !isPublishedAt(publishedAt, now);
+
+/**
+ * The axis as one list-filter arm, for a `?filter[published]=` that may be
+ * absent: none in, `always` out (no predicate) — so a list reads one line per
+ * axis.
+ *
+ * @since 0.1.0
+ */
+export const publishedFilter = <Following = never>(
+  column: string,
+  wanted: Option.Option<boolean>,
+): ListFilter<Following> =>
+  Option.match(wanted, {
+    onNone: (): ListFilter<Following> => always,
+    onSome: (isWanted) => (isWanted ? published(column) : notPublished(column)),
+  });
+
+/**
+ * The rows whose publication stamp arrived in the window `(since, now]`:
+ * `since < column AND column <= now`, as a list filter for an application's
+ * cron to drive a scheduled-publication sweep (pulpit#45). A write fires its
+ * lifecycle events when it is made, so a version stamped for the future
+ * emits nothing when its stamp arrives; a sweep that passes each run's `now`
+ * as the next run's `since` sees every such row exactly once, since the
+ * windows are half-open and abut. Pass it as a list request's `where`, read
+ * as a viewer who may see the rows the sweep is for (the list still applies
+ * the leaf's access and soft-delete arms). An unordered instant (an invalid
+ * `Date`) matches nothing. `column` defaults to `publishedAt`.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { evaluate } from "@thomasfosterau/pulpit/filter";
+ * import { duePublications } from "@thomasfosterau/pulpit/publication";
+ *
+ * const due = duePublications(new Date("2026-10-22T00:00:00Z"), new Date("2026-10-22T01:00:00Z"));
+ * const context = { now: new Date("2026-10-22T01:00:00Z"), contains: () => false };
+ * strictEqual(evaluate(due, { publishedAt: new Date("2026-10-22T00:30:00Z") }, context), true);
+ * strictEqual(evaluate(due, { publishedAt: new Date("2026-10-22T00:00:00Z") }, context), false);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const duePublications = <Following = never>(
+  since: Date,
+  now: Date,
+  column: string = "publishedAt",
+): ListFilter<Following> => and<Following>(gt(column, since), lte(column, now));
+
+/* oxlint-disable effect/prefer-option-over-null -- an optional field is `?: T | undefined` (AGENTS.md → Conventions), so a caller can forward its own `undefined` under `exactOptionalPropertyTypes`; the omitted key is the absence, read as such by every reader, so there is no value to model as an `Option` */
+/**
+ * A family's cache posture: which absent axes are refusals.
+ *
+ * @since 0.1.0
+ */
+export interface ServeabilityOptions {
+  /** An owned family: a missing `visibility` refuses (#1096). */
+  readonly owned?: boolean | undefined;
+  /** A stamp-gated family: a missing, unparseable or future `publishedAt` refuses. */
+  readonly publishGated?: boolean | undefined;
+  /** The instant a stamp must have arrived by; the wall clock when omitted. */
+  readonly now?: Date | undefined;
+}
+/* oxlint-enable effect/prefer-option-over-null */
+
+/* oxlint-disable effect/no-unknown-parameters, effect/no-unknown-returns -- the cache's security gate must accept whatever the KV hands back, including a value that fails to parse: refusing malformed input IS its contract, so the untyped value is the boundary itself */
+/**
+ * Whether a serialised `publishedAt` names an instant that has arrived. The
+ * value crosses KV as JSON, so it arrives as a string on a hit and as a
+ * `Date` on populate; anything that does not parse to a finite instant is
+ * refused rather than guessed at.
+ */
+const hasArrivedStamp = (publishedAt: unknown, now: Date): boolean => {
+  const instant =
+    publishedAt instanceof Date
+      ? publishedAt.getTime()
+      : Predicate.isString(publishedAt)
+        ? Option.match(DateTime.make(publishedAt), {
+            onNone: () => Number.NaN,
+            onSome: DateTime.toEpochMillis,
+          })
+        : Number.NaN;
+  return Number.isFinite(instant) && instant <= now.getTime();
+};
+
+/**
+ * Whether a cached resource may be served from the cache to a viewer who
+ * reaches the cache at all (a viewer who bypasses it for freshness reads the
+ * database directly). See the module doc for the rule.
+ *
+ * @since 0.1.0
+ */
+export const isPubliclyServeable = (
+  resource: unknown,
+  options: ServeabilityOptions = {},
+): boolean => {
+  if (!Predicate.isObject(resource)) return false;
+  const attributes = resource["attributes"];
+  // No attributes block to inspect: refuse rather than guess.
+  if (!Predicate.isObject(attributes)) return false;
+  const read = (key: string): unknown => attributes[key];
+  const visibility = read("visibility");
+  if (options.owned === true && visibility === undefined) return false;
+  if (
+    options.publishGated === true &&
+    !hasArrivedStamp(read("publishedAt"), options.now ?? DateTime.toDate(DateTime.nowUnsafe()))
+  ) {
+    return false;
+  }
+  if (visibility !== undefined && visibility !== "public") return false;
+  const moderationState = read("moderationState");
+  if (moderationState !== undefined && moderationState !== "approved") return false;
+  // The draft axis: a draft is a gate wherever it is present, and a present
+  // value that is not exactly `false` (`null` included) reads as a draft, as
+  // the operation layer's row predicate reads it (SEC-AUTH-ENUM-001).
+  const draft = read("draft");
+  if (draft !== undefined && draft !== false) return false;
+  // A tombstone is an admin-only read, and emitters omit the key while live
+  // (#691): present at all — `null` included — refuses.
+  return read("deletedAt") === undefined;
+};
+
+/**
+ * The `serveable` hook the application's resource cache takes, bound to a
+ * family's posture: `(resource) => boolean`. The cache, which the application
+ * owns (no library is expected to provide one; effect-web#33), applies it on
+ * both its read and write paths and evicts on a non-serveable write.
+ *
+ * @since 0.1.0
+ */
+export const serveablePolicy =
+  (options: Omit<ServeabilityOptions, "now"> = {}) =>
+  (resource: unknown): boolean =>
+    isPubliclyServeable(resource, options);
+/* oxlint-enable effect/no-unknown-parameters, effect/no-unknown-returns */

package/src/purge.ts

@@ -0,0 +1,313 @@
+/**
+ * **Purge**: erasure, the one destructive path through a node's history
+ * (pulpit#58).
+ *
+ * A tombstone hides a node and keeps every version of its content, readable
+ * at the view-deleted rung. Where that content is personal data and the law
+ * requires it erased rather than hidden, {@link definePurge}'s `purge`
+ * hard-deletes it. It removes the node's whole chain, every row the kernel's
+ * other seams keep for the node, and the documents and file bytes no other
+ * version references any longer.
+ *
+ * ## The model (owner decision on pulpit#58, 2026-10-14)
+ *
+ * - **The whole chain goes.** Every version row on every level of the
+ *   node's chain is deleted, with its identity row. It is the one sanctioned
+ *   exception to the append-only chain (`VERSION-CHAIN-001/002`, SECURITY.md):
+ *   nothing else deletes or rewrites a version row. With the chain go the
+ *   node's working copies, proposals, publication facts, path claims, reports
+ *   and every edge with the node at an end: rows that name a node that no
+ *   longer exists.
+ * - **Shared content is deleted only when nothing else references it.**
+ *   Documents (`./documents`) and bytes (`./blobs`) are shared by hash. A
+ *   purge drops the node's references; a document or a blob is deleted only
+ *   when no version of any other node still references its hash, so
+ *   identical content another node uses survives. A deleted document is the
+ *   one exception to `DOC-001` (a stored document is never rewritten).
+ * - **Bytes are deleted after the commit**, as `./blobs` writes them after
+ *   the commit: the chain's erasure and the document deletes run in
+ *   `transact`, the caller's write boundary, and the blob store is told only
+ *   once it has returned. A failed byte delete never fails the purge, which
+ *   has committed: the report lists the bytes left behind
+ *   ({@link PurgeReport.bytesLeft}) for a retry through `BlobStore.delete`.
+ * - **A dedicated rung.** `purge` runs at the rung the definition's
+ *   `canPurge` names, checked before anything is read, so a caller below it
+ *   learns nothing about any id (`Unauthorized` / `Forbidden` for every id
+ *   alike). At the rung, an unknown or already purged id fails
+ *   `NodeNotFound`. A live node purges as a tombstoned one does: erasure is
+ *   one step, never "delete, then purge".
+ *
+ * ## The seam
+ *
+ * The erasure itself is the application's {@link PurgeStore}: it knows
+ * which tables hold rows keyed to a node and which columns carry a document
+ * or content hash. The contract is stated in the package README → Seams.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/purge
+ * @since 0.1.0
+ */
+
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import { blobKey, type BlobStore, type ContentHash } from "./blobs.ts";
+import type { DocumentHash } from "./documents.ts";
+import {
+  Forbidden,
+  Unauthorized,
+  type ResourceCacheSeam,
+  type Viewer,
+  type ViewerAccount,
+} from "./subtype.ts";
+import { NodeNotFound, type VersionChainStore } from "./version-chain.ts";
+
+// ── The seam ──────────────────────────────────────────────────────────
+
+/**
+ * What {@link PurgeStore.eraseNode} reports: every document hash and every
+ * content hash the erased version rows referenced, each once.
+ *
+ * @since 0.1.0
+ */
+export interface ErasedReferences {
+  readonly documents: ReadonlyArray<DocumentHash>;
+  readonly blobs: ReadonlyArray<ContentHash>;
+}
+
+/**
+ * The erasure seam an application supplies, over the same tables as its
+ * other stores. Like them it applies no policy, fails only with its `E`,
+ * and never opens a transaction: {@link definePurge} runs its three methods,
+ * in order, inside the caller's `transact`.
+ *
+ * @since 0.1.0
+ */
+export interface PurgeStore<E, R> {
+  /**
+   * Hard-delete node `id`: every version row on every level of its chain,
+   * its identity row and owner row, and every row the kernel's other seams
+   * keep for it (working copies, proposals, publication facts, path claims
+   * and aliases, reports, and each edge with the node at an end). Returns
+   * the document and content hashes the deleted version rows referenced
+   * (`DELETE … RETURNING`). An id with no rows deletes nothing and returns
+   * none.
+   */
+  readonly eraseNode: (id: string) => Effect.Effect<ErasedReferences, E, R>;
+  /**
+   * Delete each document of `hashes` that no version row of any node
+   * references any longer, and return the hashes deleted. Runs after
+   * {@link PurgeStore.eraseNode} in the same transaction, so the purged
+   * node's own references are already gone.
+   */
+  readonly deleteUnreferencedDocuments: (
+    hashes: ReadonlyArray<DocumentHash>,
+  ) => Effect.Effect<ReadonlyArray<DocumentHash>, E, R>;
+  /**
+   * Of `hashes`, the content hashes no version row of any node references
+   * any longer: the bytes {@link definePurge} deletes once the transaction
+   * has returned. Runs after {@link PurgeStore.eraseNode} in the same
+   * transaction.
+   */
+  readonly unreferencedBlobs: (
+    hashes: ReadonlyArray<ContentHash>,
+  ) => Effect.Effect<ReadonlyArray<ContentHash>, E, R>;
+}
+
+// ── The operation ─────────────────────────────────────────────────────
+
+/**
+ * What a purge did: the node erased, the documents deleted, the bytes
+ * deleted, and the bytes left behind because their delete failed (or no
+ * blob store was given), each by hash.
+ *
+ * @since 0.1.0
+ */
+export interface PurgeReport {
+  readonly id: string;
+  /** The documents deleted: those the node referenced and no other version does. */
+  readonly documents: ReadonlyArray<DocumentHash>;
+  /** The bytes deleted from the blob store. */
+  readonly blobs: ReadonlyArray<ContentHash>;
+  /**
+   * Unreferenced bytes still in the blob store: their delete failed after
+   * the commit, or the definition has no blob store. Delete each with
+   * `BlobStore.delete(blobKey(hash))`; nothing references them any more.
+   */
+  readonly bytesLeft: ReadonlyArray<ContentHash>;
+}
+
+/**
+ * The operation {@link definePurge} produces.
+ *
+ * @since 0.1.0
+ */
+export interface PurgeOps<E, R> {
+  /** The leaf's wire type, as declared. */
+  readonly type: string;
+  /**
+   * Erase node `id`. Fails `Unauthorized` when anonymous and `Forbidden`
+   * below the purge rung, for every id alike; at the rung, `NodeNotFound`
+   * when `id` has no chain.
+   */
+  readonly purge: (
+    id: string,
+  ) => Effect.Effect<PurgeReport, Unauthorized | Forbidden | NodeNotFound | E, R>;
+}
+
+/**
+ * What {@link definePurge} binds.
+ *
+ * @since 0.1.0
+ */
+export interface PurgeDefinition<E, EB, R> {
+  /** The leaf's JSON:API wire type: names spans and tags `NodeNotFound`. */
+  readonly type: string;
+  /** The leaf's version-chain store: `head` says whether the node exists. */
+  readonly chain: VersionChainStore<E, R>;
+  /** The erasure seam. */
+  readonly store: PurgeStore<E, R>;
+  /** The request's viewer (effect-auth's session context). */
+  readonly viewer: Effect.Effect<Viewer, never, R>;
+  /**
+   * The purge rung: whether `account` may erase a node of this leaf. An
+   * application rung of its own (an admin, a data-protection officer),
+   * which, like the `AccessPolicy` axes, must fail closed on an unknown
+   * role.
+   */
+  readonly canPurge: (account: ViewerAccount) => boolean;
+  /** The caller's write boundary; the erasure runs inside it. */
+  readonly transact: <A, E2>(effect: Effect.Effect<A, E2, R>) => Effect.Effect<A, E2, R>;
+  /**
+   * The byte store unreferenced bytes are deleted from, after the commit.
+   * Omitted, every unreferenced content hash is reported in
+   * {@link PurgeReport.bytesLeft}.
+   */
+  // oxlint-disable-next-line effect/prefer-option-over-null -- an optional field is `?: T | undefined` (AGENTS.md → Conventions), so a caller can forward its own `undefined` under `exactOptionalPropertyTypes`; the omitted key is "no blob store"
+  readonly blobs?: BlobStore<EB, R> | undefined;
+  /**
+   * The resource cache, evicted after the commit at the version past the
+   * purged head, so no cached copy outlives the erasure (`CACHE-AUTH-005`).
+   */
+  // oxlint-disable-next-line effect/prefer-option-over-null -- an optional field is `?: T | undefined` (AGENTS.md → Conventions); the omitted key is "the leaf is not cached"
+  readonly cache?: ResourceCacheSeam<unknown, R> | undefined;
+}
+
+/**
+ * Bind a leaf's purge. `purge(id)` checks the purge rung, then, inside
+ * `transact`, erases the node through the {@link PurgeStore}, deletes the
+ * documents nothing else references, and reads which of its bytes nothing
+ * else references; once `transact` has returned it evicts the cache and
+ * deletes those bytes. A failed byte delete is logged and reported in
+ * {@link PurgeReport.bytesLeft}, never a failure.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as HashMap from "effect/HashMap";
+ * import * as Option from "effect/Option";
+ * import { defineVersionChain } from "@thomasfosterau/pulpit/version-chain";
+ * import { definePurge } from "@thomasfosterau/pulpit/purge";
+ * import {
+ *   makeInMemoryChainStore,
+ *   makeInMemoryDocumentStore,
+ *   makeInMemoryPurgeStore,
+ * } from "@thomasfosterau/pulpit/testing";
+ *
+ * const chain = makeInMemoryChainStore();
+ * const documents = makeInMemoryDocumentStore();
+ * const notes = defineVersionChain("notes", chain);
+ * const purge = definePurge({
+ *   type: "notes",
+ *   chain,
+ *   store: makeInMemoryPurgeStore({ chains: [chain], documents, documentColumns: ["body"] }),
+ *   viewer: Effect.succeed(Option.some({ id: "u-admin", role: "admin" })),
+ *   canPurge: (account) => account.role === "admin",
+ *   transact: (effect) => effect,
+ * });
+ *
+ * const report = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const { hash } = yield* documents.put({ text: "personal data" });
+ *     const { id } = yield* notes.create({
+ *       id: Option.none(),
+ *       state: { body: hash },
+ *       actorId: Option.none(),
+ *     });
+ *     return yield* purge.purge(id);
+ *   }),
+ * );
+ *
+ * // The chain and its only document (a hash no other version references) are gone.
+ * deepStrictEqual(chain.rows(), []);
+ * deepStrictEqual(HashMap.size(documents.stored()), 0);
+ * deepStrictEqual(report.documents.length, 1);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const definePurge = <E, EB, R>(definition: PurgeDefinition<E, EB, R>): PurgeOps<E, R> => {
+  const { type, chain, store, transact } = definition;
+
+  /** The purge rung, checked before any row is read. */
+  const gate = Effect.flatMap(
+    definition.viewer,
+    (viewer): Effect.Effect<ViewerAccount, Unauthorized | Forbidden> =>
+      Option.match(viewer, {
+        onNone: () => Effect.fail(new Unauthorized()),
+        onSome: (account) =>
+          definition.canPurge(account) ? Effect.succeed(account) : Effect.fail(new Forbidden()),
+      }),
+  );
+
+  /** The erasure, in the caller's transaction: what it deleted and which bytes it freed. */
+  const erase = (id: string) =>
+    Effect.gen(function* () {
+      const head = yield* chain.head(id);
+      if (Option.isNone(head)) return yield* new NodeNotFound({ type, id });
+      const erased = yield* store.eraseNode(id);
+      const documents = yield* store.deleteUnreferencedDocuments(Arr.dedupe(erased.documents));
+      const freed = yield* store.unreferencedBlobs(Arr.dedupe(erased.blobs));
+      return { head: head.value.version, documents, freed };
+    });
+
+  /** Delete one blob's bytes after the commit: whether they are gone. */
+  const deleteBytes = (hash: ContentHash) =>
+    definition.blobs === undefined
+      ? Effect.succeed(false)
+      : Effect.exit(definition.blobs.delete(blobKey(hash))).pipe(
+          Effect.tap((exit) =>
+            Exit.isFailure(exit)
+              ? Effect.logWarning(`${type}: bytes ${hash} left after purge`, exit.cause)
+              : Effect.void,
+          ),
+          Effect.map(Exit.isSuccess),
+        );
+
+  const purge = Effect.fn(`${type}.purge`)(function* (id: string) {
+    yield* gate;
+    const erased = yield* transact(erase(id));
+    if (definition.cache !== undefined) yield* definition.cache.delete(id, erased.head + 1n);
+    const deleted = yield* Effect.forEach(
+      erased.freed,
+      (hash) => Effect.map(deleteBytes(hash), (gone) => [hash, gone] as const),
+      { concurrency: 1 },
+    );
+    const gone = (wanted: boolean) =>
+      Arr.map(
+        Arr.filter(deleted, ([, deletedNow]) => deletedNow === wanted),
+        ([hash]) => hash,
+      );
+    const report: PurgeReport = {
+      id,
+      documents: erased.documents,
+      blobs: gone(true),
+      bytesLeft: gone(false),
+    };
+    return report;
+  });
+
+  return { type, purge };
+};