@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/moderation.js

@@ -0,0 +1,375 @@
+/**
+ * **The moderation workflow** — the rules that move a leaf's row between
+ * moderation states, the threshold grading of a classifier's scores, the
+ * review-queue filter, and member reports.
+ *
+ * The behavioural spec is gardeneria's comment moderation
+ * (`apps/api/src/operations/comments.ts`' `moderateCommentE`), its moderation
+ * plane (`apps/api/src/operations/moderation.ts`) and its threshold grader
+ * (`packages/jobs/src/moderation/thresholds.ts`), with their tests; a
+ * `#NNN` here names a gardeneria issue.
+ *
+ * ## The model (owner decisions on pulpit#51)
+ *
+ * The kernel owns the rules; the transport (a queue, the classifier run, the
+ * API-call ledger, moderator notifications) stays the application's.
+ *
+ * - **The state lives on the version row**, in the leaf's
+ *   `moderationState` column ({@link ModerationState}): a decision is an
+ *   appended version, so history shows who decided what, and when.
+ * - **Transitions.** Every new row starts `pending`. Only the moderate rung
+ *   changes the state: `pending → approved | rejected`, re-moderation
+ *   between `approved` and `rejected`, and re-review back to `pending`
+ *   ({@link isModerationTransition}). A write by anyone else that changes the
+ *   state fails `WriteRejected`.
+ * - **Re-review triggers are the leaf's**: an edit that changes one of its
+ *   declared `reReviewOn` attributes sends an `approved` row back to
+ *   `pending` ({@link ModerationDeclaration}).
+ * - **Owners withdraw their own content** by deleting it: the owned write
+ *   gate admits its owner in every moderation state, and a tombstone needs
+ *   no decision.
+ *
+ * {@link moderationHook} enforces the rules as a before hook (`./subtype`'s
+ * lifecycle seam), so every write path honours them, and
+ * {@link defineModeration}'s `moderate` is the decision itself.
+ *
+ * ## Grading and the queue
+ *
+ * {@link gradeScores} turns a classifier's per-category scores (shaped like
+ * effect-ai-ext's `ModerationModel` output; pulpit doesn't import it) into a
+ * verdict against the application's thresholds. Classification itself runs
+ * from an application's after hook. The review queue is the leaf's pending
+ * rows ({@link reviewQueueFilter}) plus the open member reports
+ * ({@link defineReports}), both the moderate rung's alone.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/moderation
+ * @since 0.1.0
+ */
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Formatter from "effect/Formatter";
+import * as Option from "effect/Option";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { always, eq, never } from "./filter.js";
+import { nowDate, plainRowQuery, signedIn as signedInAs } from "./internal/plain-rows.js";
+import { ModerationState } from "./publication.js";
+import { Forbidden, Unauthorized, WriteRejected, } from "./subtype.js";
+// ── Transitions ───────────────────────────────────────────────────────
+/**
+ * Whether a row may move from `from` (none for a row being created) to
+ * `to`: a new row only to `pending`; an existing one to any other state
+ * (decision, re-moderation, re-review). Staying put is no transition.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Option from "effect/Option";
+ * import { isModerationTransition } from "@thomasfosterau/pulpit/moderation";
+ *
+ * strictEqual(isModerationTransition(Option.none(), "pending"), true);
+ * strictEqual(isModerationTransition(Option.none(), "approved"), false);
+ * strictEqual(isModerationTransition(Option.some("pending"), "approved"), true);
+ * strictEqual(isModerationTransition(Option.some("approved"), "approved"), false);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const isModerationTransition = (from, to) => Option.match(from, { onNone: () => to === "pending", onSome: (state) => state !== to });
+/**
+ * The declaration with the conventional column names.
+ *
+ * @since 0.1.0
+ */
+export const moderatedColumns = (reReviewOn) => ({
+    column: "moderationState",
+    moderatedAtColumn: Option.some("moderatedAt"),
+    moderatedByColumn: Option.some("moderatedBy"),
+    reReviewOn,
+});
+const isModerationState = Schema.is(ModerationState);
+/** A column's value in a state or patch, absent (or `undefined`) as none. */
+const valueOf = (values, column) => Option.fromUndefinedOr(values[column]);
+/** The prior state's moderation state, or none (a create, or a value outside the vocabulary). */
+const priorState = (event, column) => Option.flatMap(event.prior, (prior) => Option.filter(valueOf(prior.state, column), isModerationState));
+/** The decision stamps for a patch, by the leaf's declared columns. */
+const stamps = (declaration, account, now) => ({
+    ...Option.match(declaration.moderatedAtColumn, {
+        onNone: () => ({}),
+        onSome: (column) => Record.singleton(column, now),
+    }),
+    ...Option.match(declaration.moderatedByColumn, {
+        onNone: () => ({}),
+        onSome: (column) => Record.singleton(column, account.id),
+    }),
+});
+/** The prior row's moderation columns, carried over a restored version's. */
+const carried = (event, declaration) => Option.match(event.prior, {
+    onNone: () => ({}),
+    onSome: (prior) => Record.fromEntries(Arr.map([
+        declaration.column,
+        ...Option.toArray(declaration.moderatedAtColumn),
+        ...Option.toArray(declaration.moderatedByColumn),
+    ], (column) => [column, prior.state[column] ?? null])),
+});
+/** Whether the patch changes a re-review attribute from its prior value. */
+const touchesReview = (event, declaration) => Arr.some(declaration.reReviewOn, (column) => Option.match(valueOf(event.patch, column), {
+    onNone: () => false,
+    onSome: (next) => !Option.exists(event.prior, (prior) => Option.exists(valueOf(prior.state, column), (before) => Equal.equals(before, next))),
+}));
+/**
+ * The moderation rules applied to one write: the patch the write should
+ * apply, or the reason it is refused. Pure, so every case is testable
+ * without a chain.
+ *
+ * - A **create** stores `pending`; a patch asking for another state is refused.
+ * - A **delete** is untouched (withdrawal needs no decision).
+ * - A **`restoreVersion`** by anyone but the moderate rung carries the
+ *   prior row's moderation columns over the restored version's, so an old
+ *   approval never comes back with old content.
+ * - A patch that **changes the state** is a decision: refused below the
+ *   moderate rung or outside {@link isModerationTransition}, and otherwise
+ *   stamped (`moderatedAtColumn`, `moderatedByColumn`). A patch that sets
+ *   the state it already has changes nothing.
+ * - Otherwise, an edit that changes a `reReviewOn` attribute of an
+ *   `approved` row sends it back to `pending`.
+ *
+ * @since 0.1.0
+ */
+export const moderatePatch = (event, declaration, policy, now) => {
+    const moderator = Option.filter(event.viewer, policy.canModerate);
+    if (event.action === "delete")
+        return Result.succeed(event.patch);
+    if (event.action === "create")
+        return created(event.patch, declaration.column);
+    const patch = event.action === "restoreVersion" && Option.isNone(moderator)
+        ? { ...event.patch, ...carried(event, declaration) }
+        : event.patch;
+    const from = priorState(event, declaration.column);
+    const asked = Option.filter(valueOf(patch, declaration.column), (value) => !Option.exists(from, (state) => state === value));
+    return Option.isSome(asked)
+        ? decided({ event, patch, from, asked: asked.value, moderator, declaration, now })
+        : Result.succeed(reReviewed({ ...event, patch }, from, declaration));
+};
+/** A create's patch: `pending`, whatever it asked for, unless it asked for another state. */
+const created = (patch, column) => Option.exists(valueOf(patch, column), (asked) => asked !== "pending")
+    ? Result.fail(`a new row starts pending; ${column} is the moderate rung's to change`)
+    : Result.succeed({ ...patch, [column]: "pending" });
+/** A patch that changes the state: the rung's decision, stamped (a restored version unstamped). */
+const decided = (decision) => {
+    const { patch, asked, moderator, declaration } = decision;
+    const { column } = declaration;
+    if (Option.isNone(moderator))
+        return Result.fail(`${column} is the moderate rung's to change`);
+    if (!isModerationState(asked) || !isModerationTransition(decision.from, asked)) {
+        return Result.fail(`${column} can't move to ${Predicate.isString(asked) ? asked : Formatter.format(asked)}`);
+    }
+    return Result.succeed(decision.event.action === "restoreVersion"
+        ? patch
+        : { ...patch, ...stamps(declaration, moderator.value, decision.now) });
+};
+/** An edit that leaves the state alone: back to `pending` when it touches a re-review attribute of an approved row. */
+const reReviewed = (event, from, declaration) => Option.exists(from, (state) => state === "approved") && touchesReview(event, declaration)
+    ? { ...event.patch, [declaration.column]: "pending" }
+    : event.patch;
+/**
+ * The moderation rules ({@link moderatePatch}) as a before hook for the
+ * leaf's `LifecycleHooks`: every write applies them, and a refusal
+ * fails the write with `WriteRejected`, appending nothing. Compose it first,
+ * so later hooks see the state it settled.
+ *
+ * @since 0.1.0
+ */
+export const moderationHook = (declaration, policy) => ({
+    name: "moderation",
+    run: (event) => Effect.flatMap(nowDate, (now) => {
+        return Result.match(moderatePatch(event, declaration, policy, now), {
+            onSuccess: Effect.succeed,
+            onFailure: (reason) => Effect.fail(new WriteRejected({ type: event.type, id: event.id, action: event.action, reason })),
+        });
+    }),
+});
+/**
+ * Bind a leaf's moderation decision. The leaf's hooks must include
+ * {@link moderationHook} with the same declaration: it is what admits the
+ * decision and stamps it.
+ *
+ * @since 0.1.0
+ */
+export const defineModeration = (definition) => ({
+    moderate: Effect.fn(`${definition.target.type}.moderate`)(function* (id, decision, precondition = {}) {
+        const viewer = yield* definition.viewer;
+        if (Option.isNone(viewer))
+            return yield* new Unauthorized();
+        if (!definition.policy.canModerate(viewer.value))
+            return yield* new Forbidden();
+        return yield* definition.target.update({
+            id,
+            patch: { [definition.declaration.column]: decision },
+            expectedVersion: precondition.expectedVersion,
+        });
+    }),
+});
+/**
+ * The review queue's leaf half as a list filter: the `pending` rows, for
+ * the moderate rung only (`never` for anyone else). Pass it as a list
+ * request's `where`; the leaf's own read arms still apply.
+ *
+ * @since 0.1.0
+ */
+export const reviewQueueFilter = (viewer, policy, column = "moderationState") => (Option.exists(viewer, policy.canModerate) ? eq(column, "pending") : never);
+/**
+ * The band a flagged row lands in, from its worst breach.
+ *
+ * @since 0.1.0
+ */
+export const ModerationPriority = Schema.Literals(["low", "medium", "high", "urgent"]);
+/**
+ * The bar a category with no configured threshold is graded against;
+ * strictly above it flags. A starting point to tune, not a measured value.
+ *
+ * @since 0.1.0
+ */
+export const DEFAULT_MODERATION_THRESHOLD = 0.5;
+/** The band for a breach: round cut points, a starting policy. */
+const bandFor = (score) => score >= 0.9 ? "urgent" : score >= 0.75 ? "high" : score >= 0.5 ? "medium" : "low";
+/**
+ * Grade a classifier's scores against the leaf's thresholds (a category
+ * missing from `thresholds` grades against `defaultThreshold`). A category
+ * breaches when its score is strictly above its bar; an unassessed one is
+ * absent and can't breach. The classifier's own flag is never overridden
+ * downward, only added to (raise a category's bar to `1` to ignore it). The
+ * band is the worst breaching score's, or the top score's for a flag with
+ * no breach. Pure.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { gradeScores } from "@thomasfosterau/pulpit/moderation";
+ *
+ * deepStrictEqual(
+ *   gradeScores({ flagged: false, categoryScores: { hate: 0.8, spam: 0.3 } }, { spam: 0.2 }),
+ *   { isFlagged: true, exceeded: ["hate", "spam"], topScore: 0.8, priority: "high" },
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const gradeScores = (scores, thresholds, defaultThreshold = DEFAULT_MODERATION_THRESHOLD) => {
+    const entries = Record.toEntries(scores.categoryScores);
+    const breaches = Arr.filter(entries, ([category, score]) => score > (thresholds[category] ?? defaultThreshold));
+    const top = (values) => Arr.reduce(values, 0, (worst, [, score]) => Math.max(worst, score));
+    const topScore = top(entries);
+    const topExceeded = top(breaches);
+    return {
+        isFlagged: scores.flagged || Arr.isReadonlyArrayNonEmpty(breaches),
+        exceeded: Arr.sort(Arr.map(breaches, ([category]) => category), Order.String),
+        topScore,
+        priority: bandFor(topExceeded > 0 ? topExceeded : scores.flagged ? topScore : 0),
+    };
+};
+// ── Member reports ────────────────────────────────────────────────────
+/**
+ * A report's status: `open` until the moderate rung resolves it (acted on)
+ * or dismisses it.
+ *
+ * @since 0.1.0
+ */
+export const ReportStatus = Schema.Literals(["open", "resolved", "dismissed"]);
+/**
+ * No report at that id the viewer may read: the wire's 404.
+ *
+ * @since 0.1.0
+ */
+export class ReportNotFound extends Schema.TaggedError()("ReportNotFound", {
+    id: Schema.String,
+}) {
+}
+/**
+ * The report is already resolved or dismissed: the wire's 409.
+ *
+ * @since 0.1.0
+ */
+export class ReportClosed extends Schema.TaggedError()("ReportClosed", {
+    id: Schema.String,
+    status: ReportStatus,
+}) {
+}
+/**
+ * Bind member reports against one leaf: filed by a signed-in account that
+ * can read the target, read by their reporter and the moderate rung, and
+ * resolved by the moderate rung.
+ *
+ * @since 0.1.0
+ */
+export const defineReports = (definition) => {
+    const { target, reports, policy } = definition;
+    const type = target.type;
+    const signedIn = signedInAs(definition.viewer);
+    const file = Effect.fn(`${type}.reports.file`)(function* (input) {
+        const account = yield* signedIn;
+        // A target the reporter can't read is missing to them (SEC-AUTH-ENUM-001).
+        yield* target.get(input.targetId);
+        if (definition.budget !== undefined) {
+            yield* definition.budget.spend(Option.some(account), "file", input.targetId);
+        }
+        const id = yield* reports.mintId;
+        yield* reports.insert({
+            id,
+            targetId: input.targetId,
+            targetType: type,
+            reporterId: account.id,
+            reason: input.reason,
+            details: input.details,
+            status: "open",
+            filedAt: yield* nowDate,
+            resolvedAt: Option.none(),
+            resolvedBy: Option.none(),
+            resolutionNote: Option.none(),
+        });
+        return { id };
+    });
+    const readable = (viewer, row) => row.targetType === type &&
+        Option.exists(viewer, (account) => policy.canModerate(account) || account.id === row.reporterId);
+    const get = Effect.fn(`${type}.reports.get`)(function* (id) {
+        const viewer = yield* definition.viewer;
+        const row = yield* reports.get(id);
+        if (Option.isNone(row) || !readable(viewer, row.value)) {
+            return yield* new ReportNotFound({ id });
+        }
+        return row.value;
+    });
+    const list = Effect.fn(`${type}.reports.list`)(function* (request) {
+        const viewer = yield* definition.viewer;
+        const scope = Option.match(viewer, {
+            onNone: () => never,
+            onSome: (account) => policy.canModerate(account) ? always : eq("reporterId", account.id),
+        });
+        return yield* reports.list(plainRowQuery(type, scope, request));
+    });
+    const resolve = Effect.fn(`${type}.reports.resolve`)(function* (id, outcome, note) {
+        const account = yield* signedIn;
+        if (!policy.canModerate(account))
+            return yield* new Forbidden();
+        const row = yield* reports.lock(id);
+        if (Option.isNone(row) || row.value.targetType !== type) {
+            return yield* new ReportNotFound({ id });
+        }
+        if (row.value.status !== "open") {
+            return yield* new ReportClosed({ id, status: row.value.status });
+        }
+        yield* reports.close(id, {
+            status: outcome,
+            resolvedAt: yield* nowDate,
+            resolvedBy: account.id,
+            resolutionNote: note,
+        });
+    });
+    return { file, get, list, resolve };
+};
+//# sourceMappingURL=moderation.js.map

