@jini-ai/cms 0.5.2 → 0.5.4

package/dist/comments/module.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file Composition factory for the Comments plugin (ADR-031, SPEC-033/SPEC-035) — wires the
+ * repo, spam check, hooks, ingress policy, and write-service together given the low-level deps a
+ * composition root (`server/deps.ts`/`app.ts`) already has. Both composition roots call this
+ * instead of each hand-assembling the same 5-piece wiring twice.
+ *
+ * `entryLookup` adapts `EntryRepoPort.findById` (already on `RouteDeps`) into the narrow shape
+ * `ingress.ts` expects, computing `commentsClosed` from the entry's own `status`/`publishedAt` +
+ * `CommentsSettings.closeAfterDays` — this file owns that math so `ingress.ts` itself stays free of
+ * any entries-feature knowledge (ADR-046 Phase 3's "narrow typed dependencies" convention).
+ *
+ * BUG FIX (2026-09-03, found auditing `ingress.ts` for an unrelated complexity refactor): an entry
+ * that has never been published (`status: "draft"`, `publishedAt: null`) OR was explicitly
+ * unpublished (`status: "unpublished"`) was previously readable as "open" — nothing anywhere in the
+ * ingress path checked `EntryRecord.status` at all, only `publishedAt`. A visitor who knew or
+ * guessed either entry's id could post a public, world-visible-once-moderated comment on content
+ * nobody has ever been shown, or content that was deliberately retracted. Checked ADR-031/SPEC-033/
+ * SPEC-035 (this file's own citations) for a deliberate "drafts/retracted entries are commentable"
+ * design decision — REQ-04 says only "entry-open"; no spec anywhere defines that term against
+ * publish state, names a preview/staging use case, or otherwise addresses this. Treated as spec-
+ * silent, not spec-permitted: fixed as the fail-closed reading (`isEntryOpenForComments` below),
+ * reusing the existing `entry-closed` rejection reason rather than adding a new one to `ports.ts`'s
+ * `CommentIngressRejection` union — from a submitter's point of view "never published" and
+ * "retracted" are both just "not currently open for comments." This is a deliberate BEHAVIOR
+ * CHANGE with no spec mandate behind it, disclosed here and in this commit's message rather than
+ * smuggled in as if it were spec-required.
+ *
+ * Checked for a second call site before fixing (the exact failure class a sibling session found
+ * elsewhere in this campaign — a correct primitive wired into only one of several routes): grepped
+ * the whole host source tree for every construction of `CommentIngressDeps.entryLookup` and
+ * every call to `createCommentIngressPolicy`/`repo.create` for a comment row. There is exactly ONE
+ * of each — this file's own `entryLookup` below, `createCommentsModule`'s own call to
+ * `createCommentIngressPolicy`, and `ingress.ts#submit()`'s own `repo.create()` — reached by both
+ * real composition roots (`server/runtime/composition/{app,deps}.ts`) through this one factory and
+ * by no other path (`write-service.ts` only ever calls `applyModeration`/`purge` on an EXISTING
+ * comment, never `create`). Fixing it here closes every write call site, not just the one this
+ * audit started from.
+ *
+ * Also checked the READ side for the same class of leak (does the public read path show comments
+ * on an unpublished entry, not just accept new ones on it): `CommentRepoPort.listThreadForEntry`
+ * has zero route call sites anywhere in this codebase today — grepped for every reference; the only
+ * hits are its own port declaration, its two adapter implementations, and `repo.contract.test.ts`.
+ * There is no live public comment-read route yet (ADR-031 §10's origin-isolated widget, this file's
+ * own header already cites, remains deferred — "no ADR-025 host exists yet" per SPEC-033's own
+ * Scope Note). So there is nothing to fix on the read side today; flagged here as a note for
+ * whoever builds that route next, not a bug in the current tree.
+ *
+ */
+import type { Clock as ClockPort, IdGenerator as IdGeneratorPort, UUID } from "@jini-ai/core/primitives";
+import type { OutboxPort } from "../core/index.js";
+import type { CommentRateLimiter } from "./ingress.js";
+import type { CommentIngressPolicy, CommentRepoPort, SpamCheckPort } from "./ports.js";
+import type { CommentsSettings } from "./types.js";
+import type { CommentTransactionRunner, CommentWriteService, ForgetRemovedCommentFn, RemoveCommentFn } from "./write-service.js";
+/** The publish state and date are the only entry data the comment gate needs. */
+export interface CommentEntryView {
+    status: string;
+    publishedAt: string | null;
+}
+export interface CommentsModuleDeps {
+    commentRepo: CommentRepoPort;
+    entryLookup: (required: {
+        workspaceId: UUID;
+        entryId: UUID;
+    }) => Promise<CommentEntryView | null>;
+    getSettings: (workspaceId: UUID) => Promise<CommentsSettings>;
+    rateLimiter: CommentRateLimiter;
+    outbox: OutboxPort;
+    clock: ClockPort;
+    idGen: IdGeneratorPort;
+    /** Caller-chosen spam-check adapter; both real composition roots use `HeuristicSpamCheck`.
+     * This module never picks one on its own, so the choice remains a real DI seam. */
+    spamCheck: SpamCheckPort;
+    /**
+     * The local admin Trash's three seams, passed straight through to the moderation write-service.
+     * Required, not optional: a default no-op would silently drop comments out of the Trash screen,
+     * and "deleted but unrecoverable" is exactly the failure this feature exists to prevent. See
+     * `write-service.ts`'s `RemoveCommentFn` for why none of them is a trash type.
+     */
+    remove: RemoveCommentFn;
+    forgetRemoved: ForgetRemovedCommentFn;
+    runInTransaction: CommentTransactionRunner;
+}
+export interface CommentsModule {
+    commentRepo: CommentRepoPort;
+    ingressPolicy: CommentIngressPolicy;
+    writeService: CommentWriteService;
+}
+/** Wires the comment gate and moderation service using host-owned settings, rate limits and removal.
+ * @returns The supplied repo plus ingress and moderation services.
+ * @complexity O(1) setup; calls inherit the injected ports' costs.
+ */
+export declare function createCommentsModule(deps: CommentsModuleDeps, _optional?: Record<string, never>): CommentsModule;
+//# sourceMappingURL=module.d.ts.map

package/dist/comments/module.js

@@ -0,0 +1,73 @@
+import { nowIso } from "@jini-ai/core/primitives";
+import { createCommentHookRegistry } from "./hooks.js";
+import { createCommentIngressPolicy } from "./ingress.js";
+import { createCommentWriteService } from "./write-service.js";
+/** `closeAfterDays` age math ONLY — assumes the entry is otherwise eligible. Does not, and must
+ *  not, decide publish state; see {@link isEntryOpenForComments}, which composes this with the
+ *  publish-state check this file's header documents. */
+function isPastCloseWindow(publishedAt, closeAfterDays, nowIso) {
+    if (closeAfterDays === null || publishedAt === null)
+        return false;
+    const publishedMs = Date.parse(publishedAt);
+    const nowMs = Date.parse(nowIso);
+    if (Number.isNaN(publishedMs) || Number.isNaN(nowMs))
+        return false;
+    const ageDays = (nowMs - publishedMs) / (1000 * 60 * 60 * 24);
+    return ageDays > closeAfterDays;
+}
+/**
+ * Whether an entry may currently receive a new public comment: it must actually be `published`
+ * — not `draft` (never shown to anyone) and not `unpublished` (deliberately retracted) — AND not
+ * past its `closeAfterDays` window. `status !== "published"` is checked FIRST and short-circuits:
+ * `publishedAt` alone cannot distinguish "live" from "retracted", because `unpublishEntry`
+ * (`@jini-ai/cms/entries` `write-service.ts#transitionEntryStatus`) deliberately does not clear
+ * `publishedAt` on retraction (`publishedAt: target.status === "published" ? now : current.
+ * publishedAt`) — it stays at whatever it was, so a stale `publishedAt` from before retraction
+ * would otherwise still pass the age check. See this file's header for the bug this closes.
+ */
+function isEntryOpenForComments(entry, closeAfterDays, nowIso) {
+    if (entry.status !== "published")
+        return false;
+    return !isPastCloseWindow(entry.publishedAt, closeAfterDays, nowIso);
+}
+/** Wires the comment gate and moderation service using host-owned settings, rate limits and removal.
+ * @returns The supplied repo plus ingress and moderation services.
+ * @complexity O(1) setup; calls inherit the injected ports' costs.
+ */
+export function createCommentsModule(deps, _optional = {}) {
+    const hooks = createCommentHookRegistry({}, {});
+    const spamCheck = deps.spamCheck;
+    const entryLookup = async (required) => {
+        const entry = await deps.entryLookup(required);
+        if (!entry)
+            return null;
+        const settings = await deps.getSettings(required.workspaceId);
+        return {
+            id: required.entryId,
+            commentsClosed: !isEntryOpenForComments(entry, settings.closeAfterDays, nowIso({ clock: deps.clock })),
+        };
+    };
+    const ingressPolicy = createCommentIngressPolicy({
+        repo: deps.commentRepo,
+        spamCheck,
+        hooks,
+        clock: deps.clock,
+        idGen: deps.idGen,
+        getSettings: deps.getSettings,
+        entryLookup,
+        rateLimiter: deps.rateLimiter,
+        outbox: deps.outbox,
+    });
+    const writeService = createCommentWriteService({
+        repo: deps.commentRepo,
+        outbox: deps.outbox,
+        hooks,
+        clock: deps.clock,
+        idGen: deps.idGen,
+        remove: deps.remove,
+        forgetRemoved: deps.forgetRemoved,
+        runInTransaction: deps.runInTransaction,
+    });
+    return { commentRepo: deps.commentRepo, ingressPolicy, writeService };
+}
+//# sourceMappingURL=module.js.map

package/dist/comments/ports.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @file Port contracts introduced by the Comments bundled plugin (ADR-031).
+ *
+ * Two ports, each passing ADR-006's rule-of-two (two plausible adapters, one built now):
+ *   1. `CommentRepoPort`  — in-memory (now) + SQLite-over-dataModule (now). The typed, core-owned
+ *      write path ADR-023 §7 mandates for plugin tables: no raw plugin write SQL, so the ADR-022
+ *      write chokepoint (revision + `pluginId` attribution) is preserved.
+ *   2. `SpamCheckPort`    — heuristic/local (built now) + external service (plausible
+ *      next). This is the brief's anti-spam seam.
+ *
+ * `CommentIngressPolicy` is the core-mediated public-submission boundary (NOT a rule-of-two port —
+ * one policy, like ADR-027's single `MediaIngressPolicy`): anonymous submission cannot ride
+ * `authorize()` RBAC, so it enters here — rate-limited, spam-checked, sanitized — and is the only
+ * write path a hostile visitor can reach.
+ *
+ * All cross-seam payloads are async + serializable, no live core objects (ADR-024 §3, ADR-025 §2).
+ * INTERFACES + TYPES ONLY — no feature logic lives here.
+ */
+import type { ISODateTime, UUID } from "@jini-ai/core/primitives";
+import type { DomainEvent } from "../core/index.js";
+import type { CommentRecord, CommentStatus, CommentSubmission, ModerationAction, ModerationLogEntry, ModerationQueuePage, CommentThreadNode, SpamVerdict } from "./types.js";
+/** Every read/write is workspace-scoped (ADR-007); all methods async (ADR-024 §3). */
+export interface CommentRepoPort {
+    findById(required: {
+        workspaceId: UUID;
+        id: UUID;
+    }, optional?: Record<string, never>): Promise<CommentRecord | null>;
+    /** Public/threaded read for the widget — approved-only unless `includeStatuses` is passed. */
+    listThreadForEntry(required: {
+        workspaceId: UUID;
+        entryId: UUID;
+        includeStatuses?: readonly CommentStatus[];
+    }, optional?: Record<string, never>): Promise<CommentThreadNode[]>;
+    /** The moderation queue: filter by status, keyset-paginated (ADR-022 §3).
+     *  @throws {ToolInputError} `invalid cursor` when `cursor` names no comment in the workspace. */
+    listModerationQueue(required: {
+        workspaceId: UUID;
+        status: CommentStatus;
+        limit: number;
+        cursor?: string | null;
+    }, optional?: Record<string, never>): Promise<ModerationQueuePage>;
+    /** Count for a status (e.g. the pending badge) — derived, not a denormalized column in v1. */
+    countByStatus(required: {
+        workspaceId: UUID;
+        entryId?: UUID;
+        status: CommentStatus;
+    }, optional?: Record<string, never>): Promise<number>;
+    /**
+     * Insert a new comment through the typed chokepoint (ADR-023 §7).
+     *
+     * `submitLog`, when present, must be durably recorded ATOMICALLY with `record` — OQ-3's
+     * resolution (SPEC-035): every ingress-created comment gets a `submit` `moderation_log` row,
+     * attributed to the seeded `COMMENTS_INGRESS_SYSTEM_PRINCIPAL_ID` (`types.ts`). Mirrors
+     * `ChangeSetRepoPort.insert()`'s optional third-argument co-persistence pattern (ADR-046 BR-04
+     * resolution): a SQLite adapter wraps both inserts in one transaction; the in-memory adapter
+     * pushes both synchronously. Omit `submitLog` for a comment created outside the public ingress
+     * (e.g. test fixtures, a future member-authored write path with its own attribution story).
+     * @example repo.create({ record }, { submitLog })
+     */
+    create(required: {
+        record: CommentRecord;
+    }, optional?: {
+        submitLog?: ModerationLogEntry;
+    }): Promise<void>;
+    /** The append-only audit trail for one comment, oldest-first (admin "history" view; also how
+     * OQ-3's ingress-time `submit` row is verified in tests). */
+    listModerationLog(required: {
+        workspaceId: UUID;
+        commentId: UUID;
+    }, optional?: Record<string, never>): Promise<ModerationLogEntry[]>;
+    /**
+     * OCC status flip + audit-log append, executed by CORE as ONE atomic unit — the multi-table,
+     * both-or-neither write ADR-026's envelope exists for (comment row + `moderation_log` row).
+     * Returns the updated record, or a serializable conflict (never throws a live object).
+     */
+    applyModeration(required: {
+        workspaceId: UUID;
+        id: UUID;
+        expectedVersion: number;
+        action: ModerationAction;
+        toStatus: CommentStatus;
+        actorPrincipalId: UUID;
+        note: string | null;
+        at: ISODateTime;
+    }, optional?: Record<string, never>): Promise<{
+        ok: true;
+        record: CommentRecord;
+        log: ModerationLogEntry;
+    } | {
+        ok: false;
+        reason: "not-found" | "conflict";
+        currentVersion?: number | undefined;
+    }>;
+    /**
+     * ADR-031 §9's trash→purge ladder's hard-delete half (SPEC-033 — additive widening; `purge` was
+     * a valid `ModerationAction` value with no repo method to execute it in the originally-accepted
+     * interfaces). A REAL row delete, unlike `applyModeration`'s status flip — this is the one
+     * irreversible act in the ladder. The `moderation_log` row is appended and RETAINED after the
+     * comment row is gone (chokepoint-validated, not FK-enforced, per ADR-031 §2 — an orphaned log
+     * row is the intended, permanent audit trail of a purge, not a dangling reference to clean up).
+     */
+    purge(required: {
+        workspaceId: UUID;
+        id: UUID;
+        actorPrincipalId: UUID;
+        note: string | null;
+        at: ISODateTime;
+    }, optional?: Record<string, never>): Promise<{
+        ok: true;
+        log: ModerationLogEntry;
+    } | {
+        ok: false;
+        reason: "not-found";
+    }>;
+}
+/**
+ * The anti-spam seam (ADR-006 rule-of-two). Async + serializable (ADR-024 §3); a network-backed
+ * adapter is a core-mediated capability, never a raw `fetch` from plugin code (ADR-025 §3).
+ */
+export interface SpamCheckPort {
+    /** Classify a submission. Adapters: local heuristic (now) / external service (plausible next). */
+    check(submission: CommentSubmission, optional?: Record<string, never>): Promise<SpamVerdict>;
+    /** Feed a moderator ham/spam correction back to the classifier; no-op locally. */
+    report?(required: {
+        workspaceId: UUID;
+        comment: CommentRecord;
+        verdict: "ham" | "spam";
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/**
+ * Core-mediated public-submission boundary. The single entry point for visitor-authored comments;
+ * enforces rate-limit, honeypot, size/link caps, sanitization, and spam classification before a
+ * `pending`/`spam` row is written. Mirrors ADR-027's `MediaIngressPolicy` as one policy object.
+ */
+export interface CommentIngressPolicy {
+    submit(submission: CommentSubmission, optional?: Record<string, never>): Promise<CommentIngressResult>;
+}
+export type CommentIngressResult = {
+    ok: true;
+    comment: CommentRecord;
+    autoClassified: CommentStatus;
+} | {
+    ok: false;
+    reason: CommentIngressRejection;
+};
+/** Fail-closed rejection reasons (spam is stored silently, not rejected — no oracle for spammers). */
+export type CommentIngressRejection = "comments-disabled" | "entry-not-found" | "entry-closed" | "parent-not-found" | "max-depth-exceeded" | "rate-limited" | "body-too-large" | "too-many-links" | "honeypot-tripped" | "invalid";
+/**
+ * Typed hook points the Comments plugin DECLARES (anti-hook-soup: declared owner + signature,
+ * ADR-009 §3 / §3-kernel). Handlers are async, serializable-only, with explicit priority +
+ * deterministic order + fail-closed behavior (ADR-024 §7). Spam adapters attach at `beforeSubmit`.
+ */
+export interface CommentHookPoints {
+    /** Filter: transform or veto a submission pre-persist. Returning `reject` drops it fail-closed. */
+    "comments.beforeSubmit": (payload: {
+        submission: CommentSubmission;
+    }) => Promise<{
+        submission: CommentSubmission;
+    } | {
+        reject: CommentIngressRejection;
+    }>;
+    /** Action: a comment's moderation status changed (post-commit notification hook). */
+    "comments.statusChanged": (payload: {
+        workspaceId: UUID;
+        commentId: UUID;
+        fromStatus: CommentStatus | null;
+        toStatus: CommentStatus;
+    }) => Promise<void>;
+}
+/**
+ * Domain events emitted to the outbox for async side effects (ADR-009 §2): notify the entry
+ * author, invalidate the rendered page cache, feed search/AI memory. Serializable envelopes,
+ * workspace-stamped (ADR-007). Names are frozen strings for subscribers.
+ */
+export type CommentEventName = "comments.submitted" | "comments.approved" | "comments.marked_spam" | "comments.trashed" | "comments.purged";
+export interface CommentEventPayload {
+    commentId: UUID;
+    entryId: UUID;
+    status: CommentStatus;
+}
+export type CommentDomainEvent = DomainEvent<CommentEventPayload> & {
+    name: CommentEventName;
+};
+//# sourceMappingURL=ports.d.ts.map

package/dist/comments/ports.js

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

package/dist/comments/repo.memory.d.ts

@@ -0,0 +1,70 @@
+import type { CommentRepoPort } from "./ports.js";
+import type { CommentRecord, CommentStatus, CommentThreadNode, ModerationLogEntry, ModerationQueuePage } from "./types.js";
+export declare class InMemoryCommentRepo implements CommentRepoPort {
+    private comments;
+    private log;
+    constructor({ initialComments, initialLog }?: {
+        initialComments?: CommentRecord[];
+        initialLog?: ModerationLogEntry[];
+    }, _optional?: Record<string, never>);
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }, _optional?: Record<string, never>): Promise<CommentRecord | null>;
+    /**
+     * Direct upsert of one row. NOT on {@link CommentRepoPort} — the durable half flips its marker
+     * with column SQL and needs no such method. This exists so the hermetic composition root can
+     * drive a record-store `TrashAdapter` over this double (`server/runtime/composition/app.ts`), the
+     * same way the in-memory redirect repo's `insertRedirect` is used there.
+     *
+     * @complexity O(n) over the held rows.
+     */
+    save(record: CommentRecord, _optional?: Record<string, never>): Promise<void>;
+    listThreadForEntry(required: {
+        workspaceId: string;
+        entryId: string;
+        includeStatuses?: readonly CommentStatus[];
+    }, _optional?: Record<string, never>): Promise<CommentThreadNode[]>;
+    listModerationQueue(required: {
+        workspaceId: string;
+        status: CommentStatus;
+        limit: number;
+        cursor?: string | null;
+    }, _optional?: Record<string, never>): Promise<ModerationQueuePage>;
+    countByStatus(required: {
+        workspaceId: string;
+        entryId?: string;
+        status: CommentStatus;
+    }, _optional?: Record<string, never>): Promise<number>;
+    /** Copies the comment and optional audit row synchronously so they appear atomically.
+     * @complexity O(1) time and space for fixed-shape rows.
+     * @example repo.create({ record }, { submitLog })
+     */
+    create({ record }: {
+        record: CommentRecord;
+    }, { submitLog }?: {
+        submitLog?: ModerationLogEntry;
+    }): Promise<void>;
+    listModerationLog(required: {
+        workspaceId: string;
+        commentId: string;
+    }, _optional?: Record<string, never>): Promise<ModerationLogEntry[]>;
+    applyModeration(required: {
+        workspaceId: string;
+        id: string;
+        expectedVersion: number;
+        action: ModerationLogEntry["action"];
+        toStatus: CommentStatus;
+        actorPrincipalId: string;
+        note: string | null;
+        at: string;
+    }, _optional?: Record<string, never>): ReturnType<CommentRepoPort["applyModeration"]>;
+    purge(required: {
+        workspaceId: string;
+        id: string;
+        actorPrincipalId: string;
+        note: string | null;
+        at: string;
+    }, _optional?: Record<string, never>): ReturnType<CommentRepoPort["purge"]>;
+}
+//# sourceMappingURL=repo.memory.d.ts.map

package/dist/comments/repo.memory.js

@@ -0,0 +1,120 @@
+/**
+ * @file In-memory `CommentRepoPort` adapter (ADR-006 rule-of-two "test/dev" half;
+ * `repo.sqlite.ts` is the durable half).
+ */
+import { decodeKeysetCursor, encodeKeysetCursor } from "../core/keyset-cursor.js";
+function buildThread(comments, parentId) {
+    return comments
+        .filter((c) => c.parentId === parentId)
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+        .map((comment) => ({ comment, replies: buildThread(comments, comment.id) }));
+}
+export class InMemoryCommentRepo {
+    comments;
+    log;
+    constructor({ initialComments = [], initialLog = [] } = {}, _optional = {}) {
+        this.comments = [...initialComments];
+        this.log = [...initialLog];
+    }
+    async findById(required, _optional = {}) {
+        return this.comments.find((c) => c.workspaceId === required.workspaceId && c.id === required.id) ?? null;
+    }
+    /**
+     * Direct upsert of one row. NOT on {@link CommentRepoPort} — the durable half flips its marker
+     * with column SQL and needs no such method. This exists so the hermetic composition root can
+     * drive a record-store `TrashAdapter` over this double (`server/runtime/composition/app.ts`), the
+     * same way the in-memory redirect repo's `insertRedirect` is used there.
+     *
+     * @complexity O(n) over the held rows.
+     */
+    async save(record, _optional = {}) {
+        const index = this.comments.findIndex((c) => c.workspaceId === record.workspaceId && c.id === record.id);
+        if (index === -1)
+            this.comments.push(record);
+        else
+            this.comments[index] = record;
+    }
+    async listThreadForEntry(required, _optional = {}) {
+        const statuses = required.includeStatuses ?? ["approved"];
+        const scoped = this.comments.filter((c) => c.workspaceId === required.workspaceId && c.entryId === required.entryId && statuses.includes(c.status));
+        return buildThread(scoped, null);
+    }
+    async listModerationQueue(required, _optional = {}) {
+        const scoped = this.comments
+            .filter((c) => c.workspaceId === required.workspaceId && c.status === required.status)
+            .sort((a, b) => (a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt.localeCompare(b.createdAt)));
+        // Same keyset contract as `repo.ts`: the cursor carries the last row's position itself, so the
+        // page resumes after it even if that comment has since left this status or been purged, and a
+        // malformed cursor is refused.
+        const marker = required.cursor ? decodeKeysetCursor({ cursor: required.cursor }) : undefined;
+        const startIndex = marker
+            ? scoped.filter((c) => c.createdAt < marker.createdAt || (c.createdAt === marker.createdAt && c.id.localeCompare(marker.id) <= 0)).length
+            : 0;
+        const page = scoped.slice(startIndex, startIndex + required.limit);
+        const last = page[page.length - 1];
+        const nextCursor = startIndex + required.limit < scoped.length && last ? encodeKeysetCursor(last) : null;
+        return { items: page, nextCursor };
+    }
+    async countByStatus(required, _optional = {}) {
+        return this.comments.filter((c) => c.workspaceId === required.workspaceId && c.status === required.status && (required.entryId === undefined || c.entryId === required.entryId)).length;
+    }
+    /** Copies the comment and optional audit row synchronously so they appear atomically.
+     * @complexity O(1) time and space for fixed-shape rows.
+     * @example repo.create({ record }, { submitLog })
+     */
+    async create({ record }, { submitLog } = {}) {
+        this.comments.push({ ...record });
+        if (submitLog)
+            this.log.push({ ...submitLog });
+    }
+    async listModerationLog(required, _optional = {}) {
+        return this.log
+            .filter((entry) => entry.workspaceId === required.workspaceId && entry.commentId === required.commentId)
+            .sort((a, b) => (a.at === b.at ? a.id.localeCompare(b.id) : a.at.localeCompare(b.at)));
+    }
+    async applyModeration(required, _optional = {}) {
+        const index = this.comments.findIndex((c) => c.workspaceId === required.workspaceId && c.id === required.id);
+        if (index === -1)
+            return { ok: false, reason: "not-found" };
+        const current = this.comments[index];
+        if (current.version !== required.expectedVersion) {
+            return { ok: false, reason: "conflict", currentVersion: current.version };
+        }
+        const updated = { ...current, status: required.toStatus, updatedAt: required.at, version: current.version + 1 };
+        const logEntry = {
+            id: `modlog-${required.id}-${this.log.length}`,
+            workspaceId: required.workspaceId,
+            commentId: required.id,
+            actorPrincipalId: required.actorPrincipalId,
+            action: required.action,
+            fromStatus: current.status,
+            toStatus: required.toStatus,
+            at: required.at,
+            note: required.note,
+        };
+        this.comments[index] = updated;
+        this.log.push(logEntry);
+        return { ok: true, record: updated, log: logEntry };
+    }
+    async purge(required, _optional = {}) {
+        const index = this.comments.findIndex((c) => c.workspaceId === required.workspaceId && c.id === required.id);
+        if (index === -1)
+            return { ok: false, reason: "not-found" };
+        const current = this.comments[index];
+        const logEntry = {
+            id: `modlog-${required.id}-${this.log.length}`,
+            workspaceId: required.workspaceId,
+            commentId: required.id,
+            actorPrincipalId: required.actorPrincipalId,
+            action: "purge",
+            fromStatus: current.status,
+            toStatus: current.status,
+            at: required.at,
+            note: required.note,
+        };
+        this.comments.splice(index, 1);
+        this.log.push(logEntry);
+        return { ok: true, log: logEntry };
+    }
+}
+//# sourceMappingURL=repo.memory.js.map

package/dist/comments/sanitize.d.ts

@@ -0,0 +1,15 @@
+/** Strips tags and normalizes whitespace; returns plain text without mutating the input.
+ * @complexity O(n) time and space for n input characters.
+ * @example sanitizeCommentBody({ raw: "<b>Hello</b>" }, {})
+ */
+export declare function sanitizeCommentBody({ raw }: {
+    raw: string;
+}, _optional?: Record<string, never>): string;
+/** Counts HTTP(S) links in text; performs no I/O.
+ * @complexity O(n) time and space for n input characters.
+ * @example countLinks({ text: "https://example.com" }, {})
+ */
+export declare function countLinks({ text }: {
+    text: string;
+}, _optional?: Record<string, never>): number;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/comments/sanitize.js

@@ -0,0 +1,31 @@
+/**
+ * @file A comments-scoped body sanitizer (SPEC-033 Non-Goals — no shared core `text` library
+ * exists anywhere in this codebase for this to extract into; ADR-031 §2/§4's "core `text`
+ * library" reference is design-forward, not something this spec can reuse). Strips HTML tags
+ * entirely (comments render as plain text, never `dangerouslySetInnerHTML`-equivalent raw HTML on
+ * any read path this spec builds) and collapses excess whitespace. Bounded, non-Turing-complete —
+ * a fixed regex pass, not a parser.
+ */
+const TAG_PATTERN = /<[^>]*>/g;
+const EXCESS_WHITESPACE = /[ \t]{2,}/g;
+const EXCESS_BLANK_LINES = /\n{3,}/g;
+/** Strips tags and normalizes whitespace; returns plain text without mutating the input.
+ * @complexity O(n) time and space for n input characters.
+ * @example sanitizeCommentBody({ raw: "<b>Hello</b>" }, {})
+ */
+export function sanitizeCommentBody({ raw }, _optional = {}) {
+    return raw
+        .replace(TAG_PATTERN, "")
+        .replace(EXCESS_WHITESPACE, " ")
+        .replace(EXCESS_BLANK_LINES, "\n\n")
+        .trim();
+}
+const LINK_PATTERN = /https?:\/\/\S+/gi;
+/** Counts HTTP(S) links in text; performs no I/O.
+ * @complexity O(n) time and space for n input characters.
+ * @example countLinks({ text: "https://example.com" }, {})
+ */
+export function countLinks({ text }, _optional = {}) {
+    return (text.match(LINK_PATTERN) ?? []).length;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/comments/spam.heuristic.d.ts

@@ -0,0 +1,8 @@
+import type { SpamCheckPort } from "./ports.js";
+import type { CommentSubmission, SpamVerdict } from "./types.js";
+export declare class HeuristicSpamCheck implements SpamCheckPort {
+    check(submission: CommentSubmission, _optional?: Record<string, never>): Promise<SpamVerdict>;
+    /** No feedback loop to update locally — this adapter has no model to correct. */
+    report(): Promise<void>;
+}
+//# sourceMappingURL=spam.heuristic.d.ts.map

package/dist/comments/spam.heuristic.js

@@ -0,0 +1,54 @@
+/**
+ * @file ADR-031 §5 — the local heuristic `SpamCheckPort` adapter (ADR-006 rule-of-two "built
+ * now" half; an external service adapter remains a plausible second adapter).
+ * No network I/O.
+ *
+ * Signals, combined into a `[0,1]` score:
+ * - link density in the body (a common comment-spam signal — many URLs per short body);
+ * - a small keyword list of common spam phrases;
+ * - an implausibly long body (wall-of-text link farms);
+ * - an implausibly short body with a link (drive-by link drops).
+ */
+import { countLinks } from "./sanitize.js";
+const SPAM_KEYWORDS = [
+    "viagra",
+    "cialis",
+    "casino",
+    "crypto giveaway",
+    "make money fast",
+    "click here now",
+    "weight loss miracle",
+    "bit.ly",
+];
+const LONG_BODY_THRESHOLD = 4000;
+const SHORT_BODY_WITH_LINK_THRESHOLD = 40;
+function keywordHits(bodyLower) {
+    return SPAM_KEYWORDS.reduce((count, kw) => (bodyLower.includes(kw) ? count + 1 : count), 0);
+}
+export class HeuristicSpamCheck {
+    async check(submission, _optional = {}) {
+        const body = submission.bodyRaw;
+        const bodyLower = body.toLowerCase();
+        const links = countLinks({ text: body }, {});
+        const keywords = keywordHits(bodyLower);
+        let score = 0;
+        // Link density: each link past the first adds risk; heavily link-laden bodies are the
+        // single strongest comment-spam signal.
+        score += Math.min(0.6, Math.max(0, links - 1) * 0.2);
+        // Any spam keyword is a strong, near-conclusive signal.
+        score += Math.min(0.7, keywords * 0.35);
+        // A short body that still carries a link reads as a drive-by drop.
+        if (body.length < SHORT_BODY_WITH_LINK_THRESHOLD && links > 0)
+            score += 0.3;
+        // An implausibly long body padded with links/keywords.
+        if (body.length > LONG_BODY_THRESHOLD && (links > 0 || keywords > 0))
+            score += 0.2;
+        score = Math.min(1, score);
+        return { isSpam: score >= 0.5, score, provider: "heuristic" };
+    }
+    /** No feedback loop to update locally — this adapter has no model to correct. */
+    async report() {
+        // no-op — documented in ports.ts as the local adapter's expected behavior.
+    }
+}
+//# sourceMappingURL=spam.heuristic.js.map

package/dist/comments/sql/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./repo.js";
+export * from "./repo.rows.js";
+//# sourceMappingURL=index.d.ts.map