snapback2 0.0.1

package/dist/templates/chat/shared/log.ts

@@ -0,0 +1,130 @@
+// The delivery log is the app's source of truth on the device (LLP 1012 §3):
+// every screen is a pure function over held log rows plus the durable outbox.
+import type { Api, OutboxEntry } from "snapback2/client";
+
+type ResultOf<T> = T extends { readonly __result?: infer Result } ? NonNullable<Result> : never;
+export type LogRow = ResultOf<Api["deliveries"]["inbox"]>[number];
+export type MessageRow = NonNullable<LogRow["message"]>;
+
+export interface ConversationSummary {
+  conversationId: string;
+  latestAt: number;
+  latestBody: string | undefined;
+  messages: number;
+}
+
+/** One line per conversation, newest activity first, from the held log. */
+export function conversations(rows: readonly LogRow[]): ConversationSummary[] {
+  const byConversation = new Map<string, ConversationSummary>();
+  for (const row of rows) {
+    const current = byConversation.get(row.conversationId) ?? {
+      conversationId: row.conversationId,
+      latestAt: row.at,
+      latestBody: undefined,
+      messages: 0,
+    };
+    if (row.kind === "message") current.messages += 1;
+    if (row.at >= current.latestAt) {
+      current.latestAt = row.at;
+      current.latestBody = row.message?.body ?? current.latestBody;
+    }
+    byConversation.set(row.conversationId, current);
+  }
+  return [...byConversation.values()].sort((a, b) => b.latestAt - a.latestAt);
+}
+
+export type PostArgs = { conversationId: string; body: string };
+export type EditArgs = { messageId: string; body: string; baseBody: string };
+
+export function postArgs(entry: OutboxEntry): PostArgs | undefined {
+  const args = entry.args as Partial<PostArgs> | null;
+  return entry.op === "deliveries.post" && args && typeof args.conversationId === "string" && typeof args.body === "string"
+    ? { conversationId: args.conversationId, body: args.body }
+    : undefined;
+}
+
+export function editArgs(entry: OutboxEntry): EditArgs | undefined {
+  const args = entry.args as Partial<EditArgs> | null;
+  return entry.op === "deliveries.edit" && args && typeof args.messageId === "string" && typeof args.body === "string"
+    ? { messageId: args.messageId, body: args.body, baseBody: args.baseBody ?? "" }
+    : undefined;
+}
+
+/** The label a settled or queued intent shows; never a client clock. */
+export function intentLabel(entry: OutboxEntry): string {
+  switch (entry.state) {
+    case "queued": return entry.reason === "fence" ? "Will be checked by the server" : "Sending…";
+    case "committed": return "Sent";
+    case "expired": return "Expired";
+    case "rejected": {
+      const response = entry.response as { reason?: string; code?: string; rewrite?: string; message?: string } | undefined;
+      // @ref LLP 1012#7-writes-offline — a trace conflict, or the recipe's own
+      // compare-and-set (`require msg.body = baseBody else CONFLICT`), reads the same.
+      if (response?.reason === "conflict" || response?.code === "CONFLICT") return "Not sent · Message changed";
+      return `Not sent · ${response?.rewrite ?? response?.message ?? response?.code ?? "refused"}`;
+    }
+  }
+}
+
+export type Bubble =
+  | { key: string; kind: "row"; message: MessageRow; at: number; edit?: OutboxEntry }
+  | { key: string; kind: "pending"; entry: OutboxEntry; body: string };
+
+/**
+ * The thread as bubbles: one per message id from the log (tombstoned ids
+ * hidden), then the outbox's intents for this conversation. A pending post is
+ * keyed by its first pinned id, the id the server row will carry, so the same
+ * bubble becomes the row on `committed` and nothing jumps.
+ */
+export function threadBubbles(rows: readonly LogRow[], entries: readonly OutboxEntry[], conversationId: string): Bubble[] {
+  const hidden = new Set(rows.filter((row) => row.kind === "removed" || row.kind === "expired").map((row) => row.messageId));
+  const edits = new Map(entries.map((entry) => [editArgs(entry)?.messageId, entry] as const).filter(([id]) => id !== undefined));
+  const seen = new Set<string>();
+  const bubbles: Bubble[] = [];
+  // @ref LLP 1012#7-writes-offline — a queued send the twin predicted is inside
+  // the log's rows under its pinned id; it is still the pending bubble, with
+  // `args.body` and "Sending…" and no time, until the server's row settles it.
+  const pending = new Map(entries
+    .filter((entry) => entry.state === "queued" && postArgs(entry) !== undefined)
+    .map((entry) => [entry.ids[0] ?? entry.intent, entry] as const));
+  // The log's thread page is newest-first (`last 50`); a thread reads oldest-first.
+  const chronological = [...rows].sort((a, b) => a.at - b.at || (a.messageId < b.messageId ? -1 : a.messageId > b.messageId ? 1 : 0));
+  for (const row of chronological) {
+    if (row.kind !== "message" || !row.message || hidden.has(row.messageId) || seen.has(row.messageId)) continue;
+    seen.add(row.messageId);
+    const predicted = pending.get(row.messageId);
+    if (predicted) {
+      bubbles.push({ key: row.messageId, kind: "pending", entry: predicted, body: postArgs(predicted)!.body });
+      continue;
+    }
+    const edit = edits.get(row.messageId);
+    bubbles.push({ key: row.messageId, kind: "row", message: row.message, at: row.at, ...(edit ? { edit } : {}) });
+  }
+  for (const entry of entries) {
+    const args = postArgs(entry);
+    if (!args || args.conversationId !== conversationId) continue;
+    const key = entry.ids[0] ?? entry.intent;
+    if (seen.has(key)) continue;
+    bubbles.push({ key, kind: "pending", entry, body: args.body });
+  }
+  return bubbles;
+}
+
+/** Committed posts whose server row is now held can leave the outbox. */
+export function settledByRows(rows: readonly LogRow[], entries: readonly OutboxEntry[]): OutboxEntry[] {
+  const held = new Set(rows.map((row) => row.messageId));
+  return entries.filter((entry) => entry.state === "committed" && postArgs(entry) !== undefined && held.has(entry.ids[0] ?? ""));
+}
+
+/** Offline search is a filter over the downloaded log (LLP 1012 §6); it finds nothing evicted. */
+export function searchHeld(rows: readonly LogRow[], term: string): LogRow[] {
+  const needle = term.trim().toLowerCase();
+  if (!needle) return [];
+  const seen = new Set<string>();
+  return rows.filter((row) => {
+    const body = row.message?.body;
+    if (row.kind !== "message" || !body || seen.has(row.messageId) || !body.toLowerCase().includes(needle)) return false;
+    seen.add(row.messageId);
+    return true;
+  });
+}

