cursedbelt-server 4.26.1 → 4.28.0

package/dist/server/sharing/statements.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Every SQL statement the share stores run, and the row → shape mappers — ONE copy for both
+ * the `bun:sqlite` store (`./store.ts`) and the D1 store (`./d1.ts`).
+ *
+ * Two stores with two copies of "strongest first, then oldest" is two answers the day
+ * somebody edits one of them. So the stores differ only in HOW they execute (a synchronous
+ * transaction vs one atomic `batch()`), never in WHAT they ask. Driver-free on purpose: the
+ * D1 store runs on `workerd`.
+ */
+import type { ShareAction, ShareEvent, ShareGrant, ShareLevel } from "cursedbelt-core/sharing/model";
+export interface GrantRow {
+    app: string;
+    kind: string;
+    resource_id: string;
+    subject_type: "user" | "group";
+    subject_id: string;
+    level: ShareLevel;
+    granted_by: string;
+    granted_at: string;
+    note: string;
+}
+export interface EventRow {
+    event_id: number;
+    at: string;
+    action: ShareAction;
+    app: string | null;
+    kind: string | null;
+    resource_id: string | null;
+    subject_type: "user" | "group";
+    subject_id: string;
+    level: ShareLevel | null;
+    previous_level: ShareLevel | null;
+    actor: string;
+    note: string;
+}
+export interface GroupRow {
+    group_id: string;
+    name: string;
+    created_by: string;
+    created_at: string;
+    note: string;
+}
+export interface GroupMemberRow {
+    group_id: string;
+    subject_id: string;
+    added_by: string;
+    added_at: string;
+}
+export declare const toGrant: (row: GrantRow) => ShareGrant;
+export declare const toEvent: (row: EventRow) => ShareEvent;
+export declare const SHARE_SQL: {
+    /** Binds the eleven {@link EVENT_COLUMNS}. */
+    readonly insertEvent: "INSERT INTO share_events\n\t\t\t   (at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)\n\t\t\t VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)";
+    readonly selectGrant: "SELECT * FROM share_grants WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?";
+    /** Binds app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note. */
+    readonly upsertGrant: "INSERT INTO share_grants\n\t\t\t\t   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)\n\t\t\t\t VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n\t\t\t\t ON CONFLICT (app, kind, resource_id, subject_type, subject_id)\n\t\t\t\t DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,\n\t\t\t\t               granted_at = excluded.granted_at, note = excluded.note";
+    readonly deleteGrant: "DELETE FROM share_grants WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?";
+    readonly selectResourceGrants: "SELECT * FROM share_grants WHERE app = ? AND kind = ? AND resource_id = ?";
+    readonly deleteResourceGrants: "DELETE FROM share_grants WHERE app = ? AND kind = ? AND resource_id = ?";
+    readonly selectSubjectGrants: "SELECT * FROM share_grants WHERE app = ? AND subject_type = ? AND subject_id = ?";
+    readonly deleteSubjectGrants: "DELETE FROM share_grants WHERE app = ? AND subject_type = ? AND subject_id = ?";
+    readonly selectGroupGrants: "SELECT * FROM share_grants WHERE app = ? AND subject_type = 'group' AND subject_id = ?";
+    readonly deleteGroupGrants: "DELETE FROM share_grants WHERE app = ? AND subject_type = 'group' AND subject_id = ?";
+    readonly listForResource: "SELECT * FROM share_grants\n\t\t\t\t\t WHERE app = ? AND kind = ? AND resource_id = ?\n\t\t\t\t\t -- Strongest first, then oldest. Spelled as a CASE rather than an\n\t\t\t\t\t -- ORDER BY on level, which happens to work only because 'write'\n\t\t\t\t\t -- sorts after 'read' and would silently mis-order a third level.\n\t\t\t\t\t ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC";
+    readonly listForSubject: "SELECT * FROM share_grants\n\t\t\t\t\t WHERE app = ? AND subject_type = ? AND subject_id = ?\n\t\t\t\t\t ORDER BY granted_at DESC";
+    /** Binds app, kind, resource_id, then the viewer twice. */
+    readonly accessFor: "SELECT level FROM share_grants\n\t\t\t\t\t WHERE app = ? AND kind = ? AND resource_id = ?\n\t\t\t\t\t   AND ( (subject_type = 'user' AND subject_id = ?)\n\t\t      OR (subject_type = 'group' AND subject_id IN\n\t\t          (SELECT group_id FROM share_group_members WHERE subject_id = ?)) )";
+    /** Binds app, kind, each of `levelCount` levels, then the viewer twice. */
+    readonly resourceIdsFor: (levelCount: number) => string;
+    readonly upsertGroup: "INSERT INTO share_groups (group_id, name, created_by, created_at, note)\n\t\t\t\t\t VALUES (?, ?, ?, ?, ?)\n\t\t\t\t\t ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note";
+    readonly renameGroup: "UPDATE share_groups SET name = ? WHERE group_id = ?";
+    readonly deleteGroup: "DELETE FROM share_groups WHERE group_id = ?";
+    readonly listGroups: "SELECT * FROM share_groups ORDER BY name";
+    readonly insertMember: "INSERT INTO share_group_members (group_id, subject_id, added_by, added_at)\n\t\t\t\t\t VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING";
+    readonly deleteMember: "DELETE FROM share_group_members WHERE group_id = ? AND subject_id = ?";
+    readonly listMembers: "SELECT * FROM share_group_members WHERE group_id = ? ORDER BY subject_id";
+    readonly groupIdsFor: "SELECT group_id FROM share_group_members WHERE subject_id = ? ORDER BY group_id";
+    /** The trail, newest first, under a WHERE built by {@link eventsWhere}; binds its params then the limit. */
+    readonly events: (where: string) => string;
+    /**
+     * The grant's event, read from the grant as it stands BEFORE the upsert that follows it in
+     * the same batch: `regrade` (with the old level) when the level changes, `grant` otherwise.
+     * Binds at, level, app, kind, resource_id, subject_type, subject_id, level, level, actor,
+     * note, then the five {@link ONE_GRANT} keys.
+     */
+    readonly insertGrantEvent: `INSERT INTO share_events (at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)
+\t\t\t SELECT ?, CASE WHEN g.level IS NOT NULL AND g.level <> ? THEN 'regrade' ELSE 'grant' END,
+\t\t\t        ?, ?, ?, ?, ?, ?,
+\t\t\t        CASE WHEN g.level <> ? THEN g.level ELSE NULL END, ?, ?
+\t\t\t   FROM (SELECT 1) AS one
+\t\t\t   LEFT JOIN share_grants AS g ON g.${string}
+\t\t\t RETURNING *`;
+    /**
+     * One `revoke` event per grant matching `where`, oldest grant first — written BEFORE the
+     * delete that follows it in the same batch. Binds at, actor, note, then `where`'s params.
+     */
+    readonly insertRevokeEvents: (where: string) => string;
+    readonly oneGrant: "app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?";
+    readonly resourceGrants: "app = ? AND kind = ? AND resource_id = ?";
+    readonly subjectGrants: "app = ? AND subject_type = ? AND subject_id = ?";
+    readonly groupGrants: "app = ? AND subject_type = 'group' AND subject_id = ?";
+};
+/** The trail's WHERE and its params, bound to one app — the filter both stores apply. */
+export declare function eventsWhere(app: string, query: {
+    kind?: string;
+    id?: string;
+    subject?: {
+        type: string;
+        id: string;
+    };
+}): {
+    where: string;
+    params: (string | number)[];
+};
+/** Newest first, capped: default 200, never more than 1000, never less than 1. */
+export declare const eventLimit: (limit: number | undefined) => number;