package/dist/moderation.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,204 @@
+/**
+ * **Routable content** — a leaf's path claims, tied to its version chain,
+ * the slug aliases a path change leaves behind, and the gated resolution of
+ * a path to a node or a redirect.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/pages.ts`
+ * and `packages/database/src/tables/pages.ts` (one live page per canonical
+ * path, old slugs kept in `page_slugs` and answered with a 301). A `#NNN`
+ * here names a gardeneria issue.
+ *
+ * ## The model (owner decision on pulpit#57)
+ *
+ * - **A claim lives on the root node**: one path per content item. The
+ *   locale is chosen when the resolved node is read, never by the path, so a
+ *   slug translation is not a claim of its own (pulpit#56's model (b)).
+ * - **Claims follow the node's lifecycle.** A write that leaves the node
+ *   live claims the path its new state holds in the leaf's path column; a
+ *   tombstone, or a state with no path, frees the claim; a restore re-claims
+ *   its path, or fails {@link PathTaken} when another node holds it now.
+ * - **A path change records an alias**: the old path resolves as a redirect
+ *   to the new one, for as long as no other node claims it.
+ * - **Resolution is gated** (`SEC-AUTH-ENUM-001`): {@link RoutableOps.resolve}
+ *   reads the node through the leaf's own `get`, so a hidden node's path,
+ *   and an alias to a hidden node, is {@link PathNotFound}, never a redirect.
+ *
+ * Free-form redirects (patterns, a 404 log) are the site's. The path's
+ * syntax is the leaf attribute's schema (effect-schema-ext's `Ids.slug`, once
+ * it publishes).
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/paths
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { SubtypeOps } from "./subtype.ts";
+import type { VersionChainStore } from "./version-chain.ts";
+declare const PathTaken_base: Schema.Class<PathTaken, Schema.TaggedStruct<"PathTaken", {
+    readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * Another node holds the path canonically: the wire's 409. It names the
+ * path, never the holder, so it says only that the path is taken, as a
+ * unique-key conflict does, whoever holds it.
+ *
+ * @since 0.1.0
+ */
+export declare class PathTaken extends PathTaken_base {
+}
+declare const PathNotFound_base: Schema.Class<PathNotFound, Schema.TaggedStruct<"PathNotFound", {
+    readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * No node the viewer can read answers to the path: the wire's 404. A path
+ * nobody claims, one whose node is hidden from the viewer, and an alias to a
+ * hidden node all answer this, alike (`SEC-AUTH-ENUM-001`).
+ *
+ * @since 0.1.0
+ */
+export declare class PathNotFound extends PathNotFound_base {
+}
+/**
+ * What a path is stored as: the node it names, and whether it is that
+ * node's canonical path or an alias a path change left behind.
+ *
+ * @since 0.1.0
+ */
+export interface PathEntry {
+    readonly nodeId: string;
+    readonly canonical: boolean;
+}
+/**
+ * The path table of one routable namespace (a collection): each path once,
+ * canonical for one node or an alias of one. A store that persists and
+ * applies no policy; it runs in the caller's transaction, so a write whose
+ * claim fails rolls back with its chain append.
+ *
+ * @since 0.1.0
+ */
+export interface PathStore<E, R> {
+    /** The entry for `path`, canonical or alias, or none. */
+    readonly lookup: (path: string) => Effect.Effect<Option.Option<PathEntry>, E, R>;
+    /** The node's canonical path, or none. */
+    readonly canonicalOf: (nodeId: string) => Effect.Effect<Option.Option<string>, E, R>;
+    /**
+     * Make `path` the node's canonical path, in one step: fails
+     * {@link PathTaken} when another node holds it canonically; otherwise
+     * replaces an alias at `path` (the node's own, which a revert promotes, or
+     * another node's, which the claim takes over) and turns the node's previous
+     * canonical path, if any, into its alias.
+     */
+    readonly claim: (nodeId: string, path: string) => Effect.Effect<void, PathTaken | E, R>;
+    /** Free the node's canonical path, if it has one; its aliases stay. */
+    readonly release: (nodeId: string) => Effect.Effect<void, E, R>;
+}
+/**
+ * What a path resolves to for one viewer: the node's resource at its
+ * canonical path, or a redirect from an alias to the canonical path.
+ *
+ * @since 0.1.0
+ */
+export type Resolution<Resource> = {
+    readonly kind: "node";
+    readonly id: string;
+    readonly resource: Resource;
+} | {
+    readonly kind: "redirect";
+    readonly id: string;
+    readonly path: string;
+};
+/**
+ * A routable leaf's operations: the leaf's own, each write keeping its path
+ * claim in step with the state it wrote (and failing {@link PathTaken}), plus
+ * the gated {@link resolve}.
+ *
+ * @since 0.1.0
+ */
+export interface RoutableOps<Resource, E, R> extends SubtypeOps<Resource, E | PathTaken, R> {
+    /**
+     * Resolve a path for the viewer: its node, through the leaf's own `get`, or
+     * a redirect from an alias to the node's canonical path. Fails
+     * {@link PathNotFound} for an unclaimed path, a hidden node's path, and an
+     * alias to a hidden node, alike, and for an alias whose node has no
+     * canonical path now (`SEC-AUTH-ENUM-001`); with the store's `E` otherwise.
+     */
+    readonly resolve: (path: string) => Effect.Effect<Resolution<Resource>, PathNotFound | E, R>;
+}
+/**
+ * What {@link routable} needs besides the leaf's operations.
+ *
+ * @since 0.1.0
+ */
+export interface RoutableConfig<E, R> {
+    /** The leaf's path column: a string holds the node's path; any other value, or none, claims nothing. */
+    readonly column: string;
+    /** The routable namespace's path table. */
+    readonly paths: PathStore<E, R>;
+    /** The leaf's chain store, read (ungated) for the state a write landed at. */
+    readonly chain: VersionChainStore<E, R>;
+}
+/**
+ * Make a leaf routable (pulpit#57): its writes keep the node's path claim in
+ * step with its chain, and {@link RoutableOps.resolve} answers a path through
+ * the leaf's own read gate. After each write's append, in the same
+ * transaction, the claim follows the state the write landed at: a live state
+ * with a path claims it (a change leaves the old path as an alias; another
+ * node's claim fails {@link PathTaken}), and a tombstone or a state with no
+ * path frees it. A restore into a path another node took meanwhile therefore
+ * fails `PathTaken`, and its append rolls back with it. Wrap the result with
+ * `./subtype`'s `subtypeHandlers` as the leaf's own operations, so its
+ * `transact` covers the claims.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import * as Option from "effect/Option";
+ * import { routable } from "@thomasfosterau/pulpit/paths";
+ * import { defineSubtype, nobodyFollows } from "@thomasfosterau/pulpit/subtype";
+ * import {
+ *   makeInMemoryChainStore,
+ *   makeInMemoryLeafStore,
+ *   makeInMemoryPathStore,
+ * } from "@thomasfosterau/pulpit/testing";
+ * import * as HashSet from "effect/HashSet";
+ *
+ * const chain = makeInMemoryChainStore();
+ * const pages = routable(
+ *   defineSubtype({
+ *     type: "pages",
+ *     access: { kind: "reference" },
+ *     chain,
+ *     leaves: makeInMemoryLeafStore(chain, { columns: ["slug"] }),
+ *     viewer: Effect.succeed(Option.some({ id: "editor", role: "admin" })),
+ *     policy: {
+ *       canViewPrivate: () => true,
+ *       canViewDeleted: () => true,
+ *       canModerate: () => true,
+ *       canWriteCorpus: () => true,
+ *     },
+ *     followers: nobodyFollows(HashSet.empty<string>()),
+ *     toResource: (row) => ({ id: row.id, slug: row["slug"] }),
+ *   }),
+ *   { column: "slug", paths: makeInMemoryPathStore(), chain },
+ * );
+ * const program = Effect.gen(function* () {
+ *   const { id } = yield* pages.create({ id: Option.none(), state: { slug: "about" } });
+ *   yield* pages.update({ id, patch: { slug: "about-us" } });
+ *   return yield* pages.resolve("about");
+ * });
+ * const resolved = Effect.runSync(program);
+ * strictEqual(resolved.kind === "redirect" && resolved.path, "about-us");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const routable: <Resource, E, R>(ops: SubtypeOps<Resource, E, R>, config: RoutableConfig<E, R>) => RoutableOps<Resource, E, R>;
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

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