package/dist/templates/chat/shared/offline.js

@@ -0,0 +1,8 @@
+const chatOffline = {
+  onTombstone: (item) => item.table === "deliveries" && (item.row.kind === "removed" || item.row.kind === "expired") && typeof item.row.messageId === "string" ? [{ table: "messages", id: item.row.messageId }] : [],
+  // Optional on the recipe's message row; absent/null is ordinary media.
+  viewOnce: (table, row) => table === "messages" && row.viewOnce === true
+};
+export {
+  chatOffline
+};

package/dist/templates/chat/shared/offline.ts

@@ -0,0 +1,9 @@
+type StoredRow = { table: string; row: Record<string, unknown> };
+
+export const chatOffline = {
+  onTombstone: (item: StoredRow) =>
+    item.table === "deliveries" && (item.row.kind === "removed" || item.row.kind === "expired")
+      && typeof item.row.messageId === "string" ? [{ table: "messages", id: item.row.messageId }] : [],
+  // Optional on the recipe's message row; absent/null is ordinary media.
+  viewOnce: (table: string, row: Record<string, unknown>) => table === "messages" && row.viewOnce === true,
+};

package/dist/templates/chat/snapback/deliveries.q

@@ -0,0 +1,33 @@
+query inbox(c: cursor ?):
+  page = deliveries[viewer] after c first 50 by byRecipientAt
+  return page { *, message: messages[.messageId] }
+
+query thread(conversationId: conversations, c: cursor ?):
+  require exists memberships[conversationId, viewer] else MEMBERSHIP_REQUIRED
+  page = deliveries[viewer, conversationId] after c last 50 by byRecipientConversationAt
+  return page { *, message: messages[.messageId] }
+
+mutation post(conversationId: conversations, body: text <=4000, viewOnce: bool ?):
+  require exists memberships[conversationId, viewer] else NOT_MEMBER
+  row = insert messages { conversationId, authorId: viewer, body, viewOnce, at: now }
+  for m in memberships[conversationId] first 50 by byConversationPrincipal:
+    insert deliveries { recipient: m.principal, conversationId, messageId: row.id, kind: 'message', at: now }
+  return { id: row.id }
+
+mutation unsend(messageId: messages):
+  msg = messages[messageId] ! else NOT_FOUND
+  require msg.authorId = viewer else NOT_AUTHOR
+  -- @ref LLP 1012#5-retention-revocation-and-the-fence — departed recipients evict the deleted body through the next held-page point absence.
+  for m in memberships[msg.conversationId] first 50 by byConversationPrincipal:
+    insert deliveries { recipient: m.principal, conversationId: msg.conversationId, messageId, kind: 'removed', at: now }
+  delete messages[msg]
+  return null
+
+mutation edit(messageId: messages, body: text <=4000, baseBody: text <=4000):
+  msg = messages[messageId] ! else NOT_FOUND
+  require msg.authorId = viewer else NOT_AUTHOR
+  require msg.body = baseBody else CONFLICT
+  update messages[msg] { body }
+  for m in memberships[msg.conversationId] first 50 by byConversationPrincipal:
+    insert deliveries { recipient: m.principal, conversationId: msg.conversationId, messageId, kind: 'edit', at: now }
+  return null