package/dist/server/sharing/statements.js

@@ -0,0 +1,139 @@
+import { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./schema.js";
+export const toGrant = (row) => ({
+    resource: { app: row.app, kind: row.kind, id: row.resource_id },
+    subject: { type: row.subject_type, id: row.subject_id },
+    level: row.level,
+    grantedBy: row.granted_by,
+    grantedAt: row.granted_at,
+    note: row.note,
+});
+export const toEvent = (row) => ({
+    id: row.event_id,
+    at: row.at,
+    action: row.action,
+    resource: row.app === null || row.kind === null || row.resource_id === null
+        ? null
+        : { app: row.app, kind: row.kind, id: row.resource_id },
+    subject: { type: row.subject_type, id: row.subject_id },
+    level: row.level,
+    previousLevel: row.previous_level,
+    actor: row.actor,
+    note: row.note,
+});
+/** The audit trail's columns, in the order every event insert binds them. */
+const EVENT_COLUMNS = "(at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)";
+/** One grant row's WHERE — the five columns of its UNIQUE key. */
+const ONE_GRANT = "app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?";
+const RESOURCE_GRANTS = "app = ? AND kind = ? AND resource_id = ?";
+const SUBJECT_GRANTS = "app = ? AND subject_type = ? AND subject_id = ?";
+const GROUP_GRANTS = "app = ? AND subject_type = 'group' AND subject_id = ?";
+/** "This viewer, directly or through any group they are in" — binds `subjectId` twice. */
+const VIEWER_MATCH = `( (subject_type = 'user' AND subject_id = ?)
+		      OR (subject_type = 'group' AND subject_id IN
+		          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )`;
+export const SHARE_SQL = {
+    /** Binds the eleven {@link EVENT_COLUMNS}. */
+    insertEvent: `INSERT INTO ${SHARE_EVENTS_TABLE}
+			   ${EVENT_COLUMNS}
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    selectGrant: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${ONE_GRANT}`,
+    /** Binds app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note. */
+    upsertGrant: `INSERT INTO ${SHARE_GRANTS_TABLE}
+				   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT (app, kind, resource_id, subject_type, subject_id)
+				 DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,
+				               granted_at = excluded.granted_at, note = excluded.note`,
+    deleteGrant: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${ONE_GRANT}`,
+    selectResourceGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${RESOURCE_GRANTS}`,
+    deleteResourceGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${RESOURCE_GRANTS}`,
+    selectSubjectGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${SUBJECT_GRANTS}`,
+    deleteSubjectGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${SUBJECT_GRANTS}`,
+    selectGroupGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${GROUP_GRANTS}`,
+    deleteGroupGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${GROUP_GRANTS}`,
+    listForResource: `SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${RESOURCE_GRANTS}
+					 -- Strongest first, then oldest. Spelled as a CASE rather than an
+					 -- ORDER BY on level, which happens to work only because 'write'
+					 -- sorts after 'read' and would silently mis-order a third level.
+					 ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC`,
+    listForSubject: `SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${SUBJECT_GRANTS}
+					 ORDER BY granted_at DESC`,
+    /** Binds app, kind, resource_id, then the viewer twice. */
+    accessFor: `SELECT level FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${RESOURCE_GRANTS}
+					   AND ${VIEWER_MATCH}`,
+    /** Binds app, kind, each of `levelCount` levels, then the viewer twice. */
+    resourceIdsFor: (levelCount) => `SELECT DISTINCT resource_id FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND level IN (${Array.from({ length: levelCount }, () => "?").join(", ")})
+					   AND ${VIEWER_MATCH}
+					 ORDER BY resource_id`,
+    upsertGroup: `INSERT INTO ${SHARE_GROUPS_TABLE} (group_id, name, created_by, created_at, note)
+					 VALUES (?, ?, ?, ?, ?)
+					 ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note`,
+    renameGroup: `UPDATE ${SHARE_GROUPS_TABLE} SET name = ? WHERE group_id = ?`,
+    deleteGroup: `DELETE FROM ${SHARE_GROUPS_TABLE} WHERE group_id = ?`,
+    listGroups: `SELECT * FROM ${SHARE_GROUPS_TABLE} ORDER BY name`,
+    insertMember: `INSERT INTO ${SHARE_GROUP_MEMBERS_TABLE} (group_id, subject_id, added_by, added_at)
+					 VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING`,
+    deleteMember: `DELETE FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? AND subject_id = ?`,
+    listMembers: `SELECT * FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? ORDER BY subject_id`,
+    groupIdsFor: `SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ? ORDER BY group_id`,
+    /** The trail, newest first, under a WHERE built by {@link eventsWhere}; binds its params then the limit. */
+    events: (where) => `SELECT * FROM ${SHARE_EVENTS_TABLE} WHERE ${where} ORDER BY event_id DESC LIMIT ?`,
+    // ── The D1 store's atomic forms ────────────────────────────────────────────────────────
+    // D1 has no interactive transaction, so "read the grant, then decide what to log" cannot
+    // be two round trips without a window between them. These write the audit row FROM the
+    // grant row inside one `batch()`, so the decision and the write are one atomic step. They
+    // are listed here beside the sync forms they must agree with — `d1.spec.ts` runs both
+    // stores through one scenario and compares every table.
+    /**
+     * The grant's event, read from the grant as it stands BEFORE the upsert that follows it in
+     * the same batch: `regrade` (with the old level) when the level changes, `grant` otherwise.
+     * Binds at, level, app, kind, resource_id, subject_type, subject_id, level, level, actor,
+     * note, then the five {@link ONE_GRANT} keys.
+     */
+    insertGrantEvent: `INSERT INTO ${SHARE_EVENTS_TABLE} ${EVENT_COLUMNS}
+			 SELECT ?, CASE WHEN g.level IS NOT NULL AND g.level <> ? THEN 'regrade' ELSE 'grant' END,
+			        ?, ?, ?, ?, ?, ?,
+			        CASE WHEN g.level <> ? THEN g.level ELSE NULL END, ?, ?
+			   FROM (SELECT 1) AS one
+			   LEFT JOIN ${SHARE_GRANTS_TABLE} AS g ON g.${ONE_GRANT.replaceAll(" AND ", " AND g.")}
+			 RETURNING *`,
+    /**
+     * One `revoke` event per grant matching `where`, oldest grant first — written BEFORE the
+     * delete that follows it in the same batch. Binds at, actor, note, then `where`'s params.
+     */
+    insertRevokeEvents: (where) => `INSERT INTO ${SHARE_EVENTS_TABLE} ${EVENT_COLUMNS}
+			 SELECT ?, 'revoke', app, kind, resource_id, subject_type, subject_id, level, NULL, ?, ?
+			   FROM ${SHARE_GRANTS_TABLE} WHERE ${where} ORDER BY grant_id
+			 RETURNING *`,
+    oneGrant: ONE_GRANT,
+    resourceGrants: RESOURCE_GRANTS,
+    subjectGrants: SUBJECT_GRANTS,
+    groupGrants: GROUP_GRANTS,
+};
+/** The trail's WHERE and its params, bound to one app — the filter both stores apply. */
+export function eventsWhere(app, query) {
+    const clauses = ["app IS NULL OR app = ?"];
+    const params = [app];
+    if (query.kind !== undefined) {
+        clauses.push("kind = ?");
+        params.push(query.kind);
+    }
+    if (query.id !== undefined) {
+        clauses.push("resource_id = ?");
+        params.push(query.id);
+    }
+    if (query.subject) {
+        clauses.push("subject_type = ? AND subject_id = ?");
+        params.push(query.subject.type, query.subject.id);
+    }
+    return {
+        where: clauses.map((clause) => `(${clause})`).join(" AND "),
+        params,
+    };
+}
+/** Newest first, capped: default 200, never more than 1000, never less than 1. */
+export const eventLimit = (limit) => Math.max(1, Math.min(limit ?? 200, 1000));

package/dist/server/sharing/store.d.ts

@@ -34,15 +34,9 @@
  */
 import type { Database } from "bun:sqlite";
 import { type ShareAccess, type ShareEvent, type ShareGrant, type ShareGroup, type ShareGroupMember, type ShareLevel, type ShareSubject, type ShareViewer } from "cursedbelt-core/sharing/model";
-/** Shorthand for the common subject. `group(id)` is its sibling. */
-export declare const user: (id: string) => ShareSubject;
-export declare const group: (id: string) => ShareSubject;
-/** A resource within the store's own app — the `app` half is supplied by the
- *  store, so a caller cannot mistakenly write a grant into another app's rows. */
-export interface ShareTarget {
-    kind: string;
-    id: string;
-}
+import type { GrantInput, RevokeInput, ShareEventQuery, ShareTarget } from "./contract.js";
+export { group, user } from "./contract.js";
+export type { GrantInput, RevokeInput, ShareEventQuery, ShareTarget } from "./contract.js";
 export interface ShareStoreOptions {
     db: Database;
     /** The satellite this store speaks for. Fixed at construction so `app` cannot
@@ -66,25 +60,6 @@ export interface ShareStoreOptions {
     /** Injectable clock, for tests that assert ordering. ISO-8601 strings. */
     now?: () => string;
 }
-export interface GrantInput extends ShareTarget {
-    subject: ShareSubject;
-    level: ShareLevel;
-    grantedBy: string;
-    note?: string;
-}
-export interface RevokeInput extends ShareTarget {
-    subject: ShareSubject;
-    revokedBy: string;
-    note?: string;
-}
-export interface ShareEventQuery {
-    kind?: string;
-    id?: string;
-    subject?: ShareSubject;
-    /** Newest first, capped. Default 200 — a panel shows a page, and an unbounded
-     *  audit read on a busy resource is the query that times out in production. */
-    limit?: number;
-}
 export type ShareStore = ReturnType<typeof createShareStore>;
 /**
  * Open (and migrate) the sharing tables in this database, returning the store.

package/dist/server/sharing/store.js

@@ -1,31 +1,11 @@
 import { levelsMeeting, normalizeSubjectId, strongerAccess, } from "cursedbelt-core/sharing/model";
 import { runMigrations } from "../migration/runner.js";
-import { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, SHARE_MIGRATIONS, } from "./migrations.js";
+import { SHARE_MIGRATIONS } from "./migrations.js";
 import { sharedResourceSql } from "./sql.js";
-/** Shorthand for the common subject. `group(id)` is its sibling. */
-export const user = (id) => ({ type: "user", id });
-export const group = (id) => ({ type: "group", id });
-const toGrant = (row) => ({
-    resource: { app: row.app, kind: row.kind, id: row.resource_id },
-    subject: { type: row.subject_type, id: row.subject_id },
-    level: row.level,
-    grantedBy: row.granted_by,
-    grantedAt: row.granted_at,
-    note: row.note,
-});
-const toEvent = (row) => ({
-    id: row.event_id,
-    at: row.at,
-    action: row.action,
-    resource: row.app === null || row.kind === null || row.resource_id === null
-        ? null
-        : { app: row.app, kind: row.kind, id: row.resource_id },
-    subject: { type: row.subject_type, id: row.subject_id },
-    level: row.level,
-    previousLevel: row.previous_level,
-    actor: row.actor,
-    note: row.note,
-});
+import { eventLimit, eventsWhere, SHARE_SQL, toEvent, toGrant, } from "./statements.js";
+// The contract has no driver in it, so `./d1.ts` (which runs on `workerd`) shares it without
+// reaching this file. Re-exported so `cursedbelt-server/sharing` is unchanged.
+export { group, user } from "./contract.js";
 /**
  * Open (and migrate) the sharing tables in this database, returning the store.
  *
@@ -54,9 +34,7 @@ export function createShareStore(options) {
         }
     };
     const recordEvent = (input) => {
-        db.query(`INSERT INTO ${SHARE_EVENTS_TABLE}
-			   (at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)
-			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.at, input.action, input.resource?.app ?? null, input.resource?.kind ?? null, input.resource?.id ?? null, input.subject.type, input.subject.id, input.level, input.previousLevel ?? null, input.actor, input.note ?? "");
+        db.query(SHARE_SQL.insertEvent).run(input.at, input.action, input.resource?.app ?? null, input.resource?.kind ?? null, input.resource?.id ?? null, input.subject.type, input.subject.id, input.level, input.previousLevel ?? null, input.actor, input.note ?? "");
         const id = db.query("SELECT last_insert_rowid() AS id").get().id;
         return {
             id,
@@ -76,8 +54,7 @@ export function createShareStore(options) {
     });
     const readGrant = (target, subject) => {
         const row = db
-            .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
-				 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`)
+            .query(SHARE_SQL.selectGrant)
             .get(app, target.kind, target.id, subject.type, subject.id);
         return row ? toGrant(row) : null;
     };
@@ -102,12 +79,7 @@ export function createShareStore(options) {
             const events = [];
             const grant = db.transaction(() => {
                 const existing = readGrant(input, subject);
-                db.query(`INSERT INTO ${SHARE_GRANTS_TABLE}
-					   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)
-					 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-					 ON CONFLICT (app, kind, resource_id, subject_type, subject_id)
-					 DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,
-					               granted_at = excluded.granted_at, note = excluded.note`).run(app, input.kind, input.id, subject.type, subject.id, input.level, input.grantedBy, at, input.note ?? "");
+                db.query(SHARE_SQL.upsertGrant).run(app, input.kind, input.id, subject.type, subject.id, input.level, input.grantedBy, at, input.note ?? "");
                 const resource = { app, kind: input.kind, id: input.id };
                 events.push(recordEvent({
                     action: existing && existing.level !== input.level ? "regrade" : "grant",
@@ -142,8 +114,7 @@ export function createShareStore(options) {
                 const existing = readGrant(input, subject);
                 if (!existing)
                     return null;
-                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE}
-					 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`).run(app, input.kind, input.id, subject.type, subject.id);
+                db.query(SHARE_SQL.deleteGrant).run(app, input.kind, input.id, subject.type, subject.id);
                 events.push(recordEvent({
                     action: "revoke",
                     resource: { app, kind: input.kind, id: input.id },
@@ -172,11 +143,11 @@ export function createShareStore(options) {
             const events = [];
             const count = db.transaction(() => {
                 const rows = db
-                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`)
+                    .query(SHARE_SQL.selectResourceGrants)
                     .all(app, target.kind, target.id);
                 if (rows.length === 0)
                     return 0;
-                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`).run(app, target.kind, target.id);
+                db.query(SHARE_SQL.deleteResourceGrants).run(app, target.kind, target.id);
                 for (const row of rows) {
                     events.push(recordEvent({
                         action: "revoke",
@@ -201,11 +172,11 @@ export function createShareStore(options) {
             const events = [];
             const count = db.transaction(() => {
                 const rows = db
-                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`)
+                    .query(SHARE_SQL.selectSubjectGrants)
                     .all(app, normal.type, normal.id);
                 if (rows.length === 0)
                     return 0;
-                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`).run(app, normal.type, normal.id);
+                db.query(SHARE_SQL.deleteSubjectGrants).run(app, normal.type, normal.id);
                 for (const row of rows) {
                     events.push(recordEvent({
                         action: "revoke",
@@ -224,25 +195,14 @@ export function createShareStore(options) {
         },
         /** Who can see this record, strongest first then oldest — the panel's read. */
         listForResource(target) {
-            const rows = db
-                .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
-					 WHERE app = ? AND kind = ? AND resource_id = ?
-					 -- Strongest first, then oldest. Spelled as a CASE rather than an
-					 -- ORDER BY on level, which happens to work only because 'write'
-					 -- sorts after 'read' and would silently mis-order a third level.
-					 ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC`)
-                .all(app, target.kind, target.id);
+            const rows = db.query(SHARE_SQL.listForResource).all(app, target.kind, target.id);
             return rows.map(toGrant);
         },
         /** Everything shared with one subject — "shared with you". Group grants are
          *  NOT expanded here; use {@link resourceIdsFor} for the resolved answer. */
         listForSubject(subject) {
             const normal = normalized(subject);
-            const rows = db
-                .query(`SELECT * FROM ${SHARE_GRANTS_TABLE}
-					 WHERE app = ? AND subject_type = ? AND subject_id = ?
-					 ORDER BY granted_at DESC`)
-                .all(app, normal.type, normal.id);
+            const rows = db.query(SHARE_SQL.listForSubject).all(app, normal.type, normal.id);
             return rows.map(toGrant);
         },
         /**
@@ -257,11 +217,7 @@ export function createShareStore(options) {
             if (!subjectId)
                 return "none";
             const rows = db
-                .query(`SELECT level FROM ${SHARE_GRANTS_TABLE}
-					 WHERE app = ? AND kind = ? AND resource_id = ?
-					   AND ( (subject_type = 'user' AND subject_id = ?)
-					      OR (subject_type = 'group' AND subject_id IN
-					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )`)
+                .query(SHARE_SQL.accessFor)
                 .all(app, target.kind, target.id, subjectId, subjectId);
             let access = "none";
             for (const row of rows)
@@ -276,12 +232,7 @@ export function createShareStore(options) {
                 return [];
             const levels = levelsMeeting(atLeast);
             const rows = db
-                .query(`SELECT DISTINCT resource_id FROM ${SHARE_GRANTS_TABLE}
-					 WHERE app = ? AND kind = ? AND level IN (${levels.map(() => "?").join(", ")})
-					   AND ( (subject_type = 'user' AND subject_id = ?)
-					      OR (subject_type = 'group' AND subject_id IN
-					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )
-					 ORDER BY resource_id`)
+                .query(SHARE_SQL.resourceIdsFor(levels.length))
                 .all(app, kind, ...levels, subjectId, subjectId);
             return rows.map((row) => row.resource_id);
         },
@@ -298,9 +249,7 @@ export function createShareStore(options) {
             const at = clock();
             const events = [];
             const created = db.transaction(() => {
-                db.query(`INSERT INTO ${SHARE_GROUPS_TABLE} (group_id, name, created_by, created_at, note)
-					 VALUES (?, ?, ?, ?, ?)
-					 ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note`).run(id, input.name, input.createdBy, at, input.note ?? "");
+                db.query(SHARE_SQL.upsertGroup).run(id, input.name, input.createdBy, at, input.note ?? "");
                 events.push(recordEvent({
                     action: "group.create",
                     resource: null,
@@ -326,7 +275,7 @@ export function createShareStore(options) {
             const at = clock();
             const events = [];
             db.transaction(() => {
-                db.query(`UPDATE ${SHARE_GROUPS_TABLE} SET name = ? WHERE group_id = ?`).run(name, groupId);
+                db.query(SHARE_SQL.renameGroup).run(name, groupId);
                 events.push(recordEvent({
                     action: "group.rename",
                     resource: null,
@@ -353,10 +302,8 @@ export function createShareStore(options) {
             const at = clock();
             const events = [];
             db.transaction(() => {
-                const grants = db
-                    .query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`)
-                    .all(app, groupId);
-                db.query(`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`).run(app, groupId);
+                const grants = db.query(SHARE_SQL.selectGroupGrants).all(app, groupId);
+                db.query(SHARE_SQL.deleteGroupGrants).run(app, groupId);
                 for (const row of grants) {
                     events.push(recordEvent({
                         action: "revoke",
@@ -368,7 +315,7 @@ export function createShareStore(options) {
                         at,
                     }));
                 }
-                db.query(`DELETE FROM ${SHARE_GROUPS_TABLE} WHERE group_id = ?`).run(groupId);
+                db.query(SHARE_SQL.deleteGroup).run(groupId);
                 events.push(recordEvent({
                     action: "group.delete",
                     resource: null,
@@ -382,9 +329,7 @@ export function createShareStore(options) {
             emit(events);
         },
         listGroups() {
-            const rows = db
-                .query(`SELECT * FROM ${SHARE_GROUPS_TABLE} ORDER BY name`)
-                .all();
+            const rows = db.query(SHARE_SQL.listGroups).all();
             return rows.map((row) => ({
                 id: row.group_id,
                 name: row.name,
@@ -401,8 +346,7 @@ export function createShareStore(options) {
             const at = clock();
             const events = [];
             db.transaction(() => {
-                db.query(`INSERT INTO ${SHARE_GROUP_MEMBERS_TABLE} (group_id, subject_id, added_by, added_at)
-					 VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING`).run(id, member, actor, at);
+                db.query(SHARE_SQL.insertMember).run(id, member, actor, at);
                 events.push(recordEvent({
                     action: "group.join",
                     resource: null,
@@ -421,7 +365,7 @@ export function createShareStore(options) {
             const at = clock();
             const events = [];
             db.transaction(() => {
-                db.query(`DELETE FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? AND subject_id = ?`).run(id, member);
+                db.query(SHARE_SQL.deleteMember).run(id, member);
                 events.push(recordEvent({
                     action: "group.leave",
                     resource: null,
@@ -436,7 +380,7 @@ export function createShareStore(options) {
         },
         listGroupMembers(groupId) {
             const rows = db
-                .query(`SELECT * FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? ORDER BY subject_id`)
+                .query(SHARE_SQL.listMembers)
                 .all(normalizeSubjectId("group", groupId));
             return rows.map((row) => ({
                 groupId: row.group_id,
@@ -450,34 +394,17 @@ export function createShareStore(options) {
             const member = normalizeSubjectId("user", subjectId);
             if (!member)
                 return [];
-            const rows = db
-                .query(`SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ? ORDER BY group_id`)
-                .all(member);
+            const rows = db.query(SHARE_SQL.groupIdsFor).all(member);
             return rows.map((row) => row.group_id);
         },
         // ── The audit trail ──────────────────────────────────────────────────────
         /** The trail, newest first. Filter by resource, by subject, or neither. */
         events(query = {}) {
-            const clauses = ["app IS NULL OR app = ?"];
-            const params = [app];
-            if (query.kind !== undefined) {
-                clauses.push("kind = ?");
-                params.push(query.kind);
-            }
-            if (query.id !== undefined) {
-                clauses.push("resource_id = ?");
-                params.push(query.id);
-            }
-            if (query.subject) {
-                const normal = normalized(query.subject);
-                clauses.push("subject_type = ? AND subject_id = ?");
-                params.push(normal.type, normal.id);
-            }
-            const where = clauses.map((clause) => `(${clause})`).join(" AND ");
-            const limit = Math.max(1, Math.min(query.limit ?? 200, 1000));
-            const rows = db
-                .query(`SELECT * FROM ${SHARE_EVENTS_TABLE} WHERE ${where} ORDER BY event_id DESC LIMIT ?`)
-                .all(...params, limit);
+            const { where, params } = eventsWhere(app, {
+                ...query,
+                subject: query.subject ? normalized(query.subject) : undefined,
+            });
+            const rows = db.query(SHARE_SQL.events(where)).all(...params, eventLimit(query.limit));
             return rows.map(toEvent);
         },
     };

package/docs/activity.md

@@ -40,4 +40,11 @@ a merge across apps stays labelled.
 `describeActivityEvent` / `describeActivityResource` produce the sentence a reader sees. An app
 that writes its own sentence for the same event creates a second wording that drifts.
 
+## 5. On a Worker, the same stream lives in D1
+
+`cursedbelt-server/activity/d1` (since 4.28.0, task 393) is `createD1ActivityLog` — the same
+`record`, `query`, `count`, `facets` and `sources`, each async, over the same `activity_events`
+table and the same filter semantics (one shared `query.ts`). `shareEventsSource` is re-exported
+there. It runs no DDL: `ACTIVITY_DDL` goes into the app's `db/schema.sql`. It is Worker-safe.
+
 Cite this page from an app as `cursedbelt-server/docs/activity.md`.

package/docs/engagement.md

@@ -44,4 +44,10 @@ manifest parses (`apps/roms/routes.manifest.test.ts` is the pattern).
 excluded app, `SATELLITE_ENGAGEMENT=0` or an unresolvable data directory each turn recording OFF
 and say why, and the app still boots.
 
+**On a Worker**, the same three tables live in the app's own D1 instead:
+`cursedbelt-server/engagement/d1` (since 4.27.0, task 2096) exports `ENGAGEMENT_DDL` for the
+app's `db/schema.sql`, `createD1EngagementRecorder` to mount inside the gate, and
+`placesFromManifest` for the bundled `routes.manifest.json`. It is Worker-safe and uses the same
+`policy.ts`, so there is one privacy rule whichever host records. station reads either shape.
+
 Cite this page from an app as `cursedbelt-server/docs/engagement.md`.

package/docs/notifications.md

@@ -40,4 +40,13 @@ It is not filtered by the reader's scope at read time and cannot be. Put what is
 recipient in the title and body, and let the LINK carry them to the thing, where every normal
 read filter applies (`family`'s share notification does not name the relative for this reason).
 
+## 5. On a Worker, the inbox lives in D1 and there is no live stream
+
+`cursedbelt-server/notifications/d1` (since 4.28.0, task 393) is `createD1NotificationService` —
+the same `{ center, store, mount, close }`, with cwip's center over a D1 implementation of its
+`NotificationStore` and the same table (`NOTIFICATIONS_DDL` / `notificationsDdl(table)` for the
+app's `db/schema.sql`; nothing runs DDL at request time). `hub` is always `null` and
+`{base}/stream` is not mounted: an isolate cannot share open streams, so polling (rule 1's
+backstop) is the delivery. It is Worker-safe.
+
 Cite this page from an app as `cursedbelt-server/docs/notifications.md`.