package/dist/templates/chat/snapback/delivery.ts

@@ -0,0 +1,30 @@
+import { effect } from "snapback2";
+import { recordNotified } from "./notifications";
+import { notifications } from "./schema";
+
+const baseHeaders = { accept: "application/json" };
+const requestDefaults = {
+  method: "POST",
+  headers: { ...baseHeaders, "content-type": "application/json" },
+};
+
+export const notify = effect({
+  grants: ["https://api.example.com"],
+  run: async (payload: { to: string; body: string }, { fetch, meta }) => {
+    function identity(value: string) { return value; }
+    const formatter = { format(value: string) { return identity(value); } };
+    const body = [payload.body].map(function keep(value) { return formatter.format(value); })[0];
+    try {
+      const response = await fetch("https://api.example.com/send", {
+        method: requestDefaults.method,
+        headers: { ...requestDefaults.headers, "idempotency-key": meta.id },
+        body: JSON.stringify({ ...payload, body }),
+      });
+      if (!response.ok) throw new Error(`provider ${response.status}`);
+      return { providerId: (await response.json()).id as string };
+    } catch (error) {
+      throw error;
+    }
+  },
+  then: recordNotified,
+});

package/dist/templates/chat/snapback/feeds.q

@@ -0,0 +1,14 @@
+shape authorCard = { displayName, handle }
+
+query globalFeed(c: cursor ?):
+  page = posts[] after c last 20 by byTime
+  return page {
+    post: .,
+    author: profiles[.author] authorCard,
+  }
+
+query followingFeed(c: cursor ?):
+  page = merge posts after c last 20 by byAuthorTime:
+    [viewer]
+    [f.followed] for f in follows[viewer] first 50 by byFollower
+  return page { post: ., author: profiles[.author] authorCard }

package/dist/templates/chat/snapback/follows.q

@@ -0,0 +1,11 @@
+mutation setFollow(target: principal, following: bool):
+  require target != viewer else SELF_FOLLOW
+  existing = follows[viewer, target]
+  if following:
+    if existing != null:
+      return existing
+    row = insert follows { follower: viewer, followed: target, at: now }
+    return { id: row.id, follower: viewer, followed: target, at: row.at }
+  if existing != null:
+    delete follows[existing]
+  return null

package/dist/templates/chat/snapback/groups.q

@@ -0,0 +1,40 @@
+mutation groupCreate(title: text <=120, members: [principal] <=49):
+  require count(members) >= 1 else GROUP_REQUIRES_MEMBER
+  conversationId = new
+  creatorMembershipId = new
+  joinedAt = now
+  insert conversations { id: conversationId, title, creatorId: viewer }
+  insert memberships { id: creatorMembershipId, conversationId, principal: viewer, role: 'admin', joinedAt }
+  for principal in members:
+    require principal != viewer else CREATOR_ALREADY_ADMIN
+    insert memberships { conversationId, principal, role: 'member', joinedAt }
+  return { id: conversationId, creatorMembershipId }
+
+mutation memberAdd(conversationId: conversations, principal: principal):
+  require exists memberships[conversationId, viewer, 'admin'] else ADMIN_REQUIRED
+  require principal != viewer else ADMIN_SELF_RESEAT
+  require #memberCounts[conversationId] < 50 else GROUP_FULL
+  row = insert memberships { conversationId, principal, role: 'member', joinedAt: now }
+  return { id: row.id }
+
+mutation memberPromote(conversationId: conversations, membershipId: memberships):
+  require exists memberships[conversationId, viewer, 'admin'] else ADMIN_REQUIRED
+  membership = memberships[membershipId] ! else MEMBERSHIP_REQUIRED
+  require membership.conversationId = conversationId else MEMBERSHIP_SCOPE_REQUIRED
+  require membership.role = 'member' else MEMBER_REQUIRED
+  update memberships[membership] { role: 'admin' }
+  return null
+
+mutation memberRemove(conversationId: conversations, membershipId: memberships):
+  require exists memberships[conversationId, viewer, 'admin'] else ADMIN_REQUIRED
+  membership = memberships[membershipId] ! else MEMBERSHIP_REQUIRED
+  require membership.conversationId = conversationId else MEMBERSHIP_SCOPE_REQUIRED
+  require membership.principal != viewer else ADMIN_SELF_REMOVE
+  delete memberships[membership]
+  return null
+
+mutation memberLeave(conversationId: conversations, membershipId: memberships):
+  membership = memberships[conversationId, viewer] ! else MEMBERSHIP_REQUIRED
+  require membership.id = membershipId else MEMBERSHIP_SELF_REQUIRED
+  delete memberships[membership]
+  return null

package/dist/templates/chat/snapback/messages.q

@@ -0,0 +1,32 @@
+effect notify from delivery
+
+query thread(conversationId: conversations, c: cursor ?):
+  require exists memberships[conversationId, viewer] else MEMBERSHIP_REQUIRED
+  return messages[conversationId] after c last 50
+
+query summary(conversationId: conversations):
+  require exists memberships[conversationId, viewer] else MEMBERSHIP_REQUIRED
+  return {
+    conversation: conversations[conversationId],
+    messageCount: messageCounts[conversationId],
+  }
+
+mutation send(conversationId: conversations, recipientId: profiles, body: text <=4000):
+  require exists memberships[conversationId, viewer] else NOT_MEMBER
+  recipient = profiles[recipientId] ! else RECIPIENT_UNKNOWN
+  require exists memberships[conversationId, recipient.principal] else RECIPIENT_NOT_MEMBER
+  row = insert messages { conversationId, authorId: viewer, body, photo: null, clip: null, at: now }
+  for m in memberships[conversationId] first 50 by byConversationPrincipal:
+    insert deliveries { recipient: m.principal, conversationId, messageId: row.id, kind: 'message', at: now }
+  emit notify { to: recipient.principal, body }
+  return { id: row.id }
+
+mutation sendPhoto(conversationId: conversations, photo: image <=5000000, viewOnce: bool ?):
+  require exists memberships[conversationId, viewer] else NOT_MEMBER
+  row = insert messages { conversationId, authorId: viewer, body: null, photo, clip: null, viewOnce, at: now }
+  return { id: row.id, photo: row.photo }
+
+mutation sendClip(conversationId: conversations, clip: video <=50000000, viewOnce: bool ?):
+  require exists memberships[conversationId, viewer] else NOT_MEMBER
+  row = insert messages { conversationId, authorId: viewer, body: null, photo: null, clip, viewOnce, at: now }
+  return { id: row.id, clip: row.clip, duration: clip.duration }

package/dist/templates/chat/snapback/notifications.q

@@ -0,0 +1,7 @@
+mutation recordNotified(outboxId: id, effect: text <=100, result: json <=1000):
+  insert notifications {
+    outboxId,
+    effect,
+    providerId: result.providerId,
+  }
+  return true

package/dist/templates/chat/snapback/posts.q

@@ -0,0 +1,4 @@
+mutation createPost(body: text <=500):
+  require exists profiles[viewer] else PROFILE_REQUIRED
+  row = insert posts { author: viewer, body, at: now }
+  return { id: row.id, author: viewer, body, at: row.at }

package/dist/templates/chat/snapback/profiles.q

@@ -0,0 +1,17 @@
+query mine():
+  return profiles[viewer]
+
+query byHandle(handle: text <=20):
+  return profiles[handle]
+
+mutation createMyProfile(displayName: text <=50, handle: text <=20, avatarUrl: text <=2048 ?, bio: text <=200, location: text <=50, link: text <=2048 ?):
+  existing = profiles[viewer]
+  if existing != null:
+    return existing
+  row = insert profiles { principal: viewer, displayName, handle, avatarUrl, bio, location, link }
+  return { id: row.id, principal: viewer, displayName, handle, avatarUrl, bio, location, link }
+
+mutation updateMyProfile(displayName: text <=50, handle: text <=20, avatarUrl: text <=2048 ?, bio: text <=200, location: text <=50, link: text <=2048 ?):
+  existing = profiles[viewer] ! else PROFILE_REQUIRED
+  update profiles[existing] { displayName, handle, avatarUrl, bio, location, link }
+  return { id: existing.id, principal: viewer, displayName, handle, avatarUrl, bio, location, link }

package/dist/templates/chat/snapback/schema.q

@@ -0,0 +1,136 @@
+use identity
+
+table profiles:
+  principal: principal
+  displayName: text 1..50
+  handle: text 3..20 format handle
+  avatarUrl: text <=2048 format url ?
+  bio: text <=200
+  location: text <=50
+  link: text <=2048 format url ?
+  unique byPrincipal: principal
+  unique byHandle: handle
+  immutable principal
+  public 'profiles are public'
+  insert <- .principal = viewer
+  update <- .principal = viewer
+  delete <- deny
+
+table conversations:
+  title: text <=120
+  creatorId: principal
+  by byCreator: creatorId
+  unique byIdCreator: id, creatorId
+  read <- exists memberships[.id, viewer]
+  insert <- .creatorId = viewer
+  update <- deny
+  delete <- deny
+  after insert <- exists memberships[.id, .creatorId, 'admin']
+
+table memberships:
+  conversationId: conversations
+  principal: principal
+  role: enum('member', 'admin')
+  joinedAt: time
+  unique byConversationPrincipal: conversationId, principal
+  by byConversationPrincipalRole: conversationId, principal, role
+  by byPrincipalConversation: principal, conversationId
+  immutable conversationId, principal, joinedAt
+  read <- exists memberships[.conversationId, viewer]
+  insert <- (
+    exists memberships[.conversationId, viewer, 'admin']
+    or (
+      .principal = viewer
+      and .role = 'admin'
+      and created conversations[.conversationId, viewer]
+    )
+  )
+  update (old, next) <- (
+    exists memberships[old.conversationId, viewer, 'admin']
+    and old.role = 'member'
+    and next.role = 'admin'
+  )
+  delete <- (
+    .principal = viewer
+    or exists memberships[.conversationId, viewer, 'admin']
+  )
+
+table messages:
+  conversationId: conversations
+  authorId: principal
+  body: text <=4000 ?
+  photo: image <=5000000 ?
+  clip: video <=50000000 ?
+  viewOnce: bool ?
+  at: time
+  by byConvTime: conversationId, at, id
+  retain delivered-history
+  read <- exists memberships[.conversationId, viewer]
+  insert <- (
+    .authorId = viewer
+    and exists memberships[.conversationId, viewer]
+  )
+  update <- .authorId = viewer
+  delete <- .authorId = viewer
+
+-- @ref LLP 1012#3-the-model-on-one-page-and-the-program-shape — delivery metadata stays visible only to its recipient.
+table deliveries:
+  recipient: principal
+  conversationId: conversations
+  messageId: messages
+  kind: enum('message', 'edit', 'removed', 'expired')
+  at: time
+  by byRecipientAt: recipient, at, id
+  by byRecipientConversationAt: recipient, conversationId, at, id
+  immutable recipient, conversationId, messageId, kind, at
+  read <- .recipient = viewer
+  insert <- exists memberships[.conversationId, viewer]
+  update <- deny
+  delete <- deny
+
+table posts:
+  author: principal
+  body: text 1..500
+  at: time
+  by byTime: at, id
+  by byAuthorTime: author, at, id
+  immutable author, at
+  public 'posts are globally readable product content'
+  insert <- .author = viewer
+  update <- .author = viewer
+  delete <- .author = viewer
+  after insert <- exists profiles[.author]
+
+table follows:
+  follower: principal
+  followed: principal
+  at: time
+  unique byFollowerFollowed: follower, followed
+  by byFollower: follower, followed
+  by byFollowed: followed, follower
+  immutable follower, followed, at
+  public 'follows are public product-selection relationships'
+  insert <- .follower = viewer
+  update <- deny
+  delete <- .follower = viewer
+
+table notifications:
+  outboxId: id
+  effect: text <=100
+  providerId: text <=200
+  unique byOutbox: outboxId
+  read <- deny
+  insert <- system
+  update <- system
+  delete <- deny
+
+maintain messageCounts = count messages by conversationId:
+  read <- exists memberships[.conversationId, viewer]
+
+channel typing(conversationId: conversations):
+  publish <- exists memberships[conversationId, viewer]
+  subscribe <- exists memberships[conversationId, viewer]
+  ttl 4s
+
+maintain memberCounts = count memberships by conversationId:
+  read <- exists memberships[.conversationId, viewer]

package/dist/templates/chat/snapback/seed.ts

@@ -0,0 +1,45 @@
+import { seed } from "snapback2";
+
+export default seed({
+  personas: ["alice", "bob", "charlie"],
+  rows: {
+    profiles: [
+      { id: "profile-alice", principal: "dev:alice", displayName: "Alice", handle: "alice", avatarUrl: "https://example.com/alice.png", bio: "", location: "", link: null },
+      { id: "profile-bob", principal: "dev:bob", displayName: "Bob", handle: "bob", avatarUrl: "https://example.com/bob.png", bio: "", location: "", link: null },
+    ],
+    conversations: [
+      { id: "conversation-1", title: "General", creatorId: "dev:alice" },
+      { id: "conversation-2", title: "Side room", creatorId: "dev:alice" },
+    ],
+    memberships: [
+      { id: "membership-1", conversationId: "conversation-1", principal: "dev:alice", role: "admin", joinedAt: 0 },
+      { id: "membership-2", conversationId: "conversation-1", principal: "dev:bob", role: "member", joinedAt: 0 },
+      { id: "membership-3", conversationId: "conversation-2", principal: "dev:alice", role: "admin", joinedAt: 0 },
+      { id: "membership-4", conversationId: "conversation-2", principal: "dev:charlie", role: "member", joinedAt: 0 },
+    ],
+    messages: [
+      // Keep the disjoint room first so derived invalidation probes can commit
+      // the recipe's messageId-only edit/unsend mutations outside General.
+      { id: "message-2", conversationId: "conversation-2", authorId: "dev:alice", body: "derived test", at: 1 },
+      { id: "message-1", conversationId: "conversation-1", authorId: "dev:alice", body: "Welcome", at: 1 },
+    ],
+    deliveries: [
+      { id: "delivery-1-alice", recipient: "dev:alice", conversationId: "conversation-1", messageId: "message-1", kind: "message", at: 1 },
+      { id: "delivery-1-bob", recipient: "dev:bob", conversationId: "conversation-1", messageId: "message-1", kind: "message", at: 1 },
+      { id: "delivery-2-alice", recipient: "dev:alice", conversationId: "conversation-2", messageId: "message-2", kind: "message", at: 1 },
+      { id: "delivery-2-charlie", recipient: "dev:charlie", conversationId: "conversation-2", messageId: "message-2", kind: "message", at: 1 },
+    ],
+    posts: [
+      { id: "post-alice", author: "dev:alice", body: "Hello from Alice", at: 1 },
+      { id: "post-bob", author: "dev:bob", body: "Hello from Bob", at: 2 },
+    ],
+    follows: [
+      { id: "follow-bob-alice", follower: "dev:bob", followed: "dev:alice", at: 1 },
+    ],
+    messageCounts: [],
+    memberCounts: [],
+    notifications: [
+      { id: "notification-1", outboxId: "seed-outbox", effect: "notify", providerId: "seed-provider" },
+    ],
+  },
